CLAUDE.mdを書くのが面倒くさかった——でも、それが正解だった

タイムラインにCLAUDE.md（あるいはAGENTS.md）の話題が流れるたびに、「あとで設定しよう」と思いながらスルーしていた。凝ったAGENTS.mdを作り込んでいる人たちを見ては、少し焦りを感じていた。乗り遅れているのかな、と。

それが最近出たベンチマークデータを見て、その焦りが一気に消えた。どうやら私の怠惰は、かなり理にかなったエンジニアリング判断だったらしい。

LLMが生成したコンテキストファイルは逆効果

「エージェントにコンテキストを渡せば渡すほど、精度が上がるはずでしょ？」——私もそう思っていた。

ところがSWE-bench LiteでLLMが自動生成したコンテキストを与えてテストしたところ、成功率が0.5%低下。AgentBenchではさらに2%落ちた。丁寧に手書きしたファイルでも、改善は4%どまり。これはいわば「コンテキストの過学習」とでも呼ぶべき現象だ。

• SWE-bench Lite：LLM生成コンテキストで成功率0.5%低下
• AgentBenchではさらに2%の追加低下
• 推論コストは20〜23%増加
• ドキュメントがまったく存在しないリポジトリに限っては2.7%の改善効果

Gloaguenらによる論文”Evaluating AGENTS.md”が確認したのは、コンテキストファイルはリポジトリのコンテキストをまったく与えない場合と比べても、タスク成功率を下げる傾向があるという事実だ。

エージェントが指示を忠実に守りすぎる——それが問題

エージェントが指示を無視するのが問題なのではない。むしろ逆だ。

コンテキストファイルに「uvを使え」と一行書いておくと、まったく必要のない場面でもエージェントはuvをインストールして実行する。毎回、余計なステップが挟まれる。

GPT-5.2ではコンテキストファイルがある場合、推論トークンが14〜22%増加していた。指示に従うことに意識が向いて、本来の問題解決から焦点がずれてしまっているのだ。

• 不要なpytestの実行が増える
• grepやreadツールの使用範囲が必要以上に広がる

「〇〇するな」と書くと、エージェントは〇〇のことを考える

以前の記事でSKILL.mdの本文が特定のタイミングで読み込まれる話を書いたが、AGENTS.mdにも似たような問題がある。

AGENTS.mdはシステムプロンプトとユーザープロンプトの間に挟まる「デベロッパーメッセージ」層に位置する。この配置がエージェントの思考を強く制約する。

「このファイルには触るな」と書けば、エージェントはそのファイルのことを余分に考える。研究者たちはこれを「ピンクの象効果」と呼んでいた。「ピンクの象のことを考えるな」と言われた瞬間、頭の中に象が現れるあれだ。

• 優先順位はプロバイダー指示 → システムプロンプト → AGENTS.md → ユーザープロンプトの順
• 手動でメンテナンスするファイルはコードの変化に追いつけず、情報がすぐに陳腐化する

書くなら、とにかく短く

リポジトリのドキュメントがまったく存在しないなら、コンテキストファイルは効果がある——データでも2.7%の改善が確認されている。ただし書くなら、量は最小限に抑えることだ。

リポジトリ固有のビルドツールの使い方を一行。 エージェントが繰り返し間違えるパターンの修正を一行。

「構造的に奇妙なものを見つけたら即座に報告せよ」などと書き加えると、エージェントはコードベースの脆弱性を報告するツールになってしまう。それよりも、コードの構造自体を直感的にしてしまう方がずっと効果的だ。

• ユニットテストや型チェックを強化する方がコンテキストファイルより有効
• ファイルの場所がわかりにくいなら、説明を書くより先にファイルを移動する

コンテキストファイルをうまく書けることが腕前の証拠とは限らない。コンテキストファイルの構造を理解した上で、その周辺のメタシステムをどう設計するか——そこが本当の腕の見せどころだ。そして時には「面倒くさくてやらなかった」が、最良のエンジニアリング判断になることもある。