コンテキストエンジニアリングはアーキテクチャである:650ファイルの先に見えたもの
私の CLAUDE.md は50行から始まりました。6ヶ月後、それは7層にわたる650ファイルの分散アーキテクチャへと成長していました。この進化を通じて明らかになったのは、コンテキストエンジニアリングとは「ファイルが多いプロンプトエンジニアリング」ではなく、トークンごとに記憶が劣化する基盤のためのソフトウェアアーキテクチャだということです。
コンテキストは、AIエージェントが何を考えられるか、何を記憶し、何を忘れるかを決定します。他のすべての設計判断はその下流にあります。以下は、Claude Code の本番コンテキストエンジニアリングに費やした6ヶ月間の記録です:アーキテクチャ、失敗、そしてそれらを乗り越えたシステムについて。
AIエージェントのためのコンテキストエンジニアリングとは、正しい指示を正しいタイミングでエージェントに届け、無関係な指示は一切読み込ませないシステムを設計する実践です。 良いプロンプトファイルを書くだけでは足りません。ルール、スキル、フック、設定、状態ファイルがそれぞれ特定のライフサイクルイベントで読み込まれる、層状のアーキテクチャが求められます。何を除外するかは、何を含めるかと同じくらい重要です。無関係なトークンは一つ残らず、エージェントが正しく動くために本当に必要なコンテキストを押しのけてしまうからです。
TL;DR
Böckeler のコンテキストエンジニアリングに関する記事(martinfowler.com、2026年)1と Miessler の明晰思考フレームワーク2は議論を前進させていますが、どちらも本番運用が求めるものを過小評価しています。コンテキストエンジニアリングには、正しい指示が正しいタイミングでエージェントに届き、不要な指示は一切読み込まれないシステムの設計が求められます。私のシステムは9つのルール、40のスキル、19のエージェント、84のフック、14の設定ファイルを7層階層に分散して使用しています。アーキテクチャの本質は、どのファイルがいつ読み込まれるかにあります。何を除外するかは、何を含めるかと同じくらい重要です。
コンテキストはファイルではない
毎週のように投稿される「CLAUDE.md の書き方」記事は本質を見失っています。良い CLAUDE.md を書くことは必要ですが十分ではありません。良いコードを書くことが良いシステムを構築するために必要だが十分でないのと同じです。アーキテクチャとは、コンポーネントがどのように相互作用するかを決定する構造です。エージェントシステムにおいては、コンテキストこそがその構造なのです。
50行から始まったものは、モノリスへと膨らんでいました。最初の CLAUDE.md は、コーディング規約、プロジェクト構成、好み、修正事項、哲学、認証情報、アクティブなプロジェクト状態をすべて200行に詰め込んでいました。1ヶ月は機能しました。しかし、3つのことが同時に起こりました:
- ファイルが300行を超え、自身と矛盾し始めた(ルールAは「シンプルに保て」と言い、ルールBは「徹底的なエラーハンドリングを追加せよ」と言う)
- プロジェクトAのコンテキストがプロジェクトBに漏れた(iOS固有のルールがWeb開発セッションを汚染する)
- エージェントが現在のタスクに無関係な指示の読み込みにトークンを消費していた
これらの症状が示しているのは、ドキュメントの問題ではなくアーキテクチャの問題です:結合、スコープの漏洩、リソースの浪費。ソフトウェアアーキテクチャの判断を駆動するのと同じ力学です。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
各層の具体例は次のとおりです:
Layer 1 (Core): ~/.claude/CLAUDE.md — philosophy, active projects, corrections
Layer 2 (Rules): ~/.claude/rules/security.md — "Validate ALL user input at boundaries"
Layer 3 (Skills): ~/.claude/skills/fastapi/SKILL.md — endpoint patterns, Pydantic models
Layer 4 (Agents): ~/.claude/agents/security-reviewer.md — OWASP-focused review spec
Layer 5 (Hooks): ~/.claude/hooks/pre-commit-check.sh — blocks commits with TODO/FIXME
Layer 6 (Config): ~/.claude/config/thresholds.json — {"max_spawn_children": 12}
Layer 7 (State): ~/.claude/state/agent-lineage.json — tracks active agent tree
階層内の各ファイルは単一の責務と明確な読み込みトリガーを持っています。フック(第5層)はプロジェクトの種類に関係なくプリコミット時に発火します。スキル(第3層)は FastAPI のタスクが始まったときにだけ読み込まれます。この区別がトークンコストを決めるのです。
アーキテクチャを形作った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 は「シンプルなソリューションを優先せよ」と述べていました。あるスキルは「リトライロジックとサーキットブレーカーを含む徹底的なエラーハンドリングを追加せよ」と述べていました。どちらも単独では合理的です。しかし組み合わさると、エージェントがそのターンでどちらの指示をより重視するかによって、一貫性のない出力(時に最小限、時に過剰設計)が生成されました。
コスト: 予測不能な出力品質。同じ種類のタスクがセッションごとに異なる品質レベルを生み出し、システムが信頼できなくなりました。実際に矛盾していた指示は次のとおりです:
# In CLAUDE.md (Layer 1):
- Prefer simple solutions. Avoid over-engineering.
# In skills/fastapi/SKILL.md (Layer 3):
- Add thorough error handling with retry logic and circuit breakers
for all external API calls.
どちらも単独では正しい指示です。「シンプルなソリューションを優先せよ」は一般的な助言として優れています。「外部呼び出しにはリトライロジックを追加せよ」はドメイン固有の助言として優れています。しかし両方を読んだエージェントは、あるときはリトライロジックを省き(シンプルさの原則に従って)、あるときは単純な関数を過剰設計してしまいます(エラーハンドリングの指示に従って)。
修正: 明確な優先順位階層を確立しました。CLAUDE.md は原則を設定します(「シンプルさを優先」)。ルールは制約を設定します(「すべてのユーザー入力を検証」)。スキルは手順を設定します(「FastAPI エンドポイントの構築方法はこちら」)。矛盾する場合は、より具体的な層が優先されます:スキルの手順は、そのスキルがカバーする特定のタスクにおいて原則のガイダンスをオーバーライドします。この解決方法は、プログラミング言語がスコープを処理する方法と同じです:ローカルがグローバルをオーバーライドします。5 上の例に対する修正は、スキルに限定条件を加えることでした:「外部API呼び出しにはリトライロジックを追加すること(ネットワークに依存するコードについては、これが一般的なシンプルさの原則をオーバーライドする。外部呼び出しは断続的に失敗するものであり、リトライは過剰設計ではないため)」。
アーキテクチャ制約としてのコンテキスト予算
コンテキストウィンドウは無限ではありません。Claude の標準200Kトークンのコンテキストウィンドウ6は、何がそれを消費するかを測定するまでは大きく聞こえます(API ヘッダー経由で1Mトークンのベータも利用できます。予算は比例して拡大しますが、トレードオフがなくなるわけではありません。650ファイルを読み込めば、1Mトークンでさえ使い果たしてしまいます)。
| 消費者 | 典型的なトークン数 | ウィンドウに占める割合 |
|---|---|---|
| システムプロンプト + 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分の集中セッションでは、通常のファイル読み込みとツール操作だけでウィンドウを使い果たすことがあります。なお、200Kのウィンドウは入力容量の総量であり、モデルの実効的な注意(高い忠実度で注意を向けられる部分)はそれとは別の、より小さな数字です。総トークン使用量が上限を大きく下回っている場合でも、コンテキスト予算の規律は重要です。長いコンテキストでは、冒頭にある指示のほうが中盤にある指示よりも確実に注意を向けられるからです。コンテキスト予算はアーキテクチャ上のトレードオフを強制します:
常に読み込むもの: コア哲学、アクティブな修正事項、セキュリティルール。この3つはコストが低く(予算の4-6%)、普遍的に適用されます。不要なときに読み込むコストは無視できるほど小さく、必要なときに省いたコストは誤った出力です。
オンデマンドで読み込むもの: スキル、エージェント仕様、リファレンスドキュメント。それぞれスキルごとにウィンドウの5-15%を消費し、単一のドメインにのみ適用されます。関連する場合のみ読み込むことで、実際の作業のための予算を確保します。スキルを読み込むトリガーはセッションの種類ではなくタスクの種類です。データベースのマイグレーションに出くわしたWeb開発セッションには、起動時に読み込まれていなくてもデータベーススキルが必要です。
決して読み込まないもの: 古くなったハンドオフドキュメント、非推奨の設定、過去の状態。古いファイルはすべて、出力を改善することなく予算を消費します。さらに悪いことに、古いコンテキストは時代遅れのパターンを教えることで出力を積極的に劣化させます。複利エンジニアリングパターンでは、トークンコストに見合わなくなったコンテキストの定期的な剪定が求められます。
コンテキスト予算管理は、従来のソフトウェアにおけるデータベースインデックス、キャッシュ戦略、メモリ管理を駆動するトレードオフと同じ構造を持っています。8 制約は異なりますが(バイトではなくトークン)、アーキテクチャ上の規律は同一です。
マルチエージェントシステムにおけるコンテキスト伝播
メインエージェントが Task ツールを通じてサブエージェントを生成する際、どのコンテキストを伝播するかの選択が、その他すべての設計判断を駆動します。私のマルチエージェント審議システムは10のリサーチエージェントを使用しています。各エージェントは独立して評価するのに十分なコンテキストを必要としますが、共有コンテキストが多すぎると、boids の記事で文書化した収束問題が発生します:共有コンテキストが多すぎるエージェントは同一の結論を生み出してしまうのです。
伝播ルール:
| コンテキストの種類 | 伝播するか? | 理由 |
|---|---|---|
| コア哲学 | する | エージェント間の一貫性 |
| ドメインルール | する | 共有品質基準 |
| タスク固有の指示 | する | 実際の作業内容 |
| 会話履歴 | しない | 独立性には隔離が必要 |
| 他のエージェントの発見 | しない(統合まで) | 早期収束の防止 |
| スキル手順 | 選択的に | エージェントの役割に関連するスキルのみ |
Ralph アーキテクチャは関連する問題を解決します:エージェント(並列プロセス)間ではなく、時間(イテレーション)をまたいだコンテキスト伝播です。どちらも同じ原則を共有しています:制約と原則は伝播し、実装の詳細は隔離するということです。
実践における伝播
具体例を見るとトレードオフがはっきりします。メインエージェントがセキュリティレビュアーのサブエージェントを生成するとき、Task プロンプトには次の内容が含まれます:
## Propagated Context
- Core philosophy: Quality is the only variable (from CLAUDE.md)
- Security rules: OWASP Top 10, input validation at boundaries (from rules/security.md)
- Task: Review the authentication endpoint changes in app/auth.py
## NOT Propagated
- The main agent's conversation history (50+ messages about UI layout)
- Findings from the architecture reviewer (would bias security analysis)
- The FastAPI skill (irrelevant to a security-focused review)
セキュリティレビュアーが受け取るコンテキストは40,000トークンではなく2,000トークンです。UIに関する判断に気を散らされることも、他のエージェントの結論に引きずられることもなく、セキュリティ基準に照らしてコードを評価します。この隔離が独立した評価を生み出します。セキュリティレビュアーとアーキテクチャレビュアーがそれぞれ独立して同じ懸念を指摘したなら、一方が他方のレポートを見て同意した場合よりも、その指摘の確信度は高くなります。
コンテキスト品質の観測
トークン数は代理指標に過ぎません。コンテキスト品質の真の尺度は、エージェントが最初の試行で正しい出力を生成するかどうかです。
50セッションを追跡した結果、3つの品質シグナルを特定しました:
初回成功率。 エージェントの最初のレスポンスが修正不要である割合はどの程度でしょうか。モノリシックな CLAUDE.md では、その割合は約60%でした。7層アーキテクチャの導入後、約80%に上昇しました。改善は、無関係なコンテキストの除去(気を散らす要素の減少)とドメイン固有スキルの追加(関連知識の増加)によるものです。9
トラッキングログから、代表的な導入前と導入後の例を紹介します。タスクはまったく同じで、「APIエンドポイントにレート制限を追加する」というものです。
導入前(モノリシックな CLAUDE.md、2025年7月)。 エージェントの最初のレスポンスは、プロジェクトで使われていないレート制限ライブラリをインポートしていました(iOSルール、セキュリティルール、150行の無関係な内容と一緒に読み込まれた、陳腐化した FastAPI スキルの例に従ったのです)。修正内容は「app/middleware.py にある既存の RateLimiter クラスを使うこと」。修正は1回で、「事実エラー:コードベースのコンテキスト不足」に分類されました。
導入後(7層アーキテクチャ、2025年11月)。 同じ種類のタスクで、エンドポイントだけが異なります。エージェントの最初のレスポンスは既存の RateLimiter ミドルウェアを使い、隣接するエンドポイントのパラメータ命名規則に合わせ、パターンの出典まで示していました:「app/middleware.py:42 のレート制限パターンに従っています」。修正は不要でした。FastAPI スキル(第3層)はオンデマンドで読み込まれ、最新のパターンを含んでいました。iOSの作業がないセッションだったため、iOSルールは読み込まれませんでした。
ご自身で追跡するには、最初のレスポンスの後に各エージェントセッションをログ上で「受け入れ」または「修正」とタグ付けし、その比率を毎月計算してください。粒度は精密である必要はありません。20セッション以上にわたる方向性の傾向のほうが、正確なパーセンテージよりも役に立ちます。
修正の種類。 エージェントに修正が必要な場合、そのエラーは事実に関するもの(間違った API、間違ったパターン)でしょうか、それとも判断に関するもの(間違ったアプローチ、間違った優先順位)でしょうか。事実エラーはコンテキストの不足を示します:エージェントは正しい答えを出すのに必要な情報を持っていなかったのです。判断エラーは矛盾するまたは曖昧なコンテキストを示します:エージェントは情報を持っていたものの、競合する指示の重み付けを誤ったのです。この区別が重要なのは、修正方法が異なるからです。事実エラーにはコンテキストの追加(新しいルールやスキル)が必要で、判断エラーにはコンテキストの明確化(既存の層の間の矛盾の解消)が必要です。修正の種類を追跡することで、どの層に注意が必要かが明らかになります。
タスク完了時のコンテキスト圧力。 タスクが完了した時点で、コンテキスト予算はどれだけ残っているでしょうか。タスクが半分も終わらないうちにウィンドウの90%が消費されていれば、コンテキストアーキテクチャが無関係な素材を過剰に読み込んでいます。私のフックシステムには、使用率が70%を超えた場合に警告するコンテキスト圧力モニターが含まれています。
セッションの実例:何がいつ読み込まれるか
実際のタスクで7つの層がどう連携するかは、具体的な流れを追うとよくわかります。シナリオは、blakecrosley.com プロジェクトで Claude Code に「/api/ab/event エンドポイントにレート制限を追加して」と依頼する場面です。
セッション開始(0秒)。 Claude Code は第1層(CLAUDE.md、205行、約800トークン)と第2層(9つのルールファイルすべて、約3,200トークン)を読み込みます。消費されるコンテキストの合計は約4,000トークン(200Kウィンドウの2%)です。この時点でエージェントは、何を依頼されるかに関係なく、私のコーディング哲学、セキュリティ要件、API設計規約、Gitワークフローを把握しています。
タスク開始(2秒)。 エージェントはタスクを読み、FastAPI エンドポイントの変更だと判断します。第5層(フック)が発火し、UserPromptSubmit フックが現在の日付とセッションコンテキスト(約200トークン)を注入します。エージェントは SwiftUI スキルも、iOSセキュリティルールも、Midjourney プロンプトスキルも読み込みません。これらのファイルは存在しますが、無関係だからです。除外することで約8,000トークンを節約できます。
ファイル読み込み(5-30秒)。 エージェントは app/main.py、既存のエンドポイントのコード、テストファイルを読みます。ファイル1つの読み込みで5,000-15,000トークンのコンテキストを消費します。3つのファイルを読んだ時点で約30,000-50,000トークン(ウィンドウの15-25%)が消費されています。
スキルの起動(必要な場合)。 FastAPI 固有のパターンが必要なら、エージェントは第3層(skills/fastapi/SKILL.md、約2,500トークン)を読み込みます。スキルが読み込まれるのは、セッションが始まったからではなく、タスクがそれを必要とするからです。CSSだけのタスクであれば、FastAPI スキルが読み込まれることはありません。
実装と検証(30秒-5分)。 エージェントはコードを書き、テストを実行し、結果を報告します。タスク完了時点のコンテキスト消費量は、通常60,000-100,000トークン(ウィンドウの30-50%)です。残りの予算で、追加の質問や修正、同じセッション内での2つ目のタスクに対応できます。
重要なのは次の点です。第1層と第2層はウィンドウの2%を消費し、あらゆるタスクに適用されます。第3層から第7層の内容は選択的に読み込まれ、関連する場合にのみ5-25%を消費します。もし650ファイルすべてをセッション開始時に読み込めば、およそ150,000-200,000トークンを消費し、実際の作業の余地はほとんど残らないでしょう。
分散アーキテクチャパターン
7層システムに、AIエージェント固有のものは何もありません。確立されたソフトウェアパターンを反映しています:
| ソフトウェアパターン | コンテキストにおける対応物 |
|---|---|
| 環境変数 | コア CLAUDE.md(常に読み込み、グローバル) |
| 設定ファイル | ルール(起動時に読み込み、ドメイン固有) |
| ライブラリ/モジュール | スキル(オンデマンドで読み込み、自己完結型) |
| マイクロサービス | エージェント(隔離され、プロトコルを介して通信) |
| イベントハンドラー | フック(ライフサイクルイベントで起動) |
| データベース | 状態ファイル(永続的、クエリ可能) |
| APIコントラクト | 設定スキーマ(共有数値パラメータ) |
この対応は比喩ではありません。同じ力学(結合、凝集、スコープ、ライフサイクル)が同一のアーキテクチャ判断を駆動しています。10 コンテキストエンジニアリングとは、「メモリ」が豊富で永続的なリソースではなく、希少で劣化するリソースである基盤のためのソフトウェアエンジニアリングなのです。11
このアーキテクチャの独立した裏付けは、obra/superpowers プロジェクトから得られます。このプロジェクトは、Claude Code のコンテキストについて似た多層構造を独自に進化させてきました:グローバルファイルに置かれたコア原則、オンデマンドで読み込まれるドメインスキル、そして振る舞いの指示から切り離された検証手順です。12 この収束は、層状のアーキテクチャが特異な設計上の選択ではなく、基盤の制約に対する自然な応答であることを示唆しています。
主要なポイント
エージェントシステムを構築するエンジニアへ:
-
コンテキストをドキュメントではなく、ソフトウェアアーキテクチャとして設計してください。 何がいつ読み込まれるか、何が何をオーバーライドするか、何がサブエージェントに伝播するかが、個々の指示よりもエージェントの挙動を決定します。コードに使うのと同じ関心の分離の規律を適用してください。
-
層をライフサイクルで分離してください。 普遍的なルールは毎セッション読み込まれます。ドメイン固有の知識はオンデマンドで読み込まれます。セッションごとの状態は一時的なままにします。ライフサイクルを1つのファイルに混在させると、ソフトウェアアーキテクチャが解決するために存在する結合の問題を引き起こします。
AIワークフローをスケールするチームへ:
-
コンテキストウィンドウを予算として扱ってください。 システムプロンプト、ファイル読み込み、ツール出力が200Kトークンのウィンドウを消費します。すべての永続的な指示がワーキングメモリと競合します。読み込んでいるものを測定し、トークンコストに見合わないものを剪定してください。
-
伝播ルールがマルチエージェントの品質を決定します。 サブエージェントには、一貫性のための共有原則と、独立性のための隔離された状態が必要です。コンテキストの伝播が多すぎると収束を引き起こします。少なすぎると一貫性の欠如を引き起こします。
演習:ご自身のコンテキストシステムを監査してください。 次のディレクトリ構造を作成し、既存の指示をそこに振り分けます:
mkdir -p .claude/{rules,skills,agents,hooks,config,state}
# Move domain-specific sections from CLAUDE.md into rules/
# Move reusable procedures into skills/
# Move agent specs into agents/
そのうえで、次の問いに答えてください。毎セッション読み込まれているファイルのうち、オンデマンドにすべきものはどれか。欠けているオンデマンドファイルはどれか。答えはシンプルなログで追跡しましょう。各セッションに「初回で正解」または「修正が必要」とタグを付け、20セッション後にその比率を見直してください。
よくある質問
AIコーディングエージェント向けのコンテキストファイルはどう構成すべきですか?
ドメイン固有の内容が20-30行を超え、かつ少なくとも一部のセッションでは無関係になる場合は、別ファイルに抽出してください。iOS固有のルールとWeb固有のルールを同じ CLAUDE.md に書くと、エージェントは現在のプロジェクトに関係なく両方を読み込みます。普遍的な制約(セキュリティルール、コーディング規約、哲学的原則)はコアファイルに残しましょう。ドメイン固有のパターン(FastAPI エンドポイント、SwiftUI の規約、データベースクエリ)は、タスクが必要とするときにだけ読み込まれるオンデマンドファイルへ移します。
スキルが陳腐化したことはどうすればわかりますか?
シグナルは2つあります。エージェントが動作はするものの現在のコードベースのパターンと一致しないコードを生成する場合と、エージェントがフレームワークの古いバージョンの API やパターンを参照する場合です。各スキルに「最終検証日」を追加し、四半期ごとに確認してください。さらに重要なのは品質ループ(生成されたコードは既存のパターンと一致しているか)で、これはスキルの内容に関係なく陳腐化したスキルのドリフトを検出します。
コンテキスト予算の適切な規模はどのくらいですか?
200Kトークンのウィンドウなら、システムプロンプトとルール(常に読み込み)に4-6%を確保し、会話履歴とファイル読み込み(実際の作業)に40-60%を残し、オンデマンドのスキルとエージェントコンテキストに10-15%を割り当ててください。タスクが半分も終わらないうちにコンテキスト圧力が70%を超えるなら、無関係な素材を読み込みすぎています。具体的な割合はタスクの複雑さによって変わります。複数ファイルにわたるリファクタリングは、単一関数のバグ修正よりも多くのコンテキストを消費します。
層の間で矛盾する指示はどう扱えばよいですか?
スコープに基づく優先順位を適用してください:より具体的な層が優先されます。スキル(ローカルスコープ)はルール(モジュールスコープ)をオーバーライドし、ルールは CLAUDE.md(グローバルスコープ)をオーバーライドします。矛盾を見つけたら、モデルが確率的に解決するのに任せず、解決方法を明示してください。より具体的な層に次のような注記を加えます:「この特定のコンテキストでは、Y という理由により、X という一般原則をオーバーライドする」。
この記事はコンテキストウィンドウ管理(トークン経済学)とRalph システム(ファイルシステムメモリ)を基盤としています。Claude Code フックシステムが自動化層を実装しています。エージェント連携パターンについては、マルチエージェント審議とBoids からエージェントへをご覧ください。
-
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 はコンテキストエンジニアリングを「より良い結果を得るために、モデルが見るものをキュレーションすること」と定義しています。この定義は正確です。本記事では、その情報がどのように組織化され提供されるかという構造がアーキテクチャの規律であり、ドキュメント作成の作業ではないと主張しています。 ↩
-
Daniel Miessler, “How to Talk to AI,” danielmiessler.com, June 2025. danielmiessler.com/blog/how-to-talk-to-ai. Miessler は、プロンプトエンジニアリングとコンテキストエンジニアリングの両方の根底にある真のスキルは明晰思考、つまり達成したいことを正確に言語化する能力であると主張しています。このフレーミングは、コンテキストについて明晰に考えることよりも、コンテキストを組織化する構造的規律に焦点を当てた本記事を補完するものです。 ↩
-
このソフトウェアアーキテクチャとの類比は意図的なものです。Robert C. Martin, Clean Architecture: A Craftsman’s Guide to Software Structure and Design, Prentice Hall, 2017, Part III (Design Principles) and Part V (Architecture). Martin は同じ力学を特定しています:結合、凝集、関心の分離。AIコンテキストシステムにおける違いは、「メモリ」が一時的で有界であり、従来のアーキテクチャにはない制約が加わることです。 ↩
-
650ファイルという数は、2026年2月時点での筆者の計測値です。グローバルコンテキスト:約400ファイル(ルール、スキル、エージェント、フック、設定、状態、ドキュメント、ハンドオフ)。プロジェクト固有のコンテキスト(blakecrosley.com):約250ファイル(PRD、ドキュメント、プラン、ワークフロー、i18n設定)。セッションごとに読み込まれるのはその一部のみです。 ↩
-
プログラミング言語における変数スコープ解決(ローカル、囲みスコープ、グローバル、ビルトイン)が直接的な類比です。Python の LEGB ルールが同じ階層を定義しています:ローカルスコープ、囲み関数スコープ、グローバルスコープ、ビルトインスコープ。Python Software Foundation, “Execution Model,” section 4.2.2, “Resolution of names.” docs.python.org/3/reference/executionmodel.html を参照してください。スキル(ローカルスコープ)がルール(モジュールスコープ)をオーバーライドし、ルールが CLAUDE.md(グローバルスコープ)をオーバーライドします。LLM の指示追従は決定論的ではなく確率的であるため、この類比には若干の限界がありますが、アーキテクチャの原則は有効です。 ↩
-
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トークンをサポートしています。 ↩
-
2025年8月から2026年2月の間に筆者が追跡した50回の Claude Code セッションからのトークン消費測定値です。完全な方法論についてはコンテキストウィンドウ管理を参照してください。 ↩
-
トークン予算とメモリ階層の類比は、Hennessy, J.L. and Patterson, D.A., Computer Architecture: A Quantitative Approach, 6th edition, Morgan Kaufmann, 2017, Chapter 2 (Memory Hierarchy Design) のフレームワークに従っています。Hennessy と Patterson によるキャッシュ階層、参照の局所性、異なるレベルでのメモリアクセスコストの扱いは、コンテキストエンジニアリングに直接対応します:頻繁に必要なコンテキスト(L1キャッシュ / コアルール)は最速で読み込まれ、めったに必要としないコンテキスト(ディスク / オンデマンドスキル)は参照されたときにのみ読み込まれます。 ↩
-
初回成功率は、最初のレスポンスに修正が必要だったかどうかについての筆者の主観的評価に基づくおおよその指標です。制御された実験ではありません。方向性のある改善(60%から80%)はセッションの種類を問わず一貫していますが、精密な測定値として引用すべきではありません。 ↩
-
James Lewis and Martin Fowler, “Microservices,” martinfowler.com, March 2014. martinfowler.com/articles/microservices.html. Lewis と Fowler はマイクロサービスを「それぞれ独自のプロセスで実行され、軽量なメカニズムで通信する小さなサービスの集合」と定義しています。彼らが特定した力学(独立デプロイ、分散ガバナンス、境界づけられたコンテキスト)は、ここで述べたコンテキストアーキテクチャにおけるエージェントの隔離とプロトコルベースの通信に直接対応しています。 ↩
-
「アーキテクチャとしてのコンテキスト」というフレーミングは、Xu et al., “Everything is Context: Agentic File System Abstraction for Context Engineering,” arXiv, December 2025. arxiv.org/abs/2512.05470 に依拠しています。この論文は、多様な知識アーティファクト、メモリ、ツールをトークン制約内のコンテキストとして扱い、生成AIシステムにおけるコンテキスト管理のためのファイルシステム抽象化を提案しています。その理論的フレームワークは、ここで述べた実践的なアーキテクチャを支持するものです。 ↩
-
obra/superpowers, github.com/obra/superpowers. superpowers プロジェクトは、エージェントのコンテキストをコア指示、オンデマンドのスキル、検証手順に整理しています。独立して開発されたにもかかわらず、この構造はここで述べた7層アーキテクチャと収束しました。この収束は、層状のコンテキストが有界なコンテキストウィンドウに対する自然なアーキテクチャ上の応答であるという主張を支持しています。 ↩