なぜClaude Code開発でCLAUDE.mdに指示を書きすぎると失敗するのか。コンテキスト枯渇を防ぐ最新情報管理

冒頭フック

CLAUDE.mdにルールを全部書く。AIが途中で指示を忘れる。

原因はコンテキストの枯渇だ。コンテキストの空き容量が約20%になった瞬間、過去の会話は自動圧縮される。

全部盛りは破綻への片道切符だ。

ニュースの概要：コンテキストエンジニアリングの台頭

2025年6月、AI研究者のAndrej Karpathyがプロンプトエンジニアリングの終わりを宣言した。

次なる焦点はコンテキストエンジニアリングだ。モデルが応答する際に「何を見ているか」を設計する技術を指す。

Martin FowlerやLangChain、HuggingFaceの実践者たちがこの知見を体系化し始めている。

コーディングエージェントの構造的な課題はコンテキストウィンドウの有限性にある。

上限に近づくと「コンパクション」という自動要約が走る。

「/context」コマンドで確認すると、システム予約領域がすでに数十%を占めている。MCPツールを追加するほど、この領域が圧迫される。

CLAUDE.mdは毎回読み込まれる。結果、ユーザーが使える領域が減り、すぐコンパクションが起きる。

解決策は必要な情報だけを動的に出し入れする設計だ。静的な指示から動的なシステム設計への移行が進んでいる。

コーディングエージェントの課題は大きく3つに整理される。コンテキストの肥大化、指示のコンフリクト、外部システム連携の不足だ。

これらを解決するための具体的な手法が世界中で議論されている。

※この記事は、Claude Codeで1人SaaS開発しているしんたろーが、海外AI最新情報を開発者目線で解説する「AI活用Tips」です。

開発者目線の解説：コンテキストウィンドウとコンパクションの罠

コンテキストウィンドウとは、AIが一度に扱えるテキスト量の上限だ。日本語では1文字が1〜2トークンに相当する。

Claude Sonnet 4.6やOpus 4.6では最大100万トークンまで利用可能だ。特定の条件を満たさない場合は20万トークンに制限される。

上限はユーザーの入力だけでなく、過去の会話履歴やAIの返答、システムプロンプトをすべて合算した数字だ。会話が積み重なるほど残量が減っていく。

そして、残量が0%になる前にコンパクションが発動する。コンパクションとは、古い会話内容を自動的に要約・圧縮する仕組みだ。

空き容量が全体の約20%まで減少した時点で、自動的に実行される。要約の過程で一部の情報は確実に失われる。

複数ファイルにまたがるリファクタリング中に発生すると、変更方針などの文脈が飛ぶ。さらに深刻なのは、システム予約領域の存在だ。

「/context」コマンドを実行すると消費状況が詳細にわかる。System promptやSystem tools、MCP toolsが常に一定のトークンを占有する。

Custom agentsやMemory files、Skillsなども領域を消費する。これらはユーザーが直接入力するメッセージとは別に確保される。

20万トークンが上限の場合、セッション開始直後の時点ですでに20%近くが消費されていることもある。MCPツールを大量に導入すると、この圧迫はさらに加速する。

実際にユーザーが使える領域は全体の100%ではない。セッション開始直後でも80%台となることが珍しくない。

Free spaceがAutocompact bufferと同じ約20%まで減少した時点で、自動的にコンパクションが発生する。この仕様を理解しないまま開発を進めると破綻する。

しんたろー：
/context叩いてシステム予約領域のデカさに驚いた。
ツールが便利だからと入れまくると、肝心の会話ログがすぐ圧縮される。
欲張ってツールを入れすぎた過去の自分を殴りたい。

開発者目線の解説：プロンプトからコンテキストエンジニアリングへ

プロンプトエンジニアリングは「モデルに何をどう言うか」の工夫だ。敬語で頼むか、命令形で頼むかという話し方の調整に過ぎない。

コンテキストエンジニアリングは「モデルが応答するとき何を見ているか」の設計だ。会議室に誰を呼ぶか、どの資料を机に置くかを決める。

System Prompt、Few-shot例、RAGで取得した関連ドキュメントなどを組み合わせる。ツール呼び出し結果や過去の対話履歴、メモリも含まれる。

CLAUDE.mdを書けばClaude Codeは賢くなる。しかし、それだけで満足していると早い段階で壁にぶつかる。

CLAUDE.mdを丁寧に書いてもAIが的外れな回答をする。RAGを入れると精度は上がるがトークンが爆発する。

メモリを設計すると古い情報と新しい情報が混ざって混乱する。これらはすべてコンテキストの管理不足が原因だ。

氷山の下のレイヤーを一つずつ掘り下げていく地味な作業の連続となる。CLAUDE.mdは毎回コンテキストウィンドウに読み込まれる。

ここにすべてのルールを詰め込むと、指示同士がコンフリクトを起こす。AIがどちらのルールを守れば良いのかわからない状態に陥る。

全体的な開発方針のみをCLAUDE.mdに記述する。詳細な方針は別の仕組みに切り出す。

コンテキストに何を入れるかより、何を入れないかの設計が問われている。

しんたろー：
CLAUDE.mdにルールを全部突っ込むと、途中からAIが混乱し始めるのがわかる。
氷山の下のレイヤーを一つずつ掘り下げていく地味な作業だ。
CLAUDE.mdを神格化していた時期が私にもありました。

実務への影響：スキルの活用と構造化ノート

詳細な手順は「スキル」として分離する。スキルとは「どのツールを」「どのように使うか」という方針を教える機能だ。

CLAUDE.mdは毎回読み込まれるが、スキルは必要に応じて読み込まれる。API仕様書の作成方法やセキュリティレビューの実施手順などをスキル化する。

スキルを作成する際の観点として、3つの切り口が紹介されている。「.claude/skills/」ディレクトリにタスク別のマークダウンを置く。

単一のファイルだけでなく、ディレクトリ構造で複雑な情報を管理できる。フロントエンドの実装パターンなら「frontend-patterns」ディレクトリを作る。

その中にスキル本体の「SKILL.md」を置く。さらに「best-practices.md」や実装例のコードを含めることができる。

「good-pattern.ts」や「bad-pattern.ts」などの具体例を同梱する。補助ドキュメントやスクリプトも管理可能だ。

構造化ノートも強力な手法だ。重要な情報をコンテキストウィンドウの外部に分離する戦略を指す。

「.steering/」ディレクトリに日付とタスク名でフォルダを作る。その中に作業単位のドキュメントを作成する。

要求内容を「requirements.md」に、設計を「design.md」に書く。実装タスクは「tasklist.md」、ブロッカーは「blockers.md」に分ける。

重要な決定事項は「decisions.md」に記録する。これらを更新しながら作業を進めるようClaude Codeに指示する。

コンテキストウィンドウを大幅に節約できる。会話の履歴がコンパクションで失われても、最新の状態がファイルとして残る。

実務への影響：サブエージェントとフックの活用

サブエージェントの活用も有効だ。親エージェントから独立して専門的な作業を行うエージェントを作る。

マークダウンファイルで定義することで作成できる。成果物のレビューや影響範囲分析、テストの実行などを任せる。

ログの分析など、大量の情報を読む作業を実施させることで効果を発揮する。ただし、エージェント間でコンテキストは共有されない。

作業ログをファイルやGitHub Issueに書き出して受け渡す。レポートを介してエージェント同士にコミュニケーションを取らせる。

フックの導入も検討する。Claude Codeのライフサイクルの特定のタイミングで、コマンドやスクリプトを実行する仕組みだ。

スラッシュコマンドやスキルはプロンプトベースだ。どう動くかはLLMの推論に左右されてしまう。

絶対に守ってほしいルールはフックを使って制御する。ツール実行前後や応答終了時など、トリガーされるタイミングが用意されている。

どのタイミングで何を実行したいかを考えて設計する。テストの自動実行やフォーマッターの適用などを強制する。

これにより、CLAUDE.mdに指示を書く必要がなくなりコンテキストの節約になる。

実務への影響：外部ツール連携とコンテキスト監視

MCPツールとCLIツールを使い分ける。MCPはAIアプリケーションと外部システムの接続方法を標準化したプロトコルだ。

Claude Codeを通してGitHubのプルリク作成など様々な操作が可能になる。しかし、MCPサーバーはシステム予約領域を消費する。

セキュリティリスクもあるため、導入するサーバーは慎重に検討する。すべてのシステムがMCPサーバーを提供しているわけではない。

組織内の独自システムと連携したい場合はCLIツールが便利だ。GitHub CLIなどの既存ツールや自作のカスタムCLIツールを活用する。

外部システムとの連携を柔軟にカスタマイズできる。監視の仕組みを入れる。「/statusline」コマンドを設定する。

チャット上で実行すると「settings.json」に設定が自動で追記される。再起動するとチャット欄の下部にステータスラインが表示される。

「Context: 79%」のように残りのコンテキスト割合が常時表示される。作業中でも残量を意識できる。

Claude Codeには自動警告の仕組みも備わっている。コンパクションが近づくと「Context left until auto-compact: 4%」と表示される。

この警告が出たタイミングで対策を取る。重要な前提情報を改めて伝えるか、別セッションへの引き継ぎを行う。

「/compact」コマンドで手動コンパクションも可能だ。「データベースmigrationのステップに重点をあてる」など、残したい情報を指定できる。

しんたろー：
/statuslineの常時表示を設定してから、コンパクションのタイミングが予測できるようになった。
残り数パーセントの警告が出た時の緊張感がすごい。
毎回チキンレースをしている気分になる。

FAQ

Q1: Claude Codeが途中で前の指示を忘れてしまうのはなぜですか？

A1: コンテキストウィンドウの上限に近づき、「コンパクション」と呼ばれる自動要約・圧縮機能が働くためだ。Claude Codeでは、コンテキストの空き容量が約20%になると、古い会話履歴が自動的に圧縮される。この過程で詳細な文脈や変更方針が失われる。対策として、「/statusline」コマンドで残量を常時監視する。コンパクションが起きる前に重要な前提条件を別ファイルに分離して都度読み込ませる運用が効果的だ。

Q2: CLAUDE.mdにルールをたくさん書いているのに、AIが無視することがあります。どうすればいいですか？

A2: CLAUDE.mdの肥大化により、指示同士がコンフリクトを起こしている可能性が高い。重要なルールがコンテキストの中で埋もれてしまっている。CLAUDE.mdは毎回コンテキストに読み込まれるため、ここにはプロジェクト全体の基本方針のみを記載する。特定のタスクに関する詳細な手順は、「スキル」として分離する。これにより、必要な時だけ動的にルールが読み込まれ、AIが指示を正確に守るようになる。

Q3: MCPツールを導入してClaude Codeを拡張する際の注意点はありますか？

A3: MCPツールを導入すると外部システム連携が可能になるが、コンテキストウィンドウのシステム予約領域を常時消費する。便利だからとツールを入れすぎると、ユーザーが実際に会話で使えるコンテキスト領域が圧迫される。結果としてコンパクションが頻発する原因になる。導入するMCPサーバーは最小限に留める。「/context」コマンドで現在の消費割合を確認しながら運用する。

まとめ + CTA

コンテキストの限界を知り、引き算の設計でAIの真価を引き出す。

👉 ThreadPostでSNS運用を自動化する