Plan-Doc-Do-Follow Skill
Plan → Doc → Do → Follow
의도(intent) 매칭 → 첫 번째 경로 승리 → routes/a-b.md (경로 a/b) 읽기 → 따르기 → Global Invariants + Status Model 적용. 필요한 경로, 템플릿, 하위 에이전트만 로드하고 절대 모두 로드하지 않음
경로(Routes)
계획(Planning)
| 의도(Intent) | 경로(Route) | 매개변수(Params) |
|---|---|---|
| 제품 비전에서 에픽 추출 | plan/proj | |
| 이해관계자와 에픽 검증 | plan/proj-review | |
| 에픽 PRD 및 추적 생성 | plan/epic | E{n} |
| 에픽 사양 또는 아키텍처 검증 | plan/epic-review | E{n} {prd|arch} |
| 에픽 아키텍처 설계 | plan/epic-arch | E{n} |
| 기능 PRD 생성 | plan/feat | E{n} F{n} |
| 기능 사양 또는 아키텍처 검증 | plan/feat-review | E{n} F{n} {prd|arch} |
| 기능 아키텍처(예외만) | plan/feat-arch | E{n} F{n} |
| 기능을 작업으로 분할 | plan/tasks | E{n} F{n} |
| 범위 변경 — 기능/에픽 추가/업데이트(구현된 것 포함) | plan/change | description |
| v2 프로젝트 문서를 v3로 마이그레이션(일회성) | plan/migrate |
실행(Execution)
| 의도(Intent) | 경로(Route) | 매개변수(Params) |
|---|---|---|
| 토큰 절약 도구 설정(LSP, 필터, 이코노미, 네이티브 에이전트) | do/init | |
| 하나의 작업 실행 | do/task | E{n} F{n} T{n} |
| 모든 기능 작업 실행 및 인라인 검증 | do/all-tasks | E{n} F{n} |
| 완료된 작업 검증(작업 단위 경로) | do/verify | E{n} F{n} |
| 모든 상태 재계산 및 복구 | do/sync-status | |
| 모범 사례 암기 | do/memorize |
전역 불변 규칙(Global Invariants, 모든 경로)
- 정신 일치(Spirit check):
docs/product.md와 일치; 모든 계획 경로 + 검토자 브리핑에 Product Spirit을 그대로 포함(docs/project-status.md상단) - 사용자 의지(User's will):
docs/decisions.md바인딩; 이탈 시 질문, 절대 묵시적 적용하지 않음 - 비즈니스 우선(Business first): 다음 단계 전 사양 검토
- 아키텍처 확인(Architecture check):
docs/global_architecture.md+docs/technical-stack.md와 일치 - 하나의 사실, 하나의 파일(One fact, one file): 상태/사실은 하나의 소유 파일(Status Model); 다른 파일은 링크만, 복사 금지
- 대상 언어(Audience language): 사람/비즈니스 = 완전한 문장, 설명 없는 약어 없음; 에이전트 대상 = 문서 스타일(Document style, 원시인 간결)
- 빈 스캐폴딩 금지(No empty scaffolding): 사용하지 않는 템플릿 섹션 삭제; "N/A" 또는 플레이스홀더 금지
- 추측 금지(No guessing): 차단 모호성 → 먼저 질문; 차단/중요/사소 레이블 지정
- 추적성(Traceability): 각 문서는 상위 문서 참조; 스토리 ↔ 요구사항 ↔ 작업 ↔ 테스트 연결
- 살아있는 전역 문서(Living global docs):
docs/data-model.md,docs/ui-map.md,docs/decisions.md는 영향을 주는 변경과 함께 업데이트 — 절대 "나중에" 하지 않음 - 모델 계층화(Model tiering):
plan/*+ 검토자 = 강력 모델; 모든plan/tasks작업은 PRD를 열지 않고 약한 모델로 실행 가능 - 상태 동기화(Status Sync): 상태를 변경하는 모든 경로는 상태 동기화 절차로 종료
- 인계 형식(Handoff format): 짧은 요약 · 현재 진행 · 정확한 다음 명령 · 미해결 질문
- 범위 제한 하위 에이전트(Scoped subagents): 정의된 입력 목록만 받음
- 경로별 마인드셋(Mindset per route): 경로의 Mindset 줄 채택
- 숙고는 내부 유지(Deliberation stays internal): 비평가 교환은 문서/인계에 포함되지 않음 — 사람은 최종 결과 + 검증할 사항만 봄
- 경제성은 모든 곳에(Economy everywhere): 모든 경로와 하위 에이전트에 Working Economy 적용
상태 모델(Status Model)
⚪ TODO · 🟡 SPEC 지정됨 · 🟣 PLAN 작업 생성됨 · 🔵 DEV 진행 중 · 🟢 DONE 완료 및 검증됨
소유권 — 단일 진실 공급원
| 사실 | 소유 파일(ONLY 작성 위치) |
|---|---|
| 작업 상태 | feat-tasks.md — 작업 요약 표 |
| 기능 상태 및 진행 | epic-status.md — 기능 표 |
| 에픽 상태 및 진행 | docs/project-status.md — 에픽 로드맵 표 |
| 프로젝트 진행 | docs/project-status.md — 진행 섹션 |
feat-status.md 없음. 작업별 섹션: 상태 줄 없음. Mermaid = 장식용, 소유 표에서 재생성, 진실 공급원이 아님
파생 규칙
- 기능:
feat-prd.md없음 → ⚪ · PRD 있음 → 🟡 ·feat-tasks.md있고 TODO를 넘는 작업 없음 → 🟣 · DEV/DONE 작업 있음 → 🔵 · 🟢 오직 검증 게이트(do/verify또는do/all-tasks의 최종 단계)를 통해서만. 🟢 기능에 작업 추가됨 → 🔵로 되돌림 - 에픽:
epic-prd.md없음 → ⚪ · PRD 있음 → 🟡 · 모든 기능 ≥ 🟣 → 🟣 · 🔵/🟢 기능 있음(전부 🟢 아님) → 🔵 · 전부 🟢 → 🟢 - 프로젝트: 에픽에 대해 동일한 집계
- 진행: 완료된 작업 / 전체 작업(없으면 0), 에픽 및 프로젝트 수준에서 합산
상태 동기화 절차
상태를 변경하는 경로가 끝날 때(독립형: do/sync-status, 모든 에픽):
- 영향을 받는 기능의 작업 요약 표 읽기
- 각 기능 상태 + 진행 재계산;
epic-status.md의 행 업데이트 - 영향을 받는 각 에픽 재계산;
docs/project-status.md의 행, 진행 섹션, 원형 차트 업데이트. 상태 동기화는 변경 로그를 작성하지 않음 — 변경 로그 하드 규칙(문서 스타일)에 의해 명명된 이벤트만, 마일스톤을 생성한 경로가 작성 - 인계에서 차이(저장된 것 ≠ 파생된 것) 보고
결정론적이고 멱등적
하위 에이전트(Subagents)
정의는 subagents/에 — 에이전트당 하나의 파일(형식: subagents/README.md). 호출: 파일 읽기 → 정확히 나열된 입력 조합(검토자는 항상 Product Spirit 받음) → 파일 본문을 시스템 프롬프트로 하여 생성
이코노미 프로필(Economy profile)
저장소 명령 파일 도구 섹션의 Subagent economy: 읽기 (do/init가 작성). 없음 → balanced
| 프로필 | 동작 |
|---|---|
strict | 인라인 우선 하드 · 스카우트 거의 항상 인라인 · 질문/도구/반환 제한 적용 · 비평가 여전히 생성 |
balanced | 아래 작성된 대로 인라인 우선 · 제한 적용 · 스카우트 질문 >5면 소프트 경고 |
quality | 비용 게이트는 권고사항 · 제한은 여전히 스카우트 도구 사용 및 반환 크기에 적용 |
생성 전(인라인 우선)
순서대로 실행 — 첫 번째 일치 승리 → 생성하지 않음:
- 사실이 이미 주요 컨텍스트에 있음 → 인라인 작업
- 주요 컨텍스트에서 ≤5회 Grep/Glob/Read(또는 LSP) 호출로 답변 가능 → 인라인(
subagents/repo-scout.md의 scout-lite 체크리스트 사용) - 브리핑이 예상 답변 크기에 근접 → 인라인
- 결과가 작은 표면에 대한 미용/기계적 체크리스트일 가능성 높음 → 인라인(오늘의 비용 게이트와 동일)
- 그 외에는 생성
repo-scout 추가(strict / balanced 하에서): ≥3개의 반증 가능한 질문 그리고 검색이 주요 컨텍스트가 열지 않은 ≥2개 영역에 걸치는 경우에만 생성, 또는 주요 컨텍스트가 이미 크고 격리가 명확히 저렴한 경우. 그렇지 않으면 scout-lite 인라인
생성 시:
- 도구 주입(Tooling injection): 브리핑에 저장소 명령 파일의 한 줄 도구 블록 포함(CLI 필터 접두사, LSP 선호도, 이코노미 프로필) — 하위 에이전트는 이를 따라야 함
- 정확한 브리핑(Precise brief): 정확한 질문/확인사항 · 기준이 되는 작업 표준 · 범위 외 · 스카우트의 경우 영역이 알려졌을 때 시작 경로/글로브 · 스카우트 웨이브당 ≤5개 질문(
balanced/strict; 나머지는 분할 또는 인라인) - 기준을 앞서 설정(Front-load the bar): 초안 작성 전, 비평가의 검토 질문 읽기; 첫 시도에 통과하도록 초안 작성
- 반환 페이로드 제한(Return-payload cap): 스카우트 ≤15줄 · 비평가 ≤25줄 · 주요 컨텍스트는 필요한 사실만 유지 — 스카우트 덤프를 문서에 붙여넣지 않음
비평가 결과(Critic findings): 동작, 계약 또는 인간의 결정을 변경하는 경우 적용; 쓸모없거나 미용적인 것은 조용히 폐기. 거부된 판단 호출 → 인간을 위한 결정 질문. 수렴(Convergence): 문서당 한 번 실행; 차단 결과의 실질적 재작업 후 최대 한 번 재실행, 해당 결과로 범위 제한 — 재실행은 차단만 수용; 세 번째 실행 없음. 교환 보고하지 않음(불변 규칙 16)
| 하위 에이전트 | 종류 | 호출자 | 시기 |
|---|---|---|---|
repo-scout | 연구 | plan/epic-arch, plan/feat, plan/feat-arch, plan/change | 계획이 기존 코드에 기반해야 함 |
prd-critic | 검토자 | plan/epic, plan/feat | 항상 |
arch-critic | 검토자 | plan/epic-arch, plan/feat-arch | 항상 |
perf-critic-backend / -frontend | 검토자 | 아키텍처 경로, 검증 게이트 | 트리거 기준(파일 상단)이 발동될 때만 |
task-checker | 검토자 | plan/tasks | 자체 검토 후; 최대 두 번 실행 |
feature-coder | 실행자 | do/all-tasks | 웨이브당 병렬화 가능한 작업당 하나 |
ui-consistency-reviewer | 검토자 | 검증 게이트 | UI 기능, 중요 표면 |
doc-coherence-reviewer | 검토자 | 검증 게이트 · plan/change · plan/migrate | 에픽 완료 · 변경 후 · 마이그레이션 후 |
검증 게이트(및 해당 하위 에이전트)는 do/verify에서 실행되거나 do/all-tasks의 최종 단계로 인라인 실행
인간 검토 사용자 경험(Human review UX)
결론, 프로세스 아님. 기계적 확인은 자동 검증 → 한 줄 요약. "검증이 필요한 결정(Decisions requiring your validation)": ≤10개의 평문 문장 + 차단/중요/사소로 레이블된 미해결 질문. 검증된 결정 → docs/decisions.md. 이해관계자 답변 그대로 — 절대 의역하지 않고, 절대 다시 묻지 않음(모호하면 명확화만 질문)
Working Economy(불변 규칙 17)
입력 경제(Input economy)
- 전체 파일 읽기보다 LSP/의미론적 탐색 선호; 범위가 지정된 줄 범위
- 코드 검색을 위해 Shell보다 Grep/Glob/LSP 선호 — 필요한 경우에만 Shell
- 긴 CLI 출력(테스트, 빌드, git, 패키지 관리자)은 저장소에서 선언한 필터(예:
rtk,snip)를 통해 처리 —do/init가 설정; 활성 후크 없이 Shell 사용 시 수동으로 접두사 추가 - 컨텍스트에 있는 내용을 다시 읽지 않음; "안전을 위해" 문서 로드하지 않음
- 이코노미 프로필 + 생성 전 인라인 우선(하위 에이전트) 준수
출력 스타일(주요 컨텍스트 및 하위 에이전트)
- 원시인 간결(에이전트 대상 문서와 동일한 기준): 서문 없음, 요청 재진술 없음, 후행 요약 없음, 채우기/얼버무림 없음
- 코드, 명령, 경로, 오류: 바이트 단위 정확 — 절대 의역하지 않음
- 코드 변경은 diff 또는 대상 편집으로 — 요청하지 않는 한 전체 파일 나열 금지
- 연구 답변 ≤10줄(깊이 요청되지 않은 경우); 하위 에이전트 반환은 반환 페이로드 제한 준수
- 인계(불변 규칙 13) = 마지막 블록만: ≤5줄
최소 구현(do 경로 및 feature-coder)
완전히 이해하고, 유지되는 첫 번째 단계에서 중단:
- 존재할 필요 없음 → 건너뜀(YAGNI)
- 이미 코드베이스에 있음 → 재사용
- 표준 라이브러리로 가능 → 사용
- 네이티브 플랫폼 기능 → 사용
- 설치된 종속성 → 사용
- 한 줄이면 충분 → 한 줄
- 그때에야 작동하는 최소한 작성
절대 축소하지 않음: 신뢰 경계 검증, 데이터 손실 처리, 보안, 접근성
문서 스타일(Document style)
두 대상 — 경로 분위기가 아닌 파일 목적으로 선택
인간 / 비즈니스(완전한 산문) — PRD(epic-prd.md, feat-prd.md), docs/product.md, Product Spirit, 인간 검토 본문(*-review.md 결정 섹션), 사용자 중심 문서(developer-setup, 온보딩, 인간 README). 완전한 문장. 이해관계자가 읽을 수 있음. 설명 없는 약어 없음
에이전트 대상(원시인 간결) — 스킬 플레이북(SKILL.md, routes/, subagents/, 템플릿 주석), feat-tasks.md, epic-arch.md / feat-arch.md, 상태 표/메모, 살아있는 기술 문서(data-model.md, ui-map.md, decisions.md), docs/patterns/*. caveman 전체에서 영감:
- 사실과 명령만 — 의미가 명확할 때 관사/채움/얼버무림 삭제; 조각 허용
- 짧은 동의어; 패턴
[thing] [action] [reason]·[next step] - 발명된 약어 없음(
cfg/impl/fn); 잘 알려진 기술 약어는 허용(DB/API/HTTP) - 경로, 기호, 코드, 명령, 오류 문자열: 정확
not/never/no/only/except절대 생략 금지- 줄 바꿈 전 마침표 없음(여러 절이 있는 줄의 중간 마침표는 유지)
- 결정과 사실만 — 프로세스 없음("검토자가 제안…", "논의 후…")
- 미래 에이전트가 이유(트레이드오프, 범위 축소)가 필요한 경우에만 정당화: ≤2줄
- 자동 명확성: 보안 경고, 되돌릴 수 없는 단계, 또는 명령/부정을 잘못 읽을 위험이 있는 조각은 더 완전한 산문으로 작성 — 그 후 간결 재개
변경 로그 하드 규칙(Changelog hard rule): 한 줄 {date}: {fact}, ≤25단어. 자격 있는 경우만 — 프로젝트: 에픽 완료, 주요 범위 변경, 마이그레이션; 에픽: 기능 검증 🟢, 범위 변경. 그 외 모든 것(작업 생성, PRD 초안/승인, 웨이브, 동기화, 차이 복구) = 항목 없음. 절대: 비평가 교환(불변 규칙 16), 작업 목록, 게이트 결과, 진행 숫자, Next: 명령. 장황한 기존 항목 = 레거시, 절대 선례 아님 — 자격 있는 줄만 작성하거나 아무것도 작성하지 않음
파일 구성(File Organization)
docs/
├── product.md (입력: 제품 비전)
├── global_architecture.md (입력: 아키텍처 개요)
├── technical-stack.md (입력: 기술 결정)
├── project-status.md (소유: Product Spirit, 에픽 상태, 진행)
├── project-review.md
├── decisions.md (살아있음: 바인딩 사용자 결정, 각각 한 줄)
├── data-model.md (살아있음: 전역 데이터 스키마, 있는 경우)
├── ui-map.md (살아있음: 전역 탐색 맵, UI가 있는 경우)
├── design-guidelines.md (살아있음: UI 스타일 규칙, UI가 있는 경우)
├── patterns/{pattern-name}.md (do/memorize로부터)
└── epics/e{n}-{epic-name}/ (slug 예: e2-orm-discovery)
├── epic-brief.md (plan/proj)
├── epic-prd.md (plan/epic)
├── epic-status.md (소유: 기능 상태)
├── epic-arch.md (plan/epic-arch)
├── epic-review.md (plan/epic-review)
└── f{n}-{feat-name}/ (직속 하위 — features/ 수준 없음)
├── feat-prd.md (plan/feat; 진입점 + 아키텍처 델타 있음)
├── feat-arch.md (plan/feat-arch — 예외만)
├── feat-tasks.md (소유: 작업 상태)
└── feat-review.md (plan/feat-review)
플랫폼 통합(Platform integration)
저장소 규칙, 우선순위: CLAUDE.md · AGENTS.md · .github/copilot-instructions.md · .cursor/rules/ · .github/instructions/. do/memorize는 실제로 존재하는 파일에 다시 기록
템플릿(Templates)
templates/에 있음 — 이름은 출력 파일을 반영