철학

AI 시대의 핵심 문제는 코드를 생성하는 능력이 아니다.

핵심 문제는 다음과 같다.

• 프로젝트 의도 유지
• 아키텍처 일관성 유지
• 작업 범위 제어
• 반복 실수 방지
• 컨텍스트 관리
• 모델 교체 가능성

REPL Works는 Agent Framework가 아니다.

REPL Works는 인간과 AI의 협업을 위한 Project Memory System이다.

핵심 원칙

Thinking과 Execution을 분리한다

REPL Works는 하나의 AI에게 모든 역할을 맡기지 않는다.

Discussion AI는 인간과 함께 생각한다.

Execution AI는 구현한다.

인간은 방향을 결정하고 결과를 승인한다.

Human
↕
Discussion AI

→ Idea
→ Architecture
→ Planning

Execution AI

→ Implementation

Human

→ Approval

모든 문서는 토론의 결과물이다

문서는 먼저 작성되는 것이 아니다.

문서는 토론의 결과로 생성된다.

Human
↕
Discussion AI

↓

Consensus

↓

Document

예시

Idea Discussion
↓
IDEAS.md

Architecture Discussion
↓
ARCHITECTURE.md

Planning Discussion
↓
TASKS.md

Memory Discussion
↓
LONG_CONTEXT.md

Git은 진실의 출처

프로젝트는 Git으로 시작한다.

git init

모든 변경사항은 Git으로 관리한다.

모든 구현은 Branch → PR → Merge를 통해 진행한다.

프로젝트의 진실(Source of Truth)은 Git에 존재한다.

Commit은 인간의 승인이다

코드는 AI가 작성할 수 있다.

하지만 프로젝트 상태는 인간이 승인한 변경만으로 정의된다.

AI
↓
Code Proposal
↓
Human Approval
↓
Commit

Commit은 코드 저장이 아니다.

Commit은 인간의 승인 기록이다.

모델은 교체 가능해야 한다

GPT
Claude
Gemini
Codex
Cursor
Future Models

모두 교체 가능해야 한다.

프로젝트의 가치는 모델이 아니라 Git에 저장된 기억에 있다.

문서 소유권

Planning Runtime

채팅창

역할

Idea Discussion
Architecture Design
Task Planning
Prompt Design
Memory Generation
Decision Making
Document Creation

Execution Runtime

코딩창

역할

Implementation
Refactoring
Testing
Bug Fixing

규칙

모든 Markdown 문서는 원칙적으로 Planning Runtime에서 생성한다.

모든 Markdown 문서는 원칙적으로 Planning Runtime에서 수정한다.

Execution Runtime은 문서의 대규모 수정(Rebuild, Rewrite, Revise)을 수행하지 않는다.

예외적으로 다음 문서만 최소 수정 가능하다.

TASKS.md
ARCHITECTURE.md

워크플로 개요

git init
↓
IDEAS.md
+
PITCHING_SCRIPT.md
↓
commit
↓
ARCHITECTURE.md
↓
commit
↓
AGENTS.md
↓
commit
↓
TASKS.md
↓
commit
↓
Development Loop
↓
Release
↓
README.md

Phase 1. 아이디어 정제

목적

아이디어를 사업적으로 검증한다.

Discussion AI와 반복적으로 토론한다.

검토 항목

아이디어가 충분히 매력적인가?

2년 이상 유지 가능한가?

예상 비용은 감당 가능한가?

BEP는 언제 달성 가능한가?

시장 규모는 충분한가?

사용자 증가 예측은 합리적인가?

산출물

IDEAS.md

프로젝트 의사결정 문서

PITCHING_SCRIPT.md

프로젝트 의도 문서

커밋

두 문서는 반드시 같은 Commit으로 생성한다.

git commit -m "docs: initialize product vision"

Phase 2. 아키텍처 설계

목적

프로젝트 전체 구조 정의

Execution AI는 ARCHITECTURE.md만 읽어도 프로젝트를 이해할 수 있어야 한다.

IDEAS.md와 PITCHING_SCRIPT.md는 개발 단계의 필수 문서가 아니다.

아키텍처 구조

ARCHITECTURE.md

architecture/
├── frontend.md
├── backend.md
├── database.md
└── auth.md

ARCHITECTURE.md는 Index 역할을 수행한다.

세부 설계는 architecture/ 디렉터리에 위치한다.

ARCHITECTURE.md는 프로젝트의 기술적 진실이다.

Phase 3. 헌법

목적

프로젝트 규칙 정의

산출물

AGENTS.md

AGENTS.md는 프로젝트 헌법이다.

동시에 모든 AI의 진입점이다.

AI는 항상 AGENTS.md부터 읽는다.

포함 항목

읽기 순서

ARCHITECTURE.md

TASKS.md

에이전트 레지스트리

agents/

규칙

Never create files in repository root

Reuse existing components first

Every feature must include unit tests

Build must pass

Lint must pass

Tests must pass

All task updates must trigger architecture review

Only architecture-impacting changes may modify architecture documents

Phase 4. 태스크 계획

목적

현재 개발 상태 정의

산출물

TASKS.md

TASKS.md는 현재 위치를 설명하는 문서다.

반드시 Phase로 그룹화한다.

Phase 1

- [ ]

Phase 2

- [ ]

ARCHITECTURE.md는 목적지다.

TASKS.md는 현재 위치다.

개발 루프

1단계

TASKS.md에서 작업 선택

2단계

Planning Runtime에서 구현 전략 논의

계획 수립과 구현은 분리한다.

3단계

Prompt 생성

Execution Runtime에 전달할 Prompt를 생성한다.

4단계

Branch 생성

git checkout -b feature/xxx

5단계

Execution Runtime에서 구현

모든 기능은 반드시 Unit Test를 포함해야 한다.

필수 조건

Build Success

Lint Success

Test Success

실패 시 수정 후 재실행한다.

6단계

Pull Request 생성

7단계

Human Review

8단계

Merge

9단계

TASKS.md 업데이트

- [x]

10단계

필요 시 ARCHITECTURE.md 업데이트

구조 변경이 발생한 경우에만 수행한다.

LONG_CONTEXT

목적

프로젝트 기억 압축

LONG_CONTEXT.md는 구현 문서가 아니다.

하지만 프로젝트 기억의 일부이다.

다음 상황에서 사용한다.

새로운 모델 사용

새로운 채팅 시작

기존 채팅 Context 소멸

장기간 프로젝트 중단 후 재개

사용 방법

새로운 채팅을 시작한 뒤 첫 메시지로 전달한다.

AGENTS.md에 등록하지 않는다.

Execution Runtime은 기본적으로 읽지 않는다.

생성 시점

소규모 프로젝트

TASKS.md 완료 시

대규모 프로젝트

Phase 완료 시

필요한 경우 수동으로 갱신할 수 있다.

포함 내용

왜 중요한 결정을 내렸는가

어떤 접근을 선택했는가

어떤 접근을 포기했는가

프로젝트 철학은 무엇인가

미래의 AI가 반드시 이해해야 하는 맥락은 무엇인가

LONG_CONTEXT.md는 대화 기록이 아니다.

대화에서 살아남은 기억이다.

배포

배포 수행

README.md

외부 사용자를 위한 문서

프로젝트가 충분히 완성된 이후 생성한다.

README.md는 마케팅 문서이자 진입 문서다.

지속 자산

Project Memory

Git

ARCHITECTURE.md

AGENTS.md

TASKS.md

LONG_CONTEXT.md

Human Documents

docs/IDEAS.md

docs/PITCHING_SCRIPT.md

Session Memory

Current Chat

프로젝트 기억은 Git에 저장된다.

세션 기억은 언제든지 사라질 수 있다.

어떤 모델이든 프로젝트는 Git으로 복원할 수 있어야 한다.

어떤 세션이든 LONG_CONTEXT.md로 이어갈 수 있어야 한다.