随着 AI 编码代理在软件工程领域的快速渗透，如何让这些 “数字同事” 更好地理解特定代码库的上下文，成为了提升开发效率的关键。AGENTS.md—— 一个放置在项目根目录的 Markdown 文件 —— 应运而生，被诸多代理框架（如 Claude Code、Cursor、Codex）推荐为适配代码库的标准方式。业界普遍认为，一份好的 AGENTS.md 能显著提升代理的任务完成率。但事实果真如此吗？提升的幅度有多大？我们需要为此付出什么代价？
本文通过整合近期两项关键实证研究 ——Vercel 的工程实验与苏黎世联邦理工学院的学术评估（AGENTbench）—— 对 AGENTS.md 的实际效用进行量化拆解。数据揭示了一个复杂图景：在理想条件下，AGENTS.md 能带来高达 47% 的通过率提升；但在更广泛的现实任务中，其平均增益仅为 4%，且伴随着 约 20% 的推理成本增加。我们将深入分析这巨大差异背后的原因，并最终给出一个以数据为驱动的、可落地的 AGENTS.md 编写与评估框架。
Vercel 实验：当 AGENTS.md 实现 100% 通过率
Vercel 团队面临一个具体问题：如何让编码代理正确使用训练数据中尚未包含的 Next.js 16 新 API（如 'use cache'、connection()）。他们对比了两种方案：
- 技能（Skills）：一个按需调用的、包含框架知识的工具包。
- AGENTS.md：一个包含压缩版 Next.js 文档索引的静态 Markdown 文件。
在一个精心构建的、包含新 API 的评估套件中，结果令人惊讶：
| 配置 | 通过率 | 相较于基线提升 |
|---|---|---|
| 基线（无文档） | 53% | — |
| 技能（默认行为） | 53% | +0 pp |
| 技能（显式指令触发） | 79% | +26 pp |
| AGENTS.md（文档索引） | 100% | +47 pp |
AGENTS.md 在构建（Build）、检查（Lint）、测试（Test）所有细分项上均达到了满分。Vercel 分析认为，其优势源于三个 “反直觉” 的设计：
- 无决策点：代理无需判断 “是否需要查阅文档”，信息已在上下文中。
- 持续可用性：内容存在于每个回合的系统提示里，而非异步加载。
- 无顺序问题：避免了 “先读文档还是先探索项目” 的决策脆弱性。
该实验证明了在特定、文档稀缺、且目标明确的场景下，一个经过压缩（从 40KB 降至 8KB）、指向外部详细文档的 AGENTS.md 索引，能带来质的飞跃。
学术评估：4% 的增益与 20% 的成本
然而，Vercel 的实验环境相对理想。苏黎世联邦理工学院的研究团队在论文《Are Repository-Level Context Files Helpful for Coding Agents?》中，进行了更广泛、更严格的评估。他们构建了 AGENTbench 基准，包含 138 个来自真实 GitHub Issue 的任务，这些任务所在的 12 个代码库均包含开发者编写的 AGENTS.md 文件。
研究对比了三种设置：无上下文文件、使用代理推荐命令自动生成的上下文文件、使用开发者编写的上下文文件。评估涉及 Claude Code、Codex (GPT-5.2)、Qwen Code 等多个主流代理。核心发现如下：
- 性能增益有限：开发者编写的上下文文件平均仅提升任务成功率 4%。而 LLM 自动生成的上下文文件甚至有轻微的负面影响（平均降低 3%）。
- 成本显著增加：无论是人工编写还是自动生成的上下文文件，都导致代理的平均推理步骤增加，使得 LLM 推理成本上升 约 20%。例如，GPT-5.2 在 AGENTbench 上的单任务成本从 0.38 美元（无上下文）增至 0.54 美元（有开发者上下文）。
- 行为改变：上下文文件确实改变了代理行为，使其进行更多的测试（+25%）、文件搜索（+15%）和代码库探索。代理也倾向于遵循文件中指定的工具（如
uv,pytest）。 - 冗余与无效概览：许多上下文文件（尤其是自动生成的）与代码库内现有文档高度冗余。研究还发现，文件中常见的 “代码库概览” 部分，并不能有效帮助代理更快定位到与任务相关的文件。
量化指标的冲突与统一
表面上看，两项研究的结论似乎矛盾：一项显示 47% 的提升，另一项显示仅 4% 的提升。但深入分析其场景，矛盾得以化解：
- Vercel 场景：任务是关于框架新特性，代理的训练数据中缺失此知识，且实验提供了精确压缩的文档索引。此时，AGENTS.md 提供了关键且唯一的 “知识补丁”。
- AGENTbench 场景：任务是通用代码问题（Bug 修复、功能添加），涉及 Python 等代理已拥有丰富参数化知识的语言。此时，大多数 AGENTS.md 内容成为冗余或次要约束，其收益被增加的计算成本部分抵消。
因此，AGENTS.md 的价值并非恒定，而是高度依赖于 “任务所需知识” 与 “代理已有知识” 之间的缺口。当缺口巨大且 AGENTS.md 能精准填补时，收益巨大；当缺口较小或 AGENTS.md 内容冗余时，收益微薄甚至为负。
可落地的 AGENTS.md 编写与评估参数
基于以上量化分析，我们提出以下工程化建议，旨在最大化 AGENTS.md 的 ROI（投资回报率）。
1. 编写原则：最小化、聚焦化、可检索化
- 摒弃冗长概览：不要罗列目录结构。代理自己能探索。
- 聚焦独特知识：只写入代码库特有、框架版本特定且代理可能不知道的信息。例如：
- 自定义的构建 / 测试命令（
npm run build:special）。 - 项目特有的设计模式或约定（“所有 API 响应包装在
ApiResponse对象中”）。 - 当前使用的、与主流版本不同的框架 / 库的特定配置。
- 自定义的构建 / 测试命令（
- 使用索引，而非全文：效仿 Vercel 方案。在 AGENTS.md 中放置一个压缩的索引，指向项目内
/.docs/等目录中的详细文档文件。代理在需要时可自行读取。 - 包含关键指令：一句明确的指令可能极大改变代理行为模式。例如：
“IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.”
2. 核心评估指标清单
在项目中引入 AGENTS.md 后，应建立量化评估体系，监控其实际效果。以下为推荐的核心指标：
| 指标类别 | 具体指标 | 计算公式 / 说明 | 目标 |
|---|---|---|---|
| 任务完成率 | 通过率 | 通过的任务数 / 总任务数 |
相对基线（无 AGENTS.md）稳定提升 |
| 关键任务通过率 | 针对 AGENTS.md 所涉及知识领域的任务子集的通过率 | 显著提升（如 Vercel 场景） | |
| 效率与成本 | 平均步骤数 | 代理完成单个任务的平均交互步骤 | 增幅应 < 10%（警惕过度探索） |
| 平均推理成本 | 单任务消耗的 LLM Token 估算成本 | 增幅应 < 15% | |
| 平均耗时 | 任务开始到测试通过的中位时间 | 不应显著增加 | |
| 上下文利用 | 指令遵循率 | 代理执行 AGENTS.md 中指定工具 / 流程的任务占比 | > 90% |
| 冗余失败率 | 因遵循 AGENTS.md 中过时 / 错误信息导致失败的任务占比 | < 2% |
3. 实施与监控流程
- 基准建立：在引入 AGENTS.md 前，使用一组代表性的任务（涵盖新旧知识）对代理进行基准测试，记录上述指标。
- 渐进迭代：采用最小化原则编写第一版 AGENTS.md，仅包含最确定的关键信息。
- A/B 测试：在相同任务集上，对比 “有 AGENTS.md” 和 “无 AGENTS.md” 的代理表现。重点关注关键任务通过率和平均步骤数。
- 根因分析：对于失败案例，分析是因为代理忽略了 AGENTS.md，还是因为 AGENTS.md 信息有误或带来干扰。
- 定期复审：随着代码库和依赖更新，定期审查并精简 AGENTS.md 内容，移除过时信息。
结论：从 “银弹” 想象到 “精准工具” 认知
AGENTS.md 不是提升编码代理性能的万能银弹。实证数据将其定位为一个需要谨慎使用的精准工具。它的价值峰值出现在为代理填补其知识图谱中关键且特定的缺口时。盲目地让 LLM 自动生成冗长的 AGENTS.md，或在其中堆砌显而易见的项目信息，很可能在付出 20% 额外成本的同时，只换来微不足道的性能提升，甚至适得其反。
未来的方向不在于编写更长的 AGENTS.md，而在于构建更智能的上下文管理系统：能够动态评估任务与知识缺口，并检索出最小必要信息注入上下文的机制。在此之前，遵循 “最小化、聚焦化” 原则，并配以严格的量化评估，是我们当前从 AGENTS.md 中获得确定、正向收益的最可靠路径。
资料来源
- Vercel Blog: "AGENTS.md outperforms skills in our agent evals" (2026)
- arXiv:2602.11988v1: "Are Repository-Level Context Files Helpful for Coding Agents?" (2026)