Plan Mode

概要

実装前に解決策を設計するための read-only 環境。プロジェクトを変更せずに調査し、トレードオフを評価し、実行戦略に合意してからコードに触る。既定で有効で、/settings で管理できる。

仕様

入り方

既定で Plan Mode で起動する: /settings で Default Approval Mode を Plan にする
1 回だけ: gemini --approval-mode=plan
キーボード: Shift+Tab で approval mode を巡回する（Default → Auto-Edit → Plan）。Gemini CLI が処理中、または確認ダイアログを表示している間は Plan Mode が巡回から自動的に外れる
コマンド: /plan [goal]。[goal] は任意で、指定すると Plan Mode に切り替えて即座にプロンプトを送る
自然言語: 「start a plan for...」と頼むと enter_plan_mode ツールが呼ばれる。このツールは YOLO モードでは使えない

使い方の流れ

目標を伝える（必要なら Plan Mode に入って調査する）
戦略を議論して合意する: 調査結果と提案する戦略を提示し、ask_user で質問や選択肢を出すことがある。正式な計画を書き起こす前に必ず停止して確認を待つ
計画をレビューする: 合意後、plans ディレクトリに Markdown ファイルとして詳細な実装計画を作る
- Ctrl+X で設定済みの外部エディタで計画を開ける
承認または反復
- 承認: Yes, automatically accept edits または Yes, manually accept edits
- 反復: 入力欄でフィードバックするか、計画ファイルを直接編集する
- キャンセル: Esc

計画の共同編集

計画提示時に Ctrl+X で外部エディタ（VS Code、Vim など）で開く
手順の並べ替え・削除・書き換え、またはインラインのコメント追加
保存して閉じる
Gemini CLI が変更を自動検出し、コメントをレビューして戦略を調整し、洗練した計画を最終承認のために提示する

抜け方

計画を承認すると自動的に Plan Mode を抜けて実装を始める
Shift+Tab で別のモードへ巡回する
「exit plan mode」「stop planning」と伝える

ツール制限

Plan Mode で許可されるのは以下のツールのみ。

分類	ツール
FileSystem（Read）	`read_file`、`list_directory`、`glob`
Search	`grep_search`、`google_web_search`、`web_fetch`（明示的な確認が必要）、`get_internal_docs`
Research Subagents	`codebase_investigator`、`cli_help`
Interaction	`ask_user`
MCP（Read）	read-only な MCP ツールと、コアの MCP リソースツール（`list_mcp_resources`、`read_mcp_resource`）
Planning（Write）	`write_file` と `replace`。`~/.gemini/tmp/<project>/<session-id>/plans/` またはカスタム plans ディレクトリ内の `.md` ファイルに対してのみ
Skills	`activate_skill`（read-only な形で専門的な指示とリソースを読み込む）

カスタムポリシー

Plan Mode の既定のツール制限は policy engine が管理し、組み込みの plan.toml（Tier 1）で read-only 状態を強制する。~/.gemini/policies/（Tier 2）で自分のポリシーを作って上書きできる
modes を明示しないルールは「常に有効」と見なされ、Plan Mode にも適用される
Default や Auto-Edit で与えた永続的な承認は Plan Mode には適用されない。 一方、Plan Mode で与えた承認はグローバルな信頼の意図的な選択として扱われ、すべてのモードに適用される
あるルールを Plan Mode 以外に限定したい場合、modes から "plan" を外して明示する
read-only な MCP ツールは、既定では Plan Mode でユーザー確認を要する。 toolAnnotations = { readOnlyHint = true } と mcpName のワイルドカードで自動承認にできる
組み込みの research subagent（codebase_investigator、cli_help）は既定で Plan Mode で有効。カスタム subagent はポリシーで追加する

カスタム plans ディレクトリ

既定はプロジェクト外の管理された一時ディレクトリ ~/.gemini/tmp/<project>/<session-id>/plans/
settings.json の general.plan.directory で変更できる
ユーザーが設定する plans ディレクトリのパスはプロジェクトルート内に制限される。 これにより、プロジェクトのワークスペース内で定義したカスタム保存先から脱出して他所の機微なファイルを上書きすることを防ぐ。どのユーザー設定ディレクトリもプロジェクト境界の内側になければならない
カスタムディレクトリを使う場合、その場所での write_file と replace を許すよう policy engine の設定を更新する必要がある

hooks との併用

BeforeTool / AfterTool で enter_plan_mode と exit_plan_mode のツール呼び出しを横取りできる
ツール実行によって発火する hook は、/plan コマンドや Shift+Tab で手動で Plan Mode を切り替えたときには走らない。 モード変更で hook を動かしたい場合、エージェント側が遷移を開始する形（「start a plan for...」と頼むなど）にする

自動のモデルルーティング

auto モデルを使っているとき、タスクのフェーズに応じて自動的に最適化する。

Planning Phase: Plan Mode 中は高推論の Pro モデルへルーティングする
Implementation Phase: 計画が承認されて Plan Mode を抜けると、承認済み計画の存在を検出して高速な Flash モデルへ切り替える

高推論モデルが利用できない、またはアクセス権が無い場合、ワークフローを止めないよう自動的かつ黙って高速なモデルにフォールバックする
既定で有効。general.plan.modelRouting を false にすると無効にできる

クリーンアップ

既定でセッション（とその計画）は 30 日間保持される。古いセッションデータは計画ファイルと task tracker を含めて自動削除される
/settings（Enable Session Cleanup または Keep chat history）や settings.json で変えられる
手動削除は gemini --delete-session <index|id>、または /resume のセッションブラウザで x
カスタム plans ディレクトリを使っている場合、そのファイルは自動削除されず手動管理が必要

非対話実行

policy engine が enter_plan_mode と exit_plan_mode を確認なしに自動承認する
Plan Mode を抜けて計画を実行するとき、標準の Default モードではなく YOLO モードに自動的に切り替わる。 対話的なツール承認で止まらずに実装手順を実行できるようにするため

計画ワークフロー

Plan Mode は enter_plan_mode / exit_plan_mode / ask_user といったコアツールを使う extension として実装される構成要素を提供する
組み込みの planner は適応的なワークフローでプロジェクトを解析し、ask_user でトレードオフを相談し、承認用の計画を書く
Conductor は spec 駆動開発向けのカスタム planner の例。作業を「track」に整理し、プロジェクトの conductor/ ディレクトリに永続的な成果物を保存する

コマンド

/plan copy: 現在承認されている計画をクリップボードにコピーする

設定

{
  "general": {
    "plan": {
      "directory": ".gemini/plans",
      "modelRouting": false
    }
  }
}

# default と autoEdit では npm test を許可し、Plan Mode では許可しない
[[rule]]
toolName = "run_shell_command"
commandPrefix = "npm test"
decision = "allow"
priority = 100
modes = ["default", "autoEdit"]

# Plan Mode で read-only な MCP ツールを自動承認する
[[rule]]
toolName = "*"
mcpName = "*"
toolAnnotations = { readOnlyHint = true }
decision = "allow"
priority = 100
modes = ["plan"]

# Plan Mode で git status / git diff を許可する
[[rule]]
toolName = "run_shell_command"
commandPrefix = ["git status", "git diff"]
decision = "allow"
priority = 100
modes = ["plan"]

gemini --approval-mode plan -p "Analyze telemetry and suggest improvements"