Breaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.
規劃與任務分解
概述
將工作分解為小型、可驗證的任務，並附上明確的驗收條件。良好的任務分解是區分一個能可靠完成工作的 AI 代理與一個產出混亂結果的 AI 代理的關鍵。每個任務都應夠小，以便在單次專注的工作階段中實作、測試和驗證。
使用時機
- 你有規格，需要將其分解為可實作的單元
- 任務感覺太大或太模糊，無法開始
- 工作需要在多個代理或工作階段之間平行處理
- 你需要向人類溝通範圍
- 實作順序不明確
何時不該使用： 單一檔案變更且範圍明確，或規格中已包含定義良好的任務。
規劃流程
步驟 1：進入規劃模式
在撰寫任何程式碼之前，以唯讀模式操作：
- 閱讀規格和相關程式碼庫章節
- 識別現有模式和慣例
- 繪製元件之間的依賴關係
- 記錄風險和未知事項
規劃期間請勿撰寫程式碼。 輸出是儲存在 tasks/plan.md 的規劃文件和儲存在 tasks/todo.md 的任務清單，而非實作。
步驟 2：識別依賴圖
繪製哪些部分依賴哪些部分：
資料庫結構
│
├── API 模型/型別
│ │
│ ├── API 端點
│ │ │
│ │ └── 前端 API 客戶端
│ │ │
│ │ └── UI 元件
│ │
│ └── 驗證邏輯
│
└── 種子資料 / 遷移
實作順序應遵循依賴圖由下而上：先建立基礎。
步驟 3：垂直切割
與其先建立所有資料庫、再建立所有 API、最後建立所有 UI，不如一次建立一條完整的功能路徑：
不良（水平切割）：
任務 1：建立整個資料庫結構
任務 2：建立所有 API 端點
任務 3：建立所有 UI 元件
任務 4：連接所有部分
良好（垂直切割）：
任務 1：使用者可以建立帳號（註冊的結構 + API + UI）
任務 2：使用者可以登入（驗證結構 + API + UI）
任務 3：使用者可以建立任務（任務結構 + API + UI）
任務 4：使用者可以檢視任務清單（查詢 + API + 清單檢視的 UI）
每個垂直切割都提供可運作、可測試的功能。
步驟 4：撰寫任務
每個任務遵循以下結構：
## 任務 [N]：[簡短的描述性標題]
**描述：** 一段說明此任務完成什麼的段落。
**驗收條件：**
- [ ] [具體、可測試的條件]
- [ ] [具體、可測試的條件]
**驗證：**
- [ ] 測試通過：`npm test -- --grep "feature-name"`
- [ ] 建置成功：`npm run build`
- [ ] 手動檢查：[要驗證的內容描述]
**依賴：** [此任務依賴的任務編號，或「無」]
**可能觸及的檔案：**
- `src/path/to/file.ts`
- `tests/path/to/test.ts`
**預估範圍：** [小：1-2 個檔案 | 中：3-5 個檔案 | 大：5 個以上檔案]
步驟 5：排序與檢查點
安排任務時，確保：
- 滿足依賴關係（先建立基礎）
- 每個任務都讓系統處於可運作狀態
- 每 2-3 個任務後設置驗證檢查點
- 高風險任務放在前面（快速失敗）
加入明確的檢查點：
## 檢查點：任務 1-3 完成後
- [ ] 所有測試通過
- [ ] 應用程式建置無錯誤
- [ ] 核心使用者流程端到端運作
- [ ] 在繼續之前與人類審查
任務規模指南
| 規模 | 檔案數 | 範圍 | 範例 |
|---|---|---|---|
| XS | 1 | 單一函式或設定變更 | 新增驗證規則 |
| S | 1-2 | 一個元件或端點 | 新增 API 端點 |
| M | 3-5 | 一個功能切片 | 使用者註冊流程 |
| L | 5-8 | 多元件功能 | 含篩選與分頁的搜尋 |
| XL | 8+ | 太大——需進一步分解 | — |
如果任務規模為 L 或更大，應將其分解為較小的任務。AI 代理在 S 和 M 規模的任務上表現最佳。
何時需要進一步分解任務：
- 需要超過一次專注的工作階段（約 2 小時以上的代理工作）
- 無法用 3 個或更少的要點描述驗收條件
- 觸及兩個或更多獨立的子系統（例如驗證和計費）
- 你在任務標題中寫了「和」字（表示這是兩個任務）
輸出檔案
- 規劃文件： 將實作計畫儲存至
tasks/plan.md。 - 任務清單： 將核取清單風格的任務清單儲存至
tasks/todo.md。
如果 tasks/ 目錄不存在，請建立它。這些路徑是 /build 命令和其他下游工具所預期的慣例。
規劃文件範本
# 實作計畫：[功能/專案名稱]
## 概述
[一段摘要，說明我們要建置什麼]
## 架構決策
- [關鍵決策 1 與理由]
- [關鍵決策 2 與理由]
## 任務清單
### 階段 1：基礎
- [ ] 任務 1：...
- [ ] 任務 2：...
### 檢查點：基礎
- [ ] 測試通過，建置乾淨
### 階段 2：核心功能
- [ ] 任務 3：...
- [ ] 任務 4：...
### 檢查點：核心功能
- [ ] 端到端流程運作
### 階段 3：打磨
- [ ] 任務 5：...
- [ ] 任務 6：...
### 檢查點：完成
- [ ] 所有驗收條件已滿足
- [ ] 準備好進行審查
## 風險與緩解措施
| 風險 | 影響 | 緩解措施 |
|------|--------|------------|
| [風險] | [高/中/低] | [策略] |
## 待解決問題
- [需要人類輸入的問題]
平行化作業機會
當有多個代理或工作階段可用時：
- 可安全平行化： 獨立的功能切片、已實作功能的測試、文件
- 必須循序執行： 資料庫遷移、共享狀態變更、依賴鏈
- 需要協調： 共享 API 合約的功能（先定義合約，再平行化）
常見合理化藉口
| 合理化藉口 | 現實 |
|---|---|
| 「我會邊做邊想」 | 這就是你最終得到混亂結果和重工的原因。10 分鐘的規劃能節省數小時。 |
| 「任務很明顯」 | 無論如何還是寫下來。明確的任務能揭露隱藏的依賴和被遺忘的邊界情況。 |
| 「規劃是 overhead」 | 規劃本身就是任務。沒有計畫的實作只是打字。 |
| 「我全記在腦子裡就好」 | 上下文視窗是有限的。書面計畫能跨越工作階段邊界和壓縮而存活。 |
紅旗警示
- 在沒有書面任務清單的情況下開始實作
- 任務只說「實作功能」而沒有驗收條件
- 計畫中沒有驗證步驟
- 所有任務都是 XL 規模
- 任務之間沒有檢查點
- 未考慮依賴順序
驗證
在開始實作之前，確認：
- [ ] 每個任務都有驗收條件
- [ ] 每個任務都有驗證步驟
- [ ] 任務依賴關係已識別並正確排序
- [ ] 沒有任務觸及超過約 5 個檔案
- [ ] 主要階段之間存在檢查點
- [ ] 人類已審查並批准計畫
參見
驗收條件是每個任務專屬的，回答「我們是否建置了正確的東西？」。它們建立在專案範圍的完成定義之上，這是每個任務在視為完成之前必須達到的標準門檻。請參閱 references/definition-of-done.md。
