| name | plan-feature |
| description | Plan a non-trivial code change — decompose into tasks, pre-resolve decisions, define acceptance, output one plan.md. Triggers on Korean (계획/설계/기능 추가/리팩토링/구현/수정/변경/여러 곳/전체/만들어줘/앱·도구 만들어) and English (plan/design/implement/refactor/build an app/create a tool), a multi-task request, or a change spanning multiple files, altering logic/signatures, adding a function/class/method, or refactoring a resource layer (i18n/theming/DI). Routing — approved plan.md + execute-only (구현/이대로 진행/계속/T<N> 진행/go) → implement-task; bug/crash reports (버그/에러/크래시/안 됨/왜 안 돼) → pjc-systematic-debugging first; single-component work (Domain/Application service, ViewModel, wiki page) → add-domain-service/add-viewmodel/llm-wiki. Do NOT trigger for trivial edits (single-line text/label/color/size, typo, comment, config, ≤3-line code adding no new symbol/signature, or multi-element pure value substitution of any count — Claude edits directly). Ambiguous scope — ask "A) edit directly / B) make a plan". |
| argument-hint | <요청 설명> |
Plan Feature
코드 작성 전에 작업을 분해하고, 모든 결정 분기를 사전 해결하고, 검증 가능한 수용 기준을 정의한다.
Trivial Bypass — 이 skill을 건너뛰는 경우
다음 케이스는 plan-feature를 호출하지 않고 Claude가 직접 Write/Edit으로 처리한다:
| 카테고리 | 예시 |
|---|
| UI 문구·라벨 | "확인 버튼 라벨을 'OK'로", "메시지 문구 변경" |
| 아이콘·이미지 교체 | "이 아이콘을 SVG 파일로 교체", "PNG 새 파일로 변경" |
| 색상·치수·간격 순수 값 치환 | "Primary 색상을 #336699로", "padding을 16px로", "여러 요소 width/height/font-size 숫자만 조정" (개수 무관, 로직·구조 변화 없으면) |
| 문서·README 오타 | "README 오타 수정", "줄바꿈 추가" |
| 주석 추가 | "이 메서드에 한글 주석 추가" |
| 단일 라인 설정 | ".editorconfig에 한 줄 추가", "gitignore에 폴더 추가" |
| 단일 라인 리소스 | "strings.xml의 키 한 개 값 변경" |
| 작은 코드 수정 | 변수 값·조건·문자열 변경 등 3줄 이내, 새 함수/클래스/시그니처 추가 아님 |
Trivial 판정 기준 (모두 만족):
- 변경이 3줄 이내, 단일 위치
- 새 함수/클래스/메서드 추가 없음, 시그니처 변경 없음
- 사용자 요청이 명백하고 단순 (의도 모호함 없음)
예외 — 순수 값 치환은 개수·줄 수 제한 없이 trivial: 사이즈·색상·간격·폰트 크기 등 디자인 토큰/리터럴 값을 다른 값으로 바꾸기만 하고 로직·조건·구조·시그니처 변화가 전혀 없으면, 값이 3개든 10개든·여러 줄이든 trivial로 보고 직접 수정한다(값만 바뀌므로 개수가 많아도 위험이 낮고, 잘못돼도 화면에서 바로 보인다). 단 다음은 순수 치환이 아니므로 trivial 아님(plan 또는 최소한 질문):
- 새 반응형 분기(
@media 블록 신설 등) 추가 — 화면 크기별 동작이 새로 생기는 구조 변화.
- 값 변경이 레이아웃 구조(flex/grid 방향·배치)나 동작 로직·조건을 함께 바꿈.
- 값을 바꾸면서 계산식·변수 도입(하드코딩 → 계산) 등 구조가 변함.
위 기준(1-3 또는 순수 값 치환 예외)을 만족하면 코드 파일(.cs, .xaml, .ts, .kt, .py, .css 등)이라도 직접 수정한다.
require-plan-for-write hook이 작은 변경을 자동 통과시키고, cross-file 영향은 impact-warn hook이 사후 검출한다.
애매한 경우 — plan을 강제하지 말고 질문 (3갈래)
trivial인지 plan이 필요한지 판단이 애매하면 임의로 plan-feature를 강제하지 않고 사용자에게 한 번 묻는다 — A) 바로 수정(빠르게, plan 없이 — impact-warn hook이 사후 caller 영향 검출) / B) 계획부터(plan-feature 영향분석+검증). 명백히 trivial(위 3기준)이면 묻지 말고 직접 수정, 명백히 큰 작업(다중 파일·시그니처·새 정의)이면 묻지 말고 plan 진행. 즉 3갈래: 명백 trivial=직접 / 명백 대형=plan / 애매=A/B 질문. (질문은 작업당 1회, 선택대로 진행.)
자율성 모드: USER-INTERACTIVE
이 skill 안에서는 사용자에게 물어도 된다. 모호한 요구사항은 명확화 질문 권장.
그러나 implement-task 단계로 넘어가기 전에 모든 질문이 해결되어야 한다.
implement-task는 FULLY AUTONOMOUS이므로 그 안에서는 사용자에게 묻지 않는다.
plan-feature (이 skill) | implement-task
USER-INTERACTIVE | FULLY AUTONOMOUS
|
질문 OK (Open Questions에 모음) | 질문 금지 (Halt만 가능)
사용자 승인 1회 (게이트) | plan = 전체 위임장
|
↓ 모든 질문 해결 후 ──────────→ ↓
위임장 = plan 승인(1회)이 전체 작업의 위임이며, 여기에는 plan의 ## 사전 승인 항목 (일괄 승인 대상)이 명시적으로 포함된다. 단 ## 불가피한 Halt (위임 불가) 항목(파괴적·외부/비가역·돌발 결정)은 위임에서 제외돼 그 지점에서 별도 승인받는다.
절대 규칙 (Hard Rules)
-
이 Skill은 코드 파일을 작성·수정하지 않는다. 계획 산출물은 plan.md(+ 대규모 작업 시 PRD)이며, 그 외에는 발동된 스킬 규약이 정한 큐 기록만 남긴다(예: pjc:llm-wiki 절차 K의 [SKILL-IMPROVE] 큐 1줄). 코드·문서 등 대상 프로젝트 파일은 건드리지 않는다.
-
팩트 기반 — 예측 금지, 전수 확인.
- 모르는 것은 "확인 필요"로 표시. "아마도", "보통은", "일반적으로" 같은 가정은 금지.
- 모든 주장은 Read 또는 grep으로 직접 확인한 결과여야 한다.
- 사용처는 grep으로 전수 조사. "샘플 몇 개 확인 후 전체가 그럴 것"이라 결론짓지 않는다.
- 읽기 비례 원칙 (hit 과다 시). grep hit가 30건을 초과하면 전건을 전부 Read하는 대신
grep -C <n>(문맥 포함)으로 1차 영향 판정 후 영향이 의심되는 것만 전체 Read하고, 판정 근거를 Investigation Log에 남긴다(예: "hit 42건 중 시그니처 호출부 9건만 정독, 나머지는 문자열/주석으로 문맥 확인"). 이는 전수 조사의 포기가 아니라 단순 grep 카운트만으로 끝내는 것을 막으면서 큰 결과셋을 효율적으로 다루는 방법이다(Step 4 Halt 조건의 "단순 grep 카운트만" 판정과 정합 — 카운트가 아니라 영향 판정이 있어야 한다). hit 30건 이하면 종전대로 전건 Read.
- 확인 방법은 Investigation Log에 기록.
-
근본 해결. 증상 우회는 plan의 해결책이 될 수 없다.
-
결정 사전화 — 자율 실행 전제.
implement-task는 plan.md를 받으면 사용자 개입 없이 모든 task를 끝까지 실행한다.
- 근거로 결정 가능한 항목은 자체 확정 — 질문은 근거로 결정 불가한 것만. 코드·AGENTS.md·기존 컨벤션으로 답이 정해지는 항목(명명 관례, 기존 패턴 준수, 프로젝트 표준 등)은 사용자에게 묻지 말고 Decisions에
Source(확인한 코드/문서 위치)와 함께 자체 확정한다. 사용자에게 묻는 것은 근거만으로 결정할 수 없는 항목(제품 방향·UX 선택·비가역 데이터 형식 등 갈림길)에 한한다 — 자명한 것까지 묻는 것은 과잉이다.
- 근거로 결정 불가한 모호한 요구사항은 빠짐없이 모두 사용자에게 미리 묻는다 (카테고리별로 묶어서 한 번에 제시, 개수 제한 없음).
- 각 선택지에 Claude 추천 ★ 표기로 사용자 결정 부담 ↓.
- 답변 후 새 모호함 발견 시 다음 라운드에서 추가 질문 가능 (라운드 통상 3-5회).
- 답변 시간 < 재작업 시간. 질문이 많아 보여도 plan 완전성을 우선한다. 추측으로 코드 작성하면 그게 재작업의 원인.
- 구현 도중 결정 분기 0의 대상은 "외부 관찰 가능 계약"(공개 API·스키마·UX 동작·의존성)이다 — 이 계약이 갈리는 지점은 plan에서 모두 확정한다. 반면 순수 내부 세부(지역 변수명, 국소 구현 방식 등 가역·비노출)는 구현자가 컨벤션에 따라 결정하도록 위임해도 된다(모든 미세 결정을 plan에 못박으라는 뜻이 아니다 — 계약이 흔들리지 않으면 충분).
- 자기 검증: "이 plan을 다른 사람에게 넘겨도 (외부 계약에 대한) 추가 질문 없이 끝낼 수 있는가?"
-
연관 파일 의무 명시 (Cross-File Awareness).
- 변경 대상의 모든 호출자/구현체/직렬화/테스트를 task의 Files 목록에 모두 명시.
- 누락 시 plan-reviewer 또는 spec-compliance-reviewer가 차단한다.
-
요청 범위 밖 작업 금지. "참고 김에 정리"는 plan에 새 task로 등록 후 사용자 확인.
-
"이번 제외"와 "영구 제외"를 구분해 기록. 작업을 빼기로 한 경우 둘 중 어디인지 정확히 판단한다 — 잘못 적으면 다음에 할 일이 영영 누락된다:
- 사용자가 "이번엔 빼고 다음에 하자" → plan.md의
## Deferred / Follow-up에 기록 (향후 진행 대상).
- 사용자가 "이 기능은 안 만든다" →
## Out of Scope에 기록 (영구 제외).
- 애매하면 사용자에게 "이번만 제외인가요, 아예 제외인가요?" 확인. 기본 가정은 Deferred(다음에) — 영구 제외는 명시적일 때만.
-
모든 task에 검증 가능한 acceptance — 항목 간 동시 만족 가능해야 한다. "잘 동작한다" 같은 모호한 기준 금지. 여러 acceptance 항목을 가진 task는 항목들이 동시에 만족 가능한지 확인한다 — 하나를 지키면 다른 하나가 깨지는 조합(예: "프로세스 1개만 기동" + "스크립트 무수정"인데 대상 구조상 양립 불가)은 실현 불가능한 계획이므로 발견 시 설계 자체를 재검토한다(plan-reviewer 항목 4가 BLOCKER로 검출).
실행 단계
Step 0. 작업 공간 정리 (계획 작성 전 가장 먼저)
계획을 작성하기 전에, 이전 작업의 잔여 상태부터 정리한다. 계획을 다 만든 뒤에 정리하면 그 과정에서 방금 만든 plan.md를 백업·복구해야 하는 낭비가 생긴다 — 정리를 먼저 하면 깨끗한 상태에서 계획을 쓸 수 있다.
-
컨텍스트 여유 확인 (새 세션 권유): 이번 세션에 이미 auto-compact가 있었거나 대화가 매우 길게 누적됐으면(작업 중 압축 반복으로 품질 저하 위험) 시작 전에 새 세션 시작을 권한다("plan.md로 맥락 유지 — 이대로 진행할까요, 새 세션으로?"). 시작 전은 멈춰도 안전한 분기점이다(작업 중간엔 압축 통과와 구분). 컨텍스트가 여유로우면 묻지 않고 조용히 통과(과잉 방지).
-
미커밋 변경 확인: git status로 커밋되지 않은 변경이 있는지 본다. 단, 미커밋이 있다고 항상 묻지 않는다 — 다음을 구분한다:
- 이번 요청과 무관한 이전 작업의 잔재(다른 기능의 미완성 변경 등)가 섞여 있으면 → 사용자에게 처리를 묻는다(커밋/stash/폐기). 미정리 상태로 새 작업을 쌓으면 변경이 뒤섞여 커밋 단위가 엉키기 때문이다.
- 이번 요청과 직접 관련된 변경이거나, 방금 이 세션에서 진행해 곧 이어서 작업할 변경이면 → 묻지 않고 그대로 진행한다 (개발 중 미커밋은 정상이며, 매번 물으면 과잉이다).
- 판단이 애매하면(무관한 잔재인지 진행 중인지 불분명) 그때만 한 번 묻는다.
- '폐기'는 데이터 손실이므로 Claude가 직접 실행하지 않는다 —
git clean -fd 같은 untracked 영구 삭제는 block-destructive hook이 차단한다. 단 git checkout -- <파일>(추적 파일 되돌리기)은 hook이 막지 않는다(정당한 파일 복원과 구분 불가하므로) — 그래도 uncommitted 변경 손실이라 Claude가 스스로 실행하지 않는다. 폐기를 원하면 사용자가 직접 실행하도록 안내하고, Claude는 커밋·stash까지만 돕는다.
-
기존 plan.md 확인 (= Step 0.2 — 외부 문서가 이 라벨로 지칭한다): 이미 plan.md가 있으면 다음을 구분한다 (항상 묻지 않는다):
- 이전 계획이 완료됨(모든 task 완료, notes에도 반영됨)이 명백하면 → 묻지 않고 새 계획으로 교체한다 (완료된 plan.md는 휘발성 잔재이므로 보존 가치 없음 — notes가 영구 기록을 이미 담았다). 단 교체 전에 기존 plan의
## Deferred / Follow-up에 미처리 항목이 남았는지 확인한다 — task 체크박스가 전부 [x]여도 Deferred는 "다음에 할 일"이라 완료가 아니다. 남아 있으면 이번 작업과 관련된 항목은 새 plan의 ## Deferred / Follow-up으로 이관하고, 무관한 항목은 docs/plans/deferred.md 대장의 ## 대기로 옮긴 뒤 교체한다(커밋되는 단일 대장이 Deferred 추적 정본 — 형식·중복 억제는 implement-task references/phase-f-detail.md F-6.5 규정, 파일 없으면 생성. F-6.5의 notes 포함 의무가 로컬 상세 기록으로 병행돼 유실 안전망이 이중이다).
-
PRD 연결 plan은 완료 판정에 Phase G 통과까지 포함한다: 기존 plan에 **PRD**: 줄이 있으면 task가 전부 [x]여도 그것만으로 완료가 아니다 — PRD 기반 작업의 완료는 **Phase G(요구 재검증) 통과 = active Must FR 100%**까지다. ## Phase Ledger 마커 상태로 판정한다(implement-task Phase G-4가 통과 시 남기는 완료 신호가 Step 0.2가 읽는 실제 산출물):
## Phase Ledger 마커 상태 | 판정·행동 |
|---|
Phase G 통과 (Must 100%) | 완료 — Deferred 잔여 확인 후 조용히 새 계획으로 교체 |
Phase F 통과까지만 | 완료 단정 금지 — Phase G 미실행 가능성 → '완료 여부 불분명' 분기(사용자 확인) |
Phase G 재루프 N회차 (진행 중) | 미완료 — 루프 중단 상태 → 사용자 확인 |
마커 없음 (task는 전부 [x]) | 완료 단정 금지 — 마지막 task 후 세션 단절로 Phase F/G 미실행 가능 → 사용자 확인 |
마지막 task 직후 세션이 끊겨 Phase F/G가 실행되지 않은 plan을 완료로 오인해 요구 재검증 없이 폐기하는 것을 막는다. (PRD 없는 plan은 이 표 비적용 — Phase F가 최종이므로 task 완료 + notes 반영이면 완료.)
- 진행 중이거나 미완료 task가 남은 plan.md이면 → 이번 요청과의 관계를 묻는다 (이어서 할지, 보류하고 새로 시작할지). 미완료 작업이 묻히지 않게 한다.
- 완료 여부가 불분명하면(notes 반영 안 됐을 수 있음 등) 그때만 확인한다.
-
정리가 끝난(깨끗한) 상태에서 Step 0.5 이후로 진행한다.
미커밋 변경이 없고 기존 plan.md도 없으면 이 단계는 즉시 통과한다 (묻지 않음).
이 단계의 질문은 Step 8 일괄 질문과 별개다. 작업 공간 정리는 계획을 시작하기 전에 끝나야 하는 선결 조건이므로(미정리 상태로 계획을 쓰면 안 됨), Step 8로 미루지 않고 여기서 즉시 묻고 처리한다.
Step 0.5. 대규모 작업 판정 — PRD 필요 여부
다음 중 하나라도 해당하면 대규모 작업이다. plan.md 작성 전에 PRD를 먼저 만든다:
- 앱/제품을 새로 만드는 요청 ("메모장 앱 만들어줘", "OO 도구 만들어줘")
- 예상 task가 10개 이상인 대형 feature
- 요구사항 자체가 미정의 상태 (사용자가 "필요한 기능을 검토해서" 같은 위임 표현 사용)
대규모가 아니면 이 단계를 건너뛰고 Step 1로 (일상 기능 추가·수정·버그는 plan.md만으로 충분).
대규모 작업 PRD 절차:
0. 기존 PRD 확인·귀속 판정 (초안 작성 전 필수) — 새 PRD 작성 전 docs/prd.md·docs/prds/를 확인해 신규/기존 갱신/어느 파일 귀속인지 판정한다(없으면 분할 PRD에 중복 등록·오배치). 없음 → 신규 docs/prd.md(단일 기본). 있고 연장 → 기존 PRD 갱신(새 FR은 새 ID, active/REMOVED에 같은 요구 있으면 중복 생성 금지). 분할 다수(docs/prds/) → 속하는 기능군 파일 갱신(없으면 새 분할 파일), 중복 확인은 분할 모든 파일 대상. 귀속·중복 판정 원칙(폐기 표시 5·중복 금지 6·단일/분할 7·부활 새 ID 8; 새 FR ID 부여는 4)은 references/prd-template.md 정본. 어느 PRD든 그 경로를 plan.md 상단 **PRD**: 줄에 적는다(implement-task Phase G 진입 신호).
references/prd-template.md 템플릿으로 PRD 초안 작성 — 기능 요구(FR)·비기능 요구(NFR)·Out of Scope·성공 기준- 질문 라운드 의무 (1회 이상). 대규모 작업은 요구 위임 자체가 모호함을 의미한다 — "모호하지 않다"고 판단해 질문을 생략하는 것 금지. Step 8과 같은 형식(카테고리 묶음 + 추천 ★)으로:
- Claude가 자명하게 도출한 Must 후보 → 사용자 확인 요청
- 갈림길 요구 (저장 방식, 플랫폼, 검색·다국어 여부 등) → 선택지 + 추천 ★
- 우선순위(Must/Should/Could) 배정 → 사용자 확정
- 질문 없이 초안만으로 승인 요청하는 것은 추측 코드와 같은 위반이다.
- PRD 사용자 승인 게이트 — 승인 후 PRD는 고정 (이후 임의 수정 금지, 변경은 사용자 합의 필수)
- plan.md의 각 task는 PRD 요구 ID를 역참조 (
T3 (FR-1, FR-2 충족)) + plan.md 상단에 **PRD**: <경로> 줄 의무 기록 (implement-task의 Phase G 진입 신호)
- PRD가 있으면 implement-task의 Phase G (요구 재검증) 가 활성화된다
승인 후 기능 변경 처리 (PRD 우선 갱신): plan 작성·구현 중 PRD의 요구(FR/NFR)를 바꿔야 할 필요가 생기면 —
- plan이나 코드를 먼저 바꾸지 않는다. PRD와 어긋나면 Phase G 재검증의 기준 자체가 틀려 검증이 무의미해진다.
- 변경 필요를 사용자에게 보고하고 PRD 갱신을 제안 → 승인받는다 (PRD는 승인 후 고정이므로).
- 승인 시 순서: ① PRD 갱신 → ② 영향받는 plan task 조정 → ③ plan.md의
**PRD**: 줄 유지.
- 변경 이력을 PRD에 간단히 기록한다 (무엇을·왜 바꿨는지 한 줄).
- 금지: 사용자 승인 없이 PRD를 임의 변경 / PRD는 그대로 둔 채 plan·코드만 어긋나게 변경. 변경은 항상 PRD → plan → 코드 순으로 위에서 아래로 흐른다.
Step 1. 컨텍스트 수집
AGENTS.md (또는 CLAUDE.md) 읽기
- 없으면:
pjc:bootstrap-agents-md를 Skill 도구로 호출한다(자동 호출) → 사용자 승인 후 plan-feature 계속. AGENTS.md를 스킬 경유 없이 직접 Write로 작성하는 것 금지 — 스택 템플릿 자산과 [Y/E/N] 승인 게이트가 통째로 우회된다("내가 내용을 쓸 수 있으니 스킬 생략"은 위반이며, require-plan-for-write hook의 bootstrap 게이트가 신규 생성을 차단한다 — 차단되면 정상 경로는 스킬 호출이다).
- 사용자가 bootstrap을 거부하면 추측 모드로 진행 (build/test 명령 모름 → 작업 중 Halt 빈번)
- 신선도 경량 점검 (stale 탐지): AGENTS.md를 읽으면서, 이번 계획이 실제 참조하는 명령·경로(빌드/테스트 명령이 가리키는 스크립트·파일, Repository Structure의 주요 디렉터리, Plan Location)가 실재하는지 가볍게 확인한다(Glob/Test-Path 수준의 존재 확인만 — 명령 실행 검증은 하지 않는다, 부작용 위험). 기록 후 시간이 지나 코드와 어긋난 항목(stale)은 계획을 오도하므로: 즉시 수정하지 않고 Step 8 일괄 질문(또는 계획 보고)에 "AGENTS.md 갱신 제안"으로 모아, 사용자 승인 시
pjc:record-project-fact로 갱신한다(승인 게이트 준수). 전수 검증이 아니다 — 이번 작업과 무관한 항목·트리 아스키 아트의 기계 추출은 요구하지 않는다(과잉 방지). 어긋남 0건이면 조용히 통과하고, AGENTS.md가 없으면(위 bootstrap 경로) 이 점검은 해당 없음.
- 관련 모듈/파일 식별
- 기존 컨벤션, 테스트 위치, 빌드 명령 확인
- Deferred 대장 확인:
docs/plans/deferred.md의 ## 대기를 확인한다 — 이번 작업과 관련된 항목이 있으면 plan에 반영하고(재수용 task로 채택 또는 이번에도 Deferred 유지를 명시) Investigation Log에 기록한다. 무관하거나 파일이 없으면 조용히 통과한다(빈 기록 강제 금지). 과거에 미뤄둔 일을 모르고 재발견·중복 계획하는 것을 막는 장치다(대장 형식·쓰기 규정은 implement-task references/phase-f-detail.md F-6.5 정본).
- PRD 경량 확인 (PRD 있는 프로젝트의 소규모 후속 작업): 이번 작업이 Step 0.5 대상(대규모)이 아니어도
docs/prd.md(또는 docs/prds/)가 존재하면, 이번 변경이 active FR/NFR에 닿는지 경량 확인한다 — FR 제목·요약을 훑는 수준이며 전수 대조가 아니다. 닿으면 사용자에게 PRD 갱신을 제안하고 plan 상단에 **PRD**: 줄을 연결한다 — 이 연결은 의도된 escalation이다(줄 연결로 implement-task Phase G 재검증이 활성화됨 — FR을 건드리는 이상 작은 작업이어도 요구 재검증을 받는 것이 목적). 이때 ## PRD Coverage 표에는 이번에 닿은 FR만 커버 대상으로 넣고, PRD의 나머지 active Must FR은 이번 범위 외 (기구현/후속) 행으로 명시한다 — 소규모 연결에서 Phase G·plan-reviewer 12-a 대조는 커버 대상으로 선언한 FR + 명시적 범위 외 FR에만 적용되므로(암묵 누락과 구분), 이전 세션에 이미 구현된 무관 FR을 이 작은 plan에서 재구현하도록 강요되지 않는다. 안 닿으면 조용히 통과한다(무관한 과거 PRD를 끌어오지 않는 Phase G 원칙 유지 — 이 확인은 "소규모 작업이 PRD 몰래 어긋나는" 공백만 메운다. 대규모 작업의 PRD 미연결은 plan-reviewer 12-b가 별도로 잡는다).
- 위키 참조 (llm-wiki skill 사용 중이고 vault가 존재하면): 구현할 기능과 관련된 feature/recipe/guide가 위키에 있으면
pjc:llm-wiki의 절차 K(read-only 조회)로 참조한다. 참조는 현재 프로젝트의 위키 등록 여부와 무관하다 — 현재 프로젝트가 아직 위키에 미등록(예: 신규 개발 중)이어도, 다른 프로젝트(A 등)의 관련 자료는 참조할 수 있다. 위키 참조는 읽기 전용이므로 현재 프로젝트 등록을 전제로 하지 않는다. 이미 정제된 구현 지식·과거 결정·크로스-커팅 정보를 계획에 반영하면 재조사를 줄인다. 위키는 읽기만 하고 수정하지 않는다(위키 갱신·현재 프로젝트 등록은 별도 세션, 사용자가 원할 때만 — 신규 프로젝트는 등록을 강요하지 않는다). 위키 vault 자체가 없으면(미설정) 건너뛴다. 관련 자료가 없으면 빠르게 마치고 진행한다. 계획 중 pjc 스킬 자체의 결함·마찰을 발견하면 pjc:llm-wiki 절차 K 5-1의 [SKILL-IMPROVE] 큐에 1줄 기록한다(vault 없으면 그 규약의 폴백). 대상 프로젝트의 결정 이력(decisions.md)도 함께 확인한다 — 과거에 보류·기각된 기획을 모르고 다시 계획하는 것을 방지(pjc:llm-wiki 절차 K 2). 참조 결과는 plan.md Investigation Log에 기록한다 — 형식: 위키 참조: <페이지> — <핵심 결론 1줄>(참조한 페이지별 1줄), 양방향 검색 후 무매칭이면 위키 참조: 관련 위키 자료 없음 — 코드 1차 출처로 진행 1줄(vault 미설정으로 건너뛴 경우는 기록도 생략 — 빈 기록 강제 금지). plan-reviewer·implement-task 재개 세션이 같은 근거를 재조회 없이 쓰게 하는 장치다.
- 독립 read-only 조사(위치·패턴 찾기)가 2개 이상이면
explorer subagent 병렬 위임을 기본으로 한다 (메인 컨텍스트 보호). 단일·소규모라도 메인 컨텍스트를 아껴야 하면 위임 가능.
- 서로 독립적인 조사 질문이 여러 개면 explorer를 한 turn에 병렬 호출한다 (예: "DI 등록 위치" + "기존 테마 처리 방식" + "테스트 구조" → 3개 동시). read-only라 충돌이 없고 대기 시간만 줄어든다. Step 4(영향 범위 조사)에서도 동일 — 기능별 독립 조사는 병렬로. 단 Step 4 위임은 후보 위치 찾기(grep locating)까지만이다 — 사용처를 전수 Read해 영향을 판단·확정하는 일은 메인이 직접 한다(아래 품질 경계).
- 위임 품질 경계: 위임 대상은 "어디 있나 / 패턴이 무엇인가"(locating)뿐이다. "이 코드가 X를 하는가" 같은 판단과 전체 파일을 읽어야 하는 작업은 explorer(발췌만 읽음)에 맡기지 말고 메인이 직접 한다. 정확도가 품질에 직결되는 단계를 발췌-읽기에 떠넘기면 오판 위험. (토큰보다 품질·정확도 우선 — 병렬 위임은 latency만 줄이고 토큰은 늘므로, 무분별 위임이 아니라 "독립 locating"에 집중한다.)
- explorer 결과 취급 (후보 위치일 뿐): explorer가 반환한 위치·패턴은 후보다 — Investigation Log에 근거로 등재하기 전에 메인이 그 파일을 직접 Read해 확인한다. explorer는 발췌만 읽으므로 그 요약을 검증 없이 "확인된 사실"로 옮기면 환각이 스며들 수 있다. locating은 위임하되, 등재되는 근거는 메인이 직접 본 것이어야 한다(explorer는 조회 보조이지 사실 판정자가 아니다).
- 단, 앞 결과가 다음 질문을 결정하는 의존 조사는 순차로 (예: "DI 컨테이너 종류 확인" → 그 결과에 따라 "해당 컨테이너의 등록 패턴 조사").
Step 2. 범위 명확화
다음을 답할 수 없으면 사용자에게 질문:
- 영향을 주는 사용자 시나리오는?
- 명시적으로 out of scope는?
- 성공을 어떻게 측정하는가?
질문은 Step 8과 같은 형식(카테고리 묶음 + 선택지 + 추천 ★)으로 한다. 이 단계는 보통 1-3개 핵심 질문이지만, 필요하면 더 묻는다.
Step 2.5. 시각 디자인 정합 명세 분해 (해당 시에만)
발동 조건 (모두 충족할 때만): ① 요청이 "디자인과 동일하게/똑같이 맞춰줘" 같은 시각 충실도(visual fidelity) 요청이고, ② 대조할 기준 디자인이 존재(디자인 HTML·이미지·Figma·기존 화면 등). 둘 중 하나라도 없으면 이 단계를 건너뛴다 (단순 UI 변경 "버튼 색 바꿔줘", 기준 없는 신규 화면, "동일한 로직" 같은 비시각 요청은 발동 안 함 — 과잉 방지).
발동 시, 변경 대상 화면의 시각 요소를 요소 단위로 분해한 표를 plan의 ## 시각 요소 분해 섹션에 만든다(이 표준 제목이 있어야 implement-task V-9가 표를 정확히 인식한다 — task 본문에 묻으면 V-9가 미발동으로 오판할 수 있다). "placeholder만 일치" 같은 부분 추출은 금지 — 한 요소를 속성별로 쪼갠다. 표는 "디자인 값 + 확인 방법"까지만 적는다 — "현재 값"과 "일치" 판정 열은 두지 않는다(현재 값 대조는 구현 후 implement-task V-9의 몫이다. 계획 단계에서 현재 값을 적으면 구현 시점에 stale해지고, plan-feature는 코드를 안 고치므로 "일치" 판정이 무의미하다):
| 요소 | 속성 | 디자인 값 | 확인 방법 |
|------|------|----------|-----------|
| 헤더 | font-size | 14px | 디자인 HTML `.header` 컴퓨티드 |
| 검색박스 | layout | flex:1, max 340px | 디자인 CSS |
| 검색박스 | 아이콘 | ⌕ 있음 | 디자인 스크린샷 |
| 필터 칩 | 정렬 | 세로 중앙 | 디자인 CSS `align-items` |
규칙:
- 공유·재사용 컴포넌트도 분해 대상에 포함한다. "리스트 행만 보고 헤더·검색·칩은 기존 공용 클래스라 맞겠지"라고 가정하지 않는다 (실제로 어긋나는 경우가 많다 — cross-file caller 원리의 시각 버전).
- 디자인 소스의 모든 시각 속성(폰트 크기·굵기, 간격, 정렬, 아이콘 유무, 색, 레이아웃 방식)을 요소별로 항목화한다. 체크리스트에 없으면 구현·검증에서 통째로 누락된다.
- 이 표가 Step 5 작업 분해와 Phase V 시각 대조의 기준이 된다.
- 디자인 요소가 애매한 경우(예: 정확한 색·간격 미확정)는 여기서 즉시 묻지 말고, Step 8 일괄 질문에 모아서 처리한다 (질문 분산 방지).
Step 3. 위험 식별
- 외부 의존성 (API, OS, 드라이버, 권한)
- 동시성·상태 (멀티스레드, 비동기, 라이프사이클)
- 회귀 가능성 (기존 기능 영향)
- 알려지지 않은 영역 (가설로 명시)
Step 4. 영향 범위 전수 조사 (Impact Analysis)
변경 대상의 모든 사용처를 실제로 식별하고 읽어 분석.
4-A. 심볼/타입 추적
4-B. 계약·직렬화 변경
- 시그니처, 이벤트 페이로드, 직렬화 형식 변경 → 호환성 확인
- 마이그레이션 필요 시 별도 task
4-C. 영향 받는 테스트
- 변경 대상을 직접 호출하는 테스트
- 변경 대상에 간접 의존하는 통합 테스트
- 테스트가 없으면 추가 필요성 검토 (plan에 task로)
4-D. 재사용·중복 방지 조사
Halt 조건
- 사용처 추적이 단순 grep 카운트만으로 끝남 (실제 파일 Read 안 함)
- "기타 영향 있을 수 있음" 같은 모호한 표현
- 변경 대상이 인터페이스인데 구현체 식별이 누락됨
- plan이 신규 심볼을 도입하는데 유사 기존 구현 검색 기록(4-D)이 없음
Step 5. 작업 분해
- 각 작업은 독립 검증 가능 + 주 파일 5개 이내 규모를 기준으로 나눈다(시간이 아니라 구조로 판단 — LLM 실행은 벽시계 시간이 일정치 않으므로 "몇 시간"보다 "독립 검증되는가·주 파일 몇 개인가"가 실질 기준이다). 주 파일이 5개를 크게 넘거나 독립 검증이 안 되면 task를 쪼갠다.
- 각 task는
T1, T2, ... 형식으로 번호를 매긴다. "Phase 1", "단계 1", "Step 1" 등 다른 명칭으로 작업을 나누지 않는다 — implement-task의 자율 루프가 T<N> 형식을 전제하며, "Phase"는 pjc 내부 단계(Phase P/I/V/D·F·G)와 혼동된다. 작업을 큰 묶음으로 그룹화하고 싶으면 task 번호는 유지한 채 주석으로만 묶는다 (예: T1~T3 (데이터 계층)).
- 각 작업마다 acceptance criterion 1줄 명시
- 의존 관계 표시
- 각 task에 Type 분류 명시 (의무) — implement-task가 fast-path 결정에 사용
Task Type 분류 (필수)
| Type | 정의 |
|---|
| A (Doc/Config) | .md, .json, .yml, .csproj, .editorconfig 등 코드 외 파일만. 단 동작을 바꾸는 Config는 Type A 아님 — DI 배선·기능 플래그 기본값·라우팅·빌드 산출에 영향 주는 설정은 런타임 동작을 바꾸므로 Type B 이상으로 본다(순수 문서·주석·비동작 설정만 A). Type A는 적대적 리뷰(V-5/V-6)를 건너뛰므로 동작 변경이 A로 숨으면 무검증 통과된다. |
| B (Trivial Code) | 단일 코드 파일, 단일 메서드/필드, 호출자 변경 없음. 기존 코드의 값·문자열·주석 수정, 자명한 접근자(getter/setter)·상수·순수 위임 수준 (typo, 주석). 단 비자명 로직·알고리즘·제어흐름·상태 변경을 담은 신규 심볼(함수/메서드/클래스) 추가는 파일이 하나여도 Type C 이상 — Type B는 V-5가 prefilter(Haiku)만, V-3·V-6을 생략하므로 검토가 필요한 신규 로직이 B로 새면 무검증 통과된다. |
| C (Normal Code) | 단일 또는 2-3개 파일, caller 갱신 있음 |
| D (Complex/Cross-cutting) | 다중 파일, 인터페이스 변경, 시그니처 변경, 직렬화 변경, DDD/아키텍처 영향 |
Type이 결정하는 적용 Phase V 단계 매핑은 implement-task Fast-Path 표가 정본 — plan은 Type 분류만 명시하고 V-단계 선택은 implement-task 소관이다.
확실하지 않으면 한 단계 더 무거운 쪽 선택 (안전 우선).
Type C/D의 V-6(code-quality)는 항상 실행된다 — plan이 별도 표기를 붙일 필요 없다. 종전에는 Type C가 opt-in 플래그((quality-review)) 없이는 V-6을 생략했는데, 그 기본값이 가장 흔한 Type C 코드를 spec 검증만 받고 품질 검토 0회로 커밋시키는 공백이라 반전했다(V-5와 병렬 호출이라 소요 시간은 늘지 않는다 — implement-task Fast-Path 표 정본). 기존 plan에 남은 (quality-review) 플래그는 no-op(이미 기본이 된 것의 중복 명시 — 오류 아님).
Design 필드 (Type D 필수 · Type C는 신규 심볼 도입 시)
Type D task 전부와 신규 심볼(함수/클래스/컴포넌트)을 도입하는 Type C task는 task에 **Design**: 필드로 구조 명세를 확정한다(대상 판정은 4-D 재사용 확인과 동일 기준 — 4-D 표에 신규 심볼이 있으면 대상. Type A/B는 비대상 — 과잉 방지). 4요소를 1~4줄로 자유 서술: ① 배치(어느 파일/레이어에 두는가) ② 신규 심볼과 책임(이름 — 책임 1줄) ③ 의존 방향(무엇을 참조하고 무엇이 참조하는가) ④ 비추상화 선언(이번에 추상화하지 않을 것 — YAGNI 앵커). 설계가 계획에 없으면 구현자가 그때그때 편한 구조를 택하고 사후 리뷰(V-6)는 완성된 코드를 뒤집지 못한다 — "계획 단계에서 확정하는 것이 가장 싸다"(decision-points.md와 동일 원리).
- Decisions '위치' 카테고리와의 역할 구분: Decisions '위치' = 갈림길일 때의 선택 기록(Options/Chosen), Design = task별 구조 명세의 확정 기록(갈림길이 아니어도 명시). 겹치면 Design이
(D<N> 참조)로 중복 서술을 피한다.
- 신규 심볼 없는 Type D는 "해당 없음 — <근거 1줄>"로 적는다(무근거 공백·placeholder는 plan-reviewer 항목 14가 MAJOR로 검출).
PRD 복귀 게이트: 분해 결과 task가 10개 이상인데 plan에 PRD 연결(**PRD**: 줄)이 없으면 — Step 0.5의 판정이 추정(예상 task 수) 기준이라 실분해와 어긋난 경우다 — Step 0.5로 돌아가 PRD를 먼저 작성한 뒤 계속한다(대규모 안전망(Phase G 재검증) 상실 방지).
긴 plan 분할 권고 (컨텍스트 관리)
task가 8개를 초과하면 사용자에게 분할을 제안한다:
이 plan은 <N>개 task로 큽니다. implement-task의 자율 실행 중
컨텍스트가 누적되어 후반 task의 품질이 저하될 수 있습니다.
A) 그대로 진행 (Progress Log로 일부 완화됨)
B) 2개 plan으로 분할 (앞부분 / 뒷부분)
→ 첫 plan(part1) 완료 후 둘째 plan(part2) 별도 실행
사용자가 A를 택하면 그대로 진행하되, implement-task가 Progress Log를 적극 활용.
B(분할) 선택 시 규약 (드문 경로 — 둘째 plan 망각·번호 충돌·절반 구현 오판 방지): 각 분할 plan은 T1부터 재번호(독립 실행 — implement-task "첫 실행 T1" 전제와 정합), 저장은 docs/plans/<YYYY-MM-DD>-<slug>-part1.md/-part2.md 누적(Plan Location: plan.md 덮어쓰기여도 override), 상호 포인터(**다음 plan**:/**이전 plan**: — implement-task(분할 plan 호출)·plan-completion-reviewer·plan-reviewer(항목 12-a의 PRD Coverage 분할 스코프)가 이 표식으로 분할을 인지)와 Goal 범위 한정(**전체 목표**: 별도 줄 + Deferred/Next Steps에 다음 part 상기), 시작 part는 경로 명시 호출. 분할 시 두 part plan 파일을 동시 작성한다 — Step 7.5의 합집합 전수 검증과 plan-reviewer 12-a의 "다음 part 대응 task 실재" 확인이 두 파일의 존재를 전제하므로, part2를 나중에 쓰면 이 검증들이 성립하지 않는다. 전체 규약·템플릿(위치 가이드·분할 포인터·Goal 범위)은 references/plan-template.md 정본.
Step 6. Decision Points 발굴
각 task에 대해 결정 분기를 사전 해결.
Type별 적용 범위 + 카테고리 12개 + 기록 형식은 references/decision-points.md 정본 참조 (요지: Type A skip / B 1-2개 / C 5-6개 + 보안·자격증명(해당 시) / D 12개 전체). 보안·자격증명은 Type C/D가 인증·자격증명·외부 접근을 다룰 때 발동한다 — 시드 계정 유무·강제 변경, 자격증명 보관처(문서에 값 금지), 계정 잠금·시도 제한을 계획 단계에서 확정한다.
Step 6.5. Edge Case & Halt Forecast (자율 실행 대비)
implement-task가 사용자 개입 없이 끝까지 가야 하므로, 구현 중 발생 가능한 멈춤 지점을 사전 예측.
Type별 적용 범위 + 상세 카테고리 + Halt Forecast + 자율 실행 준비도 자문은 references/edge-cases.md 정본 참조 (요지: Type A skip / B 빈·null+경계값 / C 5-6개 / D 10개 전체).
Halt Forecast ↔ Decision 역매핑 (자율 루프 중단 예방). 예측한 각 Halt Forecast 항목은 (i) 사전 해소(Step 6 Decision·Step 8 Open Question) / (ii-a) 사전 승인 가능(## 사전 승인 항목에 등록 — 비파괴 의존성/구조/스키마·계획된 공개 API 변경, plan 승인 시 일괄 위임 — "우회"가 아닌 명시적 일괄 승인) / (ii-b) 위임 불가 Halt(## 불가피한 Halt (위임 불가)) 중 하나로 분류한다. 3분류 정의·파괴적 예시 목록은 references/edge-cases.md 6.5-B 정본.
파괴적 작업은 (ii-a)에 절대 넣지 않는다 — 항상 (ii-b)(안전 게이트). 둘 다(i/ii) 아닌 예측 halt는 추측을 유발하므로 plan을 보강해 (i)로 해소한다. (ii-b) 위임 불가 항목을 사전결정으로 우회해 자동 실행으로 바꾸지 않는다 — 회피 가능한 중단(결정 누락)만 제거.
확인 이연 금지 (성립을 좌우하는 확인). 예측 halt를 (i)로 해소할 때 "구현 첫 단계에서 확인"은 해소가 아니다 — 그 확인이 설계·acceptance의 성립 여부를 좌우하면(부정될 경우 task 자체가 성립 불가) 계획 단계에서 Investigation Log로 확인을 완료해야 한다(plan-reviewer 항목 9가 BLOCKER로 검출). 결과가 진행 방식만 바꾸는 확인의 이연은 정상.
Step 7. plan.md 작성
위치 결정 (AGENTS.md의 Plan Location 항목 우선):
| 프로젝트 규모 | 권장 위치 |
|---|
| 작은 프로젝트, 단일 작업 | <repo>/plan.md (덮어쓰기) |
| 큰 프로젝트, 여러 plan 누적 | <repo>/docs/plans/<YYYY-MM-DD>-<slug>.md |
단, plan을 분할하면(위 "긴 plan 분할 권고") 덮어쓰기 모드여도 docs/plans/<YYYY-MM-DD>-<slug>-part1.md/-part2.md 누적 위치를 쓴다(두 part 충돌 방지).
## 요구 이해를 반드시 채운다 (원문 요청 인용 + 이해한 요구 3~5줄 — 형식·작성 규칙은 references/plan-template.md 정본). 승인 게이트를 통과한 요구 오해는 이후 어느 리뷰도 잡지 못하므로(구현 후 plan-completion-reviewer 항목 2.5가 요구 이해 ↔ 산출물 커버는 사후 대조하지만, 이해 자체의 옳음은 사용자만 판정), 이 섹션이 Step 10 승인 프롬프트 첫 항목으로 노출되어 사용자가 오해를 승인 전에 발견하는 장치다.
plan 작성은 이 스킬 경유가 정본이다 — 스킬 없이 손으로 쓰지 않는다 (require-plan-for-write hook이 기계 강제, v1.118.0). plan을 직접 Write하면 Step 1~9의 자산(영향 범위 전수 조사·Deferred 대장 확인·적대적 plan-reviewer 검토·Type 분류·사전 승인 항목·Halt Forecast)이 통째로 우회되고, 그렇게 만든 plan이 require-plan의 "plan 있음" 판정을 켜서 이후 모든 코드 변경이 무검증 통과한다(AGENTS.md 직접 작성 금지와 동일 구조 — Step 1 참조). hook은 plan 파일 Write와 체크박스를 새로 도입하는 Edit을 이 스킬(또는 implement-task) 발동 흔적 없이는 차단한다. 기존 plan의 부분 갱신(체크박스 [ ]→[x], Progress Log·Retry Ledger·Deferred append)은 게이트 대상이 아니므로 implement-task의 정상 갱신은 그대로 진행된다.
상세 plan.md 템플릿은 references/plan-template.md 참조.
Step 7.5. PRD 커버리지 확인 (PRD 있을 때만)
PRD가 있으면 (Step 0.5에서 새로 작성했거나 Step 1에서 기존 PRD를 연결한 경우), plan이 PRD를 빠짐없이 반영하는지 구현 전에 확인한다. 여기서 일치시키면 Phase G(구현 후 재검증)에서 누락이 발견돼 재구현하는 비용을 막는다. (소규모 연결 plan도 이 표를 채운다 — Step 1에서 정한 커버 대상·범위 외 구분을 그대로 기록.)
- FR/NFR → task 매핑표 작성 — PRD의 각 요구에 대응하는 plan task를 적는다:
| PRD ID | 우선순위 | 대응 task | 상태 |
|--------|---------|----------|------|
| FR-1 | Must | T1, T2 | ✅ 커버 |
| FR-2 | Must | T3 | ✅ 커버 |
| FR-3 | Should | (없음) | ⚠️ 누락 |
- 일치 판정 (대조 대상 = plan이 커버 대상으로 선언한 Must FR):
- 커버 대상으로 선언한 모든 Must FR에 대응 task가 있으면 → plan과 PRD가 일치. Step 8로 진행.
- 커버 대상 Must FR에 대응 task가 없으면 → 누락. plan에 task를 추가해 일치시킨 뒤 진행 (plan↔PRD 불일치 상태로 구현에 들어가지 않는다).
- 소규모 연결 plan(Step 1에서 기존 PRD를 연결)은 이번에 닿지 않은 active Must FR을
## PRD Coverage에 이번 범위 외 (기구현/후속)로 명시하며, 그 FR은 이 대조에서 제외한다(기구현 FR을 이 작은 plan에서 재구현하도록 강요하지 않음). 단 대규모 신규 작업(Step 0.5)은 이 제외를 쓰지 않고 전수 커버한다 — 미대응 Must FR은 누락으로 본다(분할 시 전수의 기준은 아래 분할 분기의 합집합).
- 분할 plan(Step 5 B — 상단
**다음/이전 plan**: 표식): 각 part의 ## PRD Coverage 표는 그 part 몫 FR만 커버 대상으로 넣고, 다른 part 몫 active Must FR은 ⏭️ 다음 part 또는 ✅ 이전 part 기구현 상태 행으로 명시한다 — 이번 범위 외 (기구현/후속)와 구분한다(범위 외는 "이 작업이 안 하는 것", 분할 행은 "이 전체 작업 안에서 다른 part가 하는 것"). 대규모 전수 커버는 part별이 아니라 분할 전체에 적용된다: 분할은 두 part plan 파일을 동시 작성하므로(Step 5 B 규약 — 이 검증의 선행조건) 여기서 두 part 표의 커버 대상 합집합 = active Must FR 전수를 확인한다(합집합에 빠진 Must FR은 누락). 3개 이상 분할이면 중간 part도 다음 part 행을 쓰고 합집합은 전 part 기준.
- Should/Could를 의도적으로 1차 범위에서 빼려면, PRD의 Out of Scope 또는 plan에 "이번 제외" 사유를 명시 (암묵적 누락과 명시적 제외를 구분).
- 매핑표는 plan.md에
## PRD Coverage 섹션으로 남긴다 (Phase G가 이 표를 기준으로 재대조).
Step 8. Open Questions 해결 — 일괄·완전 모드
질문이 있으면 여기서 사용자에게 묶어 질문하고, 답변을 plan.md에 반영한다. (리뷰 게이트(Step 9)보다 먼저 — plan-reviewer는 미해결 Open Questions를 BLOCKER로 보므로, 질문을 먼저 해소한 뒤 리뷰해야 한다.) 답변을 반영한 질문은 ## Open Questions에서 [x]로 바꾸고 답 요약을 병기한다 — [ ]로 남기면 plan-reviewer(항목 6)가 미해결로 오판할 수 있다(미해결 질문만 [ ]로 남긴다).
질문 형식 (카테고리별 묶음)
질문이 많아도 영역별로 그룹핑하여 가독성 확보. 개수 제한 없음.
## Open Questions
이 plan에 N개 결정이 필요합니다. 카테고리별로 정리했습니다.
### [명명] (3)
Q1. UserService 클래스 이름?
A) ★ UserService (현재 컨벤션과 일치, src/Application/Services 패턴)
B) UserManager
C) AccountService
Q2. ...
### [에러 처리] (4)
Q4. 검증 실패 처리 방식?
A) ★ Result<T> 패턴 (AGENTS.md 명시, 프로젝트 일관성)
B) 예외 throw
C) null 반환
Q5. ...
### [테스트 전략] (2)
...
### [UI 동작] (3)
...
원칙
- 각 선택지에 Claude 추천 ★ — 사용자가 그대로 동의하면 빠른 결정, 다른 선택을 원하면 명확한 비교 기준 제공.
- 추천 근거를 한 줄로 명시 (AGENTS.md / 코드 컨벤션 / 영향 분석 등).
- 추천(★) 기준 — 근본 해결 우선: ★은 "가장 쉽게·빨리 끝나는 선택지"가 아니라 문제를 근본적으로 해결하는 선택지에 준다(절대 규칙 3 "근본 해결"과 정합 — 증상 우회·임시방편은 구현이 간단해도 추천하지 않는다). 구현이 다소 복잡해도 근본 해결안이 있으면 그것을 추천하고, 복잡도·작업량 차이는 추천 근거에 트레이드오프로 함께 명시해 사용자가 비교할 수 있게 한다(예: "★ B — 근본 해결(원인 제거), 단 파일 3개 수정 / A는 1줄이지만 증상 우회라 재발 여지"). 단 단순함 자체가 근본 해결인 경우(YAGNI — 불필요한 구조 제거·과설계 회피)는 그 단순안이 곧 근본 해결안이다 — 복잡한 안을 기계적으로 선호하라는 뜻이 아니다.
- 질문 유형에 맞는 선택지 형식을 쓴다 (중요):
- 택1 질문(명명·에러 처리·패턴 선택 등 서로 배타적): A/B/C 중 하나를 고르는 형식.
- 범위·대상 질문(여러 항목 중 무엇을 포함할지): 고정 조합(a만/a+b/모두)만 제시하면 원하는 조합(a+c 등)이 없어 막힌다 — 개별 항목을 나열하고 자유 조합·선택하게 한다(각 항목 영향·근거 한 줄 + 추천 조합 ★). "원하는 것만 지정 가능(예: 'a와 c만')"과 "하나도 적용 안 함"도 항상 유효를 명시한다(이번 요청은 별도 진행되므로 확장 전부 거절도 막히지 않음). 기록 형식은
references/decision-points.md D2(자유 조합) 정본.
- 라운드 반복 가능 (통상 3-5 이내). 5 라운드 초과면 plan 자체가 너무 모호 → 사용자에게 작업 범위 재확인 권고. (라운드·"답변 시간 < 재작업 시간" 원칙은 절대 규칙 4.)
Step 9. 리뷰 게이트 (subagent 필수)
Open Questions가 모두 해소돼 plan이 완성된 뒤 검토한다. plan-reviewer subagent 호출. 자체 검토 금지.
- 예외 (Type A/B만으로 구성된 plan): plan의 모든 task가 Type A(Doc/Config) 또는 B(Trivial Code)뿐이면 — 적대적 plan-reviewer(Opus) 대신 메인이 자체 체크리스트 검토로 대체할 수 있다(문서 끝
## 통과 체크리스트를 메인이 직접 대조). Type A/B는 cross-file·시그니처 변경이 없어 plan-reviewer의 핵심 항목(3 Impact·9 Autonomous)이 얕게 적용되므로, Opus 호출 비용이 검증 가치를 넘는다. 단 Type C/D가 하나라도 있으면 plan-reviewer 필수(대체 불가). 자체 검토로 대체한 경우 그 사실을 사용자 승인 프롬프트에 1줄 명시한다.
- 결과가 BLOCKER 또는 MAJOR면 plan 수정 후 재호출 (최대 3회).
- incomplete·미검증 잔여분은 통과가 아니다. plan-reviewer 결과에
incomplete(turn 소진), "심볼 N개 미검증"(항목 3 grep 상한), "항목 미검토"(항목 우선순위) 표시가 있으면 — BLOCKER/MAJOR가 0이어도 그 리뷰를 통과(OK)로 보지 않는다. 메인이 잔여분을 직접 검증하거나(미검증 심볼은 grep으로 호출자를 직접 대조, 미검토 항목은 그 항목의 판정 기준을 체크리스트로 직접 대조해 결과를 남김) plan-reviewer를 재호출해 나머지를 마저 검토한 뒤에만 통과한다. 잔여분을 조용히 흘려보내고 Step 10으로 넘어가는 것은 금지 — reviewer가 정직하게 보고한 미검증분을 소비하지 않으면 보고 의무가 무의미해진다(implement-task V-5의 incomplete 처리와 동일 원칙). 단 위 Type A/B 자체 검토 대체 경로는 메인이 체크리스트 전 항목을 완주하므로 이 규정의 대상이 아니다.
- 3회 후에도 BLOCKER/MAJOR가 잔존하면 → 사용자에게 에스컬레이션(plan-reviewer의
RECURRING — escalate to user 표시를 받아 그대로 보고): 무엇이 왜 3회 반복됐는지 + 선택지(수정 방향 승인 / 범위 축소 / 직접 지침)를 제시하고 지시를 기다린다. 자동 통과·무한 재시도 금지 — plan을 통과시키지 못한 채 implement-task로 넘어가지 않는다(교착 방지: 종결은 통과 아니면 에스컬레이션 둘 중 하나).
- 리뷰 중 새 질문이 드러나면 Step 8(Open Questions)로 돌아가 해소한 뒤 다시 리뷰한다.
- 통과 후에만 다음 단계.
- 과부하(529) 시:
plan-reviewer는 Opus라 과부하가 잦을 수 있다. implement-task의 "Reviewer 과부하(529) 대응" 규칙을 따른다 — 재시도 후 계속 실패하면 Sonnet 대체 실행 + "검증 깊이 저하 가능" 명시.
Step 10. 사용자 승인 게이트
ExitPlanMode로 plan.md 제시. 승인 시 implement-task 호출. 제시 전에 문서 끝 ## 통과 체크리스트를 먼저 대조한다 — 체크리스트는 승인 후가 아니라 승인 요청 전 게이트다.
승인 프롬프트에 plan 요약을 반드시 포함한다 — 사용자가 plan.md 파일을 열지 않고도 판단할 수 있게:
- 요구 이해 — plan의
## 요구 이해(원문 인용 + 이해 3~5줄)를 최상단에 그대로 노출. 요구 오해는 사용자만 판정할 수 있으므로 승인 판단의 첫 항목이다 (여기서 어긋나면 아래 task가 전부 맞아도 무의미).
- Goal 1~2줄
- task 요약 표 (전 task):
| T# | Type | 내용 한 줄 | 주요 파일·범위 |
- Deferred / Follow-up · Out of Scope 요지 (있으면)
- 사전 승인 항목·불가피한 Halt (아래 규정)
"상세는 plan.md 참조"로 요약을 대체하지 않는다 — 승인 판단에 파일 열람을 요구하는 것 자체가 승인 마찰이다. plan.md는 실행용 정본, 승인 프롬프트의 요약은 판단용이다.
plan에 ## 사전 승인 항목 (일괄 승인 대상)이 비어 있지 않으면, 승인 프롬프트에 그 목록을 그대로 나열하고 "이 plan 승인은 아래 사전 승인 항목의 일괄 위임을 포함합니다 — 자율 루프가 그 지점에서 멈추지 않습니다"를 명시한다. 사용자가 plan을 승인하면 그 항목들은 일괄 승인된 것으로 본다(implement-task가 Phase 0에서 인정).
이 승인은 plan 실행(구현) 승인이다 — ## 불가피한 Halt (위임 불가)의 항목(push·main 병합·태그·릴리즈·PR·파괴적 작업·인증정보 필요 신규 외부 서비스·돌발 결정)은 이 승인에 포함하지 않으며, 각 지점에서 그 행위를 이름으로 적어 따로 승인받는다 (implement-task 절대 규칙 12). push·릴리즈 등은 구현·검증 완료 후 implement-task 최종 보고에서 별도로 받는다.
승인 직후 결정 큐잉: plan의 기능 단위 채택 결정·## Deferred / Follow-up(보류)·## Out of Scope(기각)를 pjc:llm-wiki 절차 K 5-2의 [DECISION] 큐에 항목별 1줄로 기록한다(vault 없으면 그 규약의 폴백, 구현 세부 결정은 제외 — 입도 기준은 K 5-2 정본) — 다음 계획 때 위키 조회로 회수된다. 같은 시점에 계획 중 확인된 작업 규약·함정 사실(레포에 안 담는 크로스 세션 지식)은 [PROJECT-FACT] 큐에 기록한다(형식·입도는 절차 K 5-3 정본 — 배치 트리거 ① plan 승인).
통과 체크리스트
다음을 모두 만족해야 implement-task로 넘어갈 수 있다:
참조 문서
- Decision Points 상세:
references/decision-points.md
- Edge Cases + Halt Forecast:
references/edge-cases.md
- plan.md 템플릿:
references/plan-template.md
- PRD 템플릿 (대규모 작업, Step 0.5):
references/prd-template.md
