使用 Task 工具進行規劃

你將學到什麼

複雜工作同時需要經過核准的方法與持續更新的執行清單。兩者彼此相關，但不是同一個機制：

• Plan 模式讓 Claude 在不編輯原始碼的情況下探索，並提出方法供你核准。
• TaskCreate、TaskGet、TaskList、TaskUpdate 用來追蹤拆分後的工作。

完成本堂課後，你會知道如何搭配兩者，而不會把規劃權限和任務狀態混為一談。

現行 Task 系統

自 Claude Code v2.1.142 起，結構化 Task 工具預設取代 TodoWrite：

工具	用途
TaskCreate	建立單一任務並取得 ID
TaskUpdate	更新狀態、細節、owner 或依賴關係
TaskGet	讀取單一任務的完整資料
TaskList	取得所有目前任務的快照

TodoWrite 是舊版相容路徑，在目前互動 session 中預設停用。新的教程與整合應使用 Task 工具。

任務通常依照以下生命週期移動：

pending → in_progress → completed

若不再需要某個任務，可用 TaskUpdate 把狀態設為 deleted。

規劃、執行、驗證

規劃
  使用唯讀工具探索 repository
  找出範圍、風險與依賴關係
  提出計畫供使用者核准
       ↓ 已核准
執行
  使用 TaskCreate 建立任務
  將一個作用中的任務設為 in_progress
  發現新事實時更新清單
       ↓ 實作完成
驗證
  執行相關測試與檢查
  檢視最終 diff
  只有在證據成立時才標記 completed

任務清單本身不是完成證據。只有在驗證過驗收條件後，任務才應設為 completed。

正確進入 Plan 模式

從 CLI 直接以 Plan 模式啟動：

claude --permission-mode plan

在互動式 CLI session 中，可按 Shift+Tab 切換至 Plan 模式，或在單次 prompt 前加上 /plan。

在 Plan 模式中，Claude 可以讀取檔案、執行唯讀 shell 命令來理解 codebase，但不會編輯原始碼。非唯讀 shell 命令仍需核准。Claude 提出計畫後，你可以核准、繼續規劃，或先編輯計畫再執行。

Plan 模式不是每次讀取都要核准。啟動時請使用上方官方記載的 --permission-mode plan。

規劃優先的 Prompt

/plan 為這個應用程式加入通知系統。

提出實作方案前：
1. 檢查現有架構與測試。
2. 找出資料庫、API、UI、migration 和 rollout 工作。
3. 清楚列出依賴關係與驗證標準。
4. 在我核准計畫前不要修改檔案。

核准後，再請 Claude 追蹤執行：

把已核准的計畫建立成結構化任務清單。除非刻意平行處理彼此獨立的工作，
否則同時只保留一個 in_progress 任務。每個任務都要有具體完成檢查，
並在工作進行時更新狀態。

Claude 在概念上可能進行這些呼叫：

{"tool": "TaskCreate", "subject": "新增通知 schema", "description": "加入 migration 並驗證 rollback"}
{"tool": "TaskUpdate", "taskId": "1", "status": "in_progress"}
{"tool": "TaskUpdate", "taskId": "1", "status": "completed"}
{"tool": "TaskList"}

真正的 task ID 由 TaskCreate 結果回傳；撰寫 SDK 整合時不要自行假造 ID。

良好規劃帶來的差異

沒有規劃 checkpoint	使用 Plan 模式 + Task 工具
尚未理解範圍就開始編輯	先進行唯讀探索
遺漏相關修改	用驗收檢查拆分工作
只用文字描述進度	任務狀態持續可見
「完成」表示 Claude 停止編輯	「完成」表示驗證已通過

下一堂課

在第 4 堂課中，我們會探索子代理與 context 隔離；第 7 堂課則會把這份任務清單延伸成依賴圖。

官方依據

• 工具參考
• 選擇權限模式
• 從 TodoWrite 遷移至 Task 工具

最後驗證：2026-07-20。