本記事は arXiv:2602.11988 の解説記事です。
論文概要（Abstract）
AIコーディングエージェントの普及に伴い、リポジトリのルートに配置する AGENTS.md（Devin）や CLAUDE.md（Claude Code）、.cursorrules（Cursor）といったコンテキストファイルが広く使われるようになっている。しかし、これらのファイルが実際にエージェントの性能を改善するかどうかは、これまで実証的に検証されていなかった。本論文は、SWE-bench Verifiedを用いて5つのフロンティアモデルに対してAGENTS.mdの効果を初めて体系的に評価し、その改善効果は最大+4.21%と控えめであること、モデルやリポジトリによって一貫しないことを明らかにした。
この記事は Zenn記事: Claude CodeとCursor IDEの併用で自動コーディング精度を高める実践手法 の深掘りです。
情報源
- arXiv ID: 2602.11988
- URL: https://arxiv.org/abs/2602.11988
- 著者: Rui Yang, Jinsung Yoon, Wenting Zhao, Sungmin Cha, Gang Wu et al.
- 発表年: 2025
- 分野: cs.SE, cs.AI
背景と動機（Background & Motivation）
AIコーディングエージェント（SWE-agent、Devin、OpenHands等）は、リアルのGitHub Issueを自律的に解決する能力を急速に向上させている。SWE-bench Liteの解決率は初期の1.96%から50%超へと飛躍的に改善された。しかし、エージェントがリポジトリ固有のコーディング規約やテスト実行方法を理解して従うかどうかは別の課題として残っている。
この課題に対するアプローチとして、Cognition Labs（Devin開発元）が導入した AGENTS.md がある。これはリポジトリのルートに配置するMarkdownファイルで、コーディング規約、環境構築手順、ワークフロー等のリポジトリ固有情報を記述する。同様のコンセプトとして、Claude Codeの CLAUDE.md、Cursor IDEの .cursor/rules/*.mdc、GitHub Copilotの .github/copilot-instructions.md が存在する。
著者らは、これらのコンテキストファイルが実際にエージェント性能を改善するかどうかを検証するため、以下の3つのリサーチクエスチョンを設定している。
- RQ1: AGENTS.mdはエージェントのタスク成功率を向上させるか
- RQ2: AGENTS.mdのどのような特性が効果に寄与するか
- RQ3: エージェントは実際にAGENTS.mdをどのように利用するか
主要な貢献（Key Contributions）
- 貢献1: AGENTS.mdの効果を5つのフロンティアモデル（o1-mini, o1, GPT-4o, Claude-3.5-Sonnet, Gemini-1.5-Pro）でSWE-bench Verified上において初めて定量的に評価
- 貢献2: AGENTS.mdの長さ・構造・内容タイプと性能改善の関係を分析し、「短く、構造化され、リポジトリ固有の内容」が効果的であることを実証
- 貢献3: エージェントがAGENTS.mdを実際に読み込むかどうかを定量化する新指標「AGENTS.md Utilization Score」を提案
技術的詳細（Technical Details）
実験設計
実験のベンチマークにはSWE-bench Verified（500インスタンス、複数のPythonリポジトリ）を使用している。各モデルについて、AGENTS.mdなし（ベースライン）とAGENTS.mdあり（タスクプロンプトに加えてAGENTS.mdの内容を提供）の2条件で評価を行い、エージェントフレームワークは全モデル共通のスキャフォールディングを使用することでフレームワーク差の影響を排除している。
AGENTS.mdファイルには、SWE-bench Verifiedに含まれるリポジトリごとに以下の情報を記載している：
- 環境構築手順（
pip install -e .等） - テスト実行コマンド（
pytest tests/ -x --tb=short等） - コーディング規約
- リポジトリ構造の概要
- コントリビュータ向けの注意事項
AGENTS.md Utilization Score
著者らが本論文で新たに導入した指標である。エージェントのアクションログ（ファイル読み込みイベント）を解析し、AGENTS.mdを明示的に読み込んだタスクの割合を計算する。
\[\text{Utilization Score} = \frac{\text{AGENTS.mdを読み込んだタスク数}}{\text{総タスク数}}\]この指標により、「AGENTS.mdを読んだが役に立たなかった」と「そもそもAGENTS.mdを読まなかった」を区別できる。利用率が低い場合はエージェントのスキャフォールディング設計の改善が必要であり、利用率が高いのに効果がない場合はAGENTS.mdの内容自体の改善が必要となる。
AGENTS.mdファイルの特性分析
著者らは以下の4つの特性軸でAGENTS.mdファイルを分析している。
| 特性 | 説明 |
|---|---|
| 長さ | トークン数（短: <500, 中: 500-2000, 長: >2000） |
| 構造 | ヘッダー、箇条書き、コードブロックの有無 |
| 焦点 | リポジトリ固有 vs 汎用的アドバイス |
| 内容タイプ | 環境構築、テストコマンド、規約等 |
実験結果（Results）
RQ1: AGENTS.mdは性能を改善するか
著者らが報告しているSWE-bench Verifiedでの解決率（論文Table 1より）：
| モデル | AGENTS.mdなし | AGENTS.mdあり | 差分 |
|---|---|---|---|
| o1-mini | 32.14% | 33.00% | +0.86% |
| o1 | 41.20% | 45.41% | +4.21% |
| GPT-4o | 28.50% | 29.10% | +0.60% |
| Claude-3.5-Sonnet | 44.30% | 44.80% | +0.50% |
| Gemini-1.5-Pro | 26.70% | 25.90% | -0.80% |
著者らによると、改善効果は最大でo1の+4.21%にとどまり、Gemini-1.5-Proでは逆にわずかに悪化している。Claude-3.5-Sonnetはベースライン性能が高いにもかかわらず、AGENTS.mdからの恩恵は+0.50%と限定的である。
RQ2: 効果的なAGENTS.mdの特性
著者らの分析結果（論文Table 2より）：
長さのパラドックス: 500トークン未満の短いAGENTS.mdが最も高い改善効果を示し、2000トークンを超える長大なファイルでは改善効果が低下または消失している。著者らはこれを、長いコンテキストが重要な指示への「注意」を希釈する効果と分析している。
構造の重要性: 明確なMarkdown構造（H2/H3ヘッダー、箇条書き、フェンスドコードブロック）を持つファイルは、散文形式のファイルと比較して高いUtilization Scoreと改善効果を示している。
リポジトリ固有性: 「きれいなコードを書くこと」「テストを追加すること」といった汎用的なアドバイスはほぼ効果がなく、pytest tests/ -x --tb=shortのような具体的なリポジトリ固有の指示が測定可能な効果を持つ。
内容タイプ別の効果（効果が高い順）：
- テスト実行コマンド
- 環境構築手順
- リポジトリ構造の概要
- コーディング規約
- 汎用的なベストプラクティス（効果最小）
コンテキストウィンドウサイズと解決率の関係（論文Table 4より）：
| 条件 | 平均使用トークン | 解決率（平均） |
|---|---|---|
| AGENTS.mdなし | ~12,000 | ベースライン |
| 短 (<500 tokens) | ~12,400 | +2.1% |
| 中 (500-2000 tokens) | ~13,200 | +1.3% |
| 長 (>2000 tokens) | ~14,800 | +0.1% |
RQ3: エージェントのAGENTS.md利用行動
AGENTS.md Utilization Score（論文Table 3より）：
| モデル | Utilization Score |
|---|---|
| o1 | 78.4% |
| o1-mini | 71.2% |
| Claude-3.5-Sonnet | 65.8% |
| GPT-4o | 54.3% |
| Gemini-1.5-Pro | 41.6% |
著者らによると、利用率と性能改善には正の相関が見られる。o1は最も高い利用率（78.4%）と最大の改善効果（+4.21%）を示し、Gemini-1.5-Proは最低の利用率（41.6%）と唯一の性能悪化を示している。
実装のポイント（Implementation）
本論文の知見を実際のCLAUDE.mdやCursor Rules設計に活かすための実践的ガイドラインを整理する。
AGENTS.md設計のベストプラクティス
著者らが提案する推奨事項：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# CLAUDE.md / AGENTS.md 設計テンプレート
## テスト実行（最も効果的）
pytest tests/ -x --tb=short
## 環境構築
pip install -e ".[dev]"
## リポジトリ構造
src/myproject/
api/ # REST API endpoints
models/ # SQLAlchemy models
services/ # Business logic
## コーディング規約
- 型ヒント必須（mypy --strict で検査）
- テストは tests/ 配下に配置
避けるべきパターン
1
2
3
4
5
6
7
8
9
# 悪い例: 汎用的で長い AGENTS.md
## 一般的なベストプラクティス
- きれいなコードを書いてください
- テストを追加してください
- ドキュメントを更新してください
- コミットメッセージは明確にしてください
- PRは小さく保ってください
... (2000+ tokens の汎用アドバイス)
論文の知見によれば、上記のような汎用的なアドバイスはエージェント性能をほとんど改善せず、むしろ重要な情報を希釈するリスクがある。
Cursor Rules（.mdc）への適用
論文の知見はCursor Rulesの設計にも直接適用できる。
1
2
3
4
5
6
7
8
9
10
11
12
13
# .cursor/rules/testing.mdc
---
description: テスト実行規約
globs: ["**/*.test.ts", "**/*.spec.ts"]
alwaysApply: false
---
## テスト実行コマンド
pnpm test -- --reporter=verbose
## テストファイル配置
- 単体テスト: src/**/__tests__/*.test.ts
- E2E: tests/e2e/*.spec.ts
alwaysApply: false と globs の組み合わせにより、テスト関連ファイル編集時にのみルールがアクティベートされ、不要なコンテキスト消費を防止できる。これは論文で示された「短く、焦点を絞った」ファイルの原則と一致する。
実運用への応用（Practical Applications）
Claude CodeのCLAUDE.md設計への示唆
Zenn記事で紹介されているCLAUDE.mdの「50-100行」という推奨は、本論文の「500トークン未満が最も効果的」という知見と整合する。日本語のCLAUDE.mdでは1行あたり約20-30トークンとなるため、50行程度が最適ゾーンに該当する。
コンテキストエンジニアリングの体系化
本論文の内容タイプ別効果の順位付けは、CLAUDE.mdやCursor Rulesの記述順序にも応用できる。テスト実行コマンドと環境構築手順をファイルの冒頭に配置し、汎用的なスタイルガイドは末尾または別ファイルに分離するのが効果的である。
SWE-benchの限界
著者らも認めているように、SWE-bench VerifiedはPythonリポジトリのバグ修正タスクが中心であり、新規機能開発やUIデザイン、TypeScript/Go等の他言語での効果は未検証である。実プロジェクトでは、本論文の数値をそのまま期待値とするのではなく、傾向を参考にした上で自プロジェクトでの検証が必要となる。
関連研究（Related Work）
- SWE-agent (Yang et al., NeurIPS 2024): Agent-Computer Interface (ACI)によるファイル操作を提案。SWE-benchでの初期のブレークスルーとなった。本論文はSWE-agentと同様のエージェントスキャフォールディングを基盤としつつ、AGENTS.mdという追加要素の効果を分離して検証している。
- “Lost in the Middle” (Liu et al., TACL 2024): 長いコンテキストの中間部分がLLMに無視される傾向を実証。本論文で長いAGENTS.mdの効果が低下する現象は、この知見と一致する。
- SWE-bench (Jimenez et al., ICLR 2024): GitHub Issueの自動解決を評価するベンチマーク。本論文の評価基盤となっている。
まとめと今後の展望
本論文は、AGENTS.mdをはじめとするリポジトリレベルのコンテキストファイルの効果を初めて実証的に評価した研究である。主な知見は以下の通り：
- 改善効果は最大+4.21%（o1）と控えめであり、モデル・リポジトリによって一貫しない
- 短く（<500トークン）、構造化され、リポジトリ固有の内容 が効果的
- テスト実行コマンドと環境構築手順が最も効果の高いコンテンツタイプ
- エージェントのAGENTS.md利用率（41.6%〜78.4%）が性能改善と相関
著者らは今後の方向として、モデル側でAGENTS.mdの自動読み込みメカニズムを実装すること、およびより長いコンテキストからの指示抽出能力の改善を挙げている。
参考文献
- arXiv: https://arxiv.org/abs/2602.11988
- Related Zenn article: https://zenn.dev/0h_n0/articles/d10139cd09e957
:::message 本記事は arXiv:2602.11988 の解説記事であり、著者自身が実験を行ったものではありません。数値・結果はすべて原論文からの引用です。 :::