---
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、開頁面看）：只用這種時，寫出為什麼比寫測試合適（例如前端沒有測試框架、行為零改動）

設計細節用章節名（或表格那一列）指回原文，不重抄；來源是口頭描述的，細節寫進「假設」。
開工前得先查清楚的事（外部 API 文件、舊實作的算法），寫成該段的「開工前提」，不列成小任務。

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

### 4. 給使用者批准

在對話裡列出：進度表草稿、每段的小任務、**要新增的測試清單**、假設。
專案裡已經在記進度的地方也列出來，說明打算怎麼換：舊的段落表、「進度以…為準」的句子、專案狀態檔（例如記著目前做到哪的 `PROJECT_STATE.md`）、CLAUDE.md 開頭的進度欄（例如 `**進度**: 段落 1–11 完成`），以及描述這些紀錄用途的句子。

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

- 決策題：換個答案，段落、範圍、對外介面（API 形狀、畫面）或舊紀錄的換法就會不同的；還有碰到步驟 2 那些高風險工作、來源又有兩種讀法的（例如月中入住的第一個月按日還是整月算）。每題附建議答案，其他假設列在草稿裡，跟批准題一起批
- 批准題：「批准：寫進設計文件並 commit」或「要修改」

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

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

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

- 已有設計文件：在標題與開頭說明之後、第一個 `##` 之前加 `## 進度表`；文件末尾加 `## 段落與小任務`，開頭寫假設、結尾附批准的測試清單。
  文件裡已經有本 skill 產的進度表時，新段落接在同一張表後面，不另開一張
- 沒有設計文件：建 `docs/designs/YYYY-MM-DD-<topic>-design.md`，寫四節：來源、假設、進度表、段落與小任務（結尾附測試清單）
- 步驟 4 列出的舊進度紀錄，照講好的方式換掉，不留兩份各說各話的進度；小任務指回去的內容留著
- 專案根目錄 CLAUDE.md 第一個 `##` 之前加一段指路，前後各空一行（不空行會併進上一段或引用區塊）：
  `進度以 docs/designs/<檔名>.md 的「進度表」為準：開工先讀表，照表下方的規則做。`
  原本指向設計文件的連結留著；連結旁邊的舊進度宣告，照步驟 4 講好的換
- 專案 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；回頭做 `BLOCKED` 過的段落時，欄裡原本的起點保留不改）；該段有「開工前提」就先查完，結果寫進「段落與小任務」該段底下。這些改動跟第一個小任務的 commit 一起送
- 每個小任務：照「段落與小任務」列的做，實作、驗證、commit，commit 訊息第一行結尾帶編號（例如 `（S2-1）`）。可用 `SKIP_DOC_CHECK=1` 先跳過 CLAUDE.md 檢查，gate 會記帳。測試照文件裡的測試清單加；想加清單以外的測試，先問使用者
- 小任務 commit 了不等於段落完成。小任務全部 commit 完，而且 SKIP 欠下的 CLAUDE.md 都補上了，才對整段跑步驟 3–8，範圍從表上這段的起點算。最後一個小任務用正常 commit；補 SKIP 改過的目錄的 CLAUDE.md 時，用 `git diff <起點> -- <目錄>` 看整段改了什麼，不要只看這次 staged 的（gate 只查 CLAUDE.md 有沒有一起送，不查寫了什麼）。步驟 6、7、8 的 commit 訊息第一行結尾帶段落編號（例如 `（S2）`）
- 標 `DONE`：步驟 3–8 全部跑完才標；commits 欄補上終點（標 `DONE` 之前最後一個 commit 的短 SHA，所以標 `DONE` 的 commit 自己不在範圍內），跟步驟 7、8 的 commit 一起送，7、8 都沒改檔就單獨開一個 docs commit。標到表上每段都 `DONE` 的那個 commit，刪掉根目錄 CLAUDE.md 的指路那段
- 接手：`IN_PROGRESS` 那段就是目前這段。拿「段落與小任務」的清單對 `git log --oneline <表上這段的起點>..HEAD` 裡結尾帶 `（S2-` 的 commit（不加範圍會對到別份文件的同編號 commit），還沒 commit 的小任務先做完。小任務都做完了，再看同一範圍裡有沒有帶 `（S2）` 的 commit：有，代表步驟 6 之後的步驟做到一半；沒有就從步驟 3 開始
- `BLOCKED` 用在這段要先停：外部卡住（等使用者決定、環境壞了），或使用者要先做別的事（別段、臨時修 bug）。狀態格寫 `BLOCKED` 和原因，外部卡住時停下來問使用者。先停之前，用正常 commit 補完這段 SKIP 欠下的 CLAUDE.md（不然 `--start-segment` 會拒絕）；回頭做這段時，範圍一樣從表上這段的起點算。依賴還沒完成的段落維持 `TODO`
- 做到一半冒出新工作：先問使用者，同意才加一列 `TODO` 排進該在的位置；ID 不重編，插在中間用 `S2.5`
- 每列一行，細節寫進 commit 訊息
```