🤖 AI

Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?

この論文は、コーディングエージェントに対するリポジトリレベルのコンテキストファイル（AGENTS.mdなど）の有効性を評価しており、一般的な慣行に反して、それらは通常タスクの成功率を向上させない一方で、推論コストを20%以上増加させるという結果を示している。

原著者： Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, Martin Vechev

公開日 2026-06-25

📖 1 分で読めます☕ さくっと読める

CC BY 4.0

原著者： Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, Martin Vechev

原論文は CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/) でライセンスされています。 ✨ これは以下の論文のAI生成解説です。著者が執筆または承認したものではありません。技術的な正確性については原論文を参照してください。免責事項の全文を読む

あなたは、非常に賢いが少し新人であるアシスタントを雇い、広大で散らかった作業場にある特定の問題を解決させようとしていると想像してください。このアシスタントはAIコーディングエージェントです。

アシスタントを助けるために、あなたは作業台の上に「チートシート」または「ユーザーマニュアル」（AGENTS.mdファイルと呼ばれます）を置いておくことにしました。このマニュアルには、以下のように伝えるつもりです。

「この作業場がどのように構成されているか」
「ものづくりにおいて従うべき具体的なルール」
「私たちの特別な道具を使いこなすための最善の方法」

ここで大きな疑問があります。このチートシートを残しておくことは、実際にアシスタントが仕事をより早く、より良く終わらせる助けになるのでしょうか？それとも、彼らを混乱させ、時間を無駄にさせるだけなのでしょうか？

研究者たちは、これを知るための巨大な実験を設定しました。以下に、その発見を分かりやすく説明します。

1. 「チートシート」のパラドックス

チームは2種類のチートシートをテストしました。

人間が書いたもの： 実際の作業場のオーナー（開発者）によって書かれたもの。
AIが生成したもの： エージェントのフレームワークの指示に従って、別のAIによって書かれたもの。

結果： 驚くべきことに、どちらのタイプのチートシートも、アシスタントの成功率を高めることはありませんでした。 実際、シートがあってもなくても、成功率はほぼ全く同じでした。

2. 「準備万端すぎる」アシスタント

チートシートは、アシスタントが「正解」にたどり着く頻度を高めることはできませんでしたが、アシスタントの「働き方」を変えました。

シートがない場合： アシスタントは周囲を見渡し、いくつか試行錯誤して、問題を解決しました。
シートがある場合： アシスタントはシートを読み、それを非常に真剣に受け止め、そして「調査旅行」に出かけました。彼らはより多くのファイルを確認し、より多くのテストを実行し、自分の作業を再確認しました。

落とし穴： この「徹底さ」にはコストがかかりました。アシスタントが読み込みやテストに時間を費やしたため、AIの利用料金（請求額）は20%以上増加しました。これは、単なる靴下の紛失事件を解決するために、百科事典を丸ごと読み耽る探偵を雇うようなものです。彼らは非常に丁寧ですが、決して速いわけではなく、高価でもあります。

3. 「地図」 vs 「指示書」

研究者たちは、チートシートが実際に何を行っているのかについて、以下の違いを発見しました。

「地図」（概要）： ほとんどのチートシートには、作業場全体の大きな説明（「ここには工具小屋があり、ここには塗装室がある……」など）が含まれていました。アシスタントはこれを読みましたが、それが正しい道具を見つける助けにはなりませんでした。 これは、角を曲がるべき道を知りたいだけの人に、都市の詳細な地図を渡すようなものです。
「指示書」（ルール）： チートシートにはまた、特定のルール（「常に赤いレンチを使用すること」「サンディングの前に塗装してはいけない」など）も含まれていました。アシスタントはこれらのルールを完璧に守りました。 彼らは、言及されている特定の道具を使用し、特定のステップに従いました。

4. 結論：少なめの方が良い（今のところは）

論文は、現在、これらのチートシートを自動生成することは、金の無駄であると結論付けています。

もしAIを使ってチートシートを書かせると、エージェントを混乱させ、予算を浪費させるだけの「情報の詰め込み（長大な概要）」を追加することになります。
もし人間が書く場合、AI版よりは多少マシではありますが、それでも成功率を大幅に向上させることはできません。

まとめ：
もしあなたがAIエージェントの開発者なら、膨大なAI生成マニュアルをエージェントに投げ込まないでください。それは、エージェントを賢くするのではなく、単に作業量を増やし、コストを増大させるだけです。

もしどうしてもチートシートが必要なら、短く保ってください。コードから既に明白なことではなく、具体的で特殊なルール（例：「常に赤いレンチを使う」）だけを含めてください。作業場の歴史などを長く書かないでください。エージェントは自分自身でそれを理解できます。

要するに： チートシートは、エージェントを「より優れた成績を取る生徒」にするのではなく、「より熱心に勉強する従順な生徒」にします。そして、一生懸命勉強することには、高い授業料がかかるのです。

技術要約：AGENTS.md の評価

問題提起

ソフトウェアエンジニアリング業界ではコーディングエージェントの採用が急速に進んでおり、モデルやエージェントの開発者からは、リポジトリに特化したコンテキストファイル（AGENTS.md や CLAUDE.md など）を用いてエージェントをカスタマイズすることが推奨されています。これらのファイルには通常、ナビゲーション、ビルド実行、およびタスク解決を改善することを目的とした、リポジトリの概要、ツールの指示、およびスタイルガイドが含まれています。60,000以上のオープンソースリポジトリで報告されている広範な採用と業界からの強い推奨にもかかわらず、これらのコンテキストファイルが実際のタスクにおいてコーディングエージェントのパフォーマンスを本当に向上させるのかについて、厳密かつ大規模な調査は行われていません。SWE-benchのような従来のベンチマークにはコンテキストファイルが含まれておらず、それらのベンチマークで使用される一般的なリポジトリは、コンテキストファイルが実際に展開されているコードベースを代表していない可能性があります。

メソドロジー

このギャップに対処するため、著者らは2つの補完的な設定にわたって包括的な評価を実施しました。

新規ベンチマーク (CTXBENCH): 著者らは、開発者がコミットしたコンテキストファイルが既に存在する、12のニッチなPythonベースのリポジトリから派生した138のインスタンスからなる新しいベンチマークを構築しました。人気のあるリポジトリに依存するSWE-benchとは異なり、CTXBENCHはコンテキストファイルが活発に活用されているリポジトリを対象としています。データセットの生成プロセスには以下が含まれます：
- AGENTS.md または CLAUDE.md を持ち、かつ400件以上のプルリクエスト（PR）が存在するリポジトリのフィルタリング。
- 決定論的でテスト可能な振る舞いを導入するPRの選択。
- 元のPRにテストが欠けている場合に備え、LLMエージェントを使用して標準化されたタスク記述と新しいユニットテストを生成すること。これにより、テストは修正後のコードではパスし、ベースとなるコードでは失敗するように設計されています。
- 開発者が提供したコンテキストファイルが、LLMによって生成されたもの（より短く、AI検出スコアが低い）とは明確に異なることを検証。
実験設定: 本研究では、4つのコーディングエージェント（CLAUDE CODE, CODEX, QWEN CODE）を、様々なモデル（SONNET-4.5, GPT-5.2, GPT-5.1 Mini, QWEN3-30B-CODER）と組み合わせて、2つのデータセットで評価しました。
- SWE-BENCH Lite: 開発者によるコンテキストファイルが含まれていない人気リポジトリからの300のタスク。
- CTXBENCH: 開発者によるコンテキストファイルが含まれているリポジトリからの138のタスク。
評価条件: 各タスクに対し、エージェントは以下の3つの設定でテストされました：
- None (なし): コンテキストファイルを提供しない。
- LLM: エージェントが推奨する初期化コマンドによって自動生成されたコンテキストファイル。
- DEV: 実際の開発者がコミットしたコンテキストファイル（CTXBENCHでのみ利用可能）。
指標: パフォーマンスは、成功率（生成されたパッチがすべてのテストに合格したタスクの割合）、インタラクションステップ数、および総推論コストによって測定されました。また、ツールの使用頻度や推論トークンの消費量を含む、行動の変化を理解するためのトレース分析が行われました。

主な貢献

CTXBENCH: 開発者が提供するコンテキストファイルがコーディングエージェントに与える影響を評価するために特別に設計された、12のリポジトリからなる138のインスタンスを含む新しいベンチマーク。
包括的な評価: SWE-BENCHおよびCTXBENCHの両方における複数のモデルとエージェントにわたる広範な調査により、コンテキストファイルがタスクの成功率を大幅に向上させるわけではないことを明らかにしました。
行動分析: エージェントのトレースに関する詳細な調査により、エージェントはコンテキストファイル内の指示を厳格に遵守する（結果としてテストや探索が増加する）一方で、これらのファイルは効果的なリポジトリの概要として機能せず、運用コストを増大させていることが示されました。

結果

本研究は、コンテキストファイルの有効性に関して、いくつかの直感に反する知見を提示しています。

パフォーマンスの向上なし: コンテキストファイルを提供しても、一般にタスクの成功率は向上しません。
- SWE-BENCHでは、LLM生成のコンテキストファイルは、成功率のわずかな（統計的に有意ではない）低下を招きました（平均 -0.5%）。
- CTXBENCHにおいても、LLM生成ファイルは有意な改善を示しませんでした（平均 -2%）。
- 開発者がコミットしたファイルは、「None」の設定に対して平均2.4%のわずかな改善を示しましたが、これは統計的に有意ではありませんでした（ $p=0.21$ ）。しかし、開発者ファイルはLLM生成ファイルよりも有意に優れた結果を示しました（ $p=0.038$ ）。
コストとステップ数の増加: コンテキストファイルは、一貫してタスク解決のコストと複雑さを増大させます。
- LLM生成ファイルは、両方のベンチマーク全体で、推論コストを平均20%以上増加させました。
- 開発者がコミットしたファイルは、コストを最大19%増加させました。
- コンテキストファイルが存在するすべての設定において、インタラクションステップ数が大幅に増加しました。
行動メカニズム:
- 指示への追従: エージェントはコンテキストファイル内の指示を厳格に遵守します。特定のツール（例：uv, pytest）が言及されると、その使用頻度が劇的に増加します。これにより、より徹底したテスト、ファイル探索、およびリポジトリ固有のツール使用が行われます。
- 不適切な概要: コードベースの概要を含めるという推奨事項があるにもかかわらず、これらのセクションはエージェントが関連ファイルを見つける速度を向上させません。実際、エージェントはすでにコンテキストウィンドウ内にあるコンテキストファイルを検索したり再読したりするために、余分なステップを費やすことがよくあります。
- 推論のオーバーヘッド: コンテキストファイルの存在は、適応型モデル（例：LLM生成ファイルを用いた場合のGPT-5.2で+22%）の推論トークン使用量を増加させます。これは、追加の指示が必要な情報を提供することなく、タスクを認知的に難しくしていることを示唆しています。
冗長性: コンテキストファイルはしばしば冗長なドキュメントとして機能します。既存のドキュメント（README、docsフォルダ）が削除された場合、LLM生成コンテキストファイルは実際にパフォーマンスを向上させました。これは、標準的な設定における主な価値が、独自の洞察ではなく冗長性にあることを示唆しています。

重要性と結論

本論文は、AGENTS.md のようなコンテキストファイルを自動生成したり広く含めたりするという現在の業界の慣行は、コーディングエージェントのパフォーマンスを向上させるという実証的な証拠に裏付けられていないと結論付けています。エージェントはコンテキストファイル内の指示に従い、より徹底した（そしてコストのかかる）探索を行うものの、これらのファイルはタスク解決を加速させる効果的なリポジトリの概要として機能しないことが一般的です。

著者らは、コンテキストファイルは、リポジトリのREADMEに既に存在する非標準的なコーディング慣行や特定の規約を指定するために予約されるべきであると主張しています。開発者は、自動生成や広範な推奨に頼るのではなく、コンテキストファイルを使用するあらゆる試みを、デプロイ前に厳密に評価することを推奨しています。本研究は、エージェント開発者の推奨事項と観察された結果との間の乖離を浮き彫りにしており、コーディングエージェントのための、原則に基づいた簡潔かつタスクに関連したガイダンス生成の研究を動機付けるものです。