AI最新情報読了 7 分

AGENTS.mdに1文足すだけで、コーディングAIのテスト合格率が89.4%から100%に

Shiritomo編集部 @shiritomoAI_jp 2026年11月12日更新

「ドキュメントと既存のコードが食い違うときはコードの書き方に従い、見つけた食い違いを最後の返答ですべて挙げること」。
この1文を指示ファイルに足しただけで、AIコーディングエージェントの振る舞いが大きく変わったという報告が出ています。
古いドキュメントに振り回されて意味のない修正をされた経験がある人には、見覚えのある話かもしれません。

先に結論をまとめると：
– Claude CodeやCodex CLIは、指示ファイル（CLAUDE.md/AGENTS.md）が古くて実際のコードと食い違っていても、約9割の場面で古い指示ファイルの方を優先してしまう
– 「ドキュメントと既存のコードが食い違うときはコードの書き方に従い、見つけた食い違いを最後の返答ですべて挙げること」という1文を足すだけで、既存コードに従う割合が4.2%から91.4%に跳ね上がった
– テストの合格率も89.4%から100%に改善し、学術研究でも裏付けられている

指示ファイルより古いドキュメントを信じてしまうAI

AGENTS.mdやCLAUDE.mdは、AIコーディングエージェントに「このリポジトリではこう書いてほしい」というルールを伝えるための指示ファイルです。
ところが、このファイルの内容が実際のコードと食い違っている——つまりドキュメントだけが古いまま更新されていない——場面で、AIエージェントが何を優先するのかを検証した研究結果がXで紹介されていました。

研究者らによると、CLAUDE.mdやAGENTS.mdにあらかじめ次の一文を足すことが推奨されます。
「ドキュメントと既存のコードが食い違うときはコードの書き方に従い、見つけた食い違いを最後の返答ですべて挙げること」

なぜか。
Claude… pic.twitter.com/kHcpuQ2obV
— AIDB (@ai_database) 2026年10月25日

研究者らによれば、CLAUDE.mdやAGENTS.mdに「ドキュメントと既存のコードが食い違うときはコードの書き方に従い、見つけた食い違いを最後の返答ですべて挙げること」という1文をあらかじめ足しておくことが推奨されるといいます。
なぜこの1文がそれほど効くのか、一次情報を確かめてみました。

調べて分かったこと

何割のAIが古いドキュメントを信じてしまうのか？

この話のもとになっているのは、米ジョージア工科大学のXiaonan Xu氏とコロラド大学ボルダー校のWenjing Wu氏による研究です。
Claude CodeとCodex CLIという2種類のAIコーディングエージェントを使い、40個のPythonプロジェクトに対して16種類のコーディング上の約束事（インデントの付け方や命名規則など）を仕込み、ドキュメントと実際のコードを意図的に食い違わせたうえで、エージェントがどちらに従うかを検証しました（2つのエージェント×40プロジェクト×2条件×2回＝320回の実行、720件の判断）。

結果、エージェントは古い指示ファイルの書き方を、既存コードよりも90.1%の場面で優先してしまいました。
既存コードの書き方に従ったのはわずか4.2%です。
内訳はClaude Codeが86.4%、Codex CLIが93.9%で古い指示ファイルを優先していました。
AIが「ドキュメントの方が正しいはず」と思い込んでしまう傾向は、2つのエージェントに共通していたことになります。

なぜ1文足すだけで直るのか？

研究チームが試したのが、冒頭で紹介した1文を指示ファイルに追加することでした。
英語の原文は次のような内容です。

リポジトリのドキュメントと既存のコードが食い違うときは既存コードの書き方に従い、見つけた食い違いをすべて最後の返答で報告すること

この1文を足した後、既存コードに従う割合は4.2%から91.4%まで跳ね上がりました。
エージェント別ではClaude Codeが7.5%から94.4%、Codex CLIが0.8%から88.3%に改善しています。
さらにテストの合格率も、1文を足す前は89.4%だったのに対し、足した後は160回の実行すべてで合格（100%）という結果になりました。
この研究は2026年10月に発表され、11月に入ってXでも取り上げられています。

速報：10月の調査によると、Claude CodeとCodexは、古いCLAUDE.mdやAGENTS.mdと実際のコードが食い違うとき、90%の確率で古い指示ファイルの方を優先していました。
たった1文でほとんどが解決したといいます。
その1文と、ファイル内の古い記述を見つけるためのプロンプトは以下の通りです。

BREAKING: Coding agents followed an outdated CLAUDE.md or AGENTS.md over the actual code in 90% of choices, in an October study of Claude Code and Codex.

One sentence fixed most of it. The sentence and a prompt that finds the stale lines in your files are below:
— Limestone Digital (@LimestoneHQ) 2026年11月9日

この投稿は日本時間11月10日未明の投稿で、研究結果をあらためて広めるきっかけになったようです。

AGENTS.mdはそもそもどういう位置づけのファイルなのか？

AGENTS.mdは特定の1社だけのものではなく、OpenAIをはじめ複数のAIコーディングツールが共通で読み込む指示ファイルの形式として広まっています。
公式でも、プロジェクトのルールや注意事項をAGENTS.mdにまとめておく使い方が推奨されています。
ただし今回の研究が示すとおり、ファイルを作って終わりではなく、内容が古くなっていないかを保つこと自体が重要だということになります。
ドキュメントを書いたら終わりではなく、コードを変更したタイミングでAGENTS.md側も見直す運用をセットで考える必要がありそうです。

Shiritomo編集部の考察：ドキュメントの「賞味期限」をどう管理するか

今回の研究が興味深いのは、AIエージェントの性能そのものではなく「どちらの情報を信じるか」という優先順位の設計で、挙動が9割近く変わったという点です。
SNS運用やコンテンツ制作でAIエージェントを使う場面でも、マニュアルやテンプレートを一度作ったら更新しないままにしているケースは少なくありません。
今回の結果は、プロンプトやルールファイルの精度を上げる努力より、先に「情報が古い場合はどうするか」というルールを決めておく方が効果が大きいことを示しています。
AI活用を進める現場では、指示ファイルの内容を充実させることと同じくらい、「古くなった指示をどう扱うか」というメタルールを用意しておくことが、地味だけれど効果の大きい対策になりそうです。

まとめ

AGENTS.mdやCLAUDE.mdのようなAIコーディングエージェント向けの指示ファイルは、内容が古くなっていると実際のコードよりも優先されてしまう傾向があることが、学術研究で確かめられました。
「ドキュメントと既存のコードが食い違うときはコードの書き方に従い、見つけた食い違いを最後の返答ですべて挙げること」という1文を足すだけで、この傾向は大きく改善するようです。