2026.05.02

コンテキストの設計｜「Claudeがすぐ使えなくなる」を解決する

Claude Codeでの自動化において、「トークン不足で作業が止まる」「長時間の使用で回答精度が落ちる」「CLAUDE.mdを育てたら挙動が不安定になった」といった課題に直面することがあります。

これらはすべて、コンテキストの設計が追いついていないサインです。解決策はプロンプトの改善ではなく、コンテキストそのものを設計するという発想の転換にあります。それがコンテキストの設計＝コンテキストエンジニアリングです。

この記事でわかること：

コンテキストエンジニアリングの定義と重要性
環境を崩壊させるアンチパターンと解決策
コンテキストの5層構造と役割分担の設計
既存環境のリファクタリング手順

「AIにどう指示するか」から「AIが活躍できる環境をどう整えるか」へ視点が変わることで、指示のやり直しが消え、複雑な作業も最後までスムーズに任せられるようになります。

コンテキストエンジニアリングとは

コンテキストエンジニアリングとは、AIエージェントが正確にタスクを完遂できるよう、読み込ませる情報の「量」と「配置」を最適化する設計手法です。Claude Codeは、過去の会話履歴やプロジェクト内のファイルをすべてコンテキストとして保持し、それをもとに応答を生成しています。

そのため、情報の整理を行わずに自動化の範囲を広げ続けると以下の問題が発生します。

トークンの枯渇（作業の強制停止）

コンテキストウィンドウの上限に達し、エラーや作業の強制終了が発生する状態
アテンションの分散（回答精度の劣化）

コンテキスト内の情報量が増えすぎて、重要な指示への注目度が下がる状態
文脈の忘却（Context Rot）

セッションが進むにつれて、初期に与えたルールが無視される現象

Claude Codeでの業務自動化をエラーなく成功させるには、プロンプトの書き方よりも先に、コンテキストの設計を理解しておく必要があります。

プロンプトエンジニアリングとの違い

プロンプトエンジニアリングが「どう聞くか」の技術だとすれば、コンテキストエンジニアリングは「何を見せてから聞くか」の設計です。

	コンテキストエンジニアリング	プロンプトエンジニアリング
対象	セッション全体の情報設計	1回の指示文
管理	設計・実行・運用を通じた継続管理	送信前の一度きり
目的	継続的な高精度の維持	良い回答を引き出す

コンテキストウィンドウとは

コンテキストウィンドウとは、AIが一度に保持・処理できる情報の許容量を指します。Claude Codeのコンテキストウィンドウは、以下の領域で構成されています。

図：コンテキストウィンドウとは - AIが保持できる情報の範囲

System Prompt + Tools：

CLAUDE.mdなどの基本ルールを含む、システムが使用するデータです。
Custom Agents：

Skillsやサブエージェントの指示です。
Messages：

ユーザーの指示、Claudeの応答、ツール実行結果などの会話履歴です。
Buffer：

AIが思考を維持するためにあえて空けておく、予約済みの余白領域です。

セッションが長くなるほどこれらが積み上がり、コンテキストを圧迫します。

Attention Dilution（注意希薄化）による精度低下

Attention Dilutionとは、コンテキスト内の情報量が増えるほどAIの注意力が分散し、指示の見落としや回答の誤りが発生しやすくなる現象です。

Claude Codeの実測では、コンテキスト使用量が40%を超えた時点から品質劣化が始まるとされています。トークンが満杯になる前から、静かに性能低下は進行しています。

Context Rot（文脈の忘却）

Context Rotとは、セッションが進むにつれて、初期に与えた重要なルールや指示がAIの注意から外れてしまう現象です。「最近Claudeの回答がズレてきた」と感じる場合、Attention DilutionまたはContext Rotが起きている可能性があります。

日本語コンテンツのトークンコスト

日本語は英語と比較して、1文字あたりのトークン消費量が2〜3倍です。同じ指示でも日本語で記述するとコンテキストウィンドウを早く圧迫するため、CLAUDE.mdなどの常駐ファイルは指示を厳選する必要があります。

コンテキスト崩壊を招く「3つのアンチパターン」と解決策

コンテキスト崩壊とは、情報の配置ミスによってClaude Codeの回答精度やセッション持続性が低下する状態です。原因には共通した3つのパターンがあります。

アンチパターン1：情報の重複配置

情報の重複配置とは、同じ指示やルールをCLAUDE.mdとサブエージェントの両方など、複数の場所に記述してしまう状態です。

やりがちな失敗例：

CLAUDE.md
→「変数名はcamelCaseで統一する」

サブエージェントプロンプト
→「変数名はsnake_caseで統一する」

ファイルごとの役割が未整理な状態でルールを追加すると、Claudeがどちらを信頼すべきか判断できず、「なぜか指示通りに動かない」という状態の原因になります。

解決策：情報は必ず1箇所に集約する

次のように、指示や情報を１箇所に集める構造にします。

CLAUDE.md        → 命名規則を1箇所で定義
サブエージェント → 「命名規則はCLAUDE.mdに従う」

アンチパターン2：コンテキストの過積載

コンテキストの過積載とは、現在のタスクに不要なファイルや長すぎる指示を、AIに一度に大量に読み込ませてしまう状態です。

やりがちな失敗例：

1,000行のソースファイルの丸ごとRead
500行超のCLAUDE.md
セッション序盤からの複数スキルの同時呼び出し

解決策：Just-in-Time Loadingの切り替え

Just-in-Time Loadingとは、必要な情報を必要なタイミングでのみ渡す設計手法です。以下のように情報の種類ごとにロードタイミングを分けます。

情報の種類	ロードのタイミング
プロジェクト全体のルール	常駐（CLAUDE.mdに最小限で記述）
特定タスクの手順	タスク開始時にスキルとして呼び出し
ファイルの内容	該当箇所のみ・必要な瞬間だけ
調査・リサーチ結果	サブエージェントに委任し要約のみ受け取り

CLAUDE.mdとSkillsの使い分けについては以下の記事で詳しく解説しています。

関連記事：CLAUDE.mdとSkillsの違い >>

アンチパターン3：密結合設計（変更が連鎖する構造）

密結合設計とは、CLAUDE.mdや各スキル、エージェントへの指示が互いに強く依存し合っている状態です。

やりがちな失敗例：

スキルAがスキルBの存在を前提にした処理の記述
CLAUDE.mdへのサブエージェントの詳細手順の混在
特定エージェント専用の指示のCLAUDE.mdへの記述

解決策：各要素を独立したユニットとして設計する

各ファイルが「それ単体で意味をなす」状態を保ちます。あるスキルを削除・変更しても、他のスキルやCLAUDE.mdへの影響がゼロである状態が理想です。

コンテキストの5層構造と役割分担

Claude Code環境のコンテキスト運用のベストプラクティスを統合すると、以下の5層に整理できます。どこに何を書くかの判断が曖昧なまま運用すると、上記の3つのアンチパターンが自然発生します。

役割（層）	配置場所	記述すべき内容
① 全体ルール	`CLAUDE.md`	プロジェクト共通のルール、禁止事項、技術スタック
② 役割定義	サブエージェント	各エージェントの専門知識、固有の制約
③ 実行手順	`.claude/commands`	再利用可能なタスクの実行手順、チェックリスト
④ 実装コード	ソースコードファイル	実際のプログラム、最新のビジネスロジック
⑤ 設計ドキュメント	ドキュメントファイル	プロジェクトの全体構造、設計意図、背景情報

どこに書くかの判断フロー：

情報の最適な配置場所を判断するための基準は以下の通りです。

プロジェクト全体に共通するルール： CLAUDE.mdへの集約
特定のタスクを実行する際のみ必要な手順： skill（.claude/commands）への切り出し
特定のサブエージェントのみが参照する制約： 個別プロンプトへの分割
複数の場所に存在する同じ内容： 1箇所への統合と他からの参照

既存環境のリファクタリング手順

今まで育ててきた環境を改善して、Claude Codeの質を向上させるための手順を紹介します。

Step 1：`/context` で現状把握

まず /context コマンドを実行し、コンテキストの内訳を確認します。

図：/context の実行結果 - コンテキストの状態を把握する

実行結果から、次の方法で対処します。

確認項目	判断基準	次のアクション
CLAUDE.mdのトークン量	5,000トークン超	Step2-3で対処
会話履歴の割合	全体の50%超	`/compact` 実行事例を参照
ツール実行結果の量	大量に蓄積	Step4で対処

Step 2：CLAUDE.mdの適正化

CLAUDE.mdを開き、以下を順番に確認します。

他ファイルとの重複記述の有無
今は使っていない古い指示の残留
Claudeが当然知っている汎用ルールの混入
200行・5,000トークン超過の有無

削除の判断軸は「このプロジェクト固有の情報かどうか」の1点です。

Step 3：skillへの切り出し

CLAUDE.mdに書かれた「特定タスクでしか使わない手順」を .claude/commands/ のskillファイルに移動します。

移動前：CLAUDE.mdにPR作成手順が50行
移動後：.claude/commands/create-pr.md に50行
→ /create-pr を呼んだときだけコンテキストに入る

Step 4：サブエージェント設計の見直し

コンテキストを大量に消費する調査系タスクは、サブエージェントへの委任が効果的です。

補足： サブエージェントとは、メインセッションから独立した別プロセスでタスクを実行する仕組みです。サブエージェントが処理した内容はメインのコンテキストウィンドウを消費せず、結果の要約だけが返されます。

委任に適したタスク：

ドキュメント調査・ライブラリ調査
大量ファイルの解析・検索
コードベース全体のパターン調査

メインセッションに残すべきタスク：

最終判断・実装方針の決定
ユーザーとのやり取り

サブエージェントへの委任は、プロンプト内で Task ツールを使って指示します。

調査を依頼する例：
「Task: プロジェクト内のAPI呼び出し箇所をすべて洗い出し、
 エンドポイントごとに分類して一覧を作成してください」

メインセッションには調査結果の要約だけが返るため、数千〜数万トークン分の節約になります。

`/context` の実行例：`/compact` による会話履歴の圧縮

会話履歴の割合が多い場合、/compact で履歴の圧縮を行い対処します。

事例：対処前（コンテキスト使用量：38%）

事例：対処後（コンテキスト使用量：18%）

前後比較：

削減分のほぼすべてがMessagesに集中しています。CLAUDE.mdやスキルなどの設計部分には影響を与えず、会話履歴だけが圧縮されました。

カテゴリ	対処前	対処後	変化
全体使用量	76.9k（38%）	35.3k（18%）	-41.6k（-20%）
Messages	60.6k（30.3%）	19.5k（9.8%）	-41.1k（-20.5%）
Free space	90.1k（45.1%）	131.7k（65.9%）	+41.6k（+20.8%）
その他（System prompt / Skills等）	約16k	約16k	変化なし

/compact は、コンテキストの設計を壊さずに空き容量を回復できる運用コマンドです。タスクの区切りで実行する習慣をつけておくと、40%ラインを超えにくい安定した環境を維持できます。

新しい環境構築時の設計

これからClaude Code環境を構築する場合、3つのアンチパターンを最初から避ける設計にすることで、後のリファクタリングを大幅に減らせます。

推奨する構築順序：

CLAUDE.mdを最小限から始める： 最初は10行以内。「不足を感じたら追加」の方針で育てる
スキルを先に設計する： よく使うタスク手順は最初からスキルとして分離
タスクは「仕様書→新セッション」で進める： 要件整理と実装を別セッションで分離

仕様書フェーズ：ClaudeとSPEC.mdを共同作成
      ↓ /clear（コンテキストをリセット）
実装フェーズ：SPEC.mdだけを参照して実装開始
      ↓ タスク完了ごとに /compact
次のタスクへ

コンテキストエンジニアリングに関するよくある質問

コンテキストエンジニアリングに関するよくある質問を以下にまとめました。

Q. コンテキストが増えるとなぜ精度が落ちるのですか？

コンテキスト内の情報量が増えるほど、AIの注意力が分散し、重要な指示への「注目度」が相対的に薄まります。その結果、Claudeが何を優先すべきかを見失いやすくなり、回答精度が低下します。

Q. `/compact` と `/clear` はどう使い分けますか？

/compact はセッションを継続しながら会話履歴を要約・圧縮するコマンドです。「次の作業に引き継ぎたい情報がある」場合に使います。/clear はコンテキストを完全にリセットします。仕様書から実装フェーズに切り替えるときなど、「白紙から始めたい」場合に適しています。

Q. CLAUDE.mdは何行まで書いていいですか？

目安は200行・5,000トークン以下です。日本語は英語の2〜3倍のトークンを消費するため、実質100〜150行程度が上限の目安です。超えてきたらスキルへの切り出しを検討してください。

Q. セッション途中でContext Rotに気づいたらどうすればいいですか？

まず /context でコンテキスト使用量の内訳を確認します。50%を超えていれば、/compact で引き継ぎたい情報を指定してコンテキストを圧縮します。改善しない場合は、作業内容をSPEC.mdなどに書き出してから /clear で新セッションを開始してください。

Q. CLAUDE.mdを英語で書くとトークンを節約できますか？

はい、英語記述は日本語の1/2〜1/3のトークンで済みます。ただし、読み書きコストや誤解のリスクを考えると、全文英語化は必ずしも推奨しません。「見出しは英語、説明文は日本語」にするだけでも削減効果があります。

まとめ

この記事では、コンテキストエンジニアリングについて解説しました。

この記事で解説した内容：

この記事の要点は以下の通りです。

コンテキストエンジニアリングの定義と重要性
Attention DilutionとContext Rotによる精度低下の仕組み
コンテキスト崩壊を招く3つのアンチパターンと解決策
5層構造によるコンテキストの役割分担
既存環境のリファクタリング手順

「Claudeがすぐ使えなくなる」のはモデルの限界ではなく、コンテキスト設計の問題です。まずCLAUDE.mdを開いて、重複している記述を1つ削除するところから始めてみてください。

「AIにどう指示するか」から「AIが活躍できる環境をどう整えるか」という視点に変わることで、Claudeはあなたの頼もしいパートナーへと進化します。

Claude Codeに関する関連記事の一覧です。

参考資料

以下のリンクは、この記事で解説した手順や概念に関連する参考資料です。より詳しく学びたい方は、ぜひご覧ください。

【番外編】USBも知らなかった私が独学でプログラミングを勉強してGAFAに入社するまでの話

IT未経験者必見 USBも知らなかった私が独学でプログラミングを勉強してGAFAに入社するまでの話

プログラミング塾に半年通えば、一人前になれると思っているあなた。それ、勘違いですよ。「なぜ間違いなの？」「正しい勉強法とは何なの？」ITを学び始める全ての人に知って欲しい。そう思って書きました。是非読んでみてください。

「フリーランスエンジニア」

近年やっと世間に浸透した言葉だ。ひと昔まえ、終身雇用は当たり前で、大企業に就職することは一種のステータスだった。しかし、そんな時代も終わり「優秀な人材は転職する」ことが当たり前の時代となる。フリーランスエンジニアに高価値が付く現在、ネットを見ると「未経験でも年収400万以上」などと書いてある。これに釣られて、多くの人がフリーランスになろうとITの世界に入ってきている。私もその中の1人だ。数年前、USBも知らない状態からITの世界に没入し、そこから約2年間、毎日勉学を行なった。他人の何十倍も努力した。そして、企業研修やIT塾で数多くの受講生の指導経験も得た。そこで私は、伸びるエンジニアとそうでないエンジニアをたくさん見てきた。そして、稼げるエンジニア、稼げないエンジニアを見てきた。

「成功する人とそうでない人の違いは何か？」

私が出した答えは、「量産型エンジニアか否か」である。今のエンジニア市場には、量産型エンジニアが溢れている！！ここでの量産型エンジニアの定義は以下の通りである。

比較的簡単に学習可能なWebフレームワーク（WordPress, Rails）やPython等の知識はあるが、ITの基本概念を理解していないため、単調な作業しかこなすことができないエンジニアのこと。

多くの人がフリーランスエンジニアを目指す時代に中途半端な知識や技術力でこの世界に飛び込むと返って過酷な労働条件で働くことになる。そこで、エンジニアを目指すあなたがどう学習していくべきかを私の経験を交えて書こうと思った。続きはこちらから、、、、