Plan モード徹底ガイド
Claude Code の Plan モードをマスターしよう — 先に計画を立ててから実行することで、AI プログラミングをよりコントロールしやすく、より効率的に
Plan モード徹底ガイド¶
こんな経験はありませんか。Claude Code にコードの修正を頼んだら、勢いよく十数個のファイルを書き換えたものの、最後になって方向性がずれていたと気づく。あるいは、修正の途中である依存関係を見落としていたことに気づき、やり直す羽目になる。
Plan モードは、まさにこうした問題を解決するために生まれました。Claude にまず詳細な実行計画を立てさせ、あなたが内容を確認・承認してから作業に取りかかる仕組みです。これにより、「先に矢を射てから的を描く」のではなく、「よく練ってから動く」やり方に変えられます。
Plan モードとは¶
Plan モード vs 通常モード¶
通常モードでは、Claude Code は考えながら実行します。コードの分析、ファイルの編集、コマンドの実行といった動作が交互に進みます。これは単純なタスクにはとても効率的ですが、複雑なタスクでは「一歩進んで様子を見る」式の問題を招くことがあります。
Plan モードはこれとはまったく異なります。
| 特性 | 通常モード | Plan モード |
|---|---|---|
| 実行方式 | 考えながら実行 | まず計画し、承認後に実行 |
| ファイル操作 | すぐにファイルを読み書きする | 読み取りのみで書き込みなし、分析と検索だけ |
| コマンド実行 | コマンドを直接実行する場合がある | 変更を伴うコマンドは一切実行しない |
| 適した場面 | 単純な修正、素早い修正 | 複数ファイルのリファクタリング、複雑な機能開発 |
| リスク管理 | 権限システムに依存 | 計画段階はリスクゼロ |
端的に言えば、Plan モードの Claude はノートだけを手にした建築家のようなものです。現場を入念に調査し（コードを読み、ファイルを検索し）、詳細な施工図面（実行計画）を描き上げますが、レンガを一つも動かすことはありません。
なぜ先に計画してから実行するのか¶
先に計画してから実行する利点は、「安全」というだけにとどまりません。
- 全体視点：Claude はまず関連するすべてのファイルをスキャンして全体像を把握するため、途中で見落としに気づくということがなくなります
- 計画を審査できる：実行前に計画を確認し、潜在的な問題を見つけて、修正の意見を出せます
- 手戻りの削減：計画段階で依存関係の衝突やインターフェースの不整合といった問題を発見できます
- 認識のすり合わせ：計画を読むことで、Claude のプロジェクト理解が正しいかどうかを確認できます
- 再利用できる：良い計画は保存しておき、類似タスクの参考テンプレートにできます
どんな場面で Plan モードが適しているか¶
Plan モードの使用を強く推奨する場面：
- 5 個以上のファイルにまたがる修正
- コアモジュールや公開インターフェースを変更する必要がある場合
- 新機能を追加する場合（特にデータベースや API などが絡むもの）
- 既存のコード構造をリファクタリングする場合
- 原因が不明な Bug を修正する場合（まず調査が必要）
- プロジェクトにまだ詳しくなく、Claude に構造を整理してもらいたい場合
通常モードをそのまま使ってよい場面：
- はっきりした小さな Bug を修正する
- 単一ファイルの局所的な内容を修正する
- コメントやドキュメントを追加する
- 単純なフォーマット調整やリネーム
Plan モードの使い方¶
Shift+Tab でモードを切り替える¶
Plan モードの起動はとても簡単です。Claude Code の入力欄で Shift+Tab を押すと、モードが順番に切り替わります。
default → acceptEdits → plan → bypassPermissions → default → ...
入力欄の左側にあるモードインジケーターに plan と表示されたら、Plan モードに入っています。
プロンプトを入力するときに、計画を立ててほしいと直接伝えることもできます。
まずコードを直接修正せず、計画を立ててください。ユーザーシステムにメール認証機能を追加したいです。
ヒント：
Escapeを押せば、いつでもデフォルトモードに戻れます。
Plan モードでの Claude の振る舞い¶
Plan モードに入ると、Claude の能力には制限がかかります。
できること：
- 任意のファイルを読み取る
- コードを検索する（Grep、Glob）
- プロジェクト構造を分析する
- Git 履歴を閲覧する
- ネットワークの情報を検索する
- 詳細な実行計画を生成する
しないこと：
- ファイルの作成や変更
- 副作用を引き起こす可能性のあるコマンドの実行
- 依存パッケージのインストール
- ビルドやテストの実行
つまり Plan モードでは、Claude に任意のコードを探索させても安心で、「うっかり何かを書き換えてしまう」心配がまったくありません。
計画の閲覧と編集¶
Claude が生成する計画は、通常次のような構成になっています。
## 実行計画：メール認証機能の追加
### 目標
ユーザー登録フローにメール認証のステップを追加する。
### 影響分析
- 修正が必要なファイル：6 個
- 新規作成が必要なファイル：3 個
- データベース変更：テーブルを 1 つ新規追加する必要あり
- リスクポイント：既存ユーザーには影響しないが、マイグレーションスクリプトの追加が必要
### 実行ステップ
**第 1 フェーズ：データベース層**
1. `email_verifications` テーブルのマイグレーションスクリプトを作成
2. `users` テーブルを変更し、`email_verified` フィールドを追加
**第 2 フェーズ：バックエンドロジック**
3. `email_verification_service.py` を新規作成
4. `auth_router.py` を変更し、認証関連のインターフェースを追加
5. `user_service.py` を変更し、登録フローで認証メールをトリガー
**第 3 フェーズ：フロントエンド対応**
6. 登録ページを変更し、認証の案内を追加
7. メール認証ページを新規作成
8. ルーティング設定を変更
### リスクと注意事項
- SMTP 設定をあらかじめ用意しておく必要がある
- 認証リンクの有効期限を考慮する必要がある
- すでに存在するユーザーは認証をスキップする必要がある
計画に対して修正の意見を出すこともできます。
計画は全体的に良いですが、いくつか調整したいです。
1. 認証ページを新規作成する必要はなく、既存の toast 通知で十分です
2. 認証リンクの有効期限は 24 時間に設定してください
3. 第 1 フェーズではまだ users テーブルを変更せず、email_verifications テーブルの状態で判定してください
計画を更新してください。
Claude はあなたのフィードバックをもとに計画を修正し、あなたが満足するまで対応します。
計画を承認して実行を開始する¶
計画に問題がないことを確認したら、通常モードに戻り（Shift+Tab を押す）、Claude に計画の実行を指示します。
計画に問題はなさそうです。計画に従って実行を開始してください。第 1 フェーズから始めてください。
フェーズごとに分けて実行することもできます。
まず第 1 フェーズ（データベース層）を実行し、完了したらいったん止めて、私に確認させてください。
Plan モード実践チュートリアル¶
例 1：既存プロジェクトにユーザー認証を追加する¶
FastAPI プロジェクトがあり、現在は認証の仕組みがまったくなく、JWT 認証を追加する必要があるとします。
ステップ 1：Plan モードに切り替え、要件を説明する
私の FastAPI プロジェクトには現在ユーザー認証がありません。JWT ベースのユーザー認証システムを追加する計画を立ててください。
要件：
- ユーザー登録とログイン
- JWT Token の発行と検証
- ルートの保護（一部のインターフェースはログインが必要）
- SQLAlchemy でユーザーテーブルを管理
まず既存のコード構造を分析し、その上で詳細な実行計画を立ててください。
ステップ 2：Claude がプロジェクトを分析して計画を生成する
Claude はまずあなたのプロジェクト構造をスキャンします。
プロジェクト構造を分析しました。以下が私の調査結果と実行計画です：
## プロジェクト現状分析
- フレームワーク：FastAPI 0.115.x
- データベース：SQLAlchemy 設定済み（database.py）、PostgreSQL を使用
- 既存のモデル：Product、Order（models/ ディレクトリ内）
- ルーター：product_router.py、order_router.py（いずれも認証保護なし）
- 依存管理：requirements.txt を使用
## 実行計画
### 第 1 フェーズ：基盤（2 ファイル）
1. requirements.txt に python-jose[cryptography]、passlib[bcrypt] を追加
2. config.py に JWT 関連の設定項目を追加（SECRET_KEY、ALGORITHM、TOKEN_EXPIRE）
### 第 2 フェーズ：ユーザーモデルとデータベース（2 ファイル）
3. models/user.py を新規作成 — User モデル
4. alembic マイグレーションスクリプトを新規作成
### 第 3 フェーズ：認証ロジック（3 ファイル）
5. services/auth_service.py を新規作成 — パスワードハッシュ、JWT 発行/検証
6. schemas/auth.py を新規作成 — リクエスト/レスポンスモデル
7. routers/auth_router.py を新規作成 — /register、/login、/me インターフェース
### 第 4 フェーズ：ルートの保護（3 ファイル）
8. dependencies/auth.py を新規作成 — get_current_user 依存
9. product_router.py を変更 — 書き込み操作には認証が必要
10. order_router.py を変更 — すべての操作に認証が必要
### リスクの注意
- config.py の SECRET_KEY は必ず環境変数を使用し、ハードコードしないこと
- 既存の API クライアントは認証ヘッダーに対応させる必要がある
- まずテスト環境で検証することを推奨
ステップ 3：審査して実行する
計画はとても良いです。2 点だけ調整します。
1. alembic は使わず、SQLAlchemy の create_all を直接使ってください
2. product_router の読み取り操作には認証は不要で、作成と削除のみ認証が必要です
ほかは問題ないので、計画に従って実行してください。
例 2：大きなモジュールをリファクタリングする¶
プロジェクトに 3000 行の utils.py ファイルがあり、分割してリファクタリングする必要があるとします。
Plan モードに入る：
utils.py はすでに 3000 行に膨れ上がり、あらゆるものが詰め込まれています。このファイルを分析して、責務がはっきりした複数のモジュールに分割するリファクタリング計画を立ててください。要件：
1. utils.py のすべての関数を責務ごとに分類して分析する
2. 新しいモジュール構成を設計する
3. utils.py を参照しているすべてのファイルと、影響を受けるインポートを列挙する
4. リファクタリング後も既存のすべての機能が影響を受けないことを保証する
Claude は次のような計画を生成します。
## utils.py リファクタリング計画
### 現状分析
utils.py には 47 個の関数が含まれており、責務を分析すると次の 5 種類に分類できます：
| カテゴリー | 関数の数 | 関数の例 |
|------|---------|---------|
| 文字列処理 | 12 | slugify, truncate, sanitize_html |
| 日時 | 8 | parse_date, format_datetime, get_timezone |
| ファイル操作 | 9 | read_file, ensure_dir, get_file_hash |
| データ検証 | 11 | validate_email, validate_phone, check_url |
| HTTP ツール | 7 | retry_request, parse_response, build_url |
### 参照分析
utils.py をインポートしているファイルは合計 23 個あります。詳細なリストは以下のとおりです：
（各ファイルと、それが使用している具体的な関数を列挙...）
### 新しいモジュール構成
utils/
├── __init__.py # 後方互換性のための再エクスポート
├── strings.py # 文字列処理
├── datetime.py # 日時
├── files.py # ファイル操作
├── validators.py # データ検証
└── http.py # HTTP ツール
### 実行ステップ
（ステップごとに列挙...）
### 後方互換性の方針
utils/__init__.py に既存のすべてのエクスポートを残す：
from .strings import *
from .datetime import *
...
こうすれば、見つけ切れていない参照があってもエラーになりません。
例 3：複数ファイルにまたがる Bug を修正する¶
ユーザーから「注文金額がときどき計算ミスになる」というフィードバックがあったものの、問題がどこにあるのか分からない、というケースです。
Plan モードに入る：
ユーザーから注文金額がときどき計算ミスになるとのフィードバックがありましたが、毎回ではありません。この問題を調査してください：
1. 金額計算に関わるすべてのコードを見つける
2. 偶発的なエラーを引き起こしうる原因を分析する
3. 修正計画を立てる
Claude は Plan モードで詳しく分析します。
## Bug 調査レポート
### 金額計算に関連するコード
全面的に検索した結果、金額計算に関わるコードは 4 つのファイルに分布していました：
- order_service.py:calculate_total() — 主要な計算ロジック
- discount_service.py:apply_discount() — 割引計算
- tax_service.py:calculate_tax() — 税額計算
- cart_service.py:get_cart_total() — カート合計
### 見つかった問題
**根本原因：浮動小数点の精度問題**
order_service.py の 127 行目：
total = sum(item.price * item.quantity for item in items)
Python の浮動小数点演算には精度の問題があります：
>>> 0.1 + 0.2
0.30000000000000004
注文に小数の金額の商品が複数含まれる場合、累積誤差により最終金額が 1 円分ずれる可能性があります。
**副次的な問題：割引計算の順序**
discount_service.py の割引計算は tax_service.py の税額計算の後に実行されますが、
一部の並行実行のシナリオでは、両者が非同期で呼び出されるため順序が逆転する可能性があります。
### 修正計画
1. すべての金額計算を Decimal 型に変更する
2. discount と tax の呼び出し順序を同期的な逐次処理に変更する
3. 金額の整合性を確認するユニットテストを追加する
この例は、Bug 調査における Plan モードの価値を示しています。Claude は急いでコードを書き換えようとはせず、まず徹底的に分析を行うのです。
Plan モードのベストプラクティス¶
1. 「どうするか」ではなく「なぜか」を説明する¶
おすすめしない書き方：
user.py に verify_email メソッドを追加してください。token パラメータを受け取り、
email_verifications テーブルを照会し、token が一致して有効期限内であれば
user.email_verified を True に設定してください。
おすすめの書き方：
ユーザーが自分のメールアドレスを認証できるようにする必要があります。ユーザーは登録後に
認証リンクの記載されたメールを受け取り、リンクをクリックするとメールアドレスの状態が
認証済みになります。実装方針を計画してください。
なぜでしょうか。「なぜか」を説明すると、Claude が最適な方針を設計できる余地が大きくなるからです。あなたが思いつかなかった境界ケースを発見したり、より洗練された実装方法を提案したりするかもしれません。具体的な実装まで書き切ってしまうと、Plan モードの価値は大きく損なわれてしまいます。
2. 計画の中で Claude にリスクポイントを洗い出させる¶
積極的に Claude にリスクの分析を求めましょう。
計画では特に以下に注意してください：
1. 今回の修正で壊れる可能性のある既存機能はどれですか？
2. 同時に変更が必要な設定ファイルはありますか？
3. データベースの変更にマイグレーションスクリプトは必要ですか？
4. 並行処理の安全性に関する考慮はありますか？
3. 複雑な計画はフェーズごとに実行する¶
大きなタスクでは、一気に計画全体を実行しないでください。独立して検証できるフェーズに分割します。
この計画は 4 つのフェーズがあります。次のように実行してください：
- 各フェーズが完了するたびに止める
- そのフェーズの完了状況を報告する
- 私の確認を待ってから次のフェーズに進む
こうする利点は、あるフェーズで問題が起きても、すぐに修正でき、大量の変更を巻き戻さずに済むことです。
4. 計画と Git ブランチを組み合わせる¶
最良のワークフローは、Plan モードで計画を立てる → 新しいブランチを作成 → 新しいブランチで実行 → コードレビュー → マージ です。
# まず Plan モードで計画を立てる
（Plan モードに切り替え、要件を説明し、計画を審査する）
# 満足したら、通常モードに戻る
まず新しいブランチ feature/email-verification を作成し、計画に従って実行してください。
実行の途中で計画が間違っていると分かったら、いつでも main ブランチに戻ってやり直せます。
Plan モード vs 直接コーディング¶
Plan モードが不要なとき¶
- 1〜2 個のファイルを修正する単純なタスク
- どこをどう変えるかがはっきり分かっている場合
- コメント追加や文言変更などの非機能的な変更
- コマンドの実行（依存のインストール、テストの実行など）
Plan モードを必ず使うべきとき¶
- 5 個以上のファイルにまたがる変更
- 公開インターフェースやコアモジュールを変更する場合
- プロジェクト構造にまだ詳しくない場合
- Bug の原因が不明で、まず調査が必要な場合
- 複数の方針のトレードオフを評価する必要がある場合
意思決定の参考¶
あなたのタスクは何ですか？
│
├─ 単純な修正（1〜2 ファイル、方向が明確）
│ → 通常モードで、すぐに開始
│
├─ 中程度のタスク（3〜5 ファイル、ロジックが明快）
│ → まず Plan モードで素早くスキャンし、方針を確認してから実行に切り替える
│
└─ 複雑なタスク（複数ファイル、方針が不確定、リスクが高い）
→ 必ず Plan モードを使い、詳細に計画してから実行する
高度なテクニック¶
1. CLAUDE.md で Plan テンプレートをカスタマイズする¶
プロジェクトの CLAUDE.md に計画の要件を定義しておくと、毎回の Plan モードで統一された形式に従わせることができます。
## Plan モードの要件
Plan モードに入ったら、以下のテンプレートに従って計画を生成してください：
### 必ず含めるべきセクション
1. **現状分析**：現在のコード構造と関連ファイル
2. **方針設計**：具体的な実装方針、代替案を含む
3. **影響範囲**：どのファイルを変更し、どの機能に影響するか
4. **リスク評価**：起こりうる問題と対策
5. **実行ステップ**：順番に並べ、各ステップは独立して検証可能にする
6. **テスト計画**：変更の正しさをどう検証するか
### 形式の要件
- 各実行ステップに、関わるファイルを明記する
- 新規作成するファイルには [新規作成] の印を付ける
- 変更するファイルには [変更] の印を付ける
- リスクポイントには高/中/低で深刻度を示す
これを CLAUDE.md に追加しておけば、Plan モードを使うたびに、Claude はこのテンプレートに沿って計画を構成します。
2. Plan モードでサブエージェントを使って探索する¶
Plan モードでは、Claude にサブエージェント（Agent ツール）を使って、より深い探索を依頼できます。
計画を立てる前に、まず以下を明らかにしておいてください：
1. 現在のデータベーススキーマはどうなっていますか？サブエージェントですべての model ファイルを分析させてください
2. 既存の API インターフェースの一覧は何ですか？サブエージェントですべての router ファイルをスキャンさせてください
3. プロジェクトはどんなサードパーティライブラリを使っていますか？requirements.txt か pyproject.toml を確認してください
サブエージェントは独立したコンテキストでこれらの探索タスクを実行し、その結果をメインのセッションに集約することで、Claude がより正確な計画を立てる手助けをします。
3. 計画の保存と再利用¶
良い計画は、参考テンプレートとして保存できます。Claude に計画を Markdown ファイルとしてエクスポートするよう依頼できます。
先ほど立てた計画を docs/plans/add-email-verification.md に保存してください。
今後、類似の機能を作るときに参考にします。
次に似た要件に出くわしたら、そのまま参照できます。
docs/plans/add-email-verification.md の計画構成を参考にして、
SMS 認証機能のための同様の計画を立ててください。
4. Plan モードでコードレビューを行う¶
Plan モードの読み取り専用という特性は、コードレビューにとても向いています。
（Plan モードに入る）
src/services/ ディレクトリ以下のすべてのサービスファイルをレビューしてください。重点的に見てほしいのは：
1. エラーハンドリングが十分か
2. SQL インジェクションのリスクがないか
3. 閉じられていないリソースがないか（データベース接続、ファイルハンドル）
4. 非同期コードに競合状態がないか
詳細なレビューレポートと改善提案を出してください。
Plan モードはファイルを一切変更しないため、本番コードを安心して Claude にレビューさせられ、「ついでに」何かを書き換えられる心配がありません。
5. /compact を組み合わせて長い計画セッションを管理する¶
Plan モードの探索プロセスでは、大量のコンテキストを消費することがあります（特に多くのファイルを分析した後）。コンテキストがそろそろ一杯になりそうだと感じたら、計画完了後・実行前に /compact を使えます。
/compact 完全な実行計画と影響分析は残し、途中の探索プロセスを圧縮してください
こうすることで、実行段階で十分なコンテキストの余裕を確保できます。
よくある質問¶
Q：Plan モードで Claude が誤ってファイルを変更してしまうことはありますか？
A：ありません。Plan モードはシステムレベルですべての書き込み操作を禁止しています。Claude は任意のファイルを読み取れますが、いかなる内容も作成・変更・削除することはできません。
Q：計画を立てた後、通常モードに切り替えて実行するとき、Claude は計画を覚えていますか？
A：覚えています。/clear で履歴をクリアしていない限り、モードを切り替えてもコンテキストは失われません。計画は会話履歴に残っており、Claude はそのまま計画に従って実行できます。
Q：Plan モードで MCP ツールは使えますか？
A：読み取り専用タイプの MCP ツール（検索やドキュメント照会など）は使えますが、副作用を生むツールは使えません。
Q：計画が気に入らない場合、Claude に再計画を頼めますか？
A：もちろんです。納得がいくまで、Claude に何度でも計画の修正を頼めます。Plan モードのリスクゼロという特性により、思う存分探索・調整できます。
Q：チームでの共同作業では、どうやって計画を共有しますか？
A：Claude に計画を Markdown ファイルとして保存させ、Git リポジトリにコミットできます。あるいは PR の説明に直接計画の内容を添付すれば、コードレビューにも便利です。