Todos / Planning 工具
Gemini CLI todos 和 planning 工具的用途：拆解複雜任務、跟蹤進度、避免長任務失控。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| Todos 工具 | todos | Agent 維護任務清單的能力。 |
| Planning 工具 | planning | 把任務拆成計劃的能力。 |
| 可追蹤 | trackable | 進度可見、可驗證。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你用 Gemini CLI 的 Todos / Planning 工具把複雜任務管起來。
你是 Gemini CLI 規劃工具顧問。
【角色】
Gemini CLI 規劃工具顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。
【輸入】
- 要做的複雜任務：___
- 目標和成功標準：___
- 步驟之間的依賴：___
- 可用的驗證方式：___
- 經驗水平：___
【工作流程】
1. 把任務拆成可追蹤的 todos
2. 用 Planning 工具排計劃
3. 設計每步的驗證
4. 說明怎麼跟蹤進度
5. 給推進順序
【輸出規範】
▌一、任務拆成 todos
▌二、計劃排布
▌三、每步驗證
▌四、進度跟蹤
【硬約束】
- 任務太大先拆，每步可驗證
- 計劃要審，不盲目執行
- 不可逆操作人工確認
- 不要替我臆測情況或編造不存在的工具能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述Todos 和 planning 工具適合長任務。它們讓 Gemini CLI 不只是一步一步猜，而是把任務拆開、標記狀態、按計劃執行。
Todo 是執行透明度，Plan 是風險控制。不要用一串 todo 代替執行前方案審查。
這兩類能力不是同一件事：write_todos 是目前會話裡的進度清單；Plan Mode 是安全的只讀規劃階段。前者管理執行透明度，後者管理風險。
適合場景
- 多檔案重構。
- 修多個測試失敗。
- 遷移依賴。
- 寫一組文件。
- 接 MCP 或 GitHub Action。
Todos 怎麼用
write_todos 維護完整 todo 陣列，每項有 description 和 status。狀態包括 pending、in_progress、completed、cancelled、blocked，同一時間只能有一個 in_progress。使用者可以用 Ctrl+T 檢視完整列表。
官方 todo 狀態只屬於目前會話，不是專案管理系統。它適合讓使用者看到 agent 現在做到了哪一步，但不能代替 GitHub issue、專案計劃文件或任務交接記錄。
好的 todo 應該具體
讀 package.json 和 tsconfig
定位 auth 相關檔案
列出修改計劃
只修改 login handler
跑 auth 單測
總結 diff 和風險不好的 todo
最佳化專案
修所有問題
讓程式碼更好Planning 怎麼用
Plan Mode 透過 enter_plan_mode 進入，Gemini CLI 會切到只讀的 PLAN approval mode。適合先讀程式碼、理解風險、形成方案。完成方案後，exit_plan_mode 會提交一個 Markdown plan 給使用者正式稽核；使用者批准後才切回可執行模式。
exit_plan_mode 要求 plan 檔案在專案臨時 plans 目錄裡，並且檔案存在、有內容。它不是“隨便說我計劃好了”，而是把計劃變成可審閱產物。
enter_plan_mode 會把 approval mode 切到 PLAN，並限制 agent 使用只讀工具；它不適用於 YOLO 模式。exit_plan_mode 會把最終 Markdown plan 提交給使用者確認，使用者批准後才切回 DEFAULT 或 AUTO_EDIT 這類執行模式。
使用邊界
小任務不需要複雜 planning；直接執行更快。多檔案修改、高風險許可權、生產釋出、批次刪除、跨模組遷移則應該先計劃。計劃階段不要寫檔案或跑破壞性命令，除非使用者明確批准。
| 狀態 | 應該怎麼用 | 常見問題 |
|---|---|---|
pending | 等待執行的具體步驟 | 條目太大，無法判斷進度 |
in_progress | 目前唯一正在做的步驟 | 同時多個進行中 |
completed | 已完成且可驗證 | 沒跑驗證就標完成 |
blocked | 需要外部輸入或環境修復 | 明明可繼續卻假裝阻塞 |
cancelled | 明確不再執行 | 不說明取消原因 |
好的 todo 應該能讓旁觀者理解目前任務卡在哪一步。計劃則應該能讓使用者在執行前判斷是否批准。
商業專案用法
對教學站、文件批次補齊、跨目錄改版這類長任務，todo 必須覆蓋“盤點、補源、改文、驗證、提交”五個階段。每個階段完成後再更新狀態，不要最後一次性標完成。
Plan Mode 更適合高風險動作：批次刪除、公開發布、許可權調整、生產指令碼、跨儲存庫同步。計劃裡至少寫清影響檔案、命令、回復方式、斷點風險和驗收方式。沒有這些內容，使用者無法判斷是否應該批准執行。
驗收方式
長任務開始後檢查 todo 是否覆蓋“讀取、定位、修改、驗證、總結”五類動作。Plan Mode 結束前檢查方案是否包含影響檔案、風險、回復方式和測試命令；缺任何一項都不應進入實現。