コンテキスト設計教本：AIエージェントの「忘却」を防ぐリポジトリ・アーキテクチャ
AIエージェントはなぜ「忘れる」のか。コンテキストの3層構造、CLAUDE.md・AGENTS.mdの指示ファイル設計、ADRによる再提案防止、Docs-as-Code＋CI/CDでの鮮度管理まで、4つの実践手法を体系的に解説します。
AIネイティブ・エンジニアリングの幕開け
2025年2月、Andrej Karpathy氏が「vibe coding」という言葉を生み出しました。
「コードの存在を忘れて、雰囲気で書く」
——LLMに完全に身を委ねる開発スタイルです。（参考: Andrej Karpathy - vibe coding）
実際、Claude CodeやCursor、GitHub Copilotといったツールを使えば、自然言語だけでプロトタイプを作れる時代になりました。
「ログイン画面を作って」
「APIのエンドポイントを追加して」
と伝えるだけで、動くコードが出てきます。
ところが、プロジェクトが育ってくると様子が変わります。
「さっき説明した設計方針、もう忘れたの？」
「別のセッションで決めたルールを無視してる」
「先週却下したライブラリをまた提案してきた」
——こんな経験はないでしょうか。
vibe codingはプロトタイピングでは強力です。
しかし、本番プロジェクトに持ち込むと、AIエージェントの「忘却」という壁にぶつかります。
もしAIエージェントがプロジェクトの文脈を「覚えて」いたらどうでしょう。
セッションをまたいでも一貫した判断ができたら、チームの誰が使っても同じ品質のコードが出力されたら——。
この記事では、その「もし」を実現するための「コンテキスト設計」を体系的に解説します。
なぜAIは忘れるのか、どう設計すれば防げるのか、そして実際にリポジトリにどう組み込むのか。
NotebookLMでの調査に基づいて、4つの実践手法をお伝えします。
OpenClaw入門ガイド｜便利なAIエージェントの裏に潜むリスク
OpenClawの仕組み（ローカルファースト・モデル非依存）とセキュリティリスク（CVE-2026-25253・ClawHubマルウェア・プロンプトインジェクション）を解説。安全に試すためのチェックリスト付き。
ざっくりまとめ
この記事のポイントを3つにまとめます。
- AIエージェントは「忘れる」のが前提です。
コンテキストウィンドウには上限があり、セッション間で情報は引き継がれません。
この制約を理解した上で「忘れさせない仕組み」を設計する必要があります。 - コンテキストは3層で設計します。
プロジェクト層（CLAUDE.md）、ディレクトリ層（.claude/rules/）、タスク層（ADR・メモリ）の3層構造で、AIに必要な情報を適切な粒度で渡します。 - 人間はコードを書く人から「指揮者」になります。
Docs-as-CodeとCI/CDで文書品質を自動検証し、AIエージェントのオーケストレーターとして振る舞う時代が来ています。
なぜAIエージェントは「忘却」するのか
結論から言います。
コンテキスト設計こそが、AIエージェント活用の分岐点です。
Martin Fowler氏のサイトでも、コーディングエージェントにおけるコンテキスト設計の重要性が体系的に論じられています。（参考: Context Engineering for Coding Agents）
AIエージェントの最大の弱点は「忘れること」です。
ただし、これはバグではありません。
アーキテクチャ上の制約です。
コンテキストウィンドウという「作業デスク」
AIエージェントには「コンテキストウィンドウ」という、一度に参照できる情報量の上限があります。
Claude 4.xで約20万トークン。
日本語にすると、おおよそ新書1〜2冊分です。（参考: Effective context engineering for AI agents）
この上限は一見大きく見えますが、実際のプロジェクトでは足りなくなります。
コードファイル、テスト結果、会話履歴
——これらが積み上がると、ウィンドウはあっという間に埋まります。
Anthropicの公式ドキュメントでは、この状態を「context rot（コンテキストの腐敗）」と呼んでいます。
コンテキストウィンドウに入る情報が増えるほど、モデルが個々の情報を正確に思い出す能力は下がっていくのです。
Google Developersの研究でも、全情報を1つのプロンプトに詰め込むアプローチは、コスト増大、シグナル劣化（「Lost in the middle」問題）、物理的な限界という3つの圧力で破綻すると指摘されています。（参考: Architecting efficient context-aware multi-agent framework）
セッションの壁
コンテキストウィンドウよりもさらに深刻な問題があります。
セッションが終わると、情報がリセットされることです。
前回の会話で決めた設計方針、3日前に却下したライブラリの選定理由
——これらは、明示的に渡さない限り次のセッションには引き継がれません。
AIエージェントにとって、毎回が「ゼロスタート」なのです。
クリエーションラインのブログでも
「後半になると指示が薄れる」
「新しいチャットでコンテキストが消える」 という同様の課題が報告されています。（参考: コンテキストを永続化するドキュメント設計）
この現象は「ローンウルフ（一匹狼）現象」とも呼ばれています。
セッションが切れるたびにAIが過去の設計意図を忘却し、場当たり的なコードを生成してしまう状態です。
vibe codingの限界はここにある
Karpathy氏は2025年6月、自ら「prompt engineering」よりも「context engineering」という呼称を支持する投稿をしています。
コンテキストウィンドウを適切な情報で満たすことは「繊細な技術（delicate art and science）」だと表現しました。（参考: Andrej Karpathy - context engineering）
prompt engineeringが「プロンプトの言い回し」に注目するのに対し、context engineeringは「モデルの情報環境全体を動的に設計・管理すること」を指します。（参考: Context Engineering: The Next Frontier Beyond Prompt Engineering）
vibe codingの問題は、この「繊細な技術」を省略していることにあります。
雰囲気で指示を出すスタイルでは、プロジェクトの「記憶」がどこにも永続化されません。
その結果、同じ設計判断を何度も説明する羽目になり、チームメンバーごとにAIの出力がバラバラになり、過去に却下したアプローチをAIが再提案してくるわけです。
この制約を「仕方ない」で終わらせるか、「設計で解決する」か。
ここからが本題です。
コンテキストの3層構造
AIエージェントの「忘却」に対抗するためには、コンテキストを構造化して外部に永続化する必要があります。
Anthropicの公式ガイドやGoogle ADKの設計思想を踏まえると、コンテキストは大きく3つの層に分けて設計するのが効果的です。
第1層：プロジェクト層（CLAUDE.md / AGENTS.md）
リポジトリのルートに配置する「プロジェクト全体の文脈」です。
技術スタック、コーディング規約、デプロイ手順、ガードレール（変更時に確認すべきこと）
——プロジェクトに関わるAIエージェントが最初に読み込む「エントリーポイント」として機能します。
建物にたとえるなら、「設計図」にあたる層です。
どの建材を使うか、どの工法を採用するか。
建物の全体像を示します。
第2層：ディレクトリ層（.claude/rules/ など）
特定のディレクトリやファイルパターンに適用されるルールです。
たとえば、src/components/ 配下では「コンポーネントは関数コンポーネントで書く」、テストファイルでは「モックは最小限にする」、API関連では「エラーハンドリングを必ず入れる」といった具合です。
建物にたとえるなら、「フロアガイド」です。
1階は受付、2階は会議室
——場所ごとのルールが書かれています。
pathベースのスコーピングによって、AIエージェントは必要な場面でのみ適切なルールを参照します。
全体ルールの肥大化を防ぎ、関心の分離を実現する層です。
第3層：タスク層（ADR・メモリ・スクラッチパッド）
個別のタスクや意思決定の履歴を記録する層です。
- ADR（Architecture Decision Records）:
「なぜこの技術を選んだか」
「なぜこのアプローチを却下したか」
を記録する文書。
詳しくは次のセクションで解説します。 - メモリ:
AIエージェントが会話間で保持すべき情報です。
ユーザーの好み、過去のフィードバック、プロジェクト固有の知識などが含まれます。 - スクラッチパッド / TODO:
進行中のタスクの状態管理に使います。
建物にたとえるなら、「作業メモ」です。
「この壁は昨日塗り直した」
「あの配線は仕様変更で不要になった」
——現場の判断履歴です。
この3層構造のポイントは、情報を「変化頻度」と「適用範囲」で分離することにあります。
プロジェクト層は半年〜1年変わらない情報、ディレクトリ層は数か月単位で見直す情報、タスク層は日々更新される情報を扱います。
AI向け指示ファイルの標準化
3層構造の考え方を理解したところで、最も実践的な部分に入ります。
AIエージェントに「文脈を渡す」ための指示ファイルをどう書くかです。
CLAUDE.md：プロジェクトの「取扱説明書」
CLAUDE.mdは、Anthropicが導入したClaude Code向けの指示ファイルです。
プロジェクトのルートに配置すると、AIエージェントがセッション開始時に全文を読み込みます。（参考: How Claude remembers your project）
公式ドキュメントには、こう記載されています。
CLAUDE.md files provide persistent instructions to guide Claude’s behavior across sessions.
セッションをまたいで持続する指示を提供する
——まさに「忘却」に対する直接的な解決策です。
ただし重要な注意点があります。
公式ドキュメントでは「短いファイルほど遵守率が高い」とも明記されています。
全てをCLAUDE.mdに詰め込むのは逆効果です。
HumanLayerのブログでは、ルートのCLAUDE.mdを60行以下に保つことが推奨されています。
詳細は別ファイルに分離し、必要なときだけ参照させる「Progressive Disclosure（段階的開示）」のアプローチが効果的です。（参考: Writing a good CLAUDE.md）
AGENTS.md：ツールを超えた標準化の動き
Claude CodeにはCLAUDE.md、Cursorには.cursorrules、Windsurfには.windsurfrules
——現在、AIコーディングツールごとに異なる指示ファイル名が使われています。
しかし、「リポジトリに指示を埋め込む」という思想自体は共通しています。
この状況を統一しようとする動きがAGENTS.mdです。
6万以上のオープンソースプロジェクトで使用され、Linux Foundation傘下のAgentic AI Foundationに寄贈されてオープン標準になりました。（参考: AGENTS.md）
AGENTS.mdの公式サイトでは、README.mdが人間向けであるのに対し、AGENTS.mdはAIエージェント向けの「予測可能な場所」として機能すると説明しています。
1つのAGENTS.mdで、複数のAIツールが共通の指示を参照できるようになります。
今後は、ツールごとに異なる指示ファイルを管理する必要がなくなる方向に進むでしょう。
効果的な指示ファイルの書き方（3原則）
指示ファイルを書く際の原則を3つにまとめます。
- 短く保つ。
ルートの指示ファイルは80〜120行が目安です。
AIのコンテキストウィンドウを圧迫しないためです。 - 階層化する。
全体ルールはルートに、詳細はディレクトリ別に配置します。
第2層のディレクトリ層を活用してください。 - 変化頻度で分ける。
半年〜1年変わらない情報（技術スタック、ガードレール）をルートに、頻繁に変わる情報（現在のスプリント目標など）は参照先に置きます。
プロジェクトのルートにCLAUDE.mdを1つ作り、ビルドコマンド、テストコマンド、コーディング規約の3つを書くだけで、AIエージェントの出力が変わります。
ADR：AIの再提案を防ぐガードレール
コンテキスト設計で見過ごされがちですが、最もインパクトがあるのがADR（Architecture Decision Records）の活用です。
2011年の手法、2026年に再発見
ADRは、Michael Nygard氏が2011年に提唱したアーキテクチャ上の意思決定を記録する文書です。
各ADRは「タイトル」「ステータス」「コンテキスト」「決定」「結果」の5要素で構成されます。（参考: Documenting Architecture Decisions）
元々は人間のチーム向けに設計されたものでした。
「なぜReactを選んだのか」
「なぜこのORMを採用したのか」
——チームの新メンバーが過去の判断を理解するための文書です。
しかし2026年、ADRはAIエージェント時代に新しい価値を発揮しています。
AIにとってのADRの価値
AIエージェントにとって最も厄介なのは、「過去に却下された理由」を知らないことです。
たとえば、チームがReactではなくPreactを選んだプロジェクトがあるとします。
ADRがなければ、AIエージェントは何度も「Reactに移行しませんか？」と提案してきます。
却下した理由を知らないからです。
ADRにこう書いておけば、この再提案を防げます。
## Alternatives Considered
- React: バンドルサイズが要件を超えるため却下
- Svelte: チームの学習コストが高いため却下
## Agent Constraints
- UIフレームワークの変更提案は禁止。変更が必要な場合はADR更新を先に行うこと
Chris Swan氏は自身のブログで「ADRは自然言語で構造を持つため、LLMに最適だ」と指摘しています。
人間が読めて、AIも解釈できる。この両立がADRの強みです。（参考: Using ADRs with AI coding assistants）
実践のポイント
ADRの導入は、形式にこだわりすぎないことが大切です。
docs/decisions/ディレクトリに番号付きで配置します（例:001-use-preact-over-react.md）。- CLAUDE.mdから参照パスを記載しておけば、AIが必要に応じて読み込みます。
- すべてのADRを毎回読み込ませる必要はありません。関連するものだけをコンテキストに含めてください。
- ステータス管理（proposed → accepted → deprecated）で、現在有効な決定がどれかを明示します。
2026年のベストプラクティスでは、ADRテンプレートに「Alternatives Considered（検討した代替案）」と「Agent Constraints（AIへの制約）」を含めることが推奨されています。
AIが不適切な設計を再提案するのを防ぐための仕組みです。
決定と理由が書いてあれば、形式は自由です。
大事なのは「書くこと」そのものです。
Docs-as-CodeとCI/CD
指示ファイルもADRも、書いた時点では最新です。
問題は、時間とともに陳腐化することにあります。
古い情報が残ったCLAUDE.mdは、AIに誤った前提を与えるリスクがあります。
「文書も腐る」のです。
Docs-as-Codeという考え方
Docs-as-Codeは、「ドキュメントをコードと同じツールで管理する」という哲学です。
Write the Docsコミュニティが提唱しているアプローチで、バージョン管理、レビュー、自動テストの対象にすることで、文書の品質と鮮度を保証します。（参考: Docs as Code）
AIエージェントのコンテキストとなる文書
——CLAUDE.md、ADR、ディレクトリ別ルール
——これらもすべて「コード」として扱います。
PRレビューの対象にし、変更履歴を追跡し、品質を自動検証するのです。
CI/CDで文書の鮮度を守る
具体的にCI/CDパイプラインに何を組み込むべきでしょうか。
NotebookLMの調査では、3段階のドキュメントガバナンスが提唱されています。
第1段階：PRテンプレートによる意識付け。
コード変更時に「ドキュメント更新は不要か？」を確認するチェックリストをPRテンプレートに含めます。
不要な場合は理由を明記させます。
第2段階：CIによる自動チェック。src/ 配下のコードが変更されたのに docs/ 配下の更新がない場合、PRをブロックします。
リンク切れチェック、フォーマット検証も自動化します。
第3段階：定期的な鮮度監視。
過去90日以上更新されていないドキュメントを「STALE」として検出し、GitHub Issueを自動起票します。
特に強力なのは、アーキテクチャに関わるコードが変更されたのに対応するADRが更新されていない場合にPRをブロックする「Eval-Gated CI」の仕組みです。
コードとドキュメントの同期を物理的に強制します。
結論：オーケストレーターとしての人間
この記事では、AIエージェントの「忘却」問題に対する4つの実践手法を解説しました。
- コンテキストの3層構造を理解する。
プロジェクト層、ディレクトリ層、タスク層で情報を整理し、適切な粒度でAIに渡します。 - CLAUDE.mdなどの指示ファイルでプロジェクトの文脈を永続化する。
短く、階層的に、変化頻度で分けて管理します。 - ADRで意思決定の履歴を残し、AIの再提案を防ぐ。
却下理由と制約条件を明記することがポイントです。 - Docs-as-CodeとCI/CDで文書品質を継続的に保証する。
書いて終わりではなく、鮮度を維持する仕組みを作ります。
コンテキスト設計は、「AIに仕事を奪われないためのスキル」ではありません。
AIとの協業の質を根本的に変える設計行為です。
ある調査レポートにはこう記されています。
「最も成功する組織は、最大のモデルを持つ組織ではなく、最も堅牢なコンテキストエンジニアリング・パイプラインを持つ組織だ」と。
エンジニアの役割は「コードを書く人」から「AIエージェントのオーケストレーター」へとシフトしています。
コンテキスト設計は、そのオーケストレーションの楽譜にあたります。
まずはプロジェクトのルートにCLAUDE.mdを1つ作るところから始めてみてください。
ビルドコマンド、テストコマンド、最も大事なコーディング規約
——この3つを書くだけで十分です。
AIエージェントの振る舞いが変わるはずです。
なお、AIエージェントのコンテキスト設計は急速に進化している分野です。
この記事の情報は2026年3月時点のものであり、各ツールの最新仕様は公式ドキュメントを確認してください。