新研究がAIコーディングにおけるAGENTS.mdファイルの価値を再評価
ETH Zurichの研究チームは、AIコーディングエージェントのためのAGENTS.mdファイルが実際には作業を妨げる可能性があると結論付け、LLM生成のコンテキストファイルを完全に省略し、人間が書く指示は推測不可能な詳細に限定することを推奨している。
キーポイント
AGENTS.mdファイルの再評価
業界で広く推奨されているにもかかわらず、ETH Zurichの研究論文はAGENTS.mdファイルがAIコーディングエージェントの作業をしばしば妨げると結論付けた。
LLM生成コンテキストファイルの省略推奨
研究者は、LLMによって生成されたコンテキストファイルを完全に省略することを推奨している。
人間による指示の限定
人間が書く指示は、高度に特定されたツーリングやカスタムビルドコマンドなど、推測不可能な詳細に限定すべきだと提案している。
影響分析・編集コメントを表示
影響分析
この研究は、AIコーディング支援ツールの実践的な運用方法に疑問を投げかけ、現在のベストプラクティスを見直す必要性を示唆している。開発現場でのAIエージェントの効率的な活用方法に直接影響を与える可能性があり、ツール設計やプロンプトエンジニアリングの考え方に変化をもたらすかもしれない。
編集コメント
業界の常識に挑戦する研究結果で、AIコーディング支援の実践的な運用方法に再考を促す内容。現場の開発者にとっては、ツールの設定方法を見直すきっかけとなる可能性がある。
業界全体で広く推奨されているにもかかわらず、チューリッヒ工科大学（ETH Zurich）の新しい論文は、AGENTS.md ファイルが AI コーディングエージェントにとってむしろ障害となる場合が多いと結論付けています。研究者らは、LLM 生成のコンテキストファイルを完全に省略し、人間が記述する指示を、非常に具体的なツールやカスタムビルドコマンドなど、推論できない詳細事項に限定することを推奨しています。
この研究に取り組んだチーム（Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, Martin Vechev）は、現在 60,000 のオープンソースリポジトリに AGENTS.md などのコンテキストファイルが含まれており（多くのエージェントフレームワークには自動生成用の組み込みコマンドも備わっている）、これらのファイルが実際に AI エージェントの現実世界のコーディングタスク解決能力を向上させるかどうかについては、厳密な実証調査が行われてこなかった点を指摘し、研究の正当性を説明しています。
研究者たち（その一人は「Humanity Last Exam」ベンチマークの貢献者でもあります）は、ニッチなリポジトリから収集した 138 の実世界の Python タスクからなる新規データセット「AGENTbench」を構築しました。この設定は、AI モデルが部分的に記憶してしまっている可能性のある人気ベンチマークである SWE-bench のバイアスを意図的に回避するものです。チームは、コンテキストファイルを使用しない場合、LLM 生成のファイルを使用する場合、人間が作成したファイルを使用する場合という 3 つの異なるシナリオにおいて、4 つのエージェント（Claude 3.5 Sonnet、Codex GPT-5.2 および GPT-5.1 mini、Qwen Code）をテストしました。研究者たちは、リポジトリレベルの指示が実世界に与える影響を、3 つのプロキシ指標を追跡することで評価しました。すなわち、リポジトリ内のユニットテストによって決定されるタスク成功率、エージェントが要したステップ数、および全体の推論コストです。選ばれたすべてのニッチなリポジトリには人間が作成したコンテキストファイルが含まれていましたが、最初の 2 つのシナリオではこれらのファイルを削除または置き換えてテストを行いました。
研究者たちは、LLM が生成したコンテキストファイルはパフォーマンスを低下させ、実際には何のコンテキストファイルも提供しない場合と比較してタスク成功率を平均 3% 減少させることを発見しました。また、エージェントが要するステップ数を一貫して増加させ、推論コストを 20% 以上引き上げることがわかりました。
一方、人間が作成したファイルはわずかながら改善をもたらしましたが、AGENTbench におけるタスク成功率の平均で 4% の増加にとどまりました。この肯定的な増加とは対照的に、ステップ数も並行して増加し、コストを最大 19% 引き上げることになりました。
AGENTS.md ファイルにアーキテクチャの概要やリポジトリ構造の説明などの情報を記載しても、モデルが現在のタスクに関連するファイルを見つけるのに要する時間を短縮するようには見受けられませんでした。
パフォーマンスが低下しコストが増加した理由を理解するため、著者らはエージェントのツール呼び出しと推論パターンについて詳細なトレース分析を行いました。エージェントは通常、AGENTS.md ファイルに含まれる指示に従いました。その結果、より多くのテストを実行し、より多くのファイルを読み込み、より多くの grep 検索を行い、より多くのコード品質チェックを実施しました。これは徹底した行動ではありましたが、現在の特定のタスクを解決するには往々にして不要なものでした。データは、追加の文脈が推論モデルに「より深く考える」ことを強いる一方で、最終的なパッチの質には向上をもたらさないことを示しています。
著者らは結論において、本研究の結果と現在 AI コードエージェントを使用する開発者に対して行われている推奨事項との間のギャップを強調しました：
我々は、すべての文脈ファイルがタスク完了に必要なステップ数を一貫して増加させることを見出しました。LLM 生成の文脈ファイルはタスク成功率にわずかな悪影響を与えますが、開発者が作成した文脈ファイルはわずかな性能向上をもたらします。
追跡分析の結果、コンテキストファイル内の指示は概ね遵守され、より多くのテストと広範な探索につながることが示されました。しかし、それらは効果的なリポジトリの概要としては機能していません。全体的に、私たちの結果は、コンテキストファイルがエージェントの行動に与える影響は限定的であり、手書きの場合のみ望ましい可能性が高いことを示唆しています。これは、現在のエージェント開発者への推奨事項と観察された結果との間に具体的な乖離があることを浮き彫りにし、コーディングエージェントに対して簡潔でタスク関連性の高いガイダンスを自動的に生成する原理に基づいた方法に関する将来の研究の動機となっています。
開発者はこの研究に関心を示しました。ある開発者は、この研究は実際には開発者が有用な AGENTS.md ファイルの作成に注力すべきであると指摘しました：
その研究を読みましたが、著者たちが示唆しているのとは逆のことをしていると思います。むしろ、良質な AGENTS.md ファイルを支持するものとなっています。
[…] AGENTS.md ファイルの最大の用途は、モデルが認識しておらず、プロジェクトから即座に推論できないドメイン知識です。これは、この欠陥のためにエージェントが struggling する様子を見ることで、ゆっくりと蓄積されていきます。まさにクローズドソースでは非常に一般的ですが、AGENTS.md ファイルを持つ公開 GitHub プロジェクトでは極めて稀な種類のものです。後者のプロジェクトの大半は最近の小さな vibe-coded プロジェクトで、LLM を中心にしています。もし後者種のプロジェクトで 4% の改善が見られるなら（そもそも AGENTS ファイルの品質が非常に混在している場合）、高品質な .md ファイルを持つ大規模プロジェクトでは、エージェントとの作業においてこれらは無価値ではありません。
別の開発者は、コンテキストファイルは AI ハーネスよりも開発者にとって有用である可能性があると指摘しました：
私は約 3 ヶ月間、2 つのプロジェクトで CLAUDE.md ファイルを維持してきましたが、改善は顕著です。ただし、その理由は予想されるものとは異なります。実際に提供されるトークンレベルのコンテキストの重要性よりも重要なのは、それを書くことがコードベースに関する事柄（以前は頭の中だけだったこと）を言語化することを強いるという事実です。「Y のレガシー制約のために X にはこの奇妙なパターンを使用している」といった内容です。一度それが書き留められれば、エージェントもそれを把握しますが、チームの新しい人間全員がそれを把握することになります。
開発者はオンラインで論文を閲覧できます。AGENTS.md、CLAUDE.md、.cursorrules などのコンテキストファイルの活用は、2025 年後半に重要性を増し、これは AI コーディングエージェントプロバイダーによるより大規模な推進と時期を同じくしています。
著者について
Bruno Couriol
通信工学修士。数学学士。
原文を表示
Despite widespread industry recommendations, a new ETH Zurich paper concludes that AGENTS.md files may often hinder AI coding agents. The researchers recommend omitting LLM-generated context files entirely and limiting human-written instructions to non-inferable details, such as highly specific tooling or custom build commands.
The team behind the work, including Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, and Martin Vechev, justified the research by noting that while 60,000 open-source repositories currently contain context files such as AGENTS.md (and many agent frameworks feature built-in commands to auto-generate them) there has been no rigorous empirical investigation into whether these files actually improve an AI agent’s ability to resolve real-world coding tasks.
The researchers (one of whom contributed to the Humanity Last Exam benchmark) built AGENTbench, a novel dataset of 138 real-world Python tasks sourced from niche repositories. This setup deliberately avoids the bias of popular benchmarks like SWE-bench, which AI models may have partially memorized. The team tested four agents (Claude 3.5 Sonnet, Codex GPT-5.2 and GPT-5.1 mini, and Qwen Code) across three distinct scenarios: using no context file, an LLM-generated file, and a human-written file. The researchers assessed the real-world impact of repository-level instructions by tracking three proxy indicators: task success rates (as determined by repository unit tests), the number of agent steps, and overall inference costs. All chosen niche repositories featured human-written context files; the first two scenarios were tested by removing or replacing those files.
The researchers found that LLM-generated context files degrade performance, actually reducing the task success rate by an average of 3% compared to providing no context file at all. They also consistently increased the number of steps the agent took, driving up inference costs by over 20%.
On the other hand, human-written files did offer marginal gains, with a 4% average increase in task success rate on AGENTbench. This positive increase, however, is contrasted by a parallel increase in the number of steps, raising costs by up to 19%.
Including information such as an architectural overview or an explanation of the repository structure in AGENTS.md files did not seem to reduce the time the model spent locating relevant files for the task at hand.
To understand why performance dropped while costs increased, the authors conducted a deep trace analysis of the agents’ tool calls and reasoning patterns. Agents generally followed the instructions included in the AGENTS.md file. As a result, they ran more tests, read more files, executed more grep searches, and performed more code-quality checks. While thorough, this behavior was often unnecessary for resolving the specific task at hand. The data points to the extra context, forcing reasoning models to “think” harder without yielding better final patches.
The authors concluded by emphasizing the gap between the study’s findings and the current recommendations made to developers using AI code agents:
We find that all context files consistently increase the number of steps required to complete tasks. LLM-generated context files have a marginal negative effect on task success rates, while developer-written ones provide a marginal performance gain.
Our trace analyses show that instructions in context files are generally followed and lead to more testing and a broader exploration; however, they do not function as effective repository overviews. Overall, our results suggest that context files have only a marginal effect on agent behavior and are likely only desirable when manually written. This highlights a concrete gap between current agent-developer recommendations and observed outcomes, and motivates future work on principled ways to automatically generate concise, task-relevant guidance for coding agents.
Developers received the research with interest. One developer noted that the research should actually have developers focus on writing useful AGENTS.md files:
I read the study. I think it does the opposite of what the authors suggest—it’s actually vouching for good AGENTS.md files.
[…] The biggest use case for AGENTS.md files is domain knowledge that the model is not aware of and cannot instantly infer from the project. That is gained slowly over time from seeing the agents struggle due to this deficiency. Exactly the kind of thing very common in closed-source, yet incredibly rare in public GitHub projects that have an AGENTS.md file—the huge majority of which are recent small vibe-coded projects centered around LLMs. If 4% gains are seen on the latter kind of project, which will have a very mixed quality of AGENTS files in the first place, then for bigger projects with high-quality .md's they’re invaluable when working with agents.
Another developer noted that context files may just be more useful to developers than to AI harnesses:
I’ve maintained a CLAUDE.md file for about 3 months now across two projects and the improvement is noticeable but not for the reasons you’d expect. The actual token-level context it provides matters less than the fact that writing it forces you to articulate things about your codebase that were previously just in your head. Stuff like “we use this weird pattern for X because of a legacy constraint in Y.” Once that’s written down, the agent picks it up, but so does every new human on the team.
Developers can review the paper online. The use of context files, such as AGENTS.md, CLAUDE.md, or .cursorrules, grew in importance in the second half of 2025, coinciding with a larger push by AI coding agent providers.
About the Author
Bruno Couriol
MSc in Telecommunications. BSc in Mathematics.
関連記事
今日のまとめ
AI日報で今日の重要ニュースをまとめ読み