Plan modeはClaude Codeがタスクを実行する前に考え抜くための機能として登場した——大規模なリファクタリングや危険なマイグレーション、ファイルが変わり始める前にアプローチを確認したい場面で役立つ。しかし、あまり知られていない使い方が静かに価値を発揮している：CLAUDE.mdを書く前にその設計に使い、既存のものが長くなりすぎる前に監査する用途だ。
核心的なアイデアは、Claudeのプランニングパスをデザインレビューとして活用することだ。CLAUDE.mdで達成したいことを説明し、何を入れるべきかプランを立てるよう依頼し、1行も書かないうちにプランに応答する。結果として得られるのは、トップダウンでゼロから書いたものよりも構造が整い、矛盾が少なく、ノイズが少ないCLAUDE.mdだ。
CLAUDE.mdが壊れる理由
ほとんどのCLAUDE.mdは良いアイデアとして始まり、時間とともに問題を蓄積する：
仕様の肥大化: エージェントが何か間違えるたびに、誰かがそれを防ぐルールを追加する。半年後には40のルールがあり、エージェントは数週間前から関係なくなった指示にコンテキストを費やしている。
内部矛盾: ルールAは「関数型プログラミングパターンを好む」と言う。ルールBは「すべてのビジネスロジックはクラスベースサービスを使う」と言う。どちらも別々の時期に別々の人が追加した。エージェントはどちらかを選ばなければならないが、どちらを選ぶかは常に予測できるわけではない。
スコープの曖昧さ: 1つのコンテキスト向けに書かれたルールがグローバルに適用される。TypeScriptエラーハンドリングのルールがシェルスクリプトに適用される。Reactコンポーネントのルールがデータベースマイグレーションファイルに適用される。
根拠の欠如: 文脈なしのルールは侵食される。「anyを使わない」は誰かが急いでいるときに// @ts-ignoreで回避される。なぜそのルールが存在するかの説明がないからだ。
Plan modeはこれらすべてを、エージェントを悪化させているCLAUDE.mdに埋め込まれる前に表面化する。
プランニングワークフロー
ワークフローには2つのフェーズがある：新規CLAUDE.mdのための設計プランニングと、既存ファイルの監査プランニング。
フェーズ1: 設計プランニング（新規ファイル）
Claude Codeとの会話を開始し、/planでplan modeに入り、プロジェクトの説明を与える：
/plan
Node.js APIプロジェクトのCLAUDE.mdを設計する必要があります。コンテキスト:
- Fastifyフレームワーク、TypeScript strictモード
- Drizzle ORM経由のPostgreSQL
- テストはJest（来四半期にVitestに移行予定）
- 開発者3名、シニアとミドルの混在
- 主な問題点: 一貫しないエラーハンドリング、開発者がmainに直接プッシュすることがある、
テストカバレッジが6ヶ月で80%から60%に低下
このCLAUDE.mdにはどんなセクションが必要ですか？各セクションについて説明してください:
1. どの問題を解決するか
2. どんな情報を入れるか
3. 何を省くか（理由も含めて）
実際のCLAUDE.mdはまだ書かないでください——構造のプランだけでOKです。Plan modeの回答（要約）：
## 提案するCLAUDE.md構造
### 1. Commands（必須——常に含める）
問題: エージェントはビルドコマンドを推測しなければならないとき、コンテキストを無駄にして
ミスを犯す。
含める: ビルド・テスト・リント・型チェック・devサーバーの正確なコマンド。
省く: 環境セットアップ（冗長で頻繁に変わる）、デプロイ（エージェントはこれをすべきでない）。
注意: 来四半期にVitestへの移行を予定していると書いてあります。テストコマンドが変わります。
移行期間中にエージェントが混乱しないよう、CLAUDE.mdにインラインコメントかメモを追加することを
検討してください。
### 2. Code Style
問題: コードベース全体でTypeScriptパターンが不統一。
含める: strictモードの記載、具体的なパターン（エラーハンドリングスタイル、インポート規則、
ルートとサービスの命名規則）。
省く: TypeScriptやESLintが既に強制している一般的なベストプラクティス——
.eslintrcが処理するなら「セミコロンを使う」とエージェントに伝える必要はない。
### 3. アーキテクチャ上の制約
問題: 「mainに直接プッシュすることがある」はアーキテクチャ/プロセスの混乱を示唆している。
含める: レイヤールール（ルートがサービスを呼ぶ、サービスがリポジトリを呼ぶ）、
保護パス（マイグレーションディレクトリなど）、ブランチ戦略。
省く: アーキテクチャの根拠——それは別のADRに属するもので、CLAUDE.mdではない。
### 4. エラーハンドリング（痛点として挙げたため）
問題: コードベース全体で一貫しないエラーハンドリング。
含める: 使うべき具体的なエラークラス、必須エラーフォーマット、どこでキャッチしどこでスローするか。
省く: 一般的なエラーハンドリング哲学——エージェントにはパターンを与え、理由は省く。
### ⚠ 気づいた潜在的な矛盾:
- 来四半期のVitest移行を述べています。CLAUDE.mdに基づいてエージェントがVitestのインポートと
構文を使い始めても、コードベースがまだJestなら、テストが失敗します。
決めてください: 移行完了までCLAUDE.mdをJestのままにするか、移行ルールを明示するか。
### ⚠ 省くべきもの:
- CI/CDパイプラインの詳細（エージェントはデプロイしない）
- データベーススキーマのドキュメント（別ファイルに置きCLAUDE.mdから参照する）
- 人間の開発者向けオンボーディングドキュメント（対象読者が違う）
この構造に基づいてCLAUDE.mdを書きますか？これがプランニングパスの有用な部分だ：矛盾の検知（「Vitest移行を述べています……今決めてください」）とスコープの刈り込み（「エージェントはデプロイしない——省いてください」）。これらはCLAUDE.mdをトップダウンで書く場合には現れない洞察だ。
フェーズ2: 監査プランニング（既存ファイル）
既存のCLAUDE.mdファイルには、プロンプトが異なる：
/plan
現在のCLAUDE.mdを添付します（以下に貼り付け）。変更を加える前に監査してほしいです。
各セクションまたはルールを以下に分類してください:
- KEEP: 必須で適切にスコープされており現在も正確
- TRIM: 正しいが過剰仕様または冗長
- REMOVE: 関連性がなくなった、別の場所で処理されている、または広すぎる
- CONFLICT: このファイル内の別のルールと矛盾している
- CLARIFY: 実行可能なほど具体的でない
まだ何も書き直さないでください。分類された監査結果だけでOKです。ここでのプランニングパスは、編集を始める前のセカンドオピニオンとして機能する。重要なのは編集なしに分類を得ることだ——何を変えるか決める前に何が問題かを理解したい。
具体的なテクニック
「これはXに当てはまるか？」テストでスコープ肥大化を特定
plan modeで、各ルールを通常とは異なるファイルタイプに当てはめるよう依頼する：
/plan
CLAUDE.mdから5つのルールを以下に示します。各ルールについて教えてください:
- 明らかに当てはまるファイルタイプ
- 書き方的に当てはまるべきではないが当てはまってしまうファイルタイプ
- ルールにスコープが必要かどうか
ルール:
1. 常にnamed exportを使い、default exportは使わない
2. エラーはResult<T, E>型として返し、throwしない
3. バウンダリーレイヤーですべての入力を検証する
4. 変数はcamelCase、型はPascalCase
5. すべてのパブリック関数にJSDocコメントを追加よくある発見：「throwしない」はサービスレイヤー関数には合理的だが、シェルスクリプトユーティリティでは機能しない。「すべてのパブリック関数にJSDoc」はライブラリには適切だが、3ファイルのユーティリティスクリプトには適切でない。
矛盾の検知
/plan
以下のルールをレビューして、ルールAに従うとルールBに従うことが不可能になる
論理的矛盾または不可能な組み合わせを見つけてください:
[CLAUDE.mdを全文貼り付け]
論理的矛盾と満たせない組み合わせのみに集中してください。
新しいルールの提案や改善点の提示はしないでください——矛盾を見つけるだけでOKです。根拠の抽出
Plan modeはルールの内容から追加された理由を推測するのが得意だ。それを使って、インラインコメントとしてより良い根拠を書ける：
/plan
以下のルールそれぞれについて、追加された最も可能性が高い理由を推測してください
（誰かが防ごうとした問題は何か？）。次に、インラインで追加できる
「なぜ重要か」という一文のコメントを提案してください。
ルール: [ルールを貼り付け]Plan Modeでできないこと
プランニングはゼロから書くよりも優れているが、限界もある。Plan mode中のClaudeは提供されたテキストから作業している——実際のコードベース、チームの実際の挙動、各ルールにつながった具体的な事件を知らない。プランニングパスは構造的な問題を表面化するが、文脈的な問題は表面化しない。
「関数型パターンを使う」と「クラスベースサービスを使う」の矛盾は検知される。「テストでsetTimeoutを使わない」と書かれていてもVitestのフェイクタイマーが意図された代替であることは検知されない——それは人間の判断が必要な知識のギャップだ。
有用なフレーミング：plan modeは構造的なレビュアーであり、ドメインエキスパートではない。構造にはplan modeを使い、内容には自分の知識を適用する。
トークンバジェットの考慮
書く前にプランニングすることの具体的なメリット：プランニングを通じて設計されたCLAUDE.mdファイルは、直接書いたものより短くなる傾向がある。プランニングパスは、エージェントが知る必要のないESLint/Prettier/TypeScript設定と重複するルールを一貫して特定する。ある事例では、600行のCLAUDE.mdに対してplan modeで監査を実行したところ、内容の40%がツールと重複しているか正確でなくなっていると判明した——結果として得られた360行のファイルは実際により良く機能した。エージェントがノイズに費やすコンテキストが減ったからだ。
CLAUDE.mdを2000トークン以下に抑えようとしている（コードコンテキストのためのスペースを残す合理的な目標）なら、プランニングパスが重要なものをすべて残しながら予算内に収まる最も信頼できる方法だ。