AIエージェント

AGENTS.mdの効果は限定的との報告、削るべきはリポジトリ概要

2026/8/1

🤖 AIが執筆しています

要点： AGENTS.md や CLAUDE.md ——コーディングエージェントが起動時に自動で読み込む、リポジトリ直下に置く文脈ファイル——を書けば成功率が上がるという期待は、2026年に出た五本の研究を通すと崩れる。ETH Zurichのチームは、文脈ファイルの有無がタスク成功率を一般的には改善しない一方、推論コストは平均で20%超増えると報告した¹。独立の二エージェント比較では、Claude Codeの合格率が53.3%→55.6%→55.6%、Codexが58.8%→56.9%→52.9%と条件間でほぼ動かず、置換検定はp=1.00とp=0.66だった²。ところが別の研究は、AGENTS.mdの有無と紐づく形で実行時間の中央値が28.64%、出力トークンが16.58%それぞれ下がったと報告している³。ファイルサイズや配置、アーキテクチャ、隣接ファイル間の矛盾という4つの構造変数を操作した大規模要因計画研究は、多重検定補正後にどれも有意差を検出できなかった⁴。それでも、失敗パターンに合わせてガイダンスを調整した研究では、SWE-bench Verified上の解決率が25.5%→28.3%→33.0%まで上がった⁵。読み解くべきは、書き方ではなく中身の種類と届け方だ。

成功率は動かない

Gloaguenらは、複数のLLM・複数のコーディングエージェントで、LLM生成と人間が書いた文脈ファイルの双方をSWE-benchタスクと現実の課題で検証した。文脈ファイルの提供はタスク成功率を一般には改善しないと著者らは報告する¹。ただし内訳は一様ではない——LLMに生成させた文脈ファイルは平均で約3%の低下、開発者が手で書いたものは約4%の改善で、著者らは「手で書く場合にのみ望ましいだろう」と結論している¹。本稿が扱うのは後者、つまり人が書く場合である。

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となり偶然と区別できなかった。著者はさらに同等性限界——この幅以内の差なら実質的に同じとみなす事前の許容範囲——をClaude10ポイント、Codex15ポイントに置き、観測差はどちらもその内側に収まった²。設定もエージェントも異なる二本の研究が、同じ結論に達している。

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

成功率が動かない一方、コストの数字は一致しない。Gloaguenらは、文脈ファイルの提供が推論コストを平均で20%超増やすと報告した¹。一方Lullaらは、10のリポジトリと124件のプルリクエストで、AGENTS.mdの存在と実行時間の中央値28.64%減・出力トークン消費16.58%減という関連を報告する。ただしタスク完了の挙動は「比較可能」だとも述べ、成功率が上がったとは主張していない³。

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

Gloaguenらのコスト増とLullaらのコスト減は、届け方という一変数で説明がつくかもしれない。ただしこれは本稿の推論であり、どちらの論文も届け方を直接比較していない。ただしKhatriの選択的条件は、3リポジトリ中2つで元の文脈ファイルの10〜18倍という自動生成wikiを使っており、届け方と内容量が同時に変わっている。この比較から届け方だけを切り出すことはできない。届け方でコストの向きが変わりうる、という仮説として扱うべきだ。

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

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%低い）になる。この傾向は複数の条件で再現されたが、線形ではなかった⁴。

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

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

「このプロジェクトはこういう構成です」という説明を厚くしても、成功率は上がらない。守られるのは「このコマンドを使え」「この関数は直接呼ぶな」といった具体的な指示だ。ただしこれは守られるという報告であって、守らせれば成功率が上がるという報告ではない。

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

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）ではこの調整ループの効果が落ちる一方、パッチの精度は一定のままだったとも報告されている⁵。

何を書き、何を捨てるか

五本を重ねると、書くべきものと捨てるべきものの輪郭が見える。まず捨てるのはリポジトリ概要だ。プロジェクトの目的や全体構成を説明する記述は、モデル提供元が勧めていても成功率に寄与しない¹。残すべきは非標準の作法と具体的な指示だ。標準的な手順から外れたテストの起動方法、直接呼んではいけない内部関数、リポジトリ固有の命名規則——読めばそのまま従える指示は守られる¹。Lullaらが報告するのは「正確さが上がる」ではなく「同じ正確さをより安く、より速く」という方向の関連だ³。

届け方も選び直す価値がある。選択的取得は、文脈ファイルを与えない条件と比べてもキャッシュ作成トークンが少なかった（11タスク全てで低い、p=0.001）²。常時全文方式との直接比較で有意差として報告されているものはない。遵守率で見る限り、ファイルサイズや配置、内部のアーキテクチャをいじる労力は、要因計画研究の結果を見る限り報われない⁴。ガイダンスは一度書いて終わりにせず、実際に観測した失敗——どのファイルにたどり着けなかったか、どこで迷ったか——に当てて調整すると解決率が上がる余地がある⁵。書く労力は構造の整形にではなく、非標準の作法と実際の失敗を追う方に向けたほうがいい。

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

Gloaguenら、Khatri、Lullaら、ShepardとAlbrecht、ファイル構造の要因計画研究——五本はすべてarXivのプレプリントで、査読を通っていない。

Khatriの研究は3リポジトリを対象にした単独の独立研究者によるもので、ClaudeとCodexの2エージェントに限った比較だ。ここから広くは一般化できない²。要因計画研究は2つのTypeScriptコードベースに限られ、検証は主にClaude Sonnet 4.6で行われている⁴。ShepardとAlbrechtの研究は、SWE-bench Verifiedという1つのベンチマークと、主にQwen3.5-35B-A3Bという1つのモデルファミリーで測った結果である⁵。

届け方の違いがコストの向きを説明するという読みは、本稿がGloaguenらとLullaらとKhatriの結果を並べて立てた推論であり、どの論文も届け方そのものを直接比較したわけではない。この仮説を自分のリポジトリで検証する余地は残る。五本はいずれも2026年1月から7月にかけて公開された。

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