Todos / Planning 工具
Gemini CLI todos 和 planning 工具的用途：拆解複雜任務、跟蹤進度、避免長任務失控。
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 結束前檢查方案是否包含影響檔案、風險、回復方式和測試命令；缺任何一項都不應進入實現。