AI コーディングエージェントの設定ファイル（AGENTS.md、CLAUDE.md など）は「詳しく書くほど良い」と思われがちだ。しかし ETH Zurich の研究チームが138リポジトリ・5,694プルリクエストを対象に行った調査で、詳細すぎるコンテキストファイルはむしろ性能を下げることが実証された。

研究の概要

ETH Zurich の Gloaguen、Mündler、Müller、Raychev、Vechev らが2026年2月に発表した論文で、AGENTS.md ファイルが AI コーディングエージェントの性能に与える影響を大規模に検証した。

  • 対象: 138リポジトリ、5,694プルリクエスト
  • 検証: LLM 生成ファイルと人間が書いたファイルの両方を比較

衝撃的な結果

自動生成されたコンテキストファイルは害になる

  • 成功率が約3%低下
  • 推論コストが20%以上増加
  • エージェントは推論トークンの14〜22%をドキュメント処理に消費

人間が書いても効果は限定的

  • 改善はわずか**4%**にとどまる
  • コストの増加に見合わない

なぜ詳細な指示が逆効果になるのか

AI エージェントは「従順すぎる」

エージェントはコンテキストファイルの指示を律儀に守る。そのため、不要な制約が含まれていると逆にタスクが難しくなる。「良かれと思って書いた指示」が足を引っ張る。

ディレクトリツリーやコードベース概要は不要

エージェントはファイル構造を自力で発見するのが得意だ。手動でディレクトリツリーを記述しても、トークンを消費するだけでナビゲーション速度は改善しない。

強いモデルほど追加コンテキストが邪魔になる

GPT-5.2 のような強力なモデルは、ライブラリや慣例のパラメトリック知識を既に持っている。追加コンテキストは冗長なノイズになるだけだ。

効果があるのは「非自明なツール指定」

研究で唯一、劇的な効果が確認されたのはプロジェクト固有のツール指定だ：

  • pip の代わりに uv を使う
  • npm の代わりに bun を使う

例えば uv を明示した場合、160倍多く使われたという結果が出ている。エージェントが自力では推測できない「非自明な選択」だけを書くのが正解だ。

推奨される6つの原則

  1. コード内で発見可能な情報は除外 — エージェントが自力で見つけられるものは書かない
  2. 否定形ではなく肯定形で指示 — 「〜するな」ではなく「〜せよ」
  3. 決定論的チェックと組み合わせる — linter やテストで検証可能なルールを設定
  4. 想定ではなく実際の失敗から反復 — 問題が起きてから追記する
  5. 重要情報を最初に配置 — トークン処理の優先順位を考慮
  6. 30行以下を目指す — プロチームは60行以下、推奨は300行以下

実践的な AGENTS.md の書き方

悪い例（よくある過剰な記述）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# プロジェクト概要
このプロジェクトは React + TypeScript で構築された...

# ディレクトリ構造
src/
├── components/
├── hooks/
├── utils/
└── pages/

# コーディング規約
- 変数名はキャメルケースを使用する
- コンポーネントはアロー関数で定義する
- インポートは以下の順序で記述する...
（以下100行続く）

良い例（非自明な指定のみ）

1
2
3
4
5
6
7
8

# ツール
- パッケージマネージャ: bun（npm/yarn ではなく）
- テストランナー: vitest
- フォーマッタ: biome（prettier ではなく）

# プロジェクト固有のルール
- API クライアントは src/lib/api.ts の共通関数を使う
- 環境変数は .env.local から読み込む（.env は使わない）

最良の AGENTS.md は不要なものである

研究が示す最も重要な結論は、AGENTS.md の改善に時間を費やすより、コードベース自体を改善すべきということだ：

  • 厳密な型定義
  • 包括的なテスト
  • 自動化された lint / format パイプライン
  • クリーンなコード構造

これらが揃っていれば、エージェントは AGENTS.md なしでも高いパフォーマンスを発揮する。

まとめ

AGENTS.md は「何を書くか」より「何を書かないか」が本質だ。コードから自明な情報を排除し、エージェントが自力で推測できない非自明なツール指定だけを簡潔に記述する。そして何より、AGENTS.md を磨くより、コードベースそのものの品質を上げることが、AI コーディングエージェントの性能を最大化する最善の方法だ。