← すべての記事

コンテキストエンジニアリングはアーキテクチャである：650ファイルの先に見えたもの

2分で読めます

私の CLAUDE.md は50行から始まりました。6ヶ月後、それは7層にわたる650ファイルの分散アーキテクチャへと成長していました。この進化を通じて明らかになったのは、コンテキストエンジニアリングとは「ファイルが多いプロンプトエンジニアリング」ではないということです。それは、トークンごとに記憶が劣化する基盤のためのソフトウェアアーキテクチャなのです。

コンテキストは設定ファイルではありません。AIエージェントが何を考えられるか、何を記憶し、何を忘れるかを決定するアーキテクチャ基盤です。他のすべての設計判断はコンテキストの下流にあります。以下は、Claude Code の本番コンテキストエンジニアリングに費やした6ヶ月間の記録です：アーキテクチャ、失敗、そしてそれらを乗り越えたシステムについて。

TL;DR

Böckeler のコンテキストエンジニアリングに関する記事（martinfowler.com、2026年）1と Miessler の明晰思考フレームワーク2は議論を前進させていますが、どちらも本番運用が求めるものを過小評価しています。コンテキストエンジニアリングには、正しい指示が正しいタイミングでエージェントに届き、不要な指示は一切読み込まれないシステムの設計が求められます。私のシステムは9つのルール、40のスキル、19のエージェント、84のフック、14の設定ファイルを7層階層に分散して使用しています。アーキテクチャの本質はファイルそのものにあるのではなく、どのファイルがいつ読み込まれ、何が除外されるかにあります。

コンテキストはファイルではない

毎週のように投稿される「CLAUDE.md の書き方」記事は本質を見失っています。良い CLAUDE.md を書くことは必要ですが十分ではありません。良いコードを書くことが良いシステムを構築するために必要だが十分でないのと同じです。アーキテクチャとは、コンポーネントがどのように相互作用するかを決定する構造です。エージェントシステムにおいて、コンテキストこそがその構造なのです。

最初の CLAUDE.md はモノリスでした：コーディング規約、プロジェクト構成、好み、修正事項、哲学、認証情報、アクティブなプロジェクト状態をすべて200行に詰め込んでいました。1ヶ月は機能しました。しかし、3つのことが同時に起こりました：

  1. ファイルが300行を超え、自身と矛盾し始めた（ルールAは「シンプルに保て」と言い、ルールBは「徹底的なエラーハンドリングを追加せよ」と言う）
  2. プロジェクトAのコンテキストがプロジェクトBに漏れた（iOS固有のルールがWeb開発セッションを汚染する）
  3. エージェントが現在のタスクに無関係な指示の読み込みにトークンを消費していた

これらの症状はドキュメントの問題ではなく、アーキテクチャの問題を示しています：結合、スコープの漏洩、リソースの浪費。ソフトウェアアーキテクチャの判断を駆動するのと同じ力学です。3

7つの層

6ヶ月のリファクタリングを経て、私のコンテキストシステムは7層階層に落ち着きました。各層は明確な目的を持ち、特定のタイミングで読み込まれます：

層 内容 読み込みタイミング 数量
1. コア CLAUDE.md：哲学、アクティブプロジェクト、修正事項 毎セッション開始時 1ファイル、205行
2. ルール ドメイン固有の制約（API設計、セキュリティ、テスト、Git） 毎セッション開始時 9ファイル
3. スキル 手順と例を含む再利用可能な知識モジュール オンデマンド（呼び出し時またはフックによる自動起動） 40ディレクトリ
4. エージェント 特化型レビュアー/ジェネレーター仕様 オンデマンド（Task ツール経由） 19ファイル
5. フック ライフサイクルイベントでの自動コンテキスト注入 イベント駆動（セッション開始、プリコミット、ポストツール） 84スクリプト
6. 設定 数値パラメータ（閾値、予算、制限） フックとスキルから参照 14 JSONファイル
7. 状態 ライブトラッキング（エージェント系譜、確信度キャリブレーション、コスト） フックから参照 36ファイル

重要な洞察は層の分離です。ルールは普遍的に適用されるため毎セッション読み込まれます。スキルはドメイン固有のためオンデマンドで読み込まれます。フックはタイミングが重要なためイベントで発火します。650ファイルすべてをセッション開始時に読み込めば、エージェントが最初のユーザーメッセージを読む前にコンテキストウィンドウを使い果たしてしまうでしょう。4

アーキテクチャを形作った3つの失敗

失敗1：モノリシックな CLAUDE.md

元の CLAUDE.md には、iOSルール、Webルール、API設計パターン、Git規約、認証情報管理、哲学的原則がすべて1つのファイルに含まれていました。エージェントは毎セッションそのすべてを読み込んでいました。SwiftUI に一切触れないWebプロジェクトを構築しているときでさえも。

コスト： 無関係なコンテキストが毎セッション約4,000トークンを消費していました。50セッションで合計200,000トークンが、エージェントが一度も使わない指示に費やされたことになります。

修正： ドメイン固有の内容を rules/ ファイルに抽出しました。rules/security.md は毎セッション読み込まれます（セキュリティはどこにでも適用されるため）。rules/ios-security.md はセッションがiOSプロジェクトに関わる場合のみ読み込まれます。この判断を駆動したトークン経済学については、コンテキストウィンドウ管理の記事で詳述しています。

失敗2：陳腐化したスキル

FastAPI 0.109 の例を含む fastapi スキルを作成しました。3ヶ月後、プロジェクトは異なるパターンを持つ FastAPI 0.115 を使用していました。スキルは無言で古い規約を教え続けました。エージェントは動作するコードを生成しましたが、現在のコードベースとは一致しないものでした。

コスト： 新しいエンドポイントが他のすべてのエンドポイントとは異なる依存性注入パターンを使用している理由を追跡するための45分のデバッグセッション。そのパターンはコードベースからではなく、陳腐化したスキルから来ていたのです。

修正： スキルはバージョン管理されたドキュメントを参照し、「最終検証日」を含めるようにしました。さらに重要なのは、品質ループが生成されたコードを既存のコードベースパターンと照合することを要求する点です。これはスキルの内容に関係なく、陳腐化したスキルのドリフトを検出するメタ認知的チェックです。

失敗3：異なる層での矛盾するルール

CLAUDE.md は「シンプルなソリューションを優先せよ」と述べていました。あるスキルは「リトライロジックとサーキットブレーカーを含む徹底的なエラーハンドリングを追加せよ」と述べていました。どちらも単独では合理的です。しかし組み合わさると、エージェントがそのターンでどちらの指示をより重視するかによって、一貫性のない出力（時に最小限、時に過剰設計）が生成されました。

コスト： 予測不能な出力品質。同じ種類のタスクがセッションごとに異なる品質レベルを生み出し、システムが信頼できなくなりました。

修正： 明確な優先順位階層を確立しました。CLAUDE.md は原則を設定します（「シンプルさを優先」）。ルールは制約を設定します（「すべてのユーザー入力を検証」）。スキルは手順を設定します（「FastAPI エンドポイントの構築方法はこちら」）。矛盾する場合、より具体的な層が優先されます：スキルの手順は、そのスキルがカバーする特定のタスクにおいて原則のガイダンスをオーバーライドします。この解決方法は、プログラミング言語がスコープを処理する方法と同じです：ローカルがグローバルをオーバーライドします。5

アーキテクチャ制約としてのコンテキスト予算

コンテキストウィンドウは無限ではありません。Claude の200Kトークンコンテキストウィンドウ6は、何がそれを消費するかを測定するまでは大きく聞こえます：

消費者 典型的なトークン数 ウィンドウに占める割合
システムプロンプト + CLAUDE.md + ルール 8,000-12,000 4-6%
会話履歴 20,000-80,000 10-40%
ファイル読み込み（ファイルごと） 5,000-20,000 2.5-10%
ツール出力（呼び出しごと） 1,000-10,000 0.5-5%
スキル/エージェントコンテキスト（オンデマンド） 3,000-15,000 1.5-7.5%

トークン消費量の測定は、2025年8月から2026年2月の間に私が追跡した50回の Claude Code セッションに基づいています。7 90分の集中セッションでは、通常のファイル読み込みとツール操作だけでウィンドウを使い果たすことがあります。コンテキスト予算はアーキテクチャ上のトレードオフを強制します：

常に読み込むもの コア哲学、アクティブな修正事項、セキュリティルール。この3つはコストが低く（予算の4-6%）、普遍的に適用されます。

オンデマンドで読み込むもの スキル、エージェント仕様、リファレンスドキュメント。それぞれスキルごとにウィンドウの5-15%を消費し、単一のドメインにのみ適用されます。関連する場合のみ読み込むことで、実際の作業のための予算を確保します。

決して読み込まないもの 古くなったハンドオフドキュメント、非推奨の設定、過去の状態。古いファイルはすべて出力を改善することなく予算を消費します。複利エンジニアリングパターンでは、トークンコストに見合わなくなったコンテキストの定期的な剪定が求められます。

コンテキスト予算管理は、従来のソフトウェアにおけるデータベースインデックス、キャッシュ戦略、メモリ管理を駆動するトレードオフと同じ構造を持っています。8 制約は異なりますが（バイトではなくトークン）、アーキテクチャ上の規律は同一です。

マルチエージェントシステムにおけるコンテキスト伝播

メインエージェントが Task ツールを通じてサブエージェントを生成する際、どのコンテキストを伝播するかがその他すべての設計判断を駆動します。私のマルチエージェント審議システムは10のリサーチエージェントを使用しています。各エージェントは独立して評価するのに十分なコンテキストを必要としますが、共有コンテキストが多すぎると、boids の記事で文書化されている収束問題が発生します：共有コンテキストが多すぎるエージェントは同一の結論を生み出してしまうのです。

伝播ルール：

コンテキストの種類 伝播するか？ 理由
コア哲学 する エージェント間の一貫性
ドメインルール する 共有品質基準
タスク固有の指示 する 実際の作業内容
会話履歴 しない 独立性には隔離が必要
他のエージェントの発見 しない（統合まで） 早期収束の防止
スキル手順 選択的に エージェントの役割に関連するスキルのみ

Ralph アーキテクチャは関連する問題を解決します：エージェント（並列プロセス）間ではなく、時間（イテレーション）をまたいだコンテキスト伝播です。どちらも同じ原則を共有しています：制約と原則を伝播し、実装の詳細は隔離するということです。

コンテキスト品質の測定

トークン数は代理指標に過ぎません。コンテキスト品質の真の尺度は、エージェントが最初の試行で正しい出力を生成するかどうかです。

50セッションを追跡した結果、3つの品質シグナルを特定しました：

初回成功率。 エージェントの最初のレスポンスが修正不要である割合はどの程度か？モノリシックな CLAUDE.md では、その割合は約60%でした。7層アーキテクチャの導入後、約80%に上昇しました。改善は、無関係なコンテキストの除去（気を散らす要素の減少）とドメイン固有スキルの追加（関連知識の増加）によるものです。9

修正の種類。 エージェントに修正が必要な場合、そのエラーは事実に関するもの（間違った API、間違ったパターン）か、判断に関するもの（間違ったアプローチ、間違った優先順位）か？事実エラーはコンテキストの不足を示します。判断エラーは矛盾するまたは曖昧なコンテキストを示します。修正の種類を追跡することで、どの層に注意が必要かが明らかになります。

タスク完了時のコンテキスト圧力。 タスクが完了した時点で、コンテキスト予算はどれだけ残っているか？タスクが半分も終わらないうちにウィンドウの90%が消費されていれば、コンテキストアーキテクチャが無関係な素材を過剰に読み込んでいます。私のフックシステムには、使用率が70%を超えた場合に警告するコンテキスト圧力モニターが含まれています。

分散アーキテクチャパターン

7層システムに AIエージェント固有のものは何もありません。確立されたソフトウェアパターンを反映しています：

ソフトウェアパターン コンテキストにおける対応物
環境変数 コア CLAUDE.md（常に読み込み、グローバル）
設定ファイル ルール（起動時に読み込み、ドメイン固有）
ライブラリ/モジュール スキル（オンデマンドで読み込み、自己完結型）
マイクロサービス エージェント（隔離され、プロトコルを介して通信）
イベントハンドラー フック（ライフサイクルイベントで起動）
データベース 状態ファイル（永続的、クエリ可能）
APIコントラクト 設定スキーマ（共有数値パラメータ）

この対応は比喩ではありません。同じ力学（結合、凝集、スコープ、ライフサイクル）が同一のアーキテクチャ判断を駆動しています。10 コンテキストエンジニアリングとは、「メモリ」が豊富で永続的なリソースではなく、希少で劣化するリソースである基盤のためのソフトウェアエンジニアリングなのです。11

主要なポイント

エージェントシステムを構築するエンジニアへ：

  • コンテキストをドキュメントではなく、ソフトウェアアーキテクチャとして設計してください。 何がいつ読み込まれるか、何が何をオーバーライドするか、何がサブエージェントに伝播するかが、個々の指示よりもエージェントの挙動を決定します。コードに使うのと同じ関心の分離の規律を適用してください。

  • 層をライフサイクルで分離してください。 普遍的なルールは毎セッション読み込まれます。ドメイン固有の知識はオンデマンドで読み込まれます。セッションごとの状態は一時的なままにします。ライフサイクルを1つのファイルに混在させると、ソフトウェアアーキテクチャが解決するために存在する結合の問題を引き起こします。

AIワークフローをスケールするチームへ：

  • コンテキストウィンドウを予算として扱ってください。 システムプロンプト、ファイル読み込み、ツール出力が200Kトークンウィンドウを消費します。すべての永続的な指示がワーキングメモリと競合します。読み込んでいるものを測定し、トークンコストに見合わないものを剪定してください。

  • 伝播ルールがマルチエージェントの品質を決定します。 サブエージェントは一貫性のための共有原則と、独立性のための隔離された状態を必要とします。コンテキストの伝播が多すぎると収束を引き起こします。少なすぎると一貫性の欠如を引き起こします。

この記事はコンテキストウィンドウ管理（トークン経済学）とRalph システム（ファイルシステムメモリ）を基盤としています。Claude Code フックシステムが自動化層を実装しています。エージェント連携パターンについては、マルチエージェント審議とBoids からエージェントへをご覧ください。

  1. Birgitta Böckeler, “Context Engineering for Coding Agents,” martinfowler.com, February 2026. martinfowler.com/articles/exploring-gen-ai/context-engineering-coding-agents.html. Böckeler の同僚 Bharani Subramaniam はコンテキストエンジニアリングを「より良い結果を得るために、モデルが見るものをキュレーションすること」と定義しています。この定義は正確です。本記事では、その情報がどのように組織化され提供されるかという構造がアーキテクチャの規律であり、ドキュメント作成の作業ではないと主張しています。 ↩

  2. Daniel Miessler, “How to Talk to AI,” danielmiessler.com, June 2025. danielmiessler.com/blog/how-to-talk-to-ai. Miessler は、プロンプトエンジニアリングとコンテキストエンジニアリングの両方の根底にある真のスキルは明晰思考、つまり達成したいことを正確に言語化する能力であると主張しています。このフレーミングは、コンテキストについて明晰に考えることよりも、コンテキストを組織化する構造的規律に焦点を当てた本記事を補完するものです。 ↩

  3. このソフトウェアアーキテクチャとの類比は意図的なものです。Robert C. Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design, Prentice Hall, 2017. Martin は同じ力学を特定しています：結合、凝集、関心の分離。AIコンテキストシステムにおける違いは、「メモリ」が一時的で有界であり、従来のアーキテクチャにはない制約が加わることです。 ↩

  4. 650ファイルという数は、2026年2月時点での筆者の計測値です。グローバルコンテキスト：約400ファイル（ルール、スキル、エージェント、フック、設定、状態、ドキュメント、ハンドオフ）。プロジェクト固有のコンテキスト（blakecrosley.com）：約250ファイル（PRD、ドキュメント、プラン、ワークフロー、i18n設定）。セッションごとに読み込まれるのはその一部のみです。 ↩

  5. プログラミング言語における変数スコープ解決（ローカル、囲みスコープ、グローバル、ビルトイン）が直接的な類比です。Python の LEGB ルールが同じ階層を定義しています：ローカルスコープ、囲み関数スコープ、グローバルスコープ、ビルトインスコープ。Python Software Foundation, “Execution Model,” section 4.2.2, “Resolution of names.” docs.python.org/3/reference/executionmodel.html を参照。スキル（ローカルスコープ）がルール（モジュールスコープ）をオーバーライドし、ルールが CLAUDE.md（グローバルスコープ）をオーバーライドします。LLM の指示追従は決定論的ではなく確率的であるため、この類比は若干の限界がありますが、アーキテクチャの原則は有効です。 ↩

  6. Anthropic, “Models overview,” platform.claude.com, 2025. platform.claude.com/docs/en/docs/about-claude/models. 現行のすべての Claude モデル（Opus 4.6、Sonnet 4.6、Haiku 4.5）は200Kトークンのコンテキストウィンドウを仕様としており、Opus 4.6 と Sonnet 4.6 はベータで1Mトークンをサポートしています。 ↩

  7. 2025年8月から2026年2月の間に筆者が追跡した50回の Claude Code セッションからのトークン消費測定値。完全な方法論についてはコンテキストウィンドウ管理を参照してください。 ↩

  8. トークン予算とメモリ階層の類比は、Hennessy, J.L. and Patterson, D.A., Computer Architecture: A Quantitative Approach, 6th edition, Morgan Kaufmann, 2017 のフレームワークに従っています。Hennessy と Patterson のキャッシュ階層、参照の局所性、異なるレベルでのメモリアクセスコストの扱いは、コンテキストエンジニアリングに直接対応します：頻繁に必要なコンテキスト（L1キャッシュ / コアルール）は最速で読み込まれ、めったに必要としないコンテキスト（ディスク / オンデマンドスキル）は参照された時のみ読み込まれます。 ↩

  9. 初回成功率は、最初のレスポンスに修正が必要だったかどうかについての筆者の主観的評価に基づくおおよその指標です。制御された実験ではありません。方向性のある改善（60%から80%）はセッションの種類を問わず一貫していますが、精密な測定値として引用すべきではありません。 ↩

  10. James Lewis and Martin Fowler, “Microservices,” martinfowler.com, March 2014. martinfowler.com/articles/microservices.html. Lewis と Fowler はマイクロサービスを「それぞれ独自のプロセスで実行され、軽量なメカニズムで通信する小さなサービスの集合」と定義しています。彼らが特定した力学（独立デプロイ、分散ガバナンス、境界づけられたコンテキスト）は、ここで述べられているコンテキストアーキテクチャにおけるエージェントの隔離とプロトコルベースの通信に直接対応しています。 ↩

  11. 「アーキテクチャとしてのコンテキスト」というフレーミングは、Xu et al., “Everything is Context: Agentic File System Abstraction for Context Engineering,” arXiv, December 2025. arxiv.org/abs/2512.05470 に依拠しています。この論文は、多様な知識アーティファクト、メモリ、ツールをトークン制約内のコンテキストとして扱い、生成AIシステムにおけるコンテキスト管理のためのファイルシステム抽象化を提案しています。理論的フレームワークは、ここで述べられている実践的なアーキテクチャを支持するものです。 ↩