Plan mode
Gemini CLI plan mode 的用途：只讀規劃、複雜修改前方案設計、降低誤改風險，以及和 approval mode 的關係。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| Plan mode | 規劃模式 | 先出計劃再執行。 |
| 計劃審閱 | review | 執行前檢查計劃。 |
| 分步執行 | step | 按計劃逐步推進。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你用 Gemini CLI 的 Plan mode 把複雜任務先規劃再執行。
你是 Gemini CLI Plan mode 顧問。
【角色】
Gemini CLI Plan mode 顧問，按最小夠用、安全優先的原則給可落地方案，每條結論落到能照做的步驟或示例。
【輸入】
- 要做的複雜任務：___
- 目標和約束：___
- 涉及範圍：___
- 擔心跑偏的地方：___
【工作流程】
1. 判斷是否值得先 Plan
2. 讓它出計劃
3. 審閱計劃（邊界 / 順序 / 風險）
4. 確認後分步執行驗證
【輸出規範】
▌一、是否值得先 Plan
▌二、計劃要點
▌三、審閱檢查項
▌四、分步執行 + 驗證
【硬約束】
- 複雜 / 高風險任務先 Plan
- 計劃要審閱，不盲目放行
- 執行偏離計劃要叫停
- 不要替我臆測情況或編造不存在的命令，資訊不全先問清
- 不確定的命令或引數一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述Plan mode 是複雜任務前最應該優先用的模式。官方 CLI cheatsheet 把 --approval-mode=plan 列為 approval mode 之一，官方 docs 也有 Plan mode 相關頁面。
先 plan，再 edit：跨檔案重構、依賴升級、架構調整、資料遷移、生產相關任務，都應該先讓 Gemini CLI 進入規劃階段。
怎麼啟動
gemini --approval-mode=plan也可以在普通會話裡明確要求：
先不要修改檔案。只讀分析，給我計劃、風險、影響檔案和驗證命令。適合場景
- 你還不清楚影響範圍。
- 任務需要跨多個檔案。
- 修改可能破壞構建或資料。
- 涉及許可權、安全、釋出、賬單。
- 你要先稽核方案。
典型例子：
| 任務 | 是否先 Plan | 原因 |
|---|---|---|
| 升級框架主版本 | 是 | 影響依賴、構建、路由和測試 |
| 調整認證流程 | 是 | 涉及安全、會話、許可權邊界 |
| 批次改文件格式 | 是 | 檔案多，容易誤改目錄或 frontmatter |
| 查一個 CLI 引數 | 否 | 只讀查詢，不需要規劃階段 |
| 修一個錯別字 | 否 | 直接小改更合適 |
不適合場景
- 只查一個命令。
- 只解釋一個檔案。
- 改一個明顯拼寫錯誤。
- 已經有明確 diff 的小修。
一個好計劃應該包含什麼
目標
影響檔案
不修改邊界
執行順序
驗證命令
失敗恢復
需要使用者確認的動作還應該明確“第一步只做什麼”。Plan mode 的目的不是一次性把所有事情想完，而是把執行權拆小，讓你能在每個風險節點做判斷。
flowchart TD
Read["只讀掃描"] --> Scope["確認影響範圍"]
Scope --> Plan["輸出計劃"]
Plan --> Review{"使用者批准?"}
Review -->|否| Revise["修改計劃"]
Review -->|是| FirstStep["只執行第一小步"]
FirstStep --> Verify["跑最小驗證"]
Verify --> Next["繼續或停止"]
Revise --> Plan
style Read fill:#dbeafe,stroke:#3b82f6
style Review fill:#fef3c7,stroke:#f59e0b
style Verify fill:#dcfce7,stroke:#22c55e退出 Plan mode 的判斷
只有當方案足夠具體、使用者已經理解風險、驗證命令明確時，才進入執行。計劃還停留在“最佳化專案、修復問題、整理程式碼”這種層級，就不該退出 Plan mode。
如果計劃需要寫入檔案，官方 planning tools 會要求 plan 檔案在允許的 plans 目錄中，並在退出時呈現給使用者稽核。被拒絕時應留在 Plan mode，根據反饋改計劃，而不是繞過審批開始改檔案。
和 approval mode 的關係
Plan mode 不等於“永遠不執行”。它更像執行前的只讀階段：先探索、列方案、暴露風險，等使用者批准後再進入寫入。其他 approval mode 關注工具呼叫是否需要確認，Plan mode 關注在確認之前是否已經把事情想清楚。
| 模式關注點 | 主要問題 | 審查重點 |
|---|---|---|
| Plan mode | 現在能不能開始改 | 方案、影響檔案、風險、驗證 |
| Approval mode | 工具呼叫要不要批准 | 寫檔案、跑命令、訪問網路、許可權 |
| Sandbox | 命令和檔案系統能碰哪裡 | 目錄邊界、外部副作用 |
| Checkpoint | 改壞後能不能回退 | 恢復點、diff、測試結果 |
複雜任務裡，這幾層最好一起用：Plan mode 先收斂方案，approval mode 控制每次工具呼叫，sandbox 限制可觸達範圍，checkpoint 降低單次誤改成本。
驗收方式
用一個跨檔案任務測試 Plan mode：確認它只讀探索、不會直接編輯；方案裡列出影響檔案、執行順序、驗證命令和回復策略；批准前不會動檔案。這個行為穩定後，再把 Plan mode 寫進團隊工作流。
常見錯誤
- 計劃寫得很大，但沒有第一步。
- 計劃只列目標，不列檔案。
- 計劃沒有驗證命令。
- 使用者還沒確認，就開始編輯。
- 計劃被拒絕後，繞開 Plan mode 直接執行。
一個可用的 Plan mode 輸出，應該讓人能直接判斷：這一步會改哪裡、為什麼現在改、失敗後停在哪裡。
接下來去哪
上下文與設定
CLI 工作流讀完後，繼續把規則、許可權、模型和上下文沉澱到設定層。
Todos / Planning 工具
繼續看工具層面的 todos、plans 目錄和 planning 行為。
Sandbox
如果準備讓 Gemini CLI 執行命令或寫檔案，繼續看 sandbox 與許可權邊界。