---
name: plan-generator
description: 요구·설계·현재 상태를 기능 단위 태스크와 작은 phase로 나눠 plan_setup/에 계획·상태·기록을 만들거나 갱신한다. 기존 ID와 완료·진행 이력을 보존한다.
---

# 기능 단위 계획

## 목적과 입력

`docs/PRD.md`·`docs/TRD.md`·관련 `docs/ARCHITECTURE/`·코드와 기존 `plan_setup/`을 읽는다.
요구·기술·구조·자율운영 합의를 재사용한다. 부족한 결정은 필요한 앞 문서(IDEA 포함)부터 영향 부분만 보완하고 근거·현재 기준 포인터를 남긴다. 범위·수용 기준·사용자 제약 변경은 결정 전까지 기존 기준을 유지하고 사용자에게 묻는다. Loop 이후에는 묻지 않고 영향 작업만 차단한다.
새 세션은 `loop_setup/LOOP.md`와 `plan_setup/STATE.md`의 합의·재개 지점도 이어받는다.

## 최소 산출물과 경로

- `plan_setup/PLAN.md`: phase/태스크 색인·필요한 의존·완료 목표와 요구 연결
- `plan_setup/phase-NN/phase-NN-<이름>.md`: 묶음 목표·수용 기준·태스크 링크
- `plan_setup/phase-NN/phase-NN-tasks/phase-NN-task-MM.md`: 실제 작업
- `plan_setup/STATE.md`: 현재 작업·차단·다음 행동·합의 참조·잔여 예산·재개 지점
- `plan_setup/LOG.md`: 중요한 변경·판정 증거를 덧붙이는 기록

작은 프로젝트는 phase 하나와 소수 기능 태스크면 충분하다. 빈 절과 반복 표를 만들지 않는다.
기존 PRD 추적표가 있으면 해당 담당 태스크·계획 상태만 맞춘다. 동일 추적표를 문서마다 반복하지 않는다.

## 작업 단위

태스크는 실행으로 확인할 수 있는 기능 또는 독립 위험 해소 단위다.
UI·API·DB·테스트 여러 파일을 함께 바꿀 수 있다. 파일/계층마다 쪼개거나 매 태스크 새 세션을 강제하지 않는다.
기존 구현은 재구현 대상으로 만들지 않는다. 필요한 검증·변경 범위만 계획한다.
각 태스크에 목표·범위·관련 FR/NFR/TD·설계 절 링크를 짧게 적고 다음 frontmatter를 둔다.

```yaml
---
id: phase-01-task-01
status: pending
depends_on: []
acceptance_criteria:
  - 항목을 등록한 뒤 새로고침해도 입력한 값이 목록에 남는다
  - 필수 값을 비워 등록하면 오류가 보이고 항목이 추가되지 않는다
verification: [lint, unit, e2e, task_validation]
---
```

필수 키는 `id`·`status`·`depends_on`·`acceptance_criteria`·`verification`이다.
`id`는 확장자를 뺀 파일명과 같고 상태는 `pending/in_progress/blocked/failed/completed`를 쓴다.
`files`·`architecture`·`blocked_by` 등 기존 필드는 필요하면 유지/사용한다. `phase`는 쓴다면 `"01"` 같은 문자열이다.
`files`는 예상 범위이며 합의 안의 관련 파일 추가는 이유와 함께 반영한다.
제품 Loop 태스크의 기본 verification은 위 네 게이트이며 판정은 `lint → unit → e2e → task_validation` 순서다.
`harness_setup/quality_gates/`와 `harness_setup/HARNESS.md`의 대상·명령/관찰·통과 조건·활성 범위를 참조한다.
앞 실패를 복구하기 전 뒤 완료 판정을 하지 않는다. 같은 코드 상태의 태스크를 묶거나 유효한 결과를 재사용할 때는
코드·범위·환경/데이터 조건의 유효 근거와 태스크별 수용 기준 대응을 남긴다. 변경으로 무효화된 판정은 다시 확인한다.
초기 준비의 미활성은 PASS가 아니다. 준비 수용 증거와 후속 활성 담당/태스크를 연결하고 제품 검증과 구분한다.
문서·계획만 요청에는 제품 네 게이트 실행을 강제하지 않는다. 사용자 명시 기본값 변경·자식 실행 금지를 우선하며
달라진 보장과 미검증을 기록한다. 구체 활성·독립 관찰 절차는 Harness, 실제 실행 준비·운용은 Loop에 연결한다.
task_validation은 해당 변경을 구현하지 않은 비상속 별도 세션에 요구·수용 기준·필요 설계·실행/접속·
코드 식별·허용 데이터·잔여 예산을 인계한다. 구현 대화·추론·자체 통과 결론을 상속하거나 같은 세션에서 역할만 바꾼
판정을 독립 검증으로 세지 않는다. 검증자는 제품·기준·통과 단언을 수정하지 않고 기준별 관찰 증거를 반환한다.

새 시각 방향은 PRD의 미리보기·사용자 확정을 본격적인 화면 구현·관련 Loop의 선행 조건으로 두며 미확정 UI 작업은 차단해 계획한다.
화면·공유 구성 요소의 구현 담당과 시각 수용 기준은 디자인 정본의 승인 버전·범위에 연결한다. 승인 재사용·시각 보존·문서만 요청의 범위는 PRD를 따른다.

## 의존·차단·완료

- 실제 선행 결과가 필요한 의존만 둔다. 참조가 존재하고 순환과 역방향 phase 의존이 없는지 확인한다.
- 독립·준비된 작업은 병렬 기본으로 계획한다. 검증된 선행·단독 소유권·실제 파일/DB/포트/앱 충돌·자원·전체 예산을
  확인하고 충돌 작업만 격리/직렬화한다. 워커 수와 무거운 작업 동시 상한을 구분하고 필요하면 동시 수를 1로 줄인다.
  실제 배정·자원 제어는 Loop가 맡으며 계획만 요청받았다면 자식을 실행하지 않는다.
- 미해소 OQ/CF·권한·입력 때문에 기준을 확정하거나 검증할 수 없으면 `blocked`와 원인·해소 조건을 남긴다.
  관련 의존 작업도 실행 불가로 드러내되 독립 작업은 계속 가능하게 둔다.
- 사실 확인·실험은 입력·관찰값·판정 기준이 있는 위험 해소 태스크로 만든다. 모르는 사실을 사용자에게 추측하게 하지 않는다.
- 기준은 실제 화면·응답·저장값·CLI 결과로 판정하고 중요한 실패 경로를 포함한다.
  코드 작성·종료 코드 0·검사 0건·전부 skip·미실행을 기능 완료 증거로 쓰지 않는다.
  검증 전에는 묶음 대상도 `completed`로 쓰거나 후행의 완료 선행으로 사용하지 않는다.
- phase/프로젝트는 소속 작업의 실제 완료와 묶음 기준으로 판정한다. 차단·실패·미검증을 성공으로 합산하지 않는다.

## 상태 보존과 갱신

태스크 상태가 완료 판정의 정본이고 STATE는 중단 뒤 재개 기록이다. 생성만 했다면 새 태스크는 pending 또는 blocked다.
시작·중요 전이·종료 시 둘을 맞추고 LOG에 실제 변경·검증·복구 근거를 증분 저장한다. 계획만으로 완료 이력을 만들지 않는다.
STATE에는 현재 단계·실행 주체/작업 폴더·확정/미결·마지막 검증·미반영 결과·다음 행동과 누적 시도/예산 참조를 둔다.
LOG에는 실패 관찰·가설·분석 전환·새 전략과 증거를 이어 쓴다. 같은 방식 3회 이내의 자율 분석·전략 전환은
Loop 절차에 연결하며 포기/질문 기준으로 삼지 않고 누적 이력과 전체 예산을 유지한다.
원 대화 없는 재개는 LOOP/STATE·관련 기록을 실제 코드·미커밋 변경·살아 있는 실행과 대조한 다음 행동부터 잇는다.
기존 12필드·추적표·STATE 형식·Retry·Standing Decisions를 읽고 형식 전환을 선행 조건으로 삼지 않는다.
기존 ID·상태·사용자 수정·로그·재시도 이력을 보존한다. 완료 태스크 과거 기준을 덮지 않고 후속 작업을 만든다.
새 태스크는 해당 phase 끝번호, 새 phase는 전체 끝번호에 붙인다. 완료 phase를 다시 열어 추가하지 않는다.
유효한 범위 결정으로 정식 폐기한 태스크는 파일·ID·근거·이력을 남기고 색인·의존을 맞춘 뒤 phase/프로젝트 집계 대상에서 제외한다.
기존 `blocked_by: [폐기]`도 폐기 기록으로 읽으며 PASS나 완료로 세지 않는다. 실패·차단·미검증을 완료를 위해 임의 폐기하거나 집계에서 빼지 않는다.
변경 후 영향 문서와 링크만 맞춘다. 공유 상태는 필자 하나가 갱신하고 실행 중이면 안전한 경계에서 반영한다.
루트 지침은 필요한 문서 포인터만 보완한다.

## 완료 증거와 연결

YAML을 파싱해 필수 키·파일명/ID·상태를 검사하고 색인·링크·의존 순환·요구 누락·차단 전파를 확인한다.
신규 계획과 실제 실행을 구분해 변경 태스크·검사 결과·미완료/재개 지점을 보고한다.
계획만 요청되면 그 범위로 끝내고 다음 스킬을 제안한다. 다음 단계는 `harness-setup`/`harness-update`다.
단계를 마치면 결과(요약·주요 결정·가정·남은 결정)를 보고하고 다음 스킬로 이어 진행할지 사용자에게 확인한다. 수정 요청은 반영해 다시 보고한다. Loop 실행 전까지 모든 단계에 적용하며, 사용자가 자기 말로 단계별 확인 생략을 지시했을 때만 확인 없이 이어 간다. '만들어줘'·'끝까지'나 사전 권한·예산 합의만으로는 생략하지 않고, 에이전트는 확인 생략이나 자동 진행을 먼저 권하거나 추천하거나 생략 방법을 안내하지 않으며, 그렇게 받은 선택도 근거가 아니다. 진행이 확인되면 실행을 사용자에게 떠넘기지 않는다.
이미 합의한 내용을 다시 승인받거나 승인된 실행의 명령·새 세션을 사용자에게 요구하지 않는다.
Loop 이후 복구 불가이면 독립 작업을 마치고 변경·실패 증거·재개 조건을 보존한 미완료 결과로 종료한다.

## 환경 참고

도구 차이가 필요할 때만 [Claude Code](references/claude-code.md) 또는 [Codex](references/codex.md)를 읽는다.