---
title: "Plan mode"
description: "Gemini CLI plan mode 的用途：只讀規劃、複雜修改前方案設計、降低誤改風險，以及和 approval mode 的關係。"
verifiedAt: "2026-05-09"
---

Plan mode 是複雜任務前最應該優先用的模式。官方 CLI cheatsheet 把 `--approval-mode=plan` 列為 approval mode 之一，官方 docs 也有 Plan mode 相關頁面。

> [!IMPORTANT]
> **先 plan，再 edit**：跨檔案重構、依賴升級、架構調整、資料遷移、生產相關任務，都應該先讓 Gemini CLI 進入規劃階段。

## 怎麼啟動

```bash
gemini --approval-mode=plan
```

也可以在普通會話裡明確要求：

```text
先不要修改文件。只读分析，给我计划、风险、影响文件和验证命令。
```

## 適合場景

- 你還不清楚影響範圍。
- 任務需要跨多個檔案。
- 修改可能破壞構建或資料。
- 涉及許可權、安全、釋出、賬單。
- 你要先稽核方案。

典型例子：

| 任務 | 是否先 Plan | 原因 |
| --- | --- | --- |
| 升級框架主版本 | 是 | 影響依賴、構建、路由和測試 |
| 調整認證流程 | 是 | 涉及安全、會話、許可權邊界 |
| 批次改文件格式 | 是 | 檔案多，容易誤改目錄或 frontmatter |
| 查一個 CLI 引數 | 否 | 只讀查詢，不需要規劃階段 |
| 修一個錯別字 | 否 | 直接小改更合適 |

## 不適合場景

- 只查一個命令。
- 只解釋一個檔案。
- 改一個明顯拼寫錯誤。
- 已經有明確 diff 的小修。

## 一個好計劃應該包含什麼

```text
目标
影响文件
不修改边界
执行顺序
验证命令
失败恢复
需要用户确认的动作
```

還應該明確“第一步只做什麼”。Plan mode 的目的不是一次性把所有事情想完，而是把執行權拆小，讓你能在每個風險節點做判斷。

```mermaid
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 輸出，應該讓人能直接判斷：這一步會改哪裡、為什麼現在改、失敗後停在哪裡。

## 接下來去哪

<Cards>
  <Card title="上下文與配置" description="CLI 工作流讀完後，繼續把規則、許可權、模型和上下文沉澱到配置層。" href="/zh-Hant/docs/gemini-cli/official/02-context-config" />
  <Card title="Todos / Planning 工具" description="繼續看工具層面的 todos、plans 目錄和 planning 行為。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/34-todos-planning-tools" />
  <Card title="Sandbox" description="如果準備讓 Gemini CLI 執行命令或寫檔案，繼續看 sandbox 與許可權邊界。" href="/zh-Hant/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
</Cards>

## 官方來源

- [Gemini CLI plan mode](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/plan-mode.md)
- [Plan mode steering tutorial](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/plan-mode-steering.md)
- [Gemini CLI planning tools](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/planning.md)
