AGENTS.md はコーディングエージェントに本当に役立つのか？— ETH Zürich論文分析

コーディングエージェントを使っていると、一度は目にするファイルがあります。AGENTS.md、CLAUDE.md、CODEX.md のようなコンテキストファイルです。リポジトリの構造、ビルド方法、コーディング規約などをエージェントに伝える一種の「エージェント用 README」ですが、Anthropic・OpenAI・Alibaba をはじめ、すべてのエージェントベンダーが積極的に推奨しており、GitHub には 6 万以上のリポジトリに含まれています。

しかし、本当に効果があるのでしょうか？

ETH Zürich の Thibaud Gloaguen らが ICML 2026 に発表した論文 "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" は、この質問に初めて定量的な答えを出しました。結論から言うと、現在の方式のコンテキストファイルは期待ほど効果的ではありません。

実験設計: 2つのベンチマーク、3つの条件

研究チームは 2 つのベンチマークを使用しました。

SWE-bench Lite: 11 個の有名な Python プロジェクトから抽出した 300 個の GitHub issue。コンテキストファイルがないリポジトリです。
AGENTbench (新規): 研究チームが独自に構築したベンチマーク。開発者が実際にコンテキストファイルをコミットした 12 個のニッチなリポジトリから 138 個の issue を収集しました。

各ベンチマークで 3 つの条件で実験しました。

None: コンテキストファイルなし
LLM: エージェントの /init コマンドで自動生成したコンテキストファイル
Human: 開発者が直接作成したコンテキストファイル (AGENTbench のみ)

コーディングエージェントは Claude Code(Sonnet 4.5)、Codex(GPT-5.2, GPT-5.1 mini)、Qwen Code(Qwen3-30b-coder) の 4 種類をテストしました。

主要な結果: LLM 生成ファイルはむしろ逆効果

結果を要約すると以下のようになります。

LLM が自動生成したコンテキストファイル:

8 つの設定のうち 5 つで 性能低下 (平均 -0.5%~-2%)
推論コストは 20~23% 増加
ステップ数も平均 2.5~3.9 個増加

開発者が直接書いたコンテキストファイル:

Claude Code を除く 3 つのエージェントでわずかに性能向上 (平均 +4%)
しかしコストは同様に増加 (最大 19%)

一言で言うと、LLM が自動生成したコンテキストファイルはお金がかかるだけで性能は低下します。開発者が直接書いたファイルはわずかな改善効果がありますが、それもコスト効率が良いとは言えません。

なぜこのような結果になったのか？

1. 既存のドキュメントとの重複

LLM が生成したコンテキストファイルのほとんどは、README、docs/、サンプルコードなど、すでにリポジトリにある情報を繰り返していました。研究チームがリポジトリからすべてのドキュメントを削除した後に実験したところ、LLM 生成コンテキストファイルがむしろ 平均 2.7% の性能向上を示しました。つまり、ドキュメントが十分なリポジトリでは、コンテキストファイルは純粋なノイズになるということです。

2. リポジトリの概要は実質的に無意味

コンテキストファイルの代表的な推奨事項が「リポジトリ構造の概要を入れること」ですが、実験の結果、関連ファイルをより早く見つけるのにまったく役立ちませんでした。むしろ GPT-5.1 mini は、コンテキストファイルがあると、そのファイルを何度も繰り返し読むという非効率的な行動を見せました。

3. 不必要な要求事項がタスクを難しくする

コンテキストファイルに「このプロジェクトは uv を使用します」、「テストは pytest で実行してください」のような指示が入ると、エージェントはそれを 忠実に守ります。問題は、その過程でより多くの探索、より多くのテスト、より多くの推論トークンを消費するということです。GPT-5.2 の reasoning トークンは、コンテキストファイルがあるとき 22% 増加 しました。エージェントが指示を無視して問題なのではなく、あまりにもよく守って問題なのです。

4. 強力なモデルがより良いコンテキストファイルを作成するわけでもない

GPT-5.2 で生成したコンテキストファイルを他のエージェントに入れてみましたが、SWE-bench Lite ではわずかな改善(+2%)があったものの、AGENTbench ではむしろ -3% でした。プロンプトを変更しても一貫した違いはありませんでした。

実務的な示唆

今すぐできること

LLM 自動生成コンテキストファイルは使用しないでください。 /init で自動生成することは、現時点ではコストを増やすだけで性能上のメリットはありません。

手動で書く場合は最小限にしてください。 論文の結論は明確です: 「リポジトリの概要」、「ディレクトリの説明」、「アーキテクチャ図」のようなものは入れないでください。エージェントはすでに grep と find でリポジトリを探索できます。むしろ、エージェントが自力で知り得ない情報のみを入れるべきです。

効果的なコンテキストファイルの例:

このプロジェクトは uv で依存関係を管理する (pip ではない)
テスト実行: make test-unit (pytest を直接呼び出すことは禁止)
CI で Python 3.12 のみサポート
src/legacy/ は触らないでください

効果的でないコンテキストファイルの例:

プロジェクトの概要と目的の説明
ディレクトリ構造のリスト
コーディングスタイルガイド (lint がチェックする)
アーキテクチャの説明

ドキュメントが不足しているリポジトリでは効果的

興味深いことに、ドキュメントがほとんどないリポジトリでは、コンテキストファイルが実際に役立ちます。内部プロジェクトやドキュメント化が不十分なリポジトリでエージェントを使用する場合は、ビルド/テストコマンドと主要な依存関係程度を書き留めておくことは有意義な効果があります。

Python 以外の言語では？

この論文は Python のみを扱っています。Python は LLM 学習データに豊富に含まれている言語であるため、モデルはすでに pip、pytest、Django、Flask などの慣習をよく知っています。Rust、Zig、Elixir のようなニッチな言語では、コンテキストファイルの効果が変わる可能性があります。これは今後の研究課題として残っています。

私たちのワークフローへの適用

この論文の教訓をまとめると:

AGENTS.md にリポジトリ構造を長々と書かないでください — エージェントはすでに探索能力があります
エージェントが知り得ないことだけを書いてください — ビルドツール、特殊なコマンド、禁止領域
自動生成(/init)は避けてください — 既存のドキュメントと重複すると純粋な害
コストモニタリング必須 — コンテキストファイル追加後、トークン使用量が 20%+ 増加する可能性があります
ドキュメントがないプロジェクトでのみ積極的に作成してください

結局のところ、良いコンテキストファイルは 短く、具体的で、エージェントが自力で発見できない情報のみ を含んでいる必要があります。「より多くの情報 = より良い結果」という直感は、少なくとも現在のコーディングエージェントには通用しません。

論文: Gloaguen et al., "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", ICML 2026. arXiv:2602.11988

ベンチマークコード: github.com/eth-sri/agentbench