---
name: task-planner
description: 功能段落規劃：把工作拆成依序執行的功能段落（段落內再列小任務），進度表寫進設計文件。當提到任務拆解、微任務、task breakdown、工作分解時啟用；或動手前判斷出這件工作要跨多輪 8 步開發迴圈（多個功能段落）才做得完時主動啟用。一輪迴圈內做得完的工作不啟用。
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, AskUserQuestion
---

# Task Planner — 功能段落規劃

把一件要跨好幾輪 8 步開發迴圈的工作，拆成**段落**（`S1`、`S2`…）與段落裡的**小任務**（`S2-1`、`S2-2`…），
進度表寫進設計文件。換 session、`/compact` 之後，照表就知道做到哪、下一段是哪段。

## 段落與小任務

| 層 | 做法 | 完成條件 |
|---|---|---|
| 小任務 `S2-1` | 實作、驗證、commit（迴圈的步驟 1、2） | 驗證通過且已 commit |
| 段落 `S2` | 小任務全部完成後，整段跑一次步驟 3–8 | 步驟 3–8 全部跑完，才標 `DONE` |

小任務 commit 了，只代表那個小任務完成；段落還差整段的步驟 3–8。

```
S2 租金產生
├── S2-1 DB schema：實作、驗證、commit
├── S2-2 service：實作、驗證、commit
└── S2-3 API：實作、驗證、commit
    ↓ 小任務全部 commit 完
S2 整段跑步驟 3–8
    ↓
S2 = DONE
```

## 步驟

### 1. 讀來源

依序找，存在的才讀：

1. 使用者指定的設計文件（`docs/designs/*.md`，design-brainstorm 的產物）
2. issue、規格或使用者口頭描述

相關的既有程式碼、目錄結構、git 歷史自己查。

完成條件：列出「要做的項目」清單——口頭需求逐句拆開、設計文件逐個模組／端點／元件，加上會被改到的既有程式。

### 2. 切段落

- 段落照功能切：一段做完一個步驟 5 驗得到的功能（打得到的 API、點得到的頁面、跑得出結果的指令）
- 寫入金額或帳款狀態、改變權限規則、刪除資料的工作，不跟其他功能混在同一段，讓 review 專心看它；只是沿用既有的權限檢查不算。它單獨驗不到時，只帶上讓它驗得到的最少工作一起成段
- 被依賴的段落排前面，依賴只標在段落層級；表格由上往下就是執行順序

完成條件：清單每一項都放進了某一段；每段都寫得出「步驟 5 要看到什麼」；依賴沒有繞圈，第一段沒有依賴。

### 3. 列小任務

每段拆成小任務，編號 `S<段>-<序>`，照資料模型、服務、API、前端的先後排。
一個小任務的大小以「一次 commit 看得懂」為準（一個 migration、一個服務、一種資源的 API、一個頁面）。每個小任務寫：

- 動詞開頭的名稱、要動的檔案路徑、commit 訊息（結尾帶編號，例如 `feat: 新增租金產生（S2-1）`）
- **驗證方式**，二選一：
  - 用測試驗：先寫會失敗的測試，寫明測試檔、測什麼、跑哪個指令
  - 用其他方式驗（lint、tsc、curl 打真實 API、開頁面看）：寫出為什麼這樣比寫測試合適（例如專案規定走真 HTTP、前端沒有測試框架、行為零改動）

設計細節用章節名指回原文，不重抄。開工前得先查清楚的事（外部 API 文件、舊實作的算法），寫成該段的「開工前提」，不列成小任務。

完成條件：每個小任務都有檔案路徑、驗證方式、commit 訊息；所有要新增的測試整理成一份清單。

### 4. 給使用者批准

在對話裡列出：進度表草稿、每段的小任務、**要新增的測試清單**、假設。
專案裡已經在記進度的地方（舊的段落表、「進度以…為準」的句子、專案狀態檔）也列出來，說明打算怎麼換。

用 AskUserQuestion 一次問完（最多 4 題）：

- 決策題：來源有多種讀法、或會改變段落與小任務內容的假設，每題附建議答案
- 批准題：「批准：寫進設計文件並 commit」或「要修改」

決策題選了非建議答案，就回步驟 2 重出草稿再問。
使用者批准的測試清單，就是使用者要求加的測試（全域 §3.5：不主動新增測試，使用者要求時例外）；實作時想加清單以外的測試，先問。

完成條件：使用者選了批准。

### 5. 寫進設計文件並 commit

- 已有設計文件：在標題與開頭說明之後、第一個 `##` 之前加 `## 進度表`；文件末尾加 `## 段落與小任務`，開頭寫假設、結尾附批准的測試清單
- 沒有設計文件：建 `docs/designs/YYYY-MM-DD-<topic>-design.md`，寫四節：來源、假設、進度表、段落與小任務（結尾附測試清單）
- 舊的進度紀錄照步驟 4 講好的方式換掉，不留兩份各說各話的進度
- 專案根目錄 CLAUDE.md 開頭的專案說明裡加一行指路：
  `進度以 docs/designs/<檔名>.md 的「進度表」為準：開工先讀表，照表下方的規則做。`
- 專案 CLAUDE.md 對新資料夾、新文件另有規定的（例如新資料夾要附 CLAUDE.md），照規定一起補
- commit：`docs: 新增<主題>的段落進度表`。還沒有 git repo 時先只寫文件，指路與這個 commit 跟 S1 的第一個 commit 一起送

完成條件：`git log -1` 看得到這個 commit，`git status` 沒有留下這次寫的檔。

## 進度表格式

照這個骨架寫進設計文件。規則區塊整段照抄：接手的 session 只讀文件、沒載入本 skill，也要照得做。

```markdown
## 進度表

| ID | 段落 | 狀態 | 依賴 | 驗收（步驟 5 要看到什麼） | commits |
|---|---|---|---|---|---|
| S1 | 帳號登入 | TODO | — | curl 登入拿到 token；密碼錯回 401 | |
| S2 | 租金產生 | TODO | S1 | 手動觸發 job 產生 1 筆；再觸發不重複 | |

- 狀態只有 `TODO`、`IN_PROGRESS`、`BLOCKED`、`DONE`；同一時間最多一段 `IN_PROGRESS`
- 下一段：由上往下第一個 `TODO`，而且它依賴的段落都已 `DONE`。有段落 `BLOCKED` 時先停下來問使用者，不自己跳去做別段
- 開工：`~/.claude/scripts/check-claude-md.sh --start-segment` 記起點，把這段標 `IN_PROGRESS`，跟第一個小任務的 commit 一起送
- 每個小任務：實作、驗證、commit，訊息結尾帶編號（例如 `（S2-1）`）。可用 `SKIP_DOC_CHECK=1` 先跳過 CLAUDE.md 檢查，gate 會記帳，之後的正常 commit 要補上
- 小任務 commit 了不等於段落完成：小任務全部 commit 完，才對整段跑步驟 3–8（範圍從起點算），全部跑完才標 `DONE`
- 標 `DONE`：commits 欄填 `<起點>..<標 DONE 之前最後一個 commit>` 的短 SHA（起點是空樹時只填後者），跟步驟 7、8 的 commit 一起送；7、8 都沒改檔就單獨開一個 docs commit。最後一段標 `DONE` 的同一個 commit，刪掉根目錄 CLAUDE.md 的指路那行
- 接手：`IN_PROGRESS` 那段就是目前這段；`git log --oneline` 找結尾帶 `（S2-` 的 commit，就知道做完哪幾個小任務
- `BLOCKED` 只用在外部卡住（等使用者決定、環境壞了）：同一格寫原因，停下來問使用者。依賴還沒完成的段落維持 `TODO`
- 做到一半冒出新工作：加一列 `TODO` 排進該在的位置；ID 不重編，插在中間用 `S2.5`
- 每列一行，細節寫進 commit 訊息
```