任務規劃
Gemini CLI 任務規劃：todos、planning 工具、複雜任務拆分、執行前計劃、執行中檢查和完成標準。
Gemini CLI 的任務規劃能力適合處理多步驟任務。官方文件把 todos / planning 作為工具能力和 tutorial 主題列出。
複雜任務先計劃：跨檔案修改、重構、遷移、測試修復、CI 自動化，都應該先讓 Gemini CLI 列計劃，再進入執行。
什麼時候需要計劃
- 需要改多個檔案。
- 需要先讀專案結構。
- 需要跑測試並根據結果迭代。
- 涉及資料庫、構建、部署、許可權。
- 你不確定它會改哪裡。
推薦 prompt
第一句先限定邊界：先不要修改檔案。請先閱讀相關程式碼，列出執行計劃、會影響哪些檔案、需要跑哪些驗證。
確認計劃後再說：
執行時再縮小範圍：按計劃執行第一步，只改一個檔案，改完展示 diff。
更完整的版本可以直接要求它輸出邊界：
先不要修改文件。请只读分析这个问题，输出：
1. 你需要检查哪些文件；
2. 你预计会修改哪些文件；
3. 哪些文件明确不会碰；
4. 每一步的验证命令；
5. 失败时停止条件；
6. 需要我确认的风险点。這類 prompt 的價值不是形式感，而是把 agent 的行動範圍提前暴露出來。計劃越具體，後續 diff 越容易稽核。
一個穩定任務迴圈
flowchart TD
A["讀專案"] --> B["列計劃"]
B --> C["使用者確認"]
C --> D["執行一小步"]
D --> E["跑驗證"]
E --> F{"透過?"}
F -->|是| G["繼續下一步"]
F -->|否| H["分析失敗原因"]
H --> B完成標準
每個任務至少要明確：
- 改哪些檔案。
- 不改哪些邊界。
- 用什麼命令驗證。
- 失敗時如何回復。
- 什麼狀態算完成。
計劃和 todo 的分工
計劃回答“為什麼這樣做、影響什麼、風險在哪”；todo 回答“當前執行到哪一步”。計劃可以寫得更完整，todo 應該短而可執行。長任務裡，兩者都需要：先有方案，再用 todo 跟蹤執行。
| 專案 | 計劃 | Todo |
|---|---|---|
| 主要作用 | 解釋方案和風險 | 跟蹤當前進度 |
| 粒度 | 可以包含背景、取捨、驗證 | 每項應該短、可執行 |
| 更新時間 | 任務邊界變化時更新 | 每完成一步就更新 |
| 使用者審查點 | 執行前審查 | 執行中看狀態 |
一個常見錯誤是把 todo 寫成“最佳化文件、修復問題、跑測試”。這種條目太大，無法判斷進度。更好的拆法是“讀取相關文件”“補導航卡”“跑 MDX 型別檢查”“記錄未覆蓋風險”。
官方 todo 工具要求同一時間只有一個 in_progress，狀態只屬於當前會話。它適合執行透明度，不適合替代專案管理。需要交接給另一個人或另一個 agent 時，要把計劃和完成狀態寫進檔案或 issue，而不是隻依賴會話內 todo。
Plan Mode 的邊界也要寫清：進入後是隻讀 PLAN approval mode，不適合 YOLO；退出時需要一個真實存在且有內容的 Markdown plan，使用者批准後才回到執行模式。
計劃質量檢查
執行前可以用這張錶快速判斷計劃是不是合格：
| 檢查項 | 合格表現 | 不合格表現 |
|---|---|---|
| 檔案範圍 | 列出會改和不會改的路徑 | 只說“相關檔案” |
| 風險邊界 | 標明許可權、資料、部署、相容性風險 | 只說“風險較低” |
| 驗證命令 | 給出具體命令和預期結果 | 只說“執行測試” |
| 中止條件 | 說明失敗後停在哪一步 | 失敗後繼續試錯 |
| 人工確認 | 高風險節點等使用者確認 | 自己連續執行高風險步驟 |
計劃不合格時，不要讓它直接開改。先要求 Gemini CLI 把計劃改到可審查，再批准第一步。
驗收方式
執行前檢查計劃是否覆蓋影響檔案、驗證命令、回復方式和人工確認點。執行中檢查 todo 是否只保留一個 in_progress。完成後要求 Gemini CLI 總結已改檔案、未覆蓋風險和實際跑過的驗證，不接受只說“完成了”。
接下來去哪
Checkpoint 與 rewind
計劃進入執行前，繼續看如何給檔案修改增加恢復點。
Todos / Planning 工具
繼續看官方工具層面的 todos、planning 和任務狀態語義。
Plan mode
高風險任務先進入只讀規劃模式，再批准執行。