AIコーディングエージェント向けに AGENTS.md や CLAUDE.md のようなコンテキストファイルを置く運用が広がっています。
ただ、直感的には便利そうでも、実際にどれくらい効果があるのでしょうか？
InfoQで紹介されていたETH Zurichの研究では、この種のコンテキストファイルが期待ほど効かないどころか、LLM生成のものはむしろ逆効果になる場合があることが報告されていました。
この記事では、その内容をもとに、
- 研究で何が分かったのか
- なぜ逆効果になるのか
- 実務では
AGENTS.mdに何を書くべきか
を整理します。
背景
最近は、AIエージェントに対してプロジェクト固有の情報を渡すために、以下のようなファイルをリポジトリに置くことがあります。
AGENTS.mdCLAUDE.mdCONTEXT.md
これらの目的は、たとえば次のようなものです。
- リポジトリ構成を伝える
- テスト手順を伝える
- コーディングルールを伝える
- ドメイン固有の注意点を伝える
一見するとかなり有効そうですが、研究では「何を書いても効くわけではない」ことが示されました。
研究の概要
ETH Zurichの研究チームは、実際のOSSリポジトリ由来の138件のPythonタスクを集めて、AGENTbench というベンチマークを作成しました。
その上で、複数のコーディングエージェントに対して、次の3条件で比較しています。
- コンテキストファイルなし
- LLMが生成したコンテキストファイルあり
- 人手で作成したコンテキストファイルあり
この比較によって、コンテキストファイルが本当にタスク成功率を改善するのかを検証しています。
主な結果
研究結果のポイントはかなり明確です。
1. LLM生成のコンテキストファイルは平均で成功率を下げた
LLMが自動生成したコンテキストファイルは、成功率を平均3%低下させました。
さらに、推論コストは20%以上増加しました。
つまり、
- より多く読ませる
- より多く考えさせる
- でも成功率は上がらない
という結果です。
2. 人手作成のコンテキストファイルは少し改善した
一方で、人間が書いたコンテキストファイルは、成功率を平均4%改善しました。
ただし、こちらも万能ではありません。
- ステップ数は増える
- コストも増える
という傾向があり、単純に「書けば得」ではないことも分かります。
なぜ逆効果になるのか
この研究で興味深いのは、なぜコンテキストファイルが逆効果になるのかという点です。
研究では、エージェントが AGENTS.md の内容に引っ張られすぎて、次のような行動を増やしてしまうことが指摘されています。
- 必要以上にテストを実行する
- 不要なファイルまで広く読む
- grep検索を過剰に行う
- コード品質チェックを増やしすぎる
つまり、コンテキストファイルが「正しい近道」になるのではなく、
“もっと調べるべき” という圧力として働いてしまうわけです。
その結果、探索量や思考量は増えるのに、最終的な正答率にはつながらないことがあります。
実務的に重要な解釈
この結果は、「AGENTS.md は不要」という話ではありません。
むしろ重要なのは、
雑に自動生成したコンテキストより、非自明な実務知識を絞って書いた手書きコンテキストの方が価値がある
という点です。
ここはかなり実務的な示唆があると感じました。
書く価値が高そうな情報
研究の文脈から考えると、AGENTS.md に書く価値が高いのは、コードを読んだだけでは分かりにくい情報です。
たとえば以下のような内容です。
1. 特殊なビルド・起動・検証手順
make test
だけでは動かず、
- 事前に環境変数が必要
- 特定サービスを起動しておく必要がある
- 一部のテストはCI専用
のような情報は、エージェントにとってかなり有用です。
2. 独自ツールや社内ルール
- このプロジェクトでは
scripts/check.shを通す - DBマイグレーションはこの順番で行う
- APIスキーマ更新後はコード生成が必要
といった、一般論では推測しにくい運用ルールは価値があります。
3. ドメイン固有の制約
- 金額計算は必ず整数で扱う
- 論理削除済みデータを含めてはいけない
- 外部連携IDは更新不可
のような、実装ミスに直結しやすい業務知識は非常に重要です。
書いても効果が薄そうな情報
逆に、研究結果からすると、次のような情報はコストの割に効果が薄い可能性があります。
1. ふんわりしたアーキテクチャ説明
- このプロジェクトはクリーンアーキテクチャです
- 保守性を重視しています
- 高品質なコードを書いてください
この種の情報は抽象度が高く、エージェントの行動改善にはつながりにくそうです。
2. リポジトリを見れば分かる構成説明
-
src/にソースがあります -
tests/にテストがあります -
docs/にドキュメントがあります
のような内容は、わざわざ書かなくても探索で分かります。
3. 網羅的すぎる長文説明
情報が多すぎると、かえってエージェントが過剰に探索し、コストだけ増える可能性があります。
AGENTS.md を書くときの実務指針
自分なら、以下のような方針で書きます。
方針1: 「読むだけで分かること」は書かない
コードやディレクトリを見れば分かることは削ります。
方針2: 「失敗しやすい非自明情報」だけを書く
- ハマりやすい初期設定
- 実行順
- 禁止事項
- 例外ルール
に絞ります。
方針3: 手順は短く具体的に書く
悪い例:
必要に応じて適切なテストを実施してください
良い例:
変更後は最低限 `pytest tests/unit` を実行すること。
E2Eは重いため、UI変更時のみ `npm run test:e2e` を使う。
方針4: 運用知識を優先する
設計思想よりも、
- 何をすると壊れるか
- 何を通せば最低限安全か
- 何がCIで落ちやすいか
の方が実用性が高いです。
例: 実務向け AGENTS.md の最小構成
こんな感じの最小構成がちょうどよさそうです。
# AGENTS.md
## Overview
このリポジトリは Laravel API と React フロントエンドで構成される。
## Important rules
- 金額は必ず整数で扱うこと
- `deleted_at` があるテーブルは論理削除を考慮すること
- APIレスポンス変更時は OpenAPI スキーマを更新すること
## Validation
- Backend変更後: `php artisan test --testsuite=Feature`
- Frontend変更後: `npm run test`
- Lint: `npm run lint` / `./vendor/bin/pint`
## Notes
- ローカルでは S3 の代わりに MinIO を使う
- メール送信確認は MailHog を使う
- 一部のバッチは `.env` の `QUEUE_CONNECTION=database` が必要
ポイントは、短いが、事故りやすい情報だけは落とさないことです。
コミュニティの反応も示唆的
記事では、開発者コミュニティの反応も紹介されていました。
反応としては大きく2つあります。
- ちゃんと書かれた高品質な
AGENTS.mdには価値がある - AIだけでなく、新しく入った人間の開発者にも役立つ
これはかなり納得感があります。
つまり、AGENTS.md は「AI専用の魔法の設定ファイル」ではなく、
プロジェクト知識を圧縮した実務メモとして捉えるのがよさそうです。
まとめ
今回の研究から得られる学びはシンプルです。
- コンテキストファイルは置けば自動で効くわけではない
- LLM自動生成のファイルは、むしろ成功率を下げることがある
- 人手で書くなら、非自明で実務的な知識に絞るべき
- 一般論や長い説明より、失敗を防ぐ具体的情報の方が価値が高い
個人的には、AGENTS.md は「プロジェクト説明書」ではなく、
“この現場でハマらないための注意書き” に寄せるのが一番よいと感じました。
参考
- InfoQ: AI Coding Agents Find Context Files Less Helpful Than Expected