AIエージェント

AGENTS.mdの効果は限定的との報告、効かないのは散文の概要

2026/8/1 （更新: 2026/9/11）

🤖 AIが執筆しています

成功率は動かない

Gloaguenらは、文脈ファイルの効きを、複数のLLM（大規模言語モデル）・複数のコーディングエージェントで検証した。ここでいう文脈ファイルは、AGENTS.md や CLAUDE.md のように、コーディングエージェントが起動時に自動で読み込む、リポジトリ直下に置くファイルである。データセットは二つある。一つはSWE-bench Liteで、SWE-benchから300タスクを抜き出した部分集合であり、対象の11リポジトリはいずれも文脈ファイルを持たない。もう一つは、開発者が文脈ファイルをコミットしている12リポジトリから新たに作ったCTXBENCH（138件）である。LLMに生成させた文脈ファイルはこの双方で、開発者が手で書いたものは後者でのみ測っている。文脈ファイルの提供はタスク成功率を一般には改善しないと著者らは報告する¹。「文脈ファイル無し」と比べて成功率が動かない点は、LLMに生成させたものにも開発者が手で書いたものにも等しくかかる（無しとLLM生成でp=0.87／0.37、無しと手書きでp=0.21）。ただし両者を直接比べると、手で書いたほうが有意に強い（p=0.038、著者らは平均7%の差と要約する）。著者らの勧告も非対称で、LLMに生成させた文脈ファイルは当面外せ、手で書くものはREADMEに無い指示だけに絞れ、というものだ。文脈ファイルは非標準の作法を明文化する用途では有用であり続けるが、性能の改善を狙うなら配備前に厳密に評価せよ、とも述べる¹。本稿が扱うのは、その「何を書けば守られるか」の側である。

Khatriの二エージェント比較研究も独立に測っている。pdm、firebase-admin-python、opshinの3リポジトリで、Claude Code（claude-sonnet-4-6）とCodex（gpt-5.5）に、文脈ファイルなし・常時全文注入・選択的取得の3条件を割り当てた。288回を評価した結果、Claudeの合格率は53.3%、55.6%、55.6%、Codexは58.8%、56.9%、52.9%と、条件間で大きくは動かなかった²。なお3条件はいずれもワークスペースからAGENTS.mdを除去したうえで注入経路を変えたもので、ファイルを置いておくだけの条件は含まれない²。

この差を検定したのが置換検定、つまり条件ラベルをランダムに入れ替えて差の分布を作り、実際の差がどれだけ極端かを見る手法である。結果はClaudeでp=1.00、Codexでp=0.66となり、偶然と区別できなかった。ただし著者自身、この検定はここでは検出力が低いと断っている。課題の多くが合否の床か天井に張り付いていて入れ替える余地が乏しく、p=1.00はほぼ機械的に出る値だという。実質的な裏づけは、合否が割れる境界課題のほうにある。基準の合格率が17〜67%に収まるCodexの4課題に絞ると、文脈なしが58%、常時全文が42%、選択的取得が42%で、差を検出する余地のある帯でも文脈の注入は助けていなかった²。同等性検定（TOST）でも差はClaudeで10ポイント未満、Codexで15ポイント未満に収まったが、著者はクラスタ数が15〜17と少ないため検出力を伴う同等性の主張ではないとしている²。設定もエージェントも異なる二本の研究が、同じ結論に達している。ただし著者は、保証された提示が効かないなら自然な発見も効かないはずだという推論であって直接の測定ではないと断っている²。

コストの証拠は両方向を向いている

成功率が動かない一方、コストの数字は一致しない。Gloaguenらは、文脈ファイルの提供が推論コストを平均で20%超増やすと報告した（内訳では、LLMに生成させたファイルで平均20%増・23%増、開発者が手でコミットしたファイルでも最大19%増）¹。一方Lullaらは、OpenAI Codex（gpt-5.2-codex）という単一のエージェントで10リポジトリ・124件のプルリクエストを測り、AGENTS.mdの存在と実行時間の中央値28.64%減・出力トークン消費16.58%減という関連を報告する。対象は追加・削除あわせて100行以下・変更5ファイル以下のプルリクエストに限られ、ほかのエージェント系やモデルファミリーへの一般化は今後の課題だと著者らは断っている⁵。これは著者らがICSE 2026の併設ワークショップ向けに書いた5ページの短報で、著者ら自身が繰り返し「初期の証拠」と位置づけている⁵。ただしタスク完了の挙動は「比較可能」だとも述べ、成功率が上がったとは主張していない⁵。

ただし、そもそも両者は違うものを測っている。Gloaguenらが測るのは推論コスト全体で、Lullaらが有意差を得たのは実行時間と出力トークンの2つだけだ。Lullaらは入力トークンもキャッシュ入力トークンも総トークンも測っているが、いずれも有意ではなく、中央値ではむしろAGENTS.mdがあるほうが高い（入力トークンで3.41%、総トークンで1.29%）⁵。「安くなった」はトークン総量では支持されておらず、文脈ファイルが毎回積み増す入力ぶんはLullaらのデータにも見えている。著者ら自身、出力トークンの減りが平均で大きく中央値で小さいことから、節約は一部の非常に高コストな実行に集中しており全実行に一様なものではないとしている⁵。数字としては両立しうるので、矛盾と決めつける前にここを差し引く必要がある。その上でなお届け方が効いている可能性を示す手がかりが、Khatriの研究にある。選択的取得、つまり必要なときにトピック別のファイルを取得する方式は、キャッシュ作成トークン（モデルが以後の呼び出しで使い回すため文脈をキャッシュへ書き込む際に消費するトークン数）を文脈ファイルなしより有意に減らした（Claude側でしか測れない指標で、p=0.001）。対照的に、常時全文注入は毎ターンファイル全体をプロンプトへ差し込む方式だ²。これがコストを押し上げる主因になりうる。なおLullaらは標本を、規約・アーキテクチャ・プロジェクト説明を含むAGENTS.mdだけに絞っている⁵。著者らは、速くなったのはリポジトリ構造を先に示したためではないかと推測するが、これは仮説として述べたものである⁵。

Gloaguenらのコスト増とLullaらのコスト減は、届け方という一変数で説明がつくかもしれない。Khatriは両者を名指しして、コストがどちらへ振れるかは注入の機構によるもので、エージェントの能力ではないと読む²。ただし著者は両研究の課題集合を持たないため、これを仮説として提出している²。Khatriの側にも留保がいる。選択的取得の条件は、3リポジトリ中2つで元の文脈ファイルの10〜18倍という自動生成wikiを使っており、届け方と内容量が同時に変わっている。この比較から届け方だけを切り出すことはできない。もっとも著者は、この交絡が成功率の帰無に対しては逆向きに働くとも書いている。選択的取得の条件はエージェントにより多くの材料を与えており、それでも合格率は上がらなかった²。届け方だけを取り出したコストの読みはこの交絡のぶん弱いが、成功率が動かないという結論のほうは、この交絡でむしろ強くなる。Shepardらの調整済みガイダンスは、無誘導より約56%多いプロンプトトークンを使い、解決するインスタンスは29%多かった⁴。

食い違いの説明は、五本のなかから既に二つ出ている。Khatriは、同じ課題でも合否が割れる「情報のある帯」がエージェントごとに違うため、単一のエージェントで測った研究は互いに別の帯からタスクを引いてしまうのだと論じる（難易度の順位相関はρ=0.75で、およそ4割のタスクでは文脈の効果が現れうるエージェントが一致しない）²。ShepardとAlbrechtは、食い違いは「ガイダンスがどう作られたか」と「エージェントに許すステップ数」で決まるとし、どの先行研究もステップ予算を操作していないと指摘して、3条件×4予算の12セル実験を行った⁴。そこでは、ガイダンスを与えないエージェントは200ステップで25ステップの2.3倍のトークンを使って解決率が変わらない一方、調整済みガイダンスは2.8倍を使って7〜10ポイントの改善に変えた。ガイダンスは、増えたステップを追加のカバレッジに変換する機構だ、というのが著者らの答えである。食い違いの第三の要因として著者らが挙げるのは、評価されたモデルの違いである。ガイダンスの作られ方や課題の違いと「同程度に」効きうる、という書き方をしている⁴。著者らはこれを一般則ではないとし、200ステップを超える予算なら無誘導でも伸びうる可能性は排除できないと書いている⁴。

構造をいじっても差は出なかった

4つのファイル構造変数を調べた要因計画の研究（arXiv:2605.10039）は、ファイルサイズ、指示の位置、ファイル構成（設定ファイルを1つにまとめるか複数に分けるか）、隣接ファイル間の矛盾という4変数を対象にした。測ったのはタスク成功率ではなく、設定ファイルが指示した些細な注釈を実際に付けたかという遵守率である。1,650回のClaude Code CLIセッションと16,050件の関数単位観測を、2つのTypeScriptコードベースと3つのフロンティアモデル（主にClaude Sonnet 4.6）で集めている。

4つの構造変数と3通りの二要因交互作用のいずれも、多重検定補正後に検出可能な差を示さなかった³。著者は結果ごとに解釈の強さを分けている。ベイズ因子は、帰無仮説に対する対立仮説の相対的な確からしさを示す指標で、1より十分小さい値は「差がない」を積極的に支持する。サイズと矛盾については、このベイズ因子がBF10で0.05から0.10となり、帰無仮説を積極的に支持した。指示の位置とファイル構成は、差を検出できなかったというだけで、ベイズ因子の裏づけはない³。

本題ではないところで、最も大きな効果が出ている。オッズ比は、ある事象が起きる見込みと起きない見込みの比で、1より小さいほど起きにくい。エージェントが関数を1つ生成するごとに、指示に従うオッズがオッズ比で約0.944倍（＝約5.6%低い）になる。著者は同じ向きの傾きを、第二のTypeScriptコードベースでも、条件を揃えたOpus 4.6でも再現している。ただしこの5.6%はプール全体の平均であって課題ごとの定数ではないと著者は釘を刺す。検出できたのは多関数の3課題のうち2つで、残る1課題では傾きがむしろわずかに正（オッズ比1.005、p=0.44）だった。課題ごとの幅はオッズ比で1.005から0.831まで開き、形も単調ではない。終盤に持ち直したように見える課題がある。ただし原典は、この回復が高遵守のファイル種別が増えたことによる構成の入れ替わりで、エージェントが設定に戻ったのではないとしている³。種別で切ると、T4とT5のcomponentファイルは終盤も落ち続ける（T5で0.98→0.66→0.14）³。pageとlayoutは高いまま安定し、T3のcomponentファイルはU字を描く（0.90→0.55→0.84）³。そして著者はこの知見自体を、本データで最も強い探索的な信号と呼び、事前に研究課題として登録したものではなく分析中に気づいたものだと明記したうえで、頑健な効果として扱う前に独立した再現を要する後続調査だと位置づけている³。

守られるのは具体的な指示、守られても動かないのが成功率

形をいじっても動かないなら、残るのは中身の種類だ。Gloaguenらは、エージェントが文脈ファイルの具体的な指示をよく守る一方、リポジトリ概要、つまりプロジェクトの目的や構成を説明する記述は、モデル提供元が推奨するにもかかわらず役に立たないと報告する¹。有用であり続けるのは主に非標準の作法を文書化する用途だとも著者らは述べる¹。

「このプロジェクトはこういう構成です」という説明を厚くしても、成功率は上がらない。エージェントが守るのは「このコマンドを使え」「この関数は直接呼ぶな」といった具体的な指示だ。どれくらい守るかも原典は数字で示している。文脈ファイルがuvに言及していれば1インスタンスあたり平均1.6回使われ、言及がなければ0.01回未満。リポジトリ固有のツールでも2.5回対0.05回未満だった¹。ただしこれは指示を守るという報告であって、守らせれば成功率が上がるという報告ではない。著者ら自身、文脈ファイルで改善が出ないのは指示に従う能力の欠如が原因ではない、と明記している。むしろ指示に従うぶん課題は重くなり、LLM生成の文脈ファイルではSWE-benchの推論トークンがGPT-5.2で22%、GPT-5.1 Miniで10%増えた¹。原典は概要が概要として働くかも直接測っている。修正対象のファイルに触れるまでの手数を、文脈ファイルはどのエージェントでも意味のあるほどには縮めなかった¹。GPT-5.1 Miniでは、この手数がむしろ有意に増えている。著者らは、ファイルを探すコマンドを重ね、すでに文脈に入っているファイルを読み直すためだとしている¹。

では守られても動かないのはなぜか。Khatriは、惜しい失敗、つまり落ちたゴールドテストが1〜4件にとどまった実行を個別に読んでいる。詰まっていたのは「認証トークンを先回りして更新する設計を選べるか」「規則は知っているのに検査を正しく配線できるか」といった実装の技能で、文脈ファイルが供給できる知識の欠落ではなかった。本物のAGENTS.mdを与え直しても、惜しい失敗が合格に転じた例はどちらのエージェントにもない（Codexは18/18で失敗のまま）²。文脈ファイルが埋められるのは知識の穴で、ここで詰まっているのは技能の穴だ、というのが著者の答えである。

概要を削れば軽くなるのか。Gloaguenらはその除去実験を実際に行っている。LLMに生成させた文脈ファイルから概要だけを取り除くと、CTXBENCHの精度は68.12%から62.32%へ下がり（有意ではない、p=0.15）、費用も有意には下がらなかった（p=0.24）。費用を有意に押し上げていたのは、むしろ残すよう勧められる側、つまりテストの指示（両ベンチマークでp=0.023／0.0035）とツールの指示（SWE-bench Liteでp=0.0012）のほうだった。概要を削れば速く安くなる、という読み方は原典にはない。

さらに「概要は効かない」には成立条件がある。著者らは理由を既存ドキュメントとの冗長性に求め、リポジトリからドキュメント（.mdファイル、例示コード、docs/以下）を全部取り除いた条件で測り直している。そこではLLMに生成させた文脈ファイルが平均2.7%の改善を示し、開発者が手で書いたものをも上回った¹。「AGENTS.mdを足したら良くなった」という経験談は、ドキュメントの乏しいマイナーなリポジトリが多いことで説明できるとも著者らは書く。READMEやdocs/が既に整っているリポジトリでは概要は重複であり、そうでないリポジトリでは話が変わる。

失敗に当てて調整すると上がる

ShepardとAlbrechtの研究は、書き方ではなく調整の仕方を変えると成果が出ることを示した。手法名はprobe-and-refine tuningで、合成したバグ修正の探りタスクを使い、エージェントのループやツール実行を伴わない単発のLLM呼び出しだけでガイダンスファイルを繰り返し診断し修正する⁴。SWE-bench Verifiedは、SWE-benchの評価対象を人手で検証し直した版である。このベンチマーク上でQwen3.5-35B-A3Bを用いた200ステップ・4試行の結果、調整済みガイダンスの平均解決率は33.0%だった。静的な知識ベース基準は28.3%、ガイダンスなし基準は25.5%で、調整済みガイダンスのこの二つに対する改善はどちらもp<0.001で有意だと著者らは報告する⁴。ただし調整済みガイダンスは静的な知識ベースより平均63%長く、著者らは内容の質とプロンプト長の寄与を切り分けられていないと断っている⁴。対象インスタンスの46%はDjangoに集中しており、主にDjangoでの効果である可能性は残るとも書いている⁴。

著者らはさらに改善の中身を分解している。調整後のガイダンスは、評価可能なパッチを生成できたケースが14.5ポイント多い一方、パッチ1件あたりの精度はほぼ一定（約59%、p=0.119で有意な変化は検出されず）だった。効果の中心はパッチの質ではなく、正しいファイルへたどり着けるかというナビゲーションの部分だ⁴。診断能力の低いモデル（NVIDIA-Nemotron-3-Nano-30B-A3B）では、調整ループ自体が第1反復以降で失速する⁴。そのモデルでは順序も反転し、解決率は無誘導28.4%、調整済み27.0%、静的な知識ベース24.6%と、どのガイダンスも与えないほうを下回った（単一試行）⁴。精度のほうは、そのモデルでも一定だった。ただし著者らは、ループの手順をQwenの出力形式に合わせて作っているため、この失速が素の能力差ではなくプロンプトの噛み合わなさである可能性も残ると書いている⁴。

ただしこの利得が出るかどうかは、エージェントに許すステップ数による。著者らが3条件を25・50・100・200ステップで走らせると、25ステップでは3条件が区別できず（全対比較でp>0.3）、50ステップでは調整済みガイダンスが静的な知識ベースを下回った（23.4%対29.8%、p=0.022）。ただし25・50・100ステップの測定は単一試行で、予算をまたぐこのパターンは再現済みの効果ではなく記述的なものとして読むよう著者らは断っている⁴。調整済みガイダンスが指示する「再現→追跡→修正」の手順は、静的な知識ベースの軽い助言より多くのステップを要するためだと著者らは説明し、不十分なステップ予算で配備すると単純な代替よりむしろ性能を下げうる、と実務者に向けて明記している⁴。ガイダンスの複雑さと予算は釣り合わせる必要がある。

何を書き、何に期待しないか

五本を重ねると、書くべきものと期待を下げるべきものの輪郭が見える。まず期待を下げるのはリポジトリ概要だ。プロジェクトの目的や全体構成を説明する記述は、モデル提供元が勧めていても成功率に寄与しない。ただし削れば軽くなるわけでもなく、READMEやdocs/が薄いリポジトリでは向きが変わる¹。ただし、効かないという結果が出たのは散文の概要である。Shepardらが使った静的な知識ベースは、tree-sitterでハブ・エントリポイント・import関係を抽出した構造要約を含む。これを与えた条件は解決率を25.5%から28.3%へ上げた（p=0.004）⁴。書くべきは非標準の作法と具体的な指示だ。標準的な手順から外れたテストの起動方法や、リポジトリ固有のツールがこれに当たる。原典が遵守を測ったのはこの種の指示で、言及すればエージェントは実際に使う¹。Khatriの1リポジトリでも、テストに20分以上かかるという警告があると、Claudeは全体テストの実行回数を減らした（3.67→2.44→1.67回）²。著者はこれを事前登録外の探索的な観察と位置づけている²。Lullaらが報告するのは「正確さが上がる」ではなく「速さと出力トークンが下がる」という方向の関連にとどまる。正確さのほうを著者らは測っていない。著者らは意味的な正しさやマージ済みPRとの機能的な等価性の評価を明示的に本稿の範囲外とし、124件から無作為に抽出した50件について「出力が空でも些末でもない」ことを目視で確かめただけだと断っている⁵。同じ正確さのまま安くなったのか、正確さごと落ちたのかは、この研究からは分からない。

届け方も選び直す価値がある。選択的取得は、文脈ファイルを与えない条件と比べてもキャッシュ作成トークンが少なかった（Claude側でしか測れない指標で、11タスク全てで低い、p=0.001）²。常時全文方式との直接比較では、著者は有意差を報告していない。遵守率で見る限り、ファイルサイズと隣接ファイル間の矛盾については、いじる労力が報われないことをベイズ因子が積極的に支持している。成功率と費用の側からも同じ向きの報告がある。Gloaguenらは結果をファイル長で層別し、成功率とも1インスタンスあたり費用とも明確な依存関係は見られないとしている¹。指示の位置とファイル構成については、この研究が差を検出できなかったというだけで、効かないことの裏づけまではない³。原典が代わりに見つけたのは、課題の同一性が構造変数より強い予測子だという事実である³。著者は、ファイルだけに頼らず、セッション中に規則を再提示する機構とリンタ・CIによる事後強制を重ねるよう勧めている³。Khatriも実務含意を書いている。汎用の文脈文書に注ぐ労力は、課題分割やツール整備、例示によるプロンプトに注ぐ労力より見返りが小さいかもしれない、というのがKhatriの「安全な読み」である²。ただしそこには続きがあり、合否を変えなくても働き方は変わる点を唯一の実務的な含意と呼んで、コストと遅延の観点なら文脈ファイルは置く価値がありうるとも書いている²。ガイダンスは一度書いて終わりにせず、失敗の探りに当てて調整すると解決率が上がる余地がある。ただしその利得はステップ予算次第で、予算が足りなければ単純な代替を下回りうる。Shepardらはさらに、ガイダンスの複雑さ・ステップ予算・モデルの能力の三つが釣り合って初めて助けになるとし、ガイダンスはそれを消費するモデルで調整するよう勧めている⁴。そのうえShepardらが当てたのは合成したバグ修正の探りタスクで、実運用で観測した失敗を材料にする形までは検証していない⁴。文脈ファイルに労力を注ぐと決めたなら、向ける先はファイルの体裁ではなく、非標準の作法と、失敗の当て方のほうだ。

この記事はAIが執筆しています。内容には誤りが含まれる可能性があります。ご注意ください。