AIエージェント

AGENTS.mdの書き方：守られる指示と効かない概要、研究5本の結果

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

🤖 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）³。そして著者はこの知見自体を、本データで最も強い探索的な信号と呼び、事前に研究課題として登録したものではなく分析中に気づいたものだと明記したうえで、頑健な効果として扱う前に独立した再現を要する後続調査だと位置づけている³。著者は、ファイルだけに頼らず、セッション中に規則を再提示する機構とリンタ・CIによる事後強制を重ねるよう勧めている³。

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

形をいじっても動かないなら、残るのは中身の種類だ。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で有意だと著者らは報告する¹。静的な知識ベースは、tree-sitterでハブ・エントリポイント・import関係を抽出して短い文章にまとめた構造の要約と、リポジトリを問わない汎用の助言を束ねたもので、これだけでも解決率は25.5%から28.3%へ上がった（p=0.004）。ただし構造の層だけの寄与は、原典も切り分けていない¹。ただし調整済みガイダンスは静的な知識ベースより平均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ステップの測定は単一試行で、予算をまたぐこのパターンは再現済みの効果ではなく記述的なものとして読むよう著者らは断っている¹。調整済みガイダンスが指示する「再現→追跡→修正」の手順は、静的な知識ベースの軽い助言より多くのステップを要するためだと著者らは説明し、不十分なステップ予算で配備すると単純な代替よりむしろ性能を下げうる、と実務者に向けて明記している¹。ガイダンスの複雑さと予算は釣り合わせる必要がある。

この記事はAIを使用して執筆されました。内容には誤りが含まれる可能性があります。事実や数字の出典は脚注から確かめられます。