CLAUDE.mdにプロジェクトのルール、アーキテクチャ概要、スタイルガイド、ツール設定…。「書いておけばAIが読んでくれるだろう」と、つい全部盛りにしたくなる気持ちは分かります。
Claude Codeの生みの親であるBoris Cherny氏は、CLAUDE.mdを**「AIのための失敗ノート」**として活用することを推奨しています。AIが間違えるたびに「次からはこうしてね」と書き加え、チームの共有財産として週に何度も更新する。AIは作業前に必ずこのノートを読み、使うほど賢くなっていく…。直感的に正しそうなアプローチですし、AIコーディングエージェントの開発元も/initコマンドによるコンテキストファイル自動生成を推奨しています。GitHubでは6万以上のリポジトリが導入済み。もはや定番のプラクティスです。
ところが、2026年2月に公開されたETH Zurichの研究が、この常識に冷や水を浴びせました。コンテキストファイルは、むしろエージェントのパフォーマンスを下げている可能性があるという実証結果です。
研究の概要：コンテキストファイルの効果を初めて定量評価
Gloaguen et al.による論文 "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" は、CLAUDE.mdやAGENTS.mdがコーディングエージェントの実タスク解決にどう影響するかを、初めて厳密に評価した研究です。
研究チームは2つのベンチマークを用いて評価を行いました。既存のSWE-bench Liteに加え、開発者が実際にコンテキストファイルを運用している12のリポジトリから138件のタスクを収集した新ベンチマーク「AGENTBENCH」を構築しています。
評価対象は4つのコーディングエージェント（Claude Code / Codex / Qwen Code）と4つのLLM。3つの条件で比較しました。
- None：コンテキストファイルなし
- LLM：エージェント推奨の方法で自動生成したコンテキストファイル
- Human：開発者が手書きしたコンテキストファイル
LLM自動生成のコンテキストファイルは逆効果
結果は、多くの開発者の直感に反するものでした。
LLM自動生成のコンテキストファイルは、タスク成功率を平均2〜3%低下させました。8つの設定のうち5つで、コンテキストファイルなしの条件を下回っています。一方で推論コストは平均20%以上増加し、タスク完了までのステップ数も全設定で増えています。
開発者が手書きしたコンテキストファイルは若干の改善（平均+4%）を見せましたが、それでもコスト増は最大19%に達し、ステップ数は平均3.34増加しました。
| 条件 | タスク成功率の変化 | 推論コストの変化 |
|---|---|---|
| LLM自動生成 | -2〜3%（平均） | +20〜23% |
| 開発者手書き | +4%（平均） | 最大+19% |
指示は守られている。問題は「量」
興味深いのは、コンテキストファイルの指示自体はきちんと守られている点です。たとえば uv というツールがコンテキストファイルに記載されている場合、インスタンスあたり平均1.6回使用されましたが、記載がなければ0.01回未満でした。リポジトリ固有ツールも同様に、記載の有無で使用頻度が50倍以上異なります。
つまり、パフォーマンス低下の原因は「指示を無視しているから」ではありません。指示が多すぎて、タスクそのものが難しくなっているのです。
これを裏付けるように、GPT-5.2の推論トークン数はコンテキストファイルの存在により22%増加しています。エージェント自身が「このタスクはより難しい」と判断し、より多くの思考リソースを割いている証拠です。
コンテキストファイルはリポジトリ概要として機能しない
「コンテキストファイルにリポジトリ概要を書けば、エージェントが素早く目的のファイルにたどり着ける」という期待もありますが、研究はこれも否定しています。
エージェントがPRパッチに含まれるファイルに初めてアクセスするまでのステップ数は、コンテキストファイルの有無で有意な差がありませんでした。Sonnet-4.5が生成したコンテキストファイルの100%にリポジトリ概要が含まれていたにもかかわらず、です。
さらに問題なのは、GPT-5.1 Miniがコンテキストファイルを見つけるために複数のコマンドを発行し、すでにコンテキストに含まれているにもかかわらず繰り返し読み込むという行動が観察されたことです。コンテキストファイルの存在が、かえってエージェントの行動を非効率にしているケースすらあったのです。
自動生成ファイルが有効になる唯一の条件
ただし例外もあります。リポジトリからREADME.mdやdocs/フォルダなどのドキュメント類をすべて除去した場合、LLM自動生成のコンテキストファイルは平均2.7%の改善を見せ、開発者手書きのものを上回りました。
この結果は示唆的です。自動生成コンテキストファイルは、既存ドキュメントと大部分が重複している。ドキュメントが充実したリポジトリでは冗長なノイズにしかならず、ドキュメントの乏しいリポジトリでのみ価値を発揮するということです。
CLAUDE.mdには「最小限の固有情報」だけを
研究チームの結論は明確です。CLAUDE.mdやAGENTS.mdには最小限の要件のみを記述すべきであり、LLM自動生成のコンテキストファイルは現時点では使用を控えるべきだとしています。
では「最小限の要件」とは何か。この研究結果とこれまでの知見を合わせると、以下のような情報に絞るのが効果的です。
- プロジェクト固有のビルド・テストコマンド（npm test、uv run pytest など）
- リポジトリ固有のツールや規約（READMEからは読み取れないもの）
- コーディングスタイルの最低限の指定（使用禁止のパターンなど）
逆に含めるべきでないのは、アーキテクチャの網羅的な説明、設計方針の経緯、ファイル構造の一覧といった情報です。これらはエージェントが自力で発見できるか、もしくは静的に詰め込むよりも動的に参照したほうが効率的な情報です。
ルールと経緯はCLAUDE.mdの外に
では、設計方針の背景やプロジェクトの制約事項といった、開発の文脈を形成する重要な情報はどこに置くべきでしょうか。
Boris Cherny氏の「失敗をノートに書き留め、チームで共有する」という発想自体は正しいと考えています。過去の失敗から学び、同じ間違いを繰り返さないことは、開発チームにとって本質的に重要だからです。問題は、その蓄積先がCLAUDE.mdという一枚岩の静的ファイルであることにあります。
今回の研究が示したのは、コンテキストを「持たせる」ことと「活用できる」ことは別の問題だということです。CLAUDE.mdに全部書いても、情報量が増えるほどエージェントの推論品質は劣化し、コストは増加する。Chroma Researchの"Context Rot"研究が示すように、これはLLMの本質的な特性です。
sqlewは、この課題に対して「外部記憶化」というアプローチを取ります。設計方針（Decision）や誓約事項（Constraint）を構造化してデータベースに蓄積し、AIエージェントがMCP経由で必要な文脈だけをJust-in-Timeで取得する仕組みです。
CLAUDE.mdは「何をすべきか」の最小限の指示にとどめ、「なぜそうすべきか」という設計の根拠や経緯は外部記憶に委ねる。静的な全量投入から動的な選択的参照へ。今回の研究結果は、このアプローチの合理性を改めて裏付けています。
参考文献
- "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" — Gloaguen, T., Mündler, N., Müller, M., Raychev, V., & Vechev, M. (2026) — https://doi.org/10.48550/arXiv.2602.11988
- "Context Rot: How Increasing Input Tokens Impacts LLM Performance" — Chroma Research — https://research.trychroma.com/context-rot
- "Agent READMEs: An Empirical Study of Context Files for Agentic Coding" — Chatlatanagulchai, W. et al. (2025) — https://doi.org/10.48550/arXiv.2511.12884
- "AIは道具ってか15人の部下。Claude Code生みの親が語った"究極すぎるマネジメント術"" — かみやまたくみ, GIZMODO Japan (2026) — https://www.gizmodo.jp/2026/01/boris_cherny_how_to_use_claude_code.html
