plan-task git:20260928.21afea3A

Immutable. This exact content never changes and is served at /api/v1/blob/b2ad33300ab35f77.

---
name: plan-task
description: Structured task planning into a plan file. Use for any new feature, bug fix, or project that needs a task breakdown before implementation.
---

# Plan-Task 스킬

## 사용법

```
/plan-task 로그인 기능 추가                       # 새 요청
/plan-task fix the auth bug                      # 새 요청 (description 형식)
/plan-task docs/plans/2026-09-28-login-lockout   # 기존 계획 재개 (디렉토리 또는 그 plan.md)
```

## Phase Gate

`brainstorming`(설계 승인)은 **설계가 필요한 Large 새 기능**에만 선행한다 — 크기 기준은
아래 Step 1-1 과 같다. 그런 작업인데 `docs/specs/`에 관련 스펙이 없으면 먼저 `brainstorming`
을 invoke 한다. 버그 수정·Small·Medium 은 바로 진행한다(건너뛴 사실만 한 줄 적는다).

---

요구사항을 명확히 하고 구현 계획을 세운다. Medium/Large 면 결과를 **계획 파일**에 남긴다 —
규약(위치·frontmatter·절 순서) SSOT: `references/plan-format.md`.

**영속 상태는 `plan.md`(와 실행 단계의 checklist)다.** 호스트 태스크 도구는 진행 추적에만
쓴다 — 세션 스코프이거나(Claude Code) 아예 없는(Codex 등) 하네스가 있어서 세션을 넘지 못한다.

---

## Step 0: 진입 [건너뛰기 금지]

1. 호스트 태스크 도구가 있으면 로드한다(Claude Code: `ToolSearch("select:TaskCreate,TaskUpdate,TaskList")`).

   > **Task 도구가 없으면 멈추지 말고 대체 경로로 간다** — `plan-task/references/task-tools-fallback.md`
   > 의 대체 경로로 추적한다.

   이미 `[Planning]` Task 가 있으면 생성을 건너뛴다. 없으면:

   ```
   T1: [Planning] 요구사항 명확화
   T2: [Planning] 구현 계획 수립   ← blockedBy T1
   ```

2. **기존 계획 경로가 주어졌으면** 그 `plan.md` 를 읽고 `status` 와 비어 있는 절을 보고
   중단된 지점부터 재개한다. `status: done` 이면 재개하지 않고 사용자에게 알린다.

3. **새 요청이면** 아직 파일을 만들지 않는다 — 규모 판정(Step 1-1) 후에 만든다.

---

## Step 1: T1 — 요구사항 명확화

`clarify-requirements` 에이전트에 위임하거나 직접 진행.

> **절차 SSOT: `references/elicitation.md`** — 규모가 Medium 이상이면 **읽고 시작한다.**
> 등급 체계만으로는 *"딱히 모호한 게 없었다"* 로 끝나고, 못 찾은 모호함은 사라지지 않고
> 구현 중 추측으로 메워진다.

1. **규모 판단** (`references/elicitation.md` §6 이 기준을 소유한다):
   Small 1모듈·1-3파일 / Medium 2-3모듈·4-10파일 / Large 4모듈+·10파일+.

   **Medium/Large 면 지금 계획 파일을 만든다**: `docs/plans/<오늘 YYYY-MM-DD>-<slug>/plan.md`
   (이름이 있으면 `-2`, `-3`). frontmatter 는 `status: planning` 과 판정한 `size`,
   본문은 `plan-format.md` 의 절 머리만 둔다(`## 검증 결과` 제외). **Small 은 파일 없이** 진행한다.

2. **자격 인벤토리** (Large 필수 · Medium 권장 — `elicitation.md` §0):
   확보된 권한을 세고 그 경계를 **이번 범위선**으로 삼는다. 미확보 항목은 기다리지 말고
   mock/adapter 로 처리한다. 이 인벤토리가 그대로 **위임 브리프의 금지사항**이 된다.

3. **모호함 탐색** — 감지되기를 기다리지 않고 네 자리를 훑는다 (`elicitation.md` §2):
   상태 전이가 갈라지는 지점 · 두 규칙이 동시 적용되는 지점 · 부등호의 등호 포함 여부 ·
   실패 후 롤백 범위. **하나도 안 나왔다면 훑지 않은 것이다** — 어디를 봤는지 기록한다.

   **구현 결과를 바꾸는 것만 묻는다.** 조사로 채울 수 있는 값은 묻지 말고
   `[researched: 출처, n]` 으로 채운 뒤 검토만 요청한다. 한 번에 5개 이하로 묶는다.

4. **P0 모호함 해결**: P0 발견 시 즉시 중단 → 사용자에게 질문.
   P1~P3 는 등급대로 처리하고 멈추지 않는다. P0 의 답은 근거와 함께 `## 결정` 에 적는다.

   ```
   맥락: [상황]   질문: [구체적 질문]
   옵션: 1. [A]   2. [B]
   ```

5. **요구사항 정리**: 핵심 요구사항, 영향 범위, 리스크.
   **모든 값에 출처 태그**(`[confirmed]` / `[researched: 출처, n]` / `[unresolved]`)를
   붙인다. 상충은 고르지 말고 상충 사실을 기록해 설정값으로 위임한다.
   정책값(임계값·상한·기간·비율)은 산문에서 빼내 한 곳에 모은다 — **산문에 숫자가 남아
   있으면 미완성**이다.

6. **기록** (계획 파일이 있을 때): 결과를 `## 요구사항`, P0 결정을 `## 결정` 에 쓴다.
   brainstorming 스펙(`docs/specs/…`)이 있으면 `## 요구사항` 첫 줄에 그 경로를 적는다.

7. T1 완료 마킹(호스트 태스크 도구가 있으면 `TaskUpdate(T1, status="completed")`)

---

## Step 2: T2 — 구현 계획 수립

`plan-implementation` 에이전트에 위임하거나 직접 진행:

1. T1 결과(`## 요구사항`·`## 결정`) 기반으로 구현 계획 작성
2. 규모별 추가 단계 (`references/elicitation.md` §6):
   - Medium+: 사용자 여정 설계 포함
   - Large+: 비즈니스 로직 정의 포함
3. 구현 순서, 의존성, 예상 범위 명시

4. **완료 조건을 실행 가능한 명령으로 쓴다** [건너뛰기 금지] (`references/elicitation.md` §5):
   각 단계의 완료 조건은 **종료코드로 판정되는 명령**이어야 한다.

   ```
   ✗ 로그인이 정상 동작한다
   ✓ pytest tests/test_auth.py -q     (exit 0)
   ```

   판정이 stdout 에 있는 검증(조회 성공만으로 exit 0 이 되는 명령)은 게이트가 아니다.
   비결정적 산출물이 섞이면 조건을 둘로 나눈다 — 결정적 부분만 통과/실패로, 나머지는
   고정 평가셋과 임계값으로. **금지 행위 위반은 임계값이 아니라 0이다.**

5. **기록** (계획 파일이 있을 때): `## 구현 계획` 과 `## 완료 조건` 을 채운다.

6. T2 완료 마킹

---

## Step 3: Planning 완료 처리

0. **[건너뛰기 금지]** auto-dev invoke(핸드오프) **전에** 이 계획의 `[Planning]`/`[Brainstorm]` 중
   "끝났는데 마킹 안 된" 태스크를 completed로 정리한다
   (규율 SSOT: `rules/definition-of-done.md#task-마감-규율`).
1. 계획 파일이 있으면 네 절이 채워졌는지 확인하고 frontmatter `status: in-progress` 로 바꾼다.
   Small 이면 요구사항·계획·완료 조건을 대화창에 출력한다.
2. 다음 단계:

Planning이 완료되었습니다. 바로 개발을 시작하겠습니다.

`auto-dev` 스킬을 즉시 invoke합니다 — 계획 디렉토리를 인자로 넘긴다(Small 은 인자 없이,
대화창의 계획으로). 사용자가 "나중에" 또는 "직접 실행"을 원하면 아래 명령을 안내하고 invoke를 건너뜁니다.

```
/auto-dev docs/plans/<YYYY-MM-DD>-<slug>
```

---

## 참고 문서

이 스킬 디렉토리 기준 경로다(소비자 프로젝트 cwd 기준이 아니다):
계획 파일 규약 `references/plan-format.md` · 요구사항 정련 절차 `references/elicitation.md` ·
Planning 프로토콜은 규범 `planning-protocol`(세션 주입).