From db43576d413e9cd451052569e5ef0565e56a3e57 Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Fri, 12 Jun 2026 21:01:58 +0900 Subject: [PATCH] docs: review `workflow` content --- src/content/workflow/index.mdx | 550 ++++++++++++++++++++++++++++++++- src/content/workflow/v1.md | 489 ----------------------------- 2 files changed, 539 insertions(+), 500 deletions(-) delete mode 100644 src/content/workflow/v1.md diff --git a/src/content/workflow/index.mdx b/src/content/workflow/index.mdx index 0b1d410..2f4be16 100644 --- a/src/content/workflow/index.mdx +++ b/src/content/workflow/index.mdx @@ -1,15 +1,105 @@ --- title: 'Workflow' version: 'v1' -description: 'The current REPL Works process for AI-native product development.' +description: 'REPL Works를 이용한 AI-Native Product Development Workflow' publishedAt: '2026-06-12T00:00:00Z' --- -## Purpose +대부분의 AI 프로젝트는 같은 문제를 반복한다. -Explain the latest REPL Works process from idea refinement through operation. +처음에는 모든 것이 명확하다. -## Workflow +무엇을 만들고 있는지, +왜 만들고 있는지, +어떤 구조를 선택했는지 모두 알고 있다. + +--- + +하지만 시간이 지나면 상황이 달라진다. + +새로운 채팅을 시작한다. + +다른 모델을 사용한다. + +프로젝트를 몇 주 동안 중단했다가 다시 돌아온다. + +새로운 사람이 프로젝트에 참여한다. + +--- + +그 순간부터 동일한 설명이 반복된다. + +```text +왜 만들고 있지? + +현재 상태가 뭐지? + +왜 이렇게 설계했지? + +다음 작업은 뭐지? +``` + +--- + +REPL Works는 이 문제를 해결하기 위해 만들어졌다. + +--- + +REPL Works의 목표는 단순히 AI로 코드를 생성하는 것이 아니다. + +프로젝트가 세션보다 오래 살아남을 수 있도록 만드는 것이다. + +--- + +# 핵심 아이디어 + +REPL Works는 프로젝트 기억(Project Memory)과 세션 기억(Session Memory)을 구분한다. + +--- + +Session Memory + +```text +현재 채팅 + +현재 Context Window + +현재 Agent Runtime +``` + +--- + +Project Memory + +```text +Git + +PRODUCT_SPEC.md + +ARCHITECTURE.md + +TASKS.md + +AGENTS.md +``` + +--- + +세션 기억은 언제든 사라질 수 있다. + +프로젝트 기억은 Git에 남아야 한다. + +--- + +어떤 모델을 사용하더라도, + +어떤 세션을 시작하더라도, + +프로젝트는 다시 복원될 수 있어야 한다. + +--- + +# 전체 흐름 ```text IDEAS.md @@ -30,21 +120,459 @@ Issue ↓ Execution AI ↓ -PR +Pull Request ↓ Human Review ↓ Merge ↓ Operation +↓ +Document Updates +↓ +Next Iteration +``` + +--- + +이 흐름은 제품 개발부터 운영까지 동일하게 유지된다. + +REPL Works는 개발 단계와 운영 단계를 분리하지 않는다. + +제품이 진화하면 문서도 함께 진화해야 한다. + +--- + +# Phase 1. 아이디어 정제 + +## 목적 + +무엇을 만들 것인지 결정한다. + +--- + +Discussion AI와 반복적으로 대화하며 아이디어를 검증한다. + +이 단계에서는 구현보다 문제와 시장을 이해하는 것이 중요하다. + +--- + +주요 질문 + +```text +누구를 위한 제품인가? + +왜 존재해야 하는가? + +사용자가 원하는가? + +지속 가능한가? + +사업적으로 의미가 있는가? +``` + +--- + +## 산출물 + +### IDEAS.md + +아이디어와 핵심 가설을 정리한다. + +--- + +### PITCHING_SCRIPT.md + +제품을 짧고 명확하게 설명할 수 있도록 정리한다. + +--- + +# Phase 2. 제품 정의 + +## 목적 + +무엇을 만들 것인지 명확하게 정의한다. + +--- + +좋은 아이디어만으로는 제품을 만들 수 없다. + +제품이 어떤 경험을 제공해야 하는지 구체적으로 정의해야 한다. + +--- + +## 산출물 + +### PRODUCT_SPEC.md + +제품의 Source of Truth이다. + +--- + +포함 내용 + +```text +Vision + +User Journey + +Navigation + +Features + +Content Structure + +Success Criteria +``` + +--- + +Execution AI는 PRODUCT_SPEC.md만 읽어도 제품의 목적을 이해할 수 있어야 한다. + +--- + +# Phase 3. 아키텍처 설계 + +## 목적 + +어떻게 만들 것인지 정의한다. + +--- + +제품 정의가 끝나면 기술 구조를 설계한다. + +--- + +## 산출물 + +### ARCHITECTURE.md + +기술적 Source of Truth이다. + +--- + +포함 내용 + +```text +Project Structure + +Routing + +Content Model + +Data Flow + +Deployment + +Constraints +``` + +--- + +PRODUCT_SPEC.md가 무엇을 정의한다면, + +ARCHITECTURE.md는 어떻게를 정의한다. + +--- + +# Phase 4. 작업 계획 + +## 목적 + +현재 개발 상태를 정의한다. + +--- + +큰 프로젝트도 결국 작은 작업들의 집합이다. + +--- + +## 산출물 + +### TASKS.md + +현재 위치를 설명하는 문서이다. + +--- + +예시 + +```text +Phase 1 + +- [ ] + +Phase 2 + +- [ ] ``` -## Roles +--- + +ARCHITECTURE.md는 목적지다. -- Planning AI defines the work and updates the project memory documents. -- Execution AI implements the approved task. -- Human Review approves the result before merge. +TASKS.md는 현재 위치다. + +--- + +작업은 항상 TASKS.md 기준으로 수행한다. + +--- + +# Phase 5. 프로젝트 규칙 정의 + +## 목적 + +AI가 따라야 하는 규칙을 정의한다. + +--- + +## 산출물 + +### AGENTS.md + +프로젝트 헌법이다. + +--- + +AI는 항상 AGENTS.md부터 읽는다. + +--- + +포함 내용 + +```text +문서 우선순위 + +구현 규칙 + +테스트 규칙 + +파일 생성 규칙 + +아키텍처 변경 규칙 +``` + +--- + +# Phase 6. 계획 수립 + +## Planning AI + +Planning AI는 구현보다 이해에 집중한다. + +--- + +역할 + +```text +요구사항 분석 + +문서 검토 + +Task 검증 + +Issue 작성 + +Architecture 검토 +``` + +--- + +Planning과 Execution은 분리한다. + +--- + +REPL Works는 설계되지 않은 구현을 지양한다. + +--- + +# Phase 7. 구현 + +## Execution AI + +Execution AI는 승인된 작업을 구현한다. + +--- + +입력 + +```text +PRODUCT_SPEC.md + +ARCHITECTURE.md + +TASKS.md + +AGENTS.md + +Issue +``` + +--- + +출력 + +```text +Code + +Tests + +Pull Request +``` + +--- + +필수 조건 + +```text +Build Success + +Lint Success + +Test Success +``` + +--- + +구현이 완료되면 Pull Request를 생성한다. + +--- + +# Phase 8. 검토 + +## Human Review + +최종 책임은 사람에게 있다. + +--- + +Human Review는 다음을 확인한다. + +```text +요구사항 충족 여부 + +제품 방향 일치 여부 + +사용자 경험 + +품질 + +릴리즈 준비 상태 +``` + +--- + +승인 후 Merge를 수행한다. + +--- + +# Phase 9. 운영 + +## Operation + +배포는 끝이 아니다. + +실제 제품 개발은 운영 단계에서 계속된다. + +--- + +운영 과정에서는 새로운 학습이 발생한다. + +```text +사용자 피드백 + +버그 + +신규 요구사항 + +제품 개선 +``` + +--- + +이 변화는 반드시 프로젝트 문서에 반영되어야 한다. + +--- + +# 운영 루프 + +```text +Operate +↓ +Learn +↓ +Update PRODUCT_SPEC.md +↓ +Update ARCHITECTURE.md +↓ +Update TASKS.md +↓ +Next Iteration +``` + +--- + +REPL Works는 문서를 한 번 작성하고 버리는 방식이 아니다. + +문서는 프로젝트의 현재 상태를 지속적으로 반영해야 한다. + +--- + +# Benefits + +REPL Works는 다음과 같은 효과를 목표로 한다. + +--- + +## Model Independence + +특정 AI 모델에 의존하지 않는다. + +--- + +## Project Continuity + +세션 종료 이후에도 프로젝트를 이어갈 수 있다. + +--- + +## Reduced Context Cost + +반복 설명을 줄이고 컨텍스트 비용을 줄인다. + +--- + +## Reduced Onboarding Cost + +새로운 사람이나 새로운 모델이 빠르게 프로젝트를 이해할 수 있다. + +--- + +## Git-Native Workflow + +Git을 중심으로 프로젝트 기억을 관리한다. + +--- + +# 결론 + +REPL Works는 AI 도구가 아니다. + +--- + +REPL Works는 AI-Native Product Development Framework이다. + +--- + +프로젝트 기억을 Git과 문서에 저장하고, + +Planning AI, Execution AI, Human Review를 통해 + +장기적으로 유지 가능한 제품 개발 프로세스를 제공한다. + +--- -## Continuity +Models forget. -The process is designed to preserve project memory across sessions and model changes. +Projects must not. diff --git a/src/content/workflow/v1.md b/src/content/workflow/v1.md deleted file mode 100644 index 497a8dc..0000000 --- a/src/content/workflow/v1.md +++ /dev/null @@ -1,489 +0,0 @@ ---- -title: 'ReplWorks 워크플로' -version: 'v1' -type: 'workflow' -description: 'ReplWorks 를 이용해서 실무에 사용하는 워크플로를 설명합니다.' -publishedAt: '2026-06-06T00:00:00Z' ---- - -# 개요 - -```text -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와 반복적으로 토론한다. - ---- - -검토 항목 - -```text -아이디어가 충분히 매력적인가? - -2년 이상 유지 가능한가? - -예상 비용은 감당 가능한가? - -BEP는 언제 달성 가능한가? - -시장 규모는 충분한가? - -사용자 증가 예측은 합리적인가? -``` - ---- - -## 산출물 - -### IDEAS.md - -프로젝트 의사결정 문서 - ---- - -### PITCHING_SCRIPT.md - -프로젝트 의도 문서 - ---- - -## 커밋 - -두 문서는 반드시 같은 Commit으로 생성한다. - -```bash -git commit -m "docs: initialize product vision" -``` - ---- - -# Phase 2. 아키텍처 설계 - -## 목적 - -프로젝트 전체 구조 정의 - ---- - -Execution AI는 ARCHITECTURE.md만 읽어도 프로젝트를 이해할 수 있어야 한다. - ---- - -IDEAS.md와 PITCHING_SCRIPT.md는 개발 단계의 필수 문서가 아니다. - ---- - -## 아키텍처 구조 - -```text -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부터 읽는다. - ---- - -포함 항목 - -### 읽기 순서 - -```text -ARCHITECTURE.md - -TASKS.md -``` - ---- - -### 에이전트 레지스트리 - -```text -agents/ -``` - ---- - -### 규칙 - -```text -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로 그룹화한다. - -```text -Phase 1 - -- [ ] - -Phase 2 - -- [ ] -``` - ---- - -ARCHITECTURE.md는 목적지다. - -TASKS.md는 현재 위치다. - ---- - -# 개발 루프 - -## 1단계 - -TASKS.md에서 작업 선택 - ---- - -## 2단계 - -Planning Runtime에서 구현 전략 논의 - ---- - -계획 수립과 구현은 분리한다. - ---- - -## 3단계 - -Prompt 생성 - ---- - -Execution Runtime에 전달할 Prompt를 생성한다. - ---- - -## 4단계 - -Branch 생성 - -```bash -git checkout -b feature/xxx -``` - ---- - -## 5단계 - -Execution Runtime에서 구현 - ---- - -모든 기능은 반드시 Unit Test를 포함해야 한다. - ---- - -필수 조건 - -```text -Build Success - -Lint Success - -Test Success -``` - ---- - -실패 시 수정 후 재실행한다. - ---- - -## 6단계 - -Pull Request 생성 - ---- - -## 7단계 - -Human Review - ---- - -## 8단계 - -Merge - ---- - -## 9단계 - -TASKS.md 업데이트 - -```text -- [x] -``` - ---- - -## 10단계 - -필요 시 ARCHITECTURE.md 업데이트 - ---- - -구조 변경이 발생한 경우에만 수행한다. - ---- - -# AI_MEMORY - -## 목적 - -프로젝트 기억 압축 - ---- - -AI_MEMORY.md는 구현 문서가 아니다. - -하지만 프로젝트 기억의 일부이다. - ---- - -다음 상황에서 사용한다. - -```text -새로운 모델 사용 - -새로운 채팅 시작 - -기존 채팅 Context 소멸 - -장기간 프로젝트 중단 후 재개 -``` - ---- - -사용 방법 - -새로운 채팅을 시작한 뒤 첫 메시지로 전달한다. - ---- - -AGENTS.md에 등록하지 않는다. - -Execution Runtime은 기본적으로 읽지 않는다. - ---- - -## 생성 시점 - -소규모 프로젝트 - -```text -TASKS.md 완료 시 -``` - ---- - -대규모 프로젝트 - -```text -Phase 완료 시 -``` - ---- - -필요한 경우 수동으로 갱신할 수 있다. - ---- - -## 포함 내용 - -```text -왜 중요한 결정을 내렸는가 - -어떤 접근을 선택했는가 - -어떤 접근을 포기했는가 - -프로젝트 철학은 무엇인가 - -미래의 AI가 반드시 이해해야 하는 맥락은 무엇인가 -``` - ---- - -AI_MEMORY.md는 대화 기록이 아니다. - -대화에서 살아남은 기억이다. - ---- - -# 배포 - -배포 수행 - ---- - -# README.md - -외부 사용자를 위한 문서 - ---- - -프로젝트가 충분히 완성된 이후 생성한다. - ---- - -README.md는 마케팅 문서이자 진입 문서다. - ---- - -# 지속 자산 - -## Project Memory - -```text -Git - -ARCHITECTURE.md - -AGENTS.md - -TASKS.md - -AI_MEMORY.md -``` - ---- - -## Human Documents - -```text -docs/IDEAS.md - -docs/PITCHING_SCRIPT.md -``` - ---- - -## Session Memory - -```text -Current Chat -``` - ---- - -프로젝트 기억은 Git에 저장된다. - -세션 기억은 언제든지 사라질 수 있다. - ---- - -어떤 모델이든 프로젝트는 Git으로 복원할 수 있어야 한다. - -어떤 세션이든 AI_MEMORY.md로 이어갈 수 있어야 한다.