概要
プランモードは、Claude Codeの読み取り専用権限モードであり、ファイルやディレクトリの変更を行わずにコードベースを探索、分析、計画するための特別な動作モードである。
プランモードは以下に示す特徴を持つ。
- 読み取り専用操作のみ許可
- ファイルの作成、編集、削除が不可
- コードベースの安全な探索と分析
- 実装前の計画立案に最適
- ユーザとの対話的な質問が可能
プランモードを使用することにより、以下に示すメリットが得られる。
- 安全性の向上
- コードベースを変更せずに探索できる
- 計画の明確化
- 実装前に詳細な計画を立案できる
- トークンの節約
- 不要な変更を避け、最初から正しいアプローチを選択できる
- コンテキストの保持
- 計画フェーズと実装フェーズを分離できる
- インタビュー機能
- Claudeがユーザに質問して要件を明確化できる
プランモードの目的と用途
プランモードは、複雑な変更やリファクタリングを実行する前に、コードベースを理解し、詳細な計画を立案するための機能である。
使用すべきケース
- 複雑なリファクタリングの計画
- 複数のファイルにまたがる大規模なリファクタリング
- アーキテクチャの変更
- 新機能の設計検討
- 実装方法の調査
- 影響範囲の分析
- 依存関係の確認
- コードベースの理解
- 新しいプロジェクトの構造把握
- レガシーコードの分析
- ドキュメント化されていないコードの調査
- 影響範囲の分析
- 変更が及ぼす影響の調査
- リスク評価
- 要件の明確化
- ユーザへの質問による詳細確認
- 仕様の曖昧な部分の洗い出し
使用すべきでないケース
- 単純な変更
- 1つのファイルの小さな修正
- 明確な手順が既にある場合
- 緊急のバグ修正
- すぐに修正が必要な場合
- 実装が明確な場合
- 計画が既に立っている場合
プランモードの開始方法
プランモードを開始するには、いくつかの方法がある。
方法 1 : キーボードショートカット
Claude Codeセッション中に、以下のキーボードショートカットを使用してプランモードに切り替える。
- [Shift] + [Tab] キー
- プランモードに切り替える
- 再度、[Shift] + [Tab] キーを押下するとプランモードを終了
プランモード中は、画面に Plan Mode と表示される。
方法 2 : コマンドラインフラグ
Claude Codeを起動する際に、コマンドラインフラグを使用してプランモードで開始する。
claude --permission-mode plan
このコマンドにより、起動時から読み取り専用モードでClaude Codeが動作する。
方法 3 : デフォルト設定
プロジェクトの設定ファイルでプランモードをデフォルトとして設定する。
- 設定ファイルのパス
- .claude/settings.json
{
"permissionMode": "plan"
}
この設定により、プロジェクトでClaude Codeを起動すると常にプランモードで開始される。
方法 4 : ヘッドレスモードでの使用
ヘッドレスモード (非対話的な実行モード) でプランモードを使用する場合の例を以下に示す。
claude --headless --permission-mode plan --prompt "このコードベースの構造を分析して、認証システムのリファクタリング計画を立ててください"
このコマンドにより、対話なしでプランモードを実行し、結果を取得できる。
プランモード中にできること
プランモードでは、読み取り専用の操作とユーザへの質問が可能である。
読み取り専用操作
- Read
- ファイルの内容を読み取る
- コードの構造を理解する
- Glob
- ファイルパターンマッチング
- 関連ファイルの検索
- Grep
- ファイル内容の検索
- 特定のパターンの検出
- Bash (読み取り専用コマンドのみ)
ls、cat、tree等のコマンドgit log、git diff等の履歴確認
ユーザへの質問
プランモードでは、Claudeがユーザに対して質問を投げかけることができる。
- AskUserQuestion ツール
- 要件の明確化
- 設計の選択肢についての確認
- 優先順位の確認
質問の例:
- 認証方式はJWTとセッションベース、どちらを希望しますか？
- データベーススキーマの変更は許可されますか？
- 既存のテストが壊れた場合、どう対処しますか？
- この変更の優先度は高いですか、それとも段階的に実装しますか？
コードベースの分析活動
プランモードで実行できる分析活動の例を以下に示す。
- アーキテクチャの理解
- ディレクトリ構造の確認
- モジュール間の依存関係の分析
- コードパターンの調査
- 既存の実装パターンの検出
- ベストプラクティスの確認
- 影響範囲の特定
- 変更が影響するファイルのリスト作成
- リスク評価
- 依存関係の分析
- 外部ライブラリの使用状況
- 内部モジュール間の依存関係
- テストカバレッジの確認
- 既存のテストの確認
- テストが不足している箇所の特定
プランモードの終了方法
プランモードを終了して、通常の編集可能モードに戻る方法を以下に示す。
方法 1 : キーボードショートカット
プランモード中に以下のキーボードショートカットを使用して終了する。
- [Shift] + [Tab] キー
- プランモードを終了して通常モードに戻る。
方法 2 : ExitPlanMode ツール
Claudeが自動的に ExitPlanMode ツールを使用してプランモードを終了することがある。
これは、以下の状況で発生する。
- 計画が完了し、実装フェーズに移行する必要がある場合
- ユーザが実装を開始するよう指示した場合
方法 3 : セッションの終了
Claude Codeセッションを終了すると、プランモードも終了する。
/exit
または、[Ctrl] + [D] キーを押下する。
使用すべきケースと使用すべきでないケース
| 状況 | プランモード使用 | 理由 |
|---|---|---|
| 複雑なリファクタリング | 推奨 | 影響範囲の分析と計画立案が必要 |
| 新機能の追加 (大規模) | 推奨 | 設計検討と実装方法の調査が必要 |
| アーキテクチャ変更 | 推奨 | 全体的な影響の把握が必要 |
| レガシーコードの理解 | 推奨 | 安全に探索できる |
| 単純なバグ修正 | 非推奨 | 計画不要で直接修正可能 |
| 小規模な変更 | 非推奨 | 計画フェーズが不要 |
| 緊急の修正 | 非推奨 | 時間がかかりすぎる |
| 明確な実装手順がある | 非推奨 | 計画が既に立っている |
ベストプラクティス
プランモードを効果的に使用するためのベストプラクティスを以下に示す。
明確な質問を用意する
プランモードを開始する前に、明確な質問や目標を用意する。
良い例:
- 認証システムをOAuth2に移行する場合の影響範囲を分析してください
- ユーザ管理モジュールのリファクタリング計画を立ててください
- このAPIのパフォーマンス改善の方法を調査してください
悪い例:
- このコードを見てください
- 何か改善できることはありますか
インタビュー機能を活用する
Claudeに質問させることで、要件を明確化する。
プロンプト例:
- 認証システムのリファクタリングを検討しています。必要な情報を質問してください。
- この機能の実装方法について、選択肢を提示して質問してください。
Claudeは以下のような質問を投げかける。
- 現在の認証方式で何が問題ですか？
- 既存のユーザデータは移行が必要ですか？
- ダウンタイムは許容されますか？
- テストカバレッジの目標は何ですか？
フォローアップで方向性を調整する
プランモードでの分析結果に基づいて、フォローアップの質問で方向性を調整する。
フォローアップの例:
- このアプローチのリスクを詳しく分析してください
- 代替案と比較して、メリット・デメリットを整理してください
- 段階的な移行計画を立ててください
CLAUDE.md への指示を追加する
プランモード終了後に得られた知見を、プロジェクトのCLAUDE.mdファイルに記録する。
記録内容の例:
- アーキテクチャの設計方針
- コーディング規約
- 実装の優先順位
- 注意すべきリスク
これにより、今後のセッションで同じ分析を繰り返す必要がなくなる。
計画をドキュメント化する
プランモードで立案した計画を、適切な形式でドキュメント化する。
ドキュメント化の方法:
- CLAUDE.mdに計画を記録
- ADR (Architecture Decision Records) を作成
- 実装チェックリストを作成
- タスクリストを作成
ドキュメント化により、実装フェーズでの迷いを減らし、効率的に作業できる。
考慮すべき事柄
プランモードを使用する際の注意点を以下に示す。
権限モードの理解
プランモードは、Claude Codeの3つの権限モードの1つである。
| 権限モード | 説明 | 使用場面 |
|---|---|---|
| Ask (デフォルト) | 各操作前にユーザに確認を求める | 通常の開発作業 |
| Plan | 読み取り専用、変更不可 | 計画立案、調査 |
| Allow | 全ての操作を自動承認 | 信頼できる自動化タスク |
プランモードから他のモードへの切り替えは、[Shift] + [Tab] キー または 設定変更で可能である。
トークン消費
プランモードでの探索は、大量のファイルを読み込むとトークンを消費する。
トークン消費を抑えるためには、以下に示す事柄を考慮する。
- 探索範囲を明確に指定する。
- 不要なファイルは読み込まない。
- 段階的に探索を進める。
コンテキストウインドウ
プランモードでの分析結果は、コンテキストウインドウに蓄積される。
コンテキストウインドウ管理のためには、以下に示す事柄を考慮する。
- 計画が完了したら、要約を作成する。
- 不要な情報はコンパクション機能で圧縮する。
- 必要に応じてセッションを分割する。
MCPツールの利用
プランモードでは、MCPツールも読み取り専用で使用できる。
読み取り専用で使用できるMCPツールの例:
- ファイルシステム読み取りツール
- データベース読み取りツール
- API呼び出しツール (GETメソッドのみ)
書き込み操作が必要なMCPツールは、プランモードでは使用できない。
インタラクティブ性
プランモードは、インタラクティブな対話を前提としている。
ただし、以下の場合はヘッドレスモードが適している。
- 自動化されたワークフロー
- CI/CDパイプライン
- 定期的な分析タスク
インタラクティブなセッションでは、ユーザとの対話を通じて最適な計画を立案できる。
他の機能との組み合わせ
プランモードは、Claude Codeの他の機能と組み合わせて使用することで、さらに効果的になる。
Extended Thinking
Extended Thinking機能は、Claudeが長時間考慮して最適な解決策を導き出す機能である。
プランモードとExtended Thinkingの組み合わせを行う例を以下に示す。
- プランモードを開始
- Extended Thinkingを有効化
- 複雑な問題の分析を依頼
- Claudeが深く考慮して詳細な計画を立案
この組み合わせにより、複雑なアーキテクチャ設計や大規模リファクタリングの計画を高品質に立案できる。
MCPサーバー
Model Context Protocol (MCP) サーバを使用することで、外部システムとの統合が可能になる。
プランモードとMCPサーバーの組み合わせ:
- データベーススキーマの読み取り
- MCPサーバー経由でデータベース構造を取得
- プランモードで安全に分析
- API仕様の取得
- MCPサーバー経由でAPI定義を取得
- プランモードで統合計画を立案
- ドキュメントの取得
- MCPサーバー経由で社内ドキュメントを取得
- プランモードで要件を分析
Subagents (サブエージェント)
サブエージェントを使用することで、計画立案を専門化できる。
プランモード専用サブエージェントの定義例を以下に示す。
---
name: architecture-planner
description: Architecture planning specialist. Use in plan mode to design complex changes before implementation.
tools: Read, Grep, Glob, Bash
model: claude-opus-4-20250514
---
あなたはアーキテクチャ計画の専門家です。
プランモードで呼び出されたとき:
1. コードベースの構造を分析
2. 既存のパターンを特定
3. 変更の影響範囲を評価
4. 詳細な実装計画を立案
5. リスクと代替案を提示
計画には以下を含める:
- 変更が必要なファイルのリスト
- 各ファイルの変更内容の概要
- 依存関係の変更
- テスト戦略
- 段階的な実装手順
- ロールバック戦略
このサブエージェントは、プランモード中に自動的に呼び出され、専門的な計画立案を行う。
Session Resume (セッション再開)
Session Resume機能を使用することで、プランモードでの分析結果を保持できる。
プランモードとSession Resumeの組み合わせ:
- プランモードでコードベースを分析
- 詳細な計画を立案
- セッションを一時中断
- 後日セッションを再開
- 計画に基づいて実装を開始
この組み合わせにより、計画と実装を別の日に分けて作業できる。
実践例
プランモードの実践的な使用例を以下に示す。
例 1 : 複雑なリファクタリングの計画
状況
レガシーな認証システムを、JWTベースの認証システムにリファクタリングする。
プランモードでの実行手順
- プランモードを開始する。
- [Shift] + [Tab] キー
- Claudeに計画立案を依頼する。
- 認証システムをセッションベースからJWTベースに移行したい。
- まず、現在のコードベースを分析して、詳細な移行計画を立ててください。
- 必要な情報があれば質問してください。
- Claudeがコードベースを分析し、質問を投げかける。
- 現在の認証システムはどのファイルに実装されていますか？
- 既存のユーザデータは移行が必要ですか？
- JWTの署名アルゴリズムは何を使用しますか？
- トークンの有効期限はどの程度にしますか？
- リフレッシュトークンは実装しますか？
- ユーザが質問に回答する。
- 現在の実装は src/auth/ ディレクトリにあります。
- 既存ユーザは次回ログイン時に新システムに移行します。
- JWTはHS256を使用し、有効期限は1時間、リフレッシュトークンも実装します。
- Claudeが詳細な計画を立案する。
- 影響を受けるファイルのリスト
- 各ファイルの変更内容
- データベーススキーマの変更
- 移行手順
- テスト戦略
- ロールバック計画
- 計画をCLAUDE.mdに記録する。
- この計画をCLAUDE.mdに記録してください。
- プランモードを終了して実装を開始する。
- [Shift] + [Tab] キー
結果
- 詳細な実装計画が得られる
- リスクが事前に特定される
- 実装フェーズでの迷いが減る
- トークンの無駄遣いを避けられる
例 2 : OAuth2への認証システムリファクタリング
状況
既存の認証システムを、OAuth2フローに対応するようにリファクタリングする。
プランモードでの実行手順
- プランモードを開始する。
claude --permission-mode plan
- 計画立案を依頼する。
- 現在の認証システムを調査して、OAuth2対応のための詳細な計画を立ててください。
- 以下の情報が必要です:
- - 現在の認証フローの分析
- - OAuth2実装に必要な変更のリスト
- - データベーススキーマの変更
- - 既存のユーザへの影響
- - 段階的な移行計画
- Claudeがコードベースを探索する。
- src/auth/ ディレクトリの構造を確認
- 既存の認証ロジックを分析
- データベーススキーマを確認
- 依存関係を調査
- Claudeが詳細な計画を提示する。
- OAuth2プロバイダーの実装 (Authorization Server)
- OAuth2クライアントの実装
- トークンエンドポイントの実装
- 認可エンドポイントの実装
- データベーススキーマの変更 (clientsテーブル、tokensテーブル)
- 既存認証との互換性維持
- 段階的な移行手順
- 代替案を検討する。
- 既存の認証システムとOAuth2を並行稼働させる方法と、完全に置き換える方法、どちらが適切ですか？
- それぞれのメリット・デメリットを教えてください。
- Claudeが比較分析を提示する。
移行戦略の比較 戦略 メリット デメリット 並行稼働 リスクが低い、段階的移行可能 コードが複雑化、保守コストが増加 完全置き換え シンプルな実装、保守が容易 リスクが高い、ロールバックが困難 - 実装手順の詳細化を依頼する。
- 並行稼働の方針で、詳細な実装手順を立ててください。
- Claudeが段階的な実装手順を提示する。
- フェーズ1: OAuth2インフラの構築
- clients テーブルの作成
- トークンエンドポイントの実装
- 認可エンドポイントの実装
- フェーズ2: 既存システムとの統合
- 互換性レイヤーの実装
- 既存認証の維持
- フェーズ3: 段階的な移行
- 新規ユーザはOAuth2のみ使用
- 既存ユーザは次回ログイン時に移行
- フェーズ4: レガシー認証の削除
- 全ユーザがOAuth2に移行後、レガシーシステムを削除
- フェーズ1: OAuth2インフラの構築
- プランモードを終了して実装を開始する。
- この計画を元に実装を開始してください。
- [Shift] + [Tab] キー
結果
- 包括的な移行計画が得られる
- リスクが明確化される
- 段階的な実装手順が明確になる
- 実装前に代替案を比較検討できる
- 計画に基づいてスムーズに実装を開始できる
参考リンク
- Claude Code公式ドキュメント - Plan Mode
- Claude Code公式ドキュメント - Permissions
- Claude Code公式ドキュメント - Extended Thinking
- Claude Code公式ドキュメント - Subagents