Plan モード深度ガイド
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 モード已进入しています。
入力プロンプトに直接 plans を说明することもできます：
まず計画を立ててもらってください。コードは直接修正しないでください。
用户システムにメール確認機能を追加したいのですが。
ヒント：
Escapeを押すといつでも通常モードに戻れます。
Plan モードでの Claude の動作¶
Plan モードに入ると、Claude の能力には制约がかかります：
できること：
- 任意のファイルを読み取る
- コードを搜索する（Grep、Glob）
- プロジェクト構造を分析する
- Git 履歴を閲覧する
- ネットワーク情報を搜索する
- 詳細な実行計画を 生成する
やらないこと：
- ファイルを作成或いは変更する
- 副作用を引き起こす可能性のあるコマンドを実行する
- 依存パッケージをインストールする
- ビルドやテストを実行する
つまり、Plan モードでは Claude に任意のコードを探索させても大丈夫です。「误って何かを変更してしまう」ことを心配する必要はありません。
計画の閲覧と編集¶
Claude が 生成した計画には、通常次の構造が含まれています：
## 実行計画：メール確認機能の追加
### 目標
ユーザー登録フローにメール確認环节を追加する。
### 影响分析
- 変更が必要なファイル：6 個
- 新規作成が必要なファイル：3 個
- データベース変更：1 つのテーブルの新規追加が必要
- リスクポイント：既存ユーザーは影響を受けないが、移行スクリプトの追加が必要
### 実行ステップ
**第一段階：データベース層**
1. `email_verifications` テーブルの移行スクリプトを作成
2. `users` テーブルを変更し、`email_verified` フィールドを追加
**第二段階：バックエンドロジック**
3. 新規作成 `email_verification_service.py`
4. `auth_router.py` を変更し、確認関連接口を追加
5. `user_service.py` を変更し、登録フローで確認メールをトリガー
**第三段階：フロントエンド适配**
6. 登録ページを変更し、確認提示を追加
7. 新規作成 メール確認ページ
8. ルーター設定を変更
### リスクと注意事項
- SMTP 設定はあらかじめ準備が必要
- 確認リンクの有効期限を考慮する必要がある
- 既に存在するユーザーは確認をスキップ
計画に対して修正意见を 提出できます：
計画全体的に問題ありませんが、いくつか調整があります：
1. 新規確認ページを作成必要はない。现在の toast 提示で构わない
2. 確認リンクの有効期限は 24 時間に设定
3. 第一段階では users テーブルを変更せず、email_verifications テーブルのステータスで判断する
計画を 更新してください。
Claude はあなたのフィードバックに基づいて計画を修正し、あなたが満足するまで対応します。
計画の承認後に実行開始¶
計画に問題がないことを確認したら、通常モードに戻り（Shift+Tab を押す）、Claude に計画の実行を指示します：
計画に問題ないように見えます。計画に従って実行を開始してください。第一段階から始めてください。
段階別に実行することを選択することもできます：
まず第一段階（データベース層）を実行し、完了したら止めて確認させてください。
Plan モード 実践チュートリアル¶
示例 1：既存プロジェクトにユーザー認証を追加¶
FastAPI プロジェクトがあり？现在は認証メカニズムが什么都没有で、JWT 認証を追加する必要があります。
第一步：Plan モードに切り替え、需求を説明
私の FastAPI プロジェクトには現在ユーザー認証がありません。JWT ベースのユーザー認証システムを追加する計画を立案してください。
要求：
- ユーザー登録とログイン
- JWT Token の発行と検証
- ルーター保護（一部の接口はログインが必要）
- SQLAlchemy でユーザーテーブルを管理
まず既存のコード構造を分析，然后制定详细的执行計画。
第二步：Claude がプロジェクトを分析し計画を 生成
Claude はまずプロジェクトの構造をスキャンします：
プロジェクト構造を分析しました。以下が私の发现と実行計画です：
## プロジェクト现状分析
- フレームワーク：FastAPI 0.115.x
- データベース：SQLAlchemy 設定済み（database.py）、PostgreSQL を使用
- 既存のモデル：Product、Order（models/ ディレクトリ内）
- ルーター：product_router.py、order_router.py（認証保護なし）
- 依存関係管理：requirements.txt を使用
## 実行計画
### 第一段階：インフラストラクチャ（2 ファイル）
1. requirements.txt に python-jose[cryptography]、passlib[bcrypt] を追加
2. config.py に JWT 関連設定項目を追加（SECRET_KEY、ALGORITHM、TOKEN_EXPIRE）
### 第二段階：ユーザーモデルとデータベース（2 ファイル）
3. 新規作成 models/user.py — User モデル
4. 新規作成 alembic 移行スクリプト
### 第三段階：認証ロジック（3 ファイル）
5. 新規作成 services/auth_service.py — パスワードハッシュ、JWT 発行/検証
6. 新規作成 schemas/auth.py — リクエスト/レスポンスモデル
7. 新規作成 routers/auth_router.py — /register、/login、/me 接口
### 第四段階：ルート保護（3 ファイル）
8. 新規作成 dependencies/auth.py — get_current_user 依存
9. product_router.py を変更 — 書き込み操作は認証が必要
10. order_router.py を変更 — 全操作は認証が必要
### リスク提示
- config.py の SECRET_KEY は必ず環境変数を使用し、ハードコード禁止
- 既存の API クライアントは認証ヘッダーに适配必要
- まずテスト環境で検証することを推奨
第三段階：確認して実行
計画はとても良いです。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 モードでは、サブエージェント（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 モードではファイルが変更されないため-production コードを安全にレビュー委托できます。「顺手」何かを変更することを心配する必要はありません。
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 の説明に直接計画内容を添付也可以、コードレビューに便利です。