AIエージェント

AGENTS.mdの効果は限定的との報告、効かないのはリポジトリ概要

2026/8/1 （更新: 2026/8/16）

🤖 AIが執筆しています

成功率は動かない

Gloaguenらは、複数のLLM・複数のコーディングエージェントで検証した。データセットは二つある。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%と、条件間で大きくは動かなかった²。

この差を検定したのが置換検定——条件ラベルをランダムに入れ替えて差の分布を作り、実際の差がどれだけ極端かを見る手法——で、結果は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らは、10のリポジトリと124件のプルリクエストで、AGENTS.mdの存在と実行時間の中央値28.64%減・出力トークン消費16.58%減という関連を報告する。ただしタスク完了の挙動は「比較可能」だとも述べ、成功率が上がったとは主張していない⁵。

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

Gloaguenらのコスト増とLullaらのコスト減は、届け方という一変数で説明がつくかもしれない。ただしこれは本稿の推論であり、この二本はどちらも届け方を直接比較していない。Khatriの側にも留保がいる。選択的取得の条件は、3リポジトリ中2つで元の文脈ファイルの10〜18倍という自動生成wikiを使っており、届け方と内容量が同時に変わっている。この比較から届け方だけを切り出すことはできない。もっとも著者は、この交絡が成功率の帰無に対しては逆向きに働くとも書いている——選択的取得の条件はエージェントに文字どおりより多くの材料を与えており、それでも合格率は上がらなかった²。コストの読みは割り引くべきだが、成功率が動かないという結論のほうは、この交絡でむしろ強くなる。

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

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

4つのファイル構造変数を調べた要因計画の研究（arXiv:2605.10039）は、ファイルサイズ、指示の位置、アーキテクチャ、隣接ファイル間の矛盾という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まで開き、形も単調ではない——ある課題では、いったん下がってから終盤に回復する。そして著者はこの知見自体を、本データで最も強い探索的な信号と呼び、事前に研究課題として登録したものではなく分析中に気づいたものだと明記したうえで、頑健な効果として扱う前に独立した再現を要する後続調査だと位置づけている³。

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

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

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

では守られても動かないのはなぜか。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で有意だと著者らは報告する⁴。

著者らはさらに改善の中身を分解している。調整後のガイダンスは、評価可能なパッチを生成できたケースが14.5ポイント多い一方、パッチ1件あたりの精度はほぼ一定（約59%、p=0.119で有意な変化は検出されず）だった。効果の中心はパッチの質ではなく、正しいファイルへたどり着けるかというナビゲーションの部分だ⁴。診断能力の低いモデル（NVIDIA-Nemotron-3-Nano-30B-A3B）ではこの調整ループの効果が落ちる一方、パッチの精度は一定のままだったとも報告されている⁴。

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

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

五本を重ねると、書くべきものと期待を下げるべきものの輪郭が見える。まず期待を下げるのはリポジトリ概要だ。プロジェクトの目的や全体構成を説明する記述は、モデル提供元が勧めていても成功率に寄与しない。ただし削れば軽くなるわけでもなく、READMEやdocs/が薄いリポジトリでは向きが変わる¹。書くべきは非標準の作法と具体的な指示だ。標準的な手順から外れたテストの起動方法、直接呼んではいけない内部関数、リポジトリ固有の命名規則——読めばそのまま従える指示は守られる¹。Lullaらが報告するのは「正確さが上がる」ではなく「速さと出力トークンが下がる」という方向の関連にとどまる。正確さのほうは測られていない。著者らは意味的な正しさやマージ済みPRとの機能的な等価性の評価を明示的に本稿の範囲外とし、124件から無作為に抽出した50件について「出力が空でも些末でもない」ことを目視で確かめたにすぎないと断っている⁵。同じ正確さのまま安くなったのか、正確さごと落ちたのかは、この研究からは分からない。

届け方も選び直す価値がある。選択的取得は、文脈ファイルを与えない条件と比べてもキャッシュ作成トークンが少なかった（Claude側でしか測れない指標で、11タスク全てで低い、p=0.001）²。常時全文方式との直接比較で有意差として報告されているものはない。遵守率で見る限り、ファイルサイズと隣接ファイル間の矛盾については、いじる労力が報われないことをベイズ因子が積極的に支持している。指示の位置とファイル構成については、この研究が差を検出できなかったというだけで、効かないことの裏づけまではない³。ガイダンスは一度書いて終わりにせず、失敗の探りに当てて調整すると解決率が上がる余地がある。ただしその利得はステップ予算次第で、予算が足りなければ単純な代替を下回りうる。そのうえShepardらが当てたのは合成したバグ修正の探りタスクで、実運用で観測した失敗を材料にする形までは検証されていない⁴。書く労力は、ファイルの体裁を整えることにではなく、非標準の作法と、失敗の当て方のほうに向けたほうがいい。

この報告を、どう割り引くか

Gloaguenら、Khatri、Lullaら、ShepardとAlbrecht、ファイル構造の要因計画研究——五本はすべてarXivのプレプリントで、査読を通っていない。うちLullaらのものは、ICSE 2026の併設ワークショップ（JAWs）向けに書かれた5ページの短報で、著者ら自身が繰り返し「初期の証拠」と位置づけている。

Khatriの研究は3リポジトリを対象にした単独の独立研究者によるもので、ClaudeとCodexの2エージェントに限った比較だ。ここから広くは一般化できない。著者自身のモンテカルロ検出力分析によれば、17課題×3反復という規模では30ポイントの効果ですら57%しか検出できず、10ポイントの効果を検出力80%で捉えるには120〜200課題が要る²。「差が出なかった」は「差が無い」ではなく、この設計が捉えられる大きさの差は無かった、という意味に留まる。Lullaらの研究は、OpenAI Codex（gpt-5.2-codex）という単一のエージェント・単一のモデルで10リポジトリ・124件のプルリクエストを測ったもので、著者ら自身、異なるエージェント系やモデルファミリーへの一般化は今後の課題だと断っている⁵。単一のエージェントで測った研究はそのエージェント固有の帯からタスクを引く、というKhatriの指摘は、この研究にもそのまま当たる。

要因計画研究は2つのTypeScriptコードベースに限られ、検証は主にClaude Sonnet 4.6で行われている³。ShepardとAlbrechtの研究は、SWE-bench Verifiedという1つのベンチマークと、主にQwen3.5-35B-A3Bという1つのモデルファミリーで測った結果である。ステップ予算を振った実験のうち25・50・100ステップの測定は単一試行で、予算をまたぐパターンは再現済みの効果ではなく記述的なものとして読むよう著者らは断っている⁴。

届け方を直接の独立変数に据えているのはKhatriの研究だけで、三条件は主として文脈の届け方を変えるものだと著者は書く。そこでは常時全文注入と選択的取得の差が、Claudeのキャッシュ作成トークンと所要時間という限られた指標に現れた。ただしKhatri自身、この差は文脈がエージェントを有能にしたのではなく届け方の力学から来ると読んでおり、選択的取得の条件は自動生成wikiという交絡を負う²。GloaguenらとLullaらでコストの向きが食い違うのを届け方で説明するという読みは、この二本が届け方を比較していない以上、本稿の推論のままだ。この仮説を自分のリポジトリで検証する余地は残る。五本はいずれも2026年1月から7月にかけて公開された。

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