task-planner

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 要看到什麼」；依賴沒有繞圈，第一段沒有依賴。 只切出 1 段就不往下走：告訴使用者一圈做得完、不用拆，照一般的 8 步迴圈做（沒有 task 工具時照全域 §4.4 記進度）。

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：不主動新增測試，使用者要求時例外）。