Claude Codeに必要な情報だけ渡すコンテキスト設計：何を入れて何を入れないか

結論：コンテキスト設計とは「何を入れないか」を決める作業

Claude Codeの精度問題のほとんどは、プロンプトの巧拙ではなくコンテキストの設計ミスから来ています。公式のBest Practicesも**「Claude’s context window fills up fast, and performance degrades as it fills.」を全体の前提として最初に置いており、入れる工夫より入れない判断**の方が効きます。

本記事では、コンテキストを「読ませたい層／必要なときだけ呼ぶ層／読ませたくない層」の3層に分けて、それぞれにClaude Code側で公式に用意されている仕掛け（@参照／/context／/clear／/compact／サブエージェント／Skills／Hooks／コードインテリジェンスプラグイン）をどう割り当てるかを整理します。情報は2026年5月1日時点の公式ドキュメントに基づいています。

「遅い／応答が劣化した」という症状から逆引きしたい場合はClaude Codeが遅いときに確認する設定・コンテキスト・ファイル量、依頼文の組み立て方はClaude Codeに伝わるプロンプトの基本構造に整理しています。本記事は**「何をコンテキストに載せるか」の設計判断**に絞ります。

前提：コンテキストに入るもの一覧

Claude Codeのコンテキストウィンドウは、会話の全履歴を保持します。具体的にトークンを消費するものは次の通りです。

• CLAUDE.md（セッション開始時にロードされる）
• ユーザーの依頼文と過去のすべてのターン
• Claudeが@参照や明示の読み込みで取り込んだファイル全文
• Bashツールの標準出力／標準エラー全文
• MCPサーバーのツール／リソース／プロンプト定義（既定で遅延読み込み、使った瞬間に展開）
• 取り込んだ画像・PDF
• 拡張思考のトークン（出力トークンとして課金）

/contextで、いまセッション内で何が空間を取っているかが見えます。これを設計の起点にしてください。

3層モデル：何を入れて、何を入れないか

3層モデルを意識すると、「CLAUDE.mdに全部書く」「依頼文に全文貼る」のような短期最適に走らずに済みます。

読ませたい層：CLAUDE.mdは200行以内

公式のコスト最適化ガイドは**「CLAUDE.mdは200行未満を目標に」としています。理由は単純で、CLAUDE.mdは毎セッション最初にコンテキストへ読み込まれるため、肥大化させると無関係な作業のときも常に消費する固定コストになるからです。さらに、長すぎるとClaudeが半分を無視するようになる**、という公式注意もあります。

入れる／入れないの判断基準（公式表）はこうです。

CLAUDE.mdの最小／完全テンプレートはClaude Codeで最初に作るべきCLAUDE.mdの書き方とCLAUDE.mdテンプレート完全版に置いてあります。本記事は**「常時読ませる層に何を入れるか」**だけ抑えてください。

必要なときだけ呼ぶ層：Skills、サブエージェント、@参照

「特定のタスクのときだけ要る」情報はCLAUDE.mdから外し、必要な瞬間に取り込みます。手段は4つ。

1. Skills（オンデマンドのドメイン知識）

.claude/skills/<name>/SKILL.mdに置くSkillsは、関連する作業のときだけClaudeが自動で取り込むワークフロー定義です。**「PRレビュー手順」「DBマイグレーション規約」**のように、特定タスク限定の知識はここに移すのが定石。CLAUDE.mdの固定コストを増やさずに済みます。

---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)

2. サブエージェント（コンテキスト分離）

サブエージェントは別のコンテキストウィンドウで動き、終わったら要約だけ親に返します。「認証システムでトークン更新がどう実装されているか調べて」のような調査・探索は、メインのコンテキストを汚さないためにサブエージェント送りが公式推奨です。テスト実行・ログ解析・大量ドキュメントの読み込みなどverbose operationsもここへ。

詳しくはClaude Codeのサブエージェントとは？使いどころと注意点を参照してください。

3. @参照とパイプ（ピンポイント供給）

依頼文に「どこを見ろ」を書くのは書く側の仕事です。Claudeが推測で大量のファイルを開いて当てる動きほど、コンテキストを浪費するものはありません。

• @src/utils/auth.jsはファイル全文を取り込む
• @src/componentsはディレクトリの一覧を取り込む（中身は取り込まない）
• 画像はドラッグ＆ドロップまたはCtrl+Vで貼り付け
• 大きいログは前処理してから渡す（後述）

4. CLIツール（MCPより軽い）

公式が明記している通り、gh／aws／gcloud／sentry-cliのようなCLIツールはMCPより軽量です。MCPはツール定義そのものがコンテキストを取りますが、CLIならClaudeがBashで都度叩くだけ。**「MCPで増やす前にCLIで足りないか」**を先に検討してください。

読ませたくない層：先に削る、後で要約させる

入れない方が一番効きます。

Hooksで前処理する

10,000行のテストログをClaudeに丸ごと渡す代わりに、PreToolUseフックでgrep -A 5 -E '(FAIL|ERROR|error:)' | head -100に置き換える、という公式サンプルがあります。入る前に減らすのが最強です。フック自体の仕様はHooksを参照してください。

/clearをタスク境界で必ず叩く

公式がcommon failure patternとして挙げる**「kitchen sink session」――関係ないタスクを連投して文脈が泥沼化する――の唯一の解決法が/clearです。タスクが切り替わったら条件反射的に/clear**でいいくらいです。残しておきたければ/renameでセッション名を付けてから/clearし、後でclaude --resume <name>で戻れます。

/compactで要約圧縮、Esc Escで部分要約

長く続けるしかない作業では、/compact <instructions>で要約方針を指定（例：/compact Focus on the API changes）。途中だけ要約したいなら**Escを2回または/rewindでチェックポイントを選び、Summarize from hereを実行。CLAUDE.mdにコンパクション時の保持指示**（例：「変更ファイル一覧とテストコマンドは必ず残す」）を書く運用も可能です。

deny ruleと.gitignore、/sandboxで物理的に隠す

.envや認証情報はそもそも読ませない。Read denyルールと/sandboxのdenyReadの組み合わせ、加えて.gitignoreの3段防御。秘密情報の扱いはClaude Codeに秘密情報を渡さないための実践ルールに集約しているので、ここでは「コンテキスト設計の最終防衛線」とだけ覚えてください。

アンチパターン4選

公式が明示しているもの＋実務でよく踏むものを4つに絞ります。

アンチパターン1：CLAUDE.mdに全部書く

If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise.

200行を超えてきたら、「特定タスク限定」のものはSkillsへ、「ファイル単位の差分」はpathsフロントマターを使った.claude/rules/分割へ。

アンチパターン2：いきなり全文貼り付け

エラーログ・画面の長文・OpenAPI仕様などをまるっと貼ると、1ターンで数千～数万トークン消えます。先にgrep／head／jqで絞るか、Hooksで前処理するか、サブエージェントに渡して要約だけ返させる、のいずれかを選びます。

アンチパターン3：「いい感じに調べて」型の無限探索

The infinite exploration. You ask Claude to “investigate” something without scoping it. Claude reads hundreds of files, filling the context.

公式のFix：スコープを絞るか、サブエージェント送りにする。「src/auth/配下だけ」「失敗テスト1件だけ」のように対象を必ず限定してください。

アンチパターン4：MCPサーバーを“とりあえず”入れる

MCPツール定義はそれ自体がコンテキストを取ります（既定ではtool searchで遅延読み込みされますが、ツール名は載ります）。しかもサブエージェントは親のMCPツール定義を全継承するため、関係ない作業でもオーバーヘッドが乗ります。/mcpで使っていないサーバーは無効化するのが習慣。詳細はClaude CodeとMCPサーバーの基本に。

設計テンプレート：1依頼分のコンテキスト予算

依頼を投げる前に、頭の中で次のように予算配分してから書きます。慣れると数秒で終わります。

これで埋まらない欄があるなら、その依頼はまだ大きすぎるサインです。大きな開発タスクをClaude Codeに渡す前の分解方法で先に小さくしてから戻ってきてください。

投げる前の30秒チェックリスト

• **/context**でいまの占有を見た（直前のセッションの残骸が居座っていないか）
• 触るファイルを**@参照で2〜5件**だけ明示した（広すぎないか）
• エラーログや出力は事前にgrep／head／jqで絞った
• CLAUDE.mdは200行以内、特定タスクの手順はSkillに切り出した
• 調査が大きいときはサブエージェント送りにした
• MCPは使うものだけ有効、それ以外は/mcpで無効化
• タスク境界に**/clear**を入れた／長く続くなら/compact方針を書いた
• 秘密情報・.envはdeny ruleで物理的にブロックした

このチェックリストをCLAUDE.md末尾に貼っておけば、次の依頼から自動で守られます。

次に読むべき記事

• Claude Codeに伝わるプロンプトの基本構造
• Claude Codeが遅いときに確認する設定・コンテキスト・ファイル量
• 大きな開発タスクをClaude Codeに渡す前の分解方法