---
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」或「要修改」

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

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

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

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

還沒有 git repo 時，先只寫文件，做到文件寫好為止；S1 的第一個小任務負責 `git init`，
這份文件與指路跟它一起 commit，S1 的 `--start-segment` 在 `git init` 之後跑。

完成條件：步驟 4 講好要換的舊紀錄都換好了；`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`，commits 欄先填 `<起點>..`（短 SHA；起點是空樹時填它印出的完整 SHA）；該段有「開工前提」就先查完，結果寫進段落明細。這些改動跟第一個小任務的 commit 一起送
- 每個小任務：實作、驗證、commit，訊息結尾帶編號（例如 `（S2-1）`）。可用 `SKIP_DOC_CHECK=1` 先跳過 CLAUDE.md 檢查，gate 會記帳
- 小任務 commit 了不等於段落完成。小任務全部 commit 完，而且 SKIP 欠下的 CLAUDE.md 都補上了（最後一個小任務用正常 commit，被 gate 擋就照訊息補），才對整段跑步驟 3–8。範圍從表上這段的起點算。步驟 6、7、8 的 commit 訊息結尾帶段落編號（例如 `（S2）`）
- 標 `DONE`：步驟 3–8 全部跑完才標；commits 欄補上終點（標 `DONE` 之前最後一個 commit 的短 SHA），跟步驟 7、8 的 commit 一起送，7、8 都沒改檔就單獨開一個 docs commit。最後一段標 `DONE` 的同一個 commit，刪掉根目錄 CLAUDE.md 的指路那行
- 接手：`IN_PROGRESS` 那段就是目前這段。`git log --oneline` 找結尾帶 `（S2-` 的 commit，看做完哪幾個小任務；已經有帶 `（S2）` 的 commit，代表步驟 6 之後的步驟做到一半，沒有就從步驟 3 開始
- `BLOCKED` 只用在外部卡住（等使用者決定、環境壞了）：同一格寫原因，停下來問使用者。使用者要先做別段時，先用正常 commit 補完這段 SKIP 欠下的 CLAUDE.md（不然 `--start-segment` 會拒絕）；回頭做這段時，範圍一樣從表上這段的起點算。依賴還沒完成的段落維持 `TODO`
- 做到一半冒出新工作：先問使用者，同意才加一列 `TODO` 排進該在的位置；ID 不重編，插在中間用 `S2.5`
- 每列一行，細節寫進 commit 訊息
```