Claude Code Plan Mode 完全活用ガイド — 大規模変更を安全に進める計画フェーズの作り方
Claude CodeのPlan Modeを使いこなすための実践ガイド。大規模リファクタ・新機能追加・デバッグでの計画フェーズの作り方、良い計画と悪い計画の違い、ExitPlanModeの判断基準を実例付きで解説。
エンジニアのゆとです。
Plan Modeの基本操作については以前書いた記事がある。
あれを書いてから数ヶ月、実際に「複雑な作業」でPlan Modeを使い続けてわかってきたことがある。
基本操作（Shift+Tabで入る、計画が出てくる、いいね、進めてと言う）は誰でも使える。問題はここからで、「使える」と「うまく使える」の間には、思ってたより大きい溝がある。
Plan Modeを使っても思った通りにいかない理由のほとんどは、「計画フェーズの設計を間違えている」ことにある。
この記事では、「どういう計画が良い計画か」「失敗パターンはどれか」「大規模作業で安全に進めるためのフロー設計」を書く。「使い方」よりも「どう使うか」の話だ。
Plan Mode の役割を正確に理解する
Plan Modeはよく「実装前に計画を見せてくれる機能」と説明されるが、それは正確じゃない。
正確に言うと、Plan Modeは「Claude Codeが理解した内容を確認するためのインターフェース」だ。
「計画を見る」じゃなくて「Claudeの理解を検査する」という目的で使うと、活用の仕方が変わる。
具体的にはこういうことだ。Claude Codeに「ユーザー認証をJWT→Cookieベースに変更してほしい」と言ったとする。Plan Modeなしでいきなり実装させると、実装が終わったあとに初めて「あ、ここの理解がズレていた」とわかる。
Plan Modeを使うと、Claudeの理解（どのファイルを変更する予定か、どういう順序でやるか、何を前提にしているか）を実装前に見られる。ここで「この前提が違う」「このファイルは触らなくていい」と修正できる。
Plan Modeの真の価値は「計画を先に見られること」ではなく「手戻りが起きる前にズレを検出できること」にある。
使うべき状況、使わなくていい状況
全部のタスクでPlan Modeを使う必要はない。過剰に使うと「計画確認というモード切り替えコスト」が積み上がって、かえって遅くなる。
Plan Modeを使うべき状況：
- 変更が3ファイル以上にまたがる
- 既存の挙動に依存している部分がある（リファクタリング、API変更等）
- 「どこまで変更するか」の境界線が曖昧
- 本番に影響するコードを触る
- 後戻りのコストが高い（DBスキーマ変更、外部APIのインターフェース変更等）
使わなくていい状況：
- 単一ファイルのバグ修正
- 新規ファイルの追加（既存コードへの影響がない）
- ユニットテストの追加
- コメント・ドキュメントの更新
- 「やってみてダメだったら直せばいい」規模の変更
判断が難しいときは「実装を間違えたときのリカバリコストはどれくらいか」で決める。リカバリが30分以内で済むなら、Plan Modeなしで進めてOKだ。
良い計画 vs 悪い計画の違い
Plan Modeが返してくる計画の「質」にはバラつきがある。質が低い計画をそのまま進めると、手戻りが発生する。
悪い計画の典型3パターン パターン1: 粒度が粗すぎる悪い例:
1. ユーザー認証の実装
2. テストの修正
3. デプロイ設定の更新これはただの目次であって計画じゃない。「何を変えるか」が書かれていない。このまま進めると、実装中にClaudeが「どっちの方向でやるか」の判断を随時行うことになり、一貫性がなくなる。
パターン2: 前提が明記されていない悪い例:
2. JWTトークンをCookieに移行する
- auth/jwt.ts の verify 関数を修正
- middleware/auth.ts を更新「既存のセッションはどう扱うか」「トークンの有効期限の設計は変わるか」「クライアント側も変更があるか」が書かれていない。Claudeが暗黙の前提で動くと、後で「なんでそうした？」となる。
パターン3: 依存関係の順序がおかしい悪い例:
1. auth/jwt.ts を削除
2. auth/cookie.ts を新規作成
3. 既存テストを修正ステップ1で削除すると、ステップ3でそのファイルを参照しているテストが全部壊れる。壊れた状態でステップ2を進めることになる。作業中に「テストが全部落ちている状態」が続くのは心理的にしんどいし、中断したときにどこまで進んだか分からなくなる。
良い計画の特徴：
良い例:
前提条件の確認:
- 現在 JWT は Authorization header で渡している（Bearer方式）
- cookieドメインは api.example.com に限定予定
- 移行期間中は JWT/Cookie 両方をサポートする（フラグ切り替え方式）
変更ファイル一覧（変更順）:
1. auth/cookie.ts（新規作成）: setCookie/getCookie/clearCookie の実装
2. middleware/auth.ts（既存修正）: JWT検証に加えてCookie検証も追加。フラグで切り替え
3. auth/jwt.ts（既存修正）: 削除はしない。deprecation コメントを追加
4. tests/auth.test.ts（既存修正）: Cookie認証のテストケースを追加
5. .env.example（既存修正）: AUTH_METHOD 環境変数を追加
削除しないもの:
- auth/jwt.ts は残す（移行後に別PRで削除予定）
- 既存のJWTテストは削除しない（移行期間中は両方のテストを維持）前提条件・変更ファイル一覧・削除しないもの、この3つが明記されている計画は信頼できる。
計画フェーズを「良くする」対話の技術
Plan Modeで最初に出てきた計画が良くない場合、そのまま進めてはいけない。計画を改善するための対話を行う。
対話のパターンをいくつか：
前提の明示を求める「この計画の前提として何を仮定しているか、箇条書きで出して」Claudeが暗黙で前提にしていることを表面化させる。これで「あ、そこは違う」という発見ができる。
変更範囲の境界を確認する「変更する予定がないファイルを列挙して。意図して変更しないものを確認したい」変更するもの一覧だけでなく、「変更しないもの」も明示させる。境界が明確になると、スコープクリープを防げる。
リスクを出させる「この計画を実行したときに失敗しうるポイントを3つ挙げて。それぞれの対策も」「上手くいく前提」だけで書かれている計画は脆い。失敗シナリオを先に出させると、リスクへの対処が計画に組み込まれる。
段階的コミット可能かを確認する「この計画を、動作する状態のままコミットできる区切りに分けてほしい。各ステップがtestabeであることを条件に」大きな変更を一気にやると、途中でコミットできない状態が長続きする。各ステップを「それ単体でテストが通る」単位に分けると、何かあったときに切り戻しやすい。
大規模リファクタリングでのフロー設計
「全部のAPIレスポンスをsnake_caseからcamelCaseに変える」みたいな横断的変更の場合、Plan Modeの活用が特に重要になる。
実際にやったフローを紹介する。
ステップ1: 影響範囲の洗い出し（Plan Modeで）「snake_caseを使っているAPIレスポンス定義がどのファイルに存在するかを調べて、一覧を出して。
まだ変更はしないで、影響範囲の把握だけ行って」Plan Modeで出てきたファイル一覧を見て、想定外に多い/少ないものをチェックする。「このファイルも含まれるの？」という発見がここでできる。
ステップ2: 変更順序と方針の確定（Plan Modeで）「影響ファイルを確認した。変更の方針として以下を前提にして計画を立て直してほしい:
- まず型定義ファイル（types/）を先に変える
- 次にAPIレスポンスを生成する部分（controllers/）
- クライアント側（pages/、components/）は最後
- 各フェーズでテストが通ることを確認しながら進める」方針を言語化してClaudeに渡すと、計画がその制約を満たす形になる。「なんとなくやる」より変更の一貫性が上がる。
ステップ3: フェーズ1だけを実行（Plan Modeを抜ける）計画が固まったらフェーズ1だけを実行させる。全部一気にやらせない。
「計画のフェーズ1（types/のみ）を実行して。完了したらテストを回して、全部通ることを確認してから報告して」これを繰り返すことで、「大きい変更を安全な単位に切って進める」ができる。
ステップ4: 各フェーズ完了でコミット# フェーズ1完了のコミット
git commit -m "refactor: snake_case → camelCase の型定義を更新"
# フェーズ2完了のコミット
git commit -m "refactor: APIレスポンス生成をcamelCase対応に変更"途中でコミットを積んでいくと、「どこまで進んだか」と「何かあったときの切り戻しポイント」が明確になる。
新機能追加での計画フェーズ
バグ修正やリファクタより、新機能追加でPlan Modeが特に有効なシーンがある。「どこに何を追加するか」の設計判断が、実装後に変えるのが難しい部分に影響するからだ。
実例として「Webhookの受信エンドポイントを追加する」タスクでやったフロー：
最初にアーキテクチャを確定する（Plan Modeで）「WebhookのPOSTエンドポイントを /api/webhooks/stripe に追加したい。
実装前に以下を教えて:
1. 既存のroutes/の構造とどう整合させるか
2. Webhook署名検証のロジックはどこに置くのが適切か（middleware/かutils/か）
3. 非同期処理が必要な場合、キューはどう設計するか
4. 型定義は types/webhook.ts を新規作成するか、既存の types/api.ts に追加するか」このように「選択肢があるポイント」を明示してPlan Modeで聞くと、Claudeが判断根拠も含めて返してくる。判断を委ねるより、「選択肢を出してもらって人間が判断する」の方が精度が上がる。
実装方針を確定してから実行へClaudeの提案を受けて「これとこれで行こう」という判断をしてから、Plan Modeを抜ける。
「わかった。以下の方針で進めて:
- 署名検証はmiddleware/webhook-signature.tsに分離
- 型定義はtypes/webhook.tsを新規作成
- 非同期処理は今回は同期でいい（キューは次フェーズで追加）
- まずルーティングと署名検証だけを実装して、実際のビジネスロジックはTODOで置いておいて」「全部一気に実装して」より「まずここまで」という指定の方が、意図と合った実装が返ってくる。
ExitPlanMode のタイミング判断
「計画を見た、じゃあ実行させよう」のタイミングをどう判断するか。
実行に移していいサインは：
- 変更するファイルの一覧を見て、想定外のものが含まれていない
- 前提条件が明示されており、それが実際の状況と一致している
- 変更の順序が依存関係を考慮している（Aを壊してからBを直すような順序になっていない）
- 「削除するもの」「変更しないもの」が意図と一致している
もう少し計画を詰めた方がいいサインは：
- 変更ファイル数が予想より多い（スコープが広がっている可能性）
- 「〜する予定です」「〜が必要かもしれません」という不確定表現が多い
- 前提条件が明示されていない
- 「あとで対応する」という先送り項目が複数ある
一度実行に移して「やっぱり計画が違った」と気づいた場合は、作業を止めて Shift + Tab でPlan Modeに戻る。「今のコード状況を踏まえて計画を修正してほしい」と言えば、現状から再計画してくれる。
チーム開発でのPlan Mode活用
ひとりの作業でも有効だが、チームでClaude Codeを使う場合にPlan Modeが追加の価値を持つシーンがある。
レビュー前に計画を共有する実装前にPlan Modeで出力した計画をそのままPRの説明文に貼る。「何をどう変えるか」がレビュアーに伝わりやすくなる。
ペアプロ的な使い方「これどう実装する？」という設計議論の代わりに、Plan Modeで計画を出して人間2人でその計画を検討する。Claude Codeが計画のたたき台を作ってくれるので、0から設計を議論するより効率がいい。
タスク引き継ぎの際「ここまで実装した、続きをお願い」の引き継ぎで、受け取る側がPlan Modeで「現状の理解と残りの作業計画」を出させる。前の人が何をしたかを理解してから続きを実装できる。
Plan Modeを使って気づいたこと
Plan Modeを3ヶ月使ってわかったのは、「良い計画を引き出す質問を作れるかどうか」が全てだということだ。
「計画を立てて」と言えば計画は出てくる。でもそれは「Claudeが思う計画」であって、「自分がやりたいこと」と必ずしも一致しない。
よい計画を引き出すには、「自分がやりたいことの制約・前提・優先順位」を言語化してClaudeに渡す必要がある。これはPlan Mode以前の話で、要求を言語化するスキルの問題だ。
Plan Modeを使い始めると、「自分の要求がどれだけ曖昧だったか」が可視化される。これが副次的な効果として一番大きかった。
FAQ
Claude Code の Plan Mode はどうやって起動する？
セッション中に Shift+Tab を押すと permission mode が切り替わる（default → acceptEdits → plan）。または起動時に claude --permission-mode plan を指定。Plan Mode 中は read-only（Read/Glob/Grep/WebFetch/WebSearch のみ）で、Write/Edit/Bash は無効化される。計画提示後に ExitPlanMode で通常モードに戻る。
Plan Mode と通常モードの一番大きな違いは？
Plan Mode はファイルを書き換えないこと。Read系ツールでコードベースを読み込み、計画を Markdown 形式で提示するだけ。これにより「探索→計画→承認→実装」の流れが強制される。Plan Mode は 計画段階で軌道修正できる のが本質的な価値。
claude --permission-mode acceptEdits と plan の使い分けは？
acceptEdits は 「全部許可」：ファイル編集の承認プロンプトをスキップして自動実行。plan は 「実行禁止」：計画提示だけで実装はしない。両極端なので使い分け：(1) 試行錯誤フェーズで小さな変更を繰り返す → acceptEdits、(2) 大規模変更前の設計段階 → plan、(3) 通常の対話 → default。
ExitPlanMode を押すタイミングの判断基準は？
3つすべて満たしたら ExitPlanMode：(1) 計画が具体的（「authMiddleware.ts の lines 23-45 を…」レベルまで掘られてる）、(2) 影響範囲が明確（変更ファイル一覧 + 既存テストへの影響）、(3) 自分の優先順位と一致（後方互換性？パフォーマンス？読みやすさ？のどれを優先するか合意済み）。1つでも欠けていたら追加の質問で計画を磨く。
計画が悪いと感じたとき、Plan Mode 中にどう直す？
追加の文脈を投げる。「実は X というファイルが他チームの所有で触れない」「パフォーマンス劣化を避けたい」「テストが弱いので変更前にテスト追加してほしい」といった制約を Plan Mode 中に追加すると、Claude が計画を 更新版 で再提示してくれる。何度でも往復可能。ExitPlanMode を急がない こと、これが Plan Mode を活かす最大のコツ。
Plan Mode は他の Subagent と組み合わせられる？
組み合わせ可能。Plan Mode 中の調査は Plan 内部 subagent に委譲されているのが Claude Code の設計。手動で Explore subagent を呼んで「このディレクトリ構造を調べて」と委譲すれば、その結果を踏まえて Plan Mode の計画が組み立てられる。ただし Plan Mode 中は新しい subagent spawn が制限されることがあるので、調査は Plan に入る前にやっておくのが安全。
Plan Mode で提示された計画をそのまま PR description にできる？
できる、かつ推奨。Plan Mode 出力は Markdown フォーマットで構造化されている（「変更ファイル一覧」「変更内容」「リスク」など）ので、そのまま GitHub PR の Description に貼ると レビュアーが計画段階で疑問を投げられる。「実装は問題ないが、そもそもこの設計は…」を防げる。
大規模リファクタリングで Plan Mode を使うコツは？
3段階に分ける：(1) 現状理解 Plan（既存コードの構造把握、依存関係マップ）→ 一度終了、(2) 設計 Plan（新しいアーキテクチャ提案、移行戦略）→ 人間レビュー、(3) 実装 Plan（具体的なファイル別変更内容、ステップ分割）→ ExitPlanMode → 実装。1度の Plan Mode で全部やろうとすると計画が浅くなる。
Plan Mode の結果をどう保存する？
3パターン：(1) そのままチャット履歴（同セッション内で参照可能、/compact で消える可能性あり）、(2) .claude/plans/<task-id>.md にClaudeに保存させる（永続化、チームと共有可）、(3) PR description / Issue 本文 に貼る（GitHub上で永続化、レビューと一体化）。
関連記事
