AI が書いた CLAUDE.md は逆効果 — 「コンテキストファイルの自動生成は精度を下げる」という研究

@at_sushi_（門脇敦司）氏が X で投稿した、AI 生成のプロンプトファイルに関する記事が注目を集めています。

CLAUDE.md のようなプロンプトファイルを AI に生成させると「逆に精度が下がる」という研究です。AI 文書は冗長で、AI 自身を混乱させます。では、どうすればいいのか？ というと、「本当に重要な情報だけを、開発者が書く」というのが現在の正解です

元記事は Zenn の解説記事で、ETH Zurich と LogicStar.ai の研究チーム（Gloaguen et al.）による論文「Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?」を日本語で紹介しています。本記事では、この研究の実験データを詳しく読み解き、CLAUDE.md / AGENTS.md の書き方への実践的な示唆を整理します。

研究の概要 — 何を検証したのか

背景

CLAUDE.md、AGENTS.md、CURSORRULES — これらの「コンテキストファイル」は、AI コーディングエージェントにリポジトリの慣習や制約を伝えるための指示書です。Anthropic、OpenAI、Cursor はいずれもこれらのファイルの作成を強く推奨しています。

しかし、「コンテキストファイルは本当にエージェントの性能を向上させるのか?」 という基本的な問いに対して、厳密な検証はこれまで行われていませんでした。

実験設計

ETH Zurich の研究チームは、3 つの条件で比較実験を実施しました。

条件内容
なし（None）コンテキストファイルなし（ベースライン）
LLM 生成エージェント開発者の推奨に従い LLM に自動生成させたファイル
人間作成開発者がリポジトリにコミットしたファイル

評価対象モデル: Claude Code（Sonnet 4.5）、Codex（GPT-5.2 / GPT-5.1 mini）、Qwen Code（Qwen3-30b-coder）

ベンチマーク:

  • SWE-bench Lite: 11 の人気 Python リポジトリから 300 タスク
  • AGENTbench: 開発者作成のコンテキストファイルを持つ 12 リポジトリから 138 インスタンス（独自収集）

実験結果 — LLM 生成は精度を下げ、コストを上げる

成功率の変化

LLM 生成コンテキストファイルの影響:
  8 つの実験設定のうち 5 つで成功率が低下
  平均 0.5〜2% の精度低下
  最大で約 3% の精度低下

人間作成コンテキストファイルの影響:
  平均 4% の精度向上（LLM 生成版と比較して）
  ただし改善幅は限定的

推論コストの増加

モデルコンテキストなしLLM 生成ありコスト増加率
Sonnet 4.5（SWE-bench）$1.30$1.51+16%
GPT-5.2（SWE-bench）$0.32$0.43+34%
全体平均——+20〜23%

タスク完了ステップ数の増加

ベンチマークステップ数の増加
SWE-bench平均 +2.45 ステップ
AGENTbench平均 +3.92 ステップ

コンテキストファイルを追加すると、エージェントはより多くのテスト実行、リポジトリ探索、品質チェックを行うようになり、タスク完了までのステップ数が増加しました。

なぜ LLM 生成のコンテキストファイルが逆効果になるのか

原因 1: 既存ドキュメントとの重複

LLM がコンテキストファイルを生成する際、README やコメント、テストファイルなどの既存情報を再記述する傾向があります。

リポジトリの既存情報:
  README.md → プロジェクト概要、セットアップ手順
  CONTRIBUTING.md → コーディング規約、PR 手順
  pyproject.toml → 依存関係、ビルド設定

LLM 生成の AGENTS.md:
  「このプロジェクトは○○です」 ← README と重複
  「コーディング規約は△△です」 ← CONTRIBUTING と重複
  「依存関係は□□です」 ← pyproject.toml と重複

重複した情報は「ノイズ」として機能します。研究チームが既存ドキュメントを削除して LLM 生成ファイルだけを残した場合、2.7% の精度向上が確認されました。つまり、LLM 生成ファイルは「情報がないよりはマシ」だが、「既存の情報と重複すると有害」なのです。

原因 2: 有効な概要を提供できていない

コンテキストファイルの期待される効果の一つは、エージェントがリポジトリの構造を素早く理解し、関連ファイルを見つけやすくすることです。しかし実験では、ファイル発見までのステップ数は改善されませんでした。

エージェントはコンテキストファイル自体を繰り返し読み直したり、ファイルの存在を探索したりする「無駄な行動」を実行する傾向が観察されています。

原因 3: 指示遵守による認知負荷の増加

コンテキストファイルに書かれた指示を「守ろうとする」行為自体が、エージェントの認知負荷を増加させます。

GPT-5.2 では、コンテキストファイルがある場合の推論トークン数が 22% 増加しました。エージェントは「この指示に従っているか?」を逐次確認しながら作業するため、本来のタスクに割くリソースが減少します。

原因 4: モデル間での転用が効かない

強力なモデル（GPT-5.2）に生成させたコンテキストファイルを、他のエージェントに適用しても改善につながりませんでした。モデルごとに「有効な指示の書き方」が異なるため、汎用的なコンテキストファイルの自動生成は困難です。

ハーネスエンジニアリングの観点 — コンテキストは希少資源

この研究結果は、「ハーネスエンジニアリング」の考え方と一致しています。

ハーネスエンジニアリングとは、AI エージェントの性能を最大化するために、モデルを取り巻く周辺環境（ハーネス）を設計するアプローチです。

ハーネスエンジニアリングの原則:
  コンテキストは希少資源
  ↓
  巨大な指示ファイルはタスク・コード・関連ドキュメントを圧迫する
  ↓
  ガイダンスが多すぎると「すべてが重要」になり、何も重要ではなくなる
  ↓
  段階的に必要な情報だけをロードするのが正解

CLAUDE.md に 500 行の詳細な指示を書いても、エージェントはそのすべてを同時に処理しようとし、本来のタスクへの集中力が分散します。

正しい CLAUDE.md の書き方 — 研究が示す原則

原則 1: 人間が書く

LLM に CLAUDE.md を生成させないでください。「Claude に CLAUDE.md を書かせる」というプラクティスは、この研究によれば逆効果です。

開発者自身が、自分のプロジェクトのエージェントが自力では発見困難な情報だけを記述します。

原則 2: 最小限に保つ

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

# 悪い例（冗長な CLAUDE.md）

## プロジェクト概要
このプロジェクトは Django ベースの REST API です...（README と重複）

## セットアップ
pip install -r requirements.txt を実行...（README と重複）

## コーディング規約
PEP 8 に従う...（pyproject.toml の設定と重複）

## テスト
pytest を使用...（CI 設定と重複）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 良い例（最小限の CLAUDE.md）

## 重要な制約
- 本番 DB に直接クエリを投げるコードは禁止（staging のみ）
- `legacy_auth` モジュールは触らない（別チームが移行中）
- GraphQL スキーマ変更時は必ず `make generate` を実行

## ツール固有の設定
- テスト: `pytest --tb=short -q`
- リント: `ruff check --fix`

良い例は、README や設定ファイルから読み取れないプロジェクト固有の暗黙知だけを記述しています。

原則 3: 既存ドキュメントと重複しない

エージェントは README、pyproject.toml、CI 設定ファイルなどを自力で読み取れます。コンテキストファイルにこれらの情報を転記する必要はありません。

記述すべき情報記述不要な情報
プロジェクト固有の制約（「このモジュールは触るな」）プロジェクト概要（README に書いてある）
暗黙のルール（「PR は必ず staging で確認」）セットアップ手順（README に書いてある）
エッジケースの注意点（「この API は古い仕様」）依存関係（pyproject.toml に書いてある）
ツールの非標準的な使い方標準的なコマンドの説明

原則 4: CLAUDE.md は「目次」として使う

コンテキストファイルは巨大な指示書ではなく、ナビゲーションハブとして設計します。

1
2
3
4
5
6
7

## 重要な制約
- 本番 DB 直接アクセス禁止
- `legacy_auth` モジュールは移行中（触らない）

## 詳細なガイドライン
- API 設計基準: [docs/api-guidelines.md](docs/api-guidelines.md) を参照
- テスト戦略: [docs/testing.md](docs/testing.md) を参照

約 100 行に抑え、詳細は docs/ ディレクトリに構造化して配置する。これは Claude Code の Skills 設計思想（SKILL.md は 500 行以下、詳細は別ファイル）とも一致します。

LLM 生成が有効な唯一のケース

研究では、LLM 生成コンテキストファイルが唯一有効なケースも特定しています。

既存ドキュメントがほぼない小規模コードベースです。

README もない、コメントも少ない、テストもない — そのような状態のプロジェクトでは、LLM 生成のコンテキストファイルが「ないよりはマシ」な情報を提供します。逆に言えば、ある程度のドキュメントが存在するプロジェクトでは、LLM 生成のコンテキストファイルは有害です。

まとめ

  • LLM 生成のコンテキストファイルは精度を下げる: 8 つの実験設定のうち 5 つで成功率が低下し、推論コストが 20〜23% 増加した
  • 冗長性がノイズになる: LLM 生成ファイルは既存ドキュメントと重複し、エージェントを混乱させる。重複を除去すると 2.7% 精度が向上した
  • 指示遵守が認知負荷を増やす: コンテキストファイルの指示に従おうとすることで推論トークンが 22% 増加し、本来のタスクへの集中力が分散する
  • 人間が書くのが正解: 開発者が「エージェントが自力で発見困難な情報だけ」を最小限に記述したファイルは、平均 4% の精度向上をもたらした
  • CLAUDE.md は「目次」にする: 巨大な指示書ではなく、約 100 行のナビゲーションハブとして設計し、詳細は別ファイルに分離する
  • 唯一の例外は小規模コードベース: 既存ドキュメントがほぼないプロジェクトでのみ、LLM 生成が「ないよりマシ」として機能する

参考