Task Planner — 功能段落規劃

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

段落與小任務

小任務 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 要看到什麼」；依賴沒有繞圈，第一段沒有依賴。 只切出 1 段就不往下走：告訴使用者一圈做得完、不用拆，照一般的 8 步迴圈做（它仍是全域 §4.1 的複雜任務，計畫先交 plan-review；來源是 design-brainstorm 已經走過 plan-review 的設計就不再另審）（沒有 task 工具時照全域 §4.4 記進度）。

3. 列小任務

每段拆成小任務，編號 S<段>-<序>，被依賴的先做（例如資料模型、服務、API 或排程、前端依序）。 一個小任務的大小以「一次 commit 看得懂」為準（一個 migration、一個服務、一種資源的 API、一個頁面）， 而且要能照專案的驗法單獨驗過；單獨驗不過的（例如專案不承認只跑單元測試），跟用到它的那層併成一個。每個小任務寫：

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

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

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

4. 送 plan-review，問決策題與測試清單

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

草稿出好先交 plan-review 審（上面列的東西就是要交的計畫全文），照它採納的意見改草稿。不再問使用者「批准嗎」。

plan-review 結束時用 AskUserQuestion 問兩種題，跟它交回的「需使用者決定」一起問（分批照 plan-review 的「問使用者的分批」；同一件事只問一次）：

• 決策題：換個答案，段落、範圍、對外介面（API 形狀、畫面）或舊紀錄的換法就會不同的；還有碰到步驟 2 那些高風險工作、來源又有兩種讀法的（例如月中入住的第一個月按日還是整月算）。每題附建議答案，其他假設列在草稿裡
• 測試清單題：附上清單，選項「照這份清單加」或「要修改」

plan-review 有三種結束方式，每種都要問到這兩種題：

• 通過：在 plan-review 第 4 步一起問
• 第 3 輪還是不通過：照 plan-review 第 3 步改好草稿、每條重大寫明改了沒，先問還沒問的「需使用者決定」，再問「跑確認輪」「照改好的稿寫進設計文件」或「停下」（決策題與測試清單題還不問，草稿可能還會變）。 選確認輪：通過就照上一條「通過」走；沒過，先問還沒問的「需使用者決定」，再問「照改好的稿寫進設計文件」或「停下」；沒跑成，一題問「重跑」「照改好的稿寫進設計文件」「停下」（不走下面「沒跑成」那條）。選了寫進設計文件，才問決策題與測試清單題， 步驟 5 把 plan-review 第 3 步標「未經審查」的改法（第 3 輪與確認輪的重大缺失，含「需要外部查證」裡重大的；小事；因使用者答案改的地方）、決策題選非建議答案改的地方，與每條重大的現況（照 plan-review 回報的原樣，含確認輪的註記；寫進前照 plan-review 那條重判，之後改過的拿掉註記）寫進設計文件的假設，註明未經審查；確認輪跑了但沒跑成也寫明（換 session 的人才看得到）；選「停下」就不寫檔、不 commit，結束本 skill。 這條路上決策題選了非建議答案：照答案改草稿，不再送審
• 沒跑成（第 1–3 輪；確認輪沒跑成照上一條）：先問所有輪次還沒問的「需使用者決定」，再問「重跑」或「不審直接交」；選「不審直接交」之後才問決策題與測試清單題（決策題選了非建議答案：照答案改草稿，不再送審），接著走步驟 5， 並在設計文件的假設寫明「這份段落草稿沒經過 plan-review（使用者選不審直接交）」

通過那條路上，決策題選了非建議答案、會改到草稿：照答案回步驟 2 重出草稿，接續原本的輪次再送 plan-review（照 plan-review 第 4 步：還沒到第 3 輪就輪次加 1 再送，已經是第 3 輪（含確認輪）就不再送）， 三條路上只要草稿改了，測試清單題都對著新草稿重問 —— 對著舊草稿選的不算。已經答過的決策題不重問，只問重出的草稿新冒出來的決策點。 測試清單題選「要修改」：照使用者說的改清單再問一次，直到選「照這份清單加」；只改清單不算改到草稿，不再送審。 使用者在測試清單題選定的，就是使用者要求加的測試（全域 §3.5：不主動新增測試，使用者要求時例外）。

完成條件：plan-review 通過；或第 3 輪不通過、確認輪不通過、確認輪沒跑成時使用者選了「照改好的稿寫進設計文件」；或沒跑成時使用者選了「不審直接交」。而且決策題都問過、使用者對著最終草稿的測試清單選了「照這份清單加」。

5. 寫進設計文件並 commit

• 已有設計文件：在標題與開頭說明之後、第一個 ## 之前加 ## 進度表；文件末尾加 ## 段落與小任務，開頭寫假設、結尾附使用者選定的測試清單。 文件裡已經有本 skill 產的進度表時，新段落接在同一張表後面，不另開一張
• 沒有設計文件：建 docs/designs/YYYY-MM-DD-<topic>-design.md，寫四節：來源、假設、進度表、段落與小任務（結尾附測試清單）
• plan-review 通過那條路上，最終計畫標了未經審查的改法（到第 3 輪後因答案改、不再送審的）或「沒改」的重大時，一樣寫進假設並註明未經審查
• 步驟 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，也要照得做。

## 進度表

| 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）。
  **前綴是「這一段自己的 ID 加一個 `-`」**，不是固定字串：插隊進來的 `S2.5` 要找的是 `（S2.5-`，
  拿 `（S2-` 去比對不到它，拿 `（S2` 又會把 S2.5 的 commit 誤算成 S2 的，還沒 commit 的小任務先做完。小任務都做完了，再看同一範圍裡有沒有帶 `（S2）` 的 commit：有，代表步驟 6 之後的步驟做到一半；沒有就從步驟 3 開始
- `BLOCKED` 用在這段要先停：外部卡住（等使用者決定、環境壞了），或使用者要先做別的事（別段、臨時修 bug）。狀態格寫 `BLOCKED` 和原因，外部卡住時停下來問使用者。先停之前，用正常 commit 補完這段 SKIP 欠下的 CLAUDE.md（不然 `--start-segment` 會拒絕）；回頭做這段時，範圍一樣從表上這段的起點算。依賴還沒完成的段落維持 `TODO`
- 做到一半冒出新工作：先問使用者，同意才加一列 `TODO` 排進該在的位置；ID 不重編，插在中間用 `S2.5`。
  **同一批要在「段落與小任務」補上這一段的小任務**（名稱、要動的檔案、驗證方式、commit 訊息）——
  只加表上那一列的話，接手的 session 照上面「接手」那條去對 commit，清單本來就是空的，
  它會判定「小任務都做完了」而直接跳到步驟 3，整段程式碼從頭到尾沒人寫。
  沒有小任務條目的段落不得標 `IN_PROGRESS`
- 每列一行，細節寫進 commit 訊息