AGENTS.mdは本当に必要？コーディングエージェントの「常識」を覆す研究論文の衝撃

Claude Code、Codex CLI、Gemini CLIを使う開発者の間で、AGENTS.mdファイルの充実は半ば常識になっています。公式ドキュメントには「リポジトリのコンテキストをエージェントに伝えよ」と明記され、コーディングルール、アーキテクチャ、依存関係の説明を丁寧に記述する文化が急速に広まりました。

私自身、複数の企業プロジェクトで「AGENTS.mdを整備しないと開発効率が落ちる」という認識が共有されているのを目の当たりにしてきました。しかし、2026年2月にarXivで公開された研究論文「Are Repository-Level Context Files Helpful for Coding Agents?」が、この「ベストプラクティス」に根本的な疑問を投げかけています。

本研究では、実際のソフトウェア開発シナリオにおいて、AGENTS.mdのようなリポジトリレベルのコンテキストファイルがコーディングエージェントのパフォーマンスに与える影響を定量的に評価しています。

従来の仮説では「詳細なコンテキスト情報を提供すればするほど、エージェントの出力品質が向上する」と考えられていました。実際、多くの開発チームがこの前提に基づいて、数千行に及ぶAGENTS.mdファイルを作成・維持しています。

ところが研究結果は、必ずしもコンテキストファイルの充実度とパフォーマンスが比例しないことを示唆しています。特定の状況では、過剰な情報がノイズとなり、かえってエージェントの判断精度を低下させる可能性すら指摘されているのです。

GitHub Copilotとの本質的な違い

この研究結果を理解するには、Claude CodeやGemini CLIのようなエージェント型ツールと、GitHub Copilotのような補完型ツールの違いを認識する必要があります。

GitHub Copilotは主に「次の数行を予測する」タスクに特化しており、周辺コードからの即時的なコンテキストで十分機能します。一方、エージェント型ツールは「リポジトリ全体を理解して複雑な変更を実行する」という、より高度なタスクを担います。

この構造的な違いが、コンテキストファイルの有効性に影響を与えます。エージェントは既にリポジトリ全体をスキャンする能力を持っているため、別途用意されたドキュメントが冗長になる可能性があるのです。

メリットと注意点の両面分析

**AGENTS.mdが有効な場面:**

**過信すべきでない理由:**

適用範囲の再考

研究結果を踏まえると、「全てのプロジェクトで詳細なAGENTS.mdが必要」という一律的なアプローチは見直すべきです。

**AGENTS.mdを重点的に整備すべきプロジェクト:**

**最小限で良いプロジェクト:**

1. コンテキストファイルの「情報密度」を測定する

既存のAGENTS.mdを見直し、「コードから直接読み取れる情報」と「本当に文書化が必要な暗黙知」を分類してください。前者が50%を超えているなら、削減を検討すべきです。具体的には、依存関係の一覧やディレクトリ構造の説明など、エージェントが自動で把握できる情報は削除候補になります。

2. A/Bテストで効果を検証する

同じタスクを「詳細なコンテキストあり」と「最小限のコンテキスト」の両方でエージェントに実行させ、出力品質を比較してください。特に、バグ修正や機能追加といった具体的なタスクで計測すると、自チームにおけるコンテキストファイルの最適な粒度が見えてきます。

3. 「Just-in-Timeドキュメント」へのシフト

AGENTS.mdを常に完璧に保つのではなく、エージェントが実際に失敗したときに必要な情報を追記する方式に切り替えましょう。これにより、メンテナンスコストを抑えつつ、本当に必要な情報だけを蓄積できます。エージェントのエラーログを分析し、繰り返し発生する誤解に対してのみドキュメントを充実させるアプローチです。

AGENTS.mdの整備自体は無駄ではありませんが、「詳細であればあるほど良い」という単純な図式は成り立ちません。エージェントの能力向上に伴い、コンテキストファイルの役割も進化しています。

重要なのは、盲目的にドキュメントを充実させるのではなく、自チームの開発フローで実際に効果を測定し、最適なバランスを見つけることです。この研究論文は、AIコーディングツールの使い方を見直す絶好の機会を提供してくれています。

この情報は @AI Watch さんの投稿を参考にしています。