AI生成の「CLAUDE .md」、逆に精度が下がるという研究

本記事では、コーディングAIエージェントに渡す「指示ファイル」の効果について、ざっくり解説します。

株式会社ナレッジセンスは、生成AIやRAGを使ったプロダクトを、エンタープライズ企業向けに開発しているスタートアップです。

この記事は何

この記事は、コーディングAIエージェント向けの指示書ファイル（AGENTS.mdやCLAUDE.md）の効果を検証した論文^[1]について、日本語で簡単にまとめたものです。

https://arxiv.org/abs/2602.11988

本題

ざっくりサマリー

「CLAUDE.md」をAIで生成すると、むしろタスクの成功率が下がります。 ETH ZurichとLogicStar.aiの研究チームによって2026年2月に発表されました。

指示ファイルなし / LLMによる指示ファイルあり / 人間による指示ファイルありでの比較。SWE-BENCH LITE(左) / AGENTBENCH (右).

もう少し前提から話します↓

最近、「Claude Code」や「OpenAI Codex」など、コーディングエージェントが普及しています。

エージェントに文脈を伝えるために、CLAUDE.md（※Codexなら AGENTS.md）は広く使われています。^[2]

ただ、この指示ファイル、人間が書くのは、だんだん面倒になってきます（笑）。そこで、「Claude.md 自体を、AIに生成させる」という状態になりがちです。

しかし、この論文では、複数のコーディングエージェント（Claude Code、Codex、Qwen Code）で検証したところ、LLMに自動生成させた指示ファイルは、成功率を平均で約2〜3%下げ、推論コストを20%以上増加させることが分かりました。

問題意識

コーディングエージェントは、普通、リポジトリの構造を知らずに、タスクをスタートします。なので、エージェント開発者たち（Anthropicなど）は「CLAUDE.mdを書きましょう」ということを推奨しています。^[3]

なんとなく、CLAUDE.md を書いた方が良さそうです。

ただ、この論文のめちゃくちゃ面白い着眼点は「AIで生成したCLAUDE.mdであっても、本当に効果はあるのか？」という切り口です。

実験と結果

この論文では、3つの設定で比較実験を行っています。

①指示ファイルなし（None）：そのままタスクを解かせる
②LLM生成の指示ファイル（LLM）：各エージェントの推奨設定でAIに自動生成させる
③人間が書いた指示ファイル（Human）：開発者が実際にリポジトリにコミットしたもの

結果は以下の通りです。

LLM生成の指示ファイルの場合：

• 8つの実験設定のうち5つで、成功率が下がった
• 平均で0.5〜2%の精度低下
• 推論コストは平均20〜23%増加
• タスク完了までのステップ数も平均2〜4ステップ増加

人間が書いた指示ファイルの場合：

• LLM生成よりはマシで、平均4%の精度向上
• ただし、コストは最大19%増加

つまり、AIに書かせた指示ファイルは、ないほうがマシという結果になっています。

エージェントが、修正すべき正解ファイル（PRのパッチに含まれるファイル）に最初にアクセスするまでにかかったステップ数（少ない方がいい）。SWE-BENCH LITEでもAGENTBENCHでも、LLM生成の指示ファイルや人間が書いた指示ファイルがある場合よりも、指示ファイルがない場合の方が性能がいい

指示ファイルがない場合の平均的なツール使用回数と比較して、LLM生成（明るい緑）または開発者が書いた（暗い緑）指示ファイルを含めた場合に、平均ツール使用回数がどれくらい増加したか。

なぜダメなのか

論文では、エージェントの行動ログを分析し、ダメな理由を考察しています。

①既存ドキュメントと被ってるパターン

LLM生成の指示ファイルは、READMEなど既存のドキュメントとほぼ同じ内容を繰り返しているだけでした。実際、既存のドキュメントを全部削除した状態で指示ファイルを渡すと、逆に精度が改善しました（平均2.7%向上）。つまり、ドキュメントが既にあるリポジトリでは、AI生成の指示ファイルは「ノイズ」になっている可能性が高いです。

②タスク成功率が上がるほどの概要、CLAUDE.mdだけでは伝えきれない

CLAUDE.md にリポジトリの概要を入れても、エージェントが関連ファイルを発見するまでのステップ数は改善しませんでした。むしろ、例えばモデルによっては、指示ファイル自体を探しに行ってしまったり、既に指示に入っているのに何度も読み直したりする無駄な行動が観察されています。

③タスク負荷を上げている

エージェントは、指示ファイルの指示を守ります。ただ、指示を守ること自体がタスクの負荷を上げている という側面もあります。GPT-5.2では、指示ファイルがある場合、推論（思考）トークン数が22%も増加しました。^[4]

④強いモデルあっても、AI生成なら結果は同じ

GPT-5.2（一応、一番強いモデルという立ち位置）で生成した指示ファイルを他のエージェントに使わせても、一貫した改善は見られませんでした（プロンプトを変えても同様）。

ではどうすればいいのか

①CLAUDE.md、AGENTS.mdは手動で書く

これは、ここまで見てきた通り。

②最小限の要件だけ書く

人間が書いた指示ファイルは、わずかに精度を改善します。エージェントが自力では発見しにくい情報だけを書くべきです。エージェントが自分で調べれば分かるような情報は不要です。

③ドキュメントがないリポジトリでは有効

ちなみに、LLM生成の指示ファイルが役に立つケースもある、とのことです。それは、既存のドキュメントがほぼない小規模なコードベース。この場合は、指示ファイルが唯一のドキュメントとして機能するため、精度が改善します。

（個人的にはもっと多くのプラクティスというか、「希望」が欲しかったところではありますが、、、今後の研究に期待したいです）

まとめ

弊社では普段、AIをフル活用した開発を行っています。

Claude CodeのSkillやCLAUDE.md、CodexのAGENTS.mdなどは、まさに我々も日常的に使っているツールです。こうした指示ファイルは、「AIに書かせれば楽だし、精度も上がるだろう」と思いがちです。

ただ、エージェントとはいえ、結局、裏側で行われているのはRAGだったり、検索の仕組みです。

つまり、AIを混乱させないために、最小限の正しい情報を渡す、ということが重要です。ハーネスエンジニアリング^[5]、しっかり整えていきたいですね。

みなさまが業務でAIコーディングエージェントを活用する際も、参考にしていただければ幸いです。今後も、AIの活用精度を上げるような工夫や研究について、記事にしていこうと思います。我々が開発しているサービスはこちら。

脚注

1. "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", Gloaguen et al.

2. ちなみに、論文によると、すでにGitHub上で6万以上のリポジトリがAGENTS.mdを導入しているそうです。(参考: https://agents.md/ )

3. https://code.claude.com/docs/ja/overview

4. 個人的な関心としては、精度が重要なので、トークン数はあまり気にしません。が、トークン数が大きいと回答が遅くなるのは間違いないので、トレードオフはありますね。

5. https://openai.com/index/harness-engineering/