AGENTS.mdは本当に効果的か？初の実証論文が明かした意外な結果

概要

Cursor、Claude Code、Codexなどのコーディングエージェントが普及する中、リポジトリにAGENTS.md（またはCLAUDE.md、CURSOR.md）ファイルを配置し、エージェントにプロジェクトのコンテキストを提供するプラクティスが急速に広まっています。現在、GitHubだけで6万以上のリポジトリがこのファイルを含んでいます。

しかし、このファイルは本当にエージェントのタスク成功率を向上させるのでしょうか？ ETH Zürichの研究チームが、この問いに対する初の実証的な回答を発表しました。

📄 論文: Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?（arXiv 2602.11988、2026年2月）

核心的な発見：予想を覆す結果

LLM生成コンテキストファイルはむしろ成功率を下げる

研究チームは3つの設定でコーディングエージェントを評価しました：

1. コンテキストファイルなし（ベースライン）
2. LLMが自動生成したコンテキストファイル（エージェント開発者推奨方式）
3. 開発者が手動で作成したコンテキストファイル

┌─────────────────────────────────────────────┐
│        設定別の平均成功率変化                  │
├─────────────────────────────────────────────┤
│  コンテキストなし（基準）   : ████████ 基準   │
│  LLM生成コンテキスト       : ██████▌  -3%    │
│  開発者作成コンテキスト     : ████████▌ +4%   │
└─────────────────────────────────────────────┘

主要な数値をまとめると：

• LLM生成ファイル：平均成功率3%低下
• 開発者作成ファイル：平均成功率4%向上（わずかな改善）
• 推論コスト：どちらの場合も20%以上増加

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

研究チームはエージェントの行動パターンを詳細に分析しました：

graph TD
    A[AGENTS.md提供] --> B[より広い探索範囲]
    B --> C[より多くのファイル探索]
    B --> D[より多くのテスト実行]
    B --> E[より長い推論チェーン]
    C --> F[不要な要件への準拠試行]
    D --> F
    E --> F
    F --> G[コスト増加 + 成功率低下]

エージェントはコンテキストファイルの指示を忠実に従う傾向がありました。問題は、その指示の多くが当該タスクにとって不要な要件だったという点です。スタイルガイドの遵守、特定のテストパターンの使用などの指示が、むしろタスクを複雑にしていました。

AGENTbench：新しいベンチマーク

研究チームはこの評価のためにAGENTbenchという新しいベンチマークを構築しました。

項目	内容
インスタンス数	138個
対象リポジトリ	12個（開発者がコンテキストファイルを実際に使用しているリポジトリ）
タスク種類	バグ修正 + 機能追加
補完ベンチマーク	SWE-bench Lite（有名リポジトリ対象）

既存のSWE-benchは有名な大規模リポジトリが中心で、AGENTS.mdが含まれていませんでした。AGENTbenchは実際にコンテキストファイルを使用しているリポジトリからタスクを収集した初のベンチマークです。

実践的な示唆：どう活用すべきか？

❌ やるべきでないこと

• LLMに/initコマンドでAGENTS.mdを自動生成させること
• プロジェクトの全ルール、スタイルガイド、アーキテクチャ説明を1ファイルに詰め込むこと
• エージェントが「全部読んでくれる」と期待して膨大なコンテキストを提供すること

✅ やるべきこと

研究チームの推奨事項は明確です：「最小限の要件のみを記述せよ」

効果的なAGENTS.md作成の原則：

1. ビルド・テストコマンドのみ明記（例：npm test、pytest）
2. プロジェクト固有のツールの使い方のみ記述
3. スタイルガイドやアーキテクチャ説明は別ドキュメントに分離
4. エージェントがタスクに直接必要な情報のみ含める

# 良いAGENTS.mdの例

## ビルド
npm install && npm run build

## テスト
npm test              # 全テスト
npm test -- --grep "パターン"  # 特定テスト

## リント
npm run lint          # コミット前に必ず実行

# 悪いAGENTS.mdの例（不要な要件が過多）

## アーキテクチャ
このプロジェクトはクリーンアーキテクチャに従い...
（冗長な説明200行）

## コーディングスタイル
すべての関数にはJSDocコメントを含める必要があり...
変数名は必ずキャメルケースで...
（詳細ルール100行）

## コミット規則
Conventional Commitsに従い...

開発コミュニティの反応

この論文はHacker Newsで58ポイントを記録し、活発な議論を呼びました。主な反応は：

• 「直感的に正しい結果だ」：過度な指示がエージェントをかえって混乱させるという経験的な共感
• 「コンテキストウィンドウの浪費」：長いAGENTS.mdが実際のコードコンテキストを押し出すという懸念
• 「ミニマルが最善」：ビルド・テストコマンドだけで十分だという実務経験の共有

限界と今後の展望

この研究にはいくつかの限界があります：

• Python中心：AGENTbenchはPythonプロジェクトのみが対象
• ニッチなリポジトリ：開発者がコンテキストファイルを使用しているリポジトリは比較的小規模
• 静的評価：コンテキストファイルが繰り返しタスクで累積効果を発揮するかは未検証

今後の研究方向としては：

1. 適応的コンテキスト：タスク種類に応じて必要な情報のみを動的に提供
2. 構造化コンテキスト：自由テキストの代わりに機械がパースしやすい形式を活用
3. 多言語への拡張：Python以外の言語での効果検証

結論

AGENTS.mdはコーディングエージェントのエコシステムで事実上の標準になりつつありますが、今回の論文は「多く書けば書くほど良い」という通念にブレーキをかけました。

核心的なメッセージはシンプルです：

コンテキストファイルは最小限に、ビルドとテストコマンド中心で作成せよ。

エージェント開発者の推奨通りに/initで自動生成するのは、現時点ではむしろ逆効果になり得ます。手動で作成し、本当に必要な情報だけを含めるのが最も効果的な戦略です。

参考資料

• 論文原文（arXiv）
• AGENTbench GitHubリポジトリ
• AGENTS.md公式サイト
• Hacker Newsでの議論