AGENTS.md 真的有用吗：研究结果、配置异味与最小上下文实验

这是 AI Agent 工程进阶 系列的一篇先行实验。正式主线会先建立任务契约与评测基础，再在 Context Architecture 之后回到这篇，对仓库级说明做一次可复现的对照实验。

在之前的《AGENTS.md：Codex 项目说明书》里，我回答的是“怎么写”：加载层级、内容模块、项目模板和自检方式。

但把 AGENTS.md 真正放进项目后，还要面对一个更难的问题：

它到底改善了 Agent，还是只让 Agent 更认真地执行了更多要求？

这不是文字游戏。

2026 年出现的几项研究给出了看似矛盾的结果：

• 一项研究发现，仓库上下文文件没有普遍提高任务成功率，平均推理成本反而增加超过 20%。
• 另一项研究在 10 个仓库、124 个 PR 上观察到，有 AGENTS.md 时中位运行时间下降 28.64%，输出 Token 下降 16.58%。
• 还有一项研究检查 100 个开源仓库，发现 Lint Leakage、Context Bloat 和 Skill Leakage 等配置异味很常见。

如果只看社交平台上的一句总结，很容易得出两个相反结论：

AGENTS.md 没用，删掉就行。
AGENTS.md 能省很多时间，项目必须有。

这两句都过早。

这篇文章不替你站队，而是把问题改写成一个可操作的工程问题：

哪些信息值得在每次 Agent 运行时持续注入？它们改善了正确性、效率还是边界？为此又支付了多少上下文、执行和维护成本？

下载 agents-md-evidence-lab-0.1.0.zip

先说明一个边界

本文讨论的是仓库级自然语言指导，不是权限系统。AGENTS.md 可以要求 Agent 不要做某件事，但真正的文件、网络、密钥和生产权限仍应由 sandbox、approval、CI、规则与人工审批控制。

一分钟概览

如果只记住七句话，可以先看这里：

1. AGENTS.md 会改变 Agent 行为，但行为变化不等于任务正确率上升。
2. 不同研究测量了成功率、耗时、Token 和配置质量，数字不能直接互相否定。
3. 自动生成的仓库概览最容易复制已有事实，却未必补充任务真正缺失的信息。
4. 最值得保留的是项目特有、代码难以推断、长期有效、可执行且可验证的规则。
5. 能由 Lint、测试、类型系统或权限强制的规则，不要只写成自然语言。
6. 评估时同时记录正确性、耗时、Token、命令数、改动范围与意外行为。
7. 一次成功不是证据；至少重复运行、轮换顺序，并保留 trace 和 diff。

图 1：三项研究观察的是不同结果变量；工程结论不是简单保留或删除文件，而是筛选值得持续注入的规则

图 1：研究结果根据三篇论文整理。百分比只描述各自样本和实验条件，不代表所有 Agent 项目的固定收益。移动端可打开原始 SVG查看。

怎么使用这篇

1. 先理解机制：每条规则都会进入运行

根据 Codex 官方 AGENTS.md 文档，Codex 在开始工作前建立一条指导链：

1. 先读取 Codex home 里的全局指导。
2. 再从项目根目录走到当前工作目录。
3. 每个目录最多读取一个匹配文件。
4. 更靠近当前目录的指导出现在后面，可以覆盖更早的内容。
5. 默认合并上限由 project_doc_max_bytes 控制，当前默认值是 32 KiB。
6. 指导通常每次新运行或新会话加载一次。

这意味着 AGENTS.md 不是“存放在那里，必要时才查”的普通文档。被发现的内容会进入 Agent 的工作上下文。

因此每条规则至少有三类成本。

1.1 上下文成本

模型需要读取和处理它。文件越大，留给任务、代码、工具结果和推理的空间越少。即使上下文窗口足够大，更多文本也不等于更多有效信号。

1.2 遵循成本

研究的一个重要观察是：Agent 通常会遵循上下文文件里的要求。

这听起来是好事，但如果要求是“扫描所有目录”“更新所有相关文档”“每次都跑完整测试”，Agent 也会照做。任务本来只需要改一行，最终可能多读几十个文件、多跑一轮无关验证。

1.3 维护成本

命令、目录和流程会变化。旧规则不会因为代码升级而自动失效；它会继续以“项目真相”的口吻影响后续运行。

所以，一条规则的价值不能只看它是否正确，还要看：

净价值
= 避免的搜索、返工和错误
- 上下文成本
- 额外遵循成本
- 维护与冲突成本

这不是可以精确计算的公式，但它比“写得越详细越好”更接近真实工程。

2. 三项研究到底在测什么

2.1 任务成功率：不保证越有上下文越正确

论文 Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? 同时研究了 SWE-bench 上的 LLM 生成上下文，以及带有开发者提交上下文文件的真实仓库任务。

论文 v2 的摘要结论很直接：

• 提供上下文文件没有普遍改善任务成功率；
• 平均推理成本增加超过 20%；
• Agent 会遵循文件里的指导；
• 常见的仓库概览并没有表现出稳定帮助；
• 非标准、无法从仓库轻易推断的实践仍可能有价值。

这里最重要的不是“超过 20%”这个数字，而是它揭示了一个机制：

上下文文件不只提供答案，也会生成额外工作。

开发者写的文件整体比自动生成的概览更有价值，但研究仍没有证明“有一份开发者文件”相对“没有文件”必然提高所有任务的成功率。

2.2 运行效率：可能减少探索时间和输出

论文 On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents 研究了 10 个仓库和 124 个 GitHub PR，在有无 AGENTS.md 两种条件下运行编码 Agent。

它报告：

• 中位运行时间下降 28.64%；
• 输出 Token 下降 16.58%；
• 任务完成行为保持相近。

这个结果并不自动反驳上一项研究，因为两者问的不是同一个问题。

一份准确的命令和目录地图，完全可能让 Agent 更快找到入口；但它不一定提高复杂 bug 的最终正确率。反过来，更完整的检查要求可能提高探索深度，却增加运行时间。

效率和正确性要一起测。

2.3 配置质量：仓库文件本身也会生病

论文 Configuration Smells in AGENTS.md Files 对 100 个包含 AGENTS.md 或 CLAUDE.md 的热门开源仓库做了分析。

论文列出六类配置异味，摘要中给出了三个最常见的结果：

论文还指出 Context Bloat、Skill Leakage 与 Conflicting Instructions 经常共同出现。

这些比例来自特定开源样本和检测方法，不能解释为“你有 62% 的概率写错”。更有价值的用法是：把它们当作审计词汇。

3. 研究并不矛盾，缺的是结果函数

当有人说“AGENTS.md 有用”，最好追问：

对什么任务？
相对什么基线？
在哪个模型和 Agent 上？
改善的是成功率、耗时、Token、边界还是可维护性？
文件里具体放了什么？
代价是否一起记录？

同一份文件可能同时产生下面几种影响：

所以更合理的结论是：

AGENTS.md 是一个行为干预。它有没有价值，取决于被注入的信息质量，以及你如何定义和测量结果。

这也是 AI Agent 工程与普通 Prompt 技巧的分界：不是凭感觉改一句话，而是明确干预、基线、指标和证据。

4. 一条规则进入 AGENTS.md 前，要过五道闸门

我会用下面五个问题筛选规则：

1. 长期有效吗？ 下周、下个月仍然成立。
2. 项目特有吗？ 不是“写清晰代码”这种通用常识。
3. 难以自动发现吗？ 不能只靠代码、配置和 README 轻易得到。
4. 可以执行吗？ 能转成具体动作，而不是模糊价值观。
5. 可以验证吗？ Agent 和人都能判断是否遵守。

图 2：规则依次经过五道闸门；不通过时应路由到 Prompt、README、全局偏好、Skill、Lint 或 CI

图 2：AGENTS.md 不是所有规则的终点。选择正确载体，比继续扩写文件更重要。移动端可打开原始 SVG查看。

可以直接套用这张判断表：

其中最值得写进文件的，通常不是“这个仓库有哪些目录”，而是那些仓库无法自己解释的例外。

5. 六种最常见的失效方式

前三类直接借用了配置异味研究的术语；后三类是我在项目审计中会额外检查的工程风险。

5.1 Lint Leakage：把可执行约束写成愿望

- Use two-space indentation.
- Sort imports.
- Use double quotes.
- Do not leave trailing spaces.

如果项目已有 Formatter 和 Lint，这些规则进入常驻上下文的收益很低。更好的写法是：

- Run `npm run lint` after JavaScript or TypeScript changes.

Agent 不需要记住所有格式规则，只需要知道由哪个确定性工具验收。

5.2 Context Bloat：把仓库导览写成仓库副本

自动生成文件很容易列出每个目录、依赖、脚本和模块。问题是这些事实往往已经存在于 package.json、README 和代码中，而且会变化。

导航不是完全没用，但应该只保留高价值入口：

- Start with `docs/architecture.md` for request flow.
- Payment-specific rules live in `apps/payments/AGENTS.md`.

这是地图，不是把整座城市塞进地图图例。

5.3 Skill Leakage：把任务手册塞进常驻指导

一套技术文章审稿流程可能包含：

• 资料来源优先级；
• 事实核对表；
• 链接和图片检查脚本；
• 多轮读者审查；
• 发布前清单。

这些内容很有价值，但不是每次修改博客样式都要加载。它更适合 Skill，在任务触发时按需读取。

5.4 Conflicting Instructions：作用域越多，冲突越隐蔽

根目录要求“所有改动必须跑完整测试”，子目录要求“这里只运行单元测试”，全局指导又说“优先快速验证”。Agent 最终要在三个合理要求之间猜优先级。

冲突不一定表现为报错，更常见的是行为漂移：同类任务这次跑全量，下次只跑局部。

5.5 README Duplication：同一个事实维护两份

当安装命令同时出现在 README 和 AGENTS.md，总会有一份先过期。

如果事实对人也有价值，让 README 或 docs 成为事实源；AGENTS.md 只保留入口和 Agent 特有的边界。

5.6 Stale Guidance：正确的旧规则比空白更危险

“使用 npm”“不要修改旧路由”“测试需要 Node.js 18”都可能曾经正确。过期后，它们仍然会被 Agent 当作当前约束。

建议每条高风险规则都能回答两个问题：

它的事实源在哪里？
什么变化发生时应该删除或更新它？

6. 从宽泛概览缩到最小规则，决策信息没有少多少

下面是一份典型的宽泛版本：

# Project Instructions

This repository uses TypeScript and React.
Source files are under src/.
Tests are under tests/.
Use two spaces.
Use semicolons.
Prefer const.
Keep functions small.
Write clean code.
Update documentation when needed.
Add tests for behavior changes.
Run tests before completion.
...

大部分内容要么能从项目发现，要么太模糊，要么应该由工具强制。

经过路由后，可以缩成：

# Repository guidance

- Install and run scripts with `pnpm`; do not replace `pnpm-lock.yaml`.
- Start architecture questions at `docs/system-map.md`.
- Changes under `apps/payments/` must follow its nested `AGENTS.md`.
- Never use production credentials in local tests; use the sandbox profile.
- Run `pnpm test --filter <changed-package>` for focused changes.
- Before a PR, run `pnpm lint` and the affected package tests.
- Done means checks pass and the final response lists changed files, commands, and remaining risk.

这七条不是更“简洁”这么简单。它们分别提供：

• 不能从通用经验推断的包管理约束；
• 最短项目入口；
• 局部作用域；
• 安全边界；
• 两层验证策略；
• 可检查的交付格式。

删掉的是通用常识，留下的是决策信息。

7. 用 15 分钟审计现有 AGENTS.md

不要先重写。先逐条给现有内容打标签：

KEEP      项目特有、长期、难发现、可执行、可验证
DOC       人和 Agent 都需要，移动到 README / docs
ENFORCE   机器可以强制，移动到 Lint / test / CI / permissions
SKILL     任务型长流程，移动到 Skill
PROMPT    本次任务的临时范围，移动到 Prompt
DELETE    模糊、重复、过期或相互冲突

第一步：确认 Codex 实际读到了什么

官方文档给出的验证思路是让 Codex 复述当前指导：

codex --ask-for-approval never "Summarize the current instructions and list the instruction files you used."

如果在子目录工作，再切到相同目录验证。先确认加载链，避免审计了一个根本没有生效的文件。

第二步：给每一行找事实源

第三步：删除后跑一次真实任务

审计不是把文件压到最短，而是看删掉低价值内容后是否仍能稳定交付。

选一个过去经常失败、但风险可控的小任务，记录：

• 是否找对入口；
• 是否执行正确命令；
• 测试是否通过；
• 是否修改了无关文件；
• 总耗时和 Token；
• 最终汇报是否包含必要信息。

如果删除某条规则后连续出现同类失败，再把它加回来。规则应该来自观察到的摩擦，而不是对未来错误的无限想象。

8. 亲手做一次三条件实验

为了避免只复述论文，我准备了一个零第三方依赖的 Node.js 小实验。

它包含同一个 Unicode 用户名 bug，以及三份隔离工作区：

任务、源代码、测试、文档和 Codex 执行配置保持一致。

generated 只是实验条件名。包里的文件是预先固定的“自动生成风格”样本，不会在每轮重新调用模型生成。否则每轮得到不同内容，就同时改变了两个变量。

图 3：三条件实验只改变仓库级 AGENTS.md，并统一记录正确性、耗时、Token、命令数和改动范围

图 3：实验的目标不是证明最小版本必胜，而是让你看到不同上下文如何改变搜索、修改和验证行为。移动端可打开原始 SVG查看。

8.1 准备条件

• Node.js 18 或更高版本；
• 已安装并登录 Codex CLI；
• 允许一次小型 workspace-write 任务；
• 明白实际执行会消耗正常的 Codex 使用额度。

解压实验包后进入目录：

agents-md-evidence-lab/

先记录当前环境：

node --version
codex --version

三种条件必须使用相同的 Codex 配置、默认模型与推理设置。实验过程中不要修改个人配置文件。

先创建第一轮隔离工作区：

node prepare.mjs --round r1

工作区默认放在系统临时目录，而不是当前 Git 仓库里。这样可以避免意外继承当前项目的根级 AGENTS.md。

个人全局 ~/.codex/AGENTS.md 仍可能生效。不要在三种条件之间修改它，并在实验记录里注明是否存在。

8.2 先做 dry run

下面三条命令只打印即将运行的 Codex 参数，不调用模型：

node run.mjs none --round r1
node run.mjs generated --round r1
node run.mjs minimal --round r1

你应该看到：

• 使用 codex exec；
• 启用 --ephemeral，不保留会话 rollout；
• 输出 --json 事件；
• sandbox 是 workspace-write；
• approval 是 never，越过 sandbox 的请求会失败而不是等待交互批准；
• 使用 --skip-git-repo-check 允许临时 fixture 在非 Git 目录运行；
• 三次任务文本相同；
• 工作目录分别指向三个隔离目录。

8.3 执行与计分

确认后再运行：

node run.mjs none --round r1 --execute
node run.mjs generated --round r1 --execute
node run.mjs minimal --round r1 --execute

然后分别评分：

node score.mjs none --round r1
node score.mjs generated --round r1
node score.mjs minimal --round r1

每个工作区会留下：

trace.jsonl   Codex 运行事件
run-meta.json 起止时间、命令和退出状态
score.json    测试、Token、命令数与改动文件

score.mjs 会重新运行 node --test，并把工作区与原始 fixture 做内容哈希比较。

8.4 至少重复三轮

Agent 运行具有非确定性，一轮不够。

node prepare.mjs --round r2
node prepare.mjs --round r3

每轮改变执行顺序，例如：

r1: none → generated → minimal
r2: minimal → none → generated
r3: generated → minimal → none

这样不能消除所有时段、缓存和服务负载影响，但比永远按同一顺序更可信。

三轮都完成评分后，生成汇总表：

node compare.mjs r1 r2 r3

它会打印每个条件的测试通过次数，以及耗时、输入/输出 Token、命令数和改动文件数的均值，同时写出 comparison.json。均值只用来整理这九次观察，不能替代 trace、diff 和人工判断。

9. 怎么读实验结果

不要只比较哪个 Token 最少。

先按下面顺序判断：

9.1 正确性先过门槛

测试是否通过？
公开 API 是否保留？
Unicode 契约是否真正满足？
有没有通过削弱测试来“修复”？

未通过正确性门槛时，省下的 Token 没有工程价值。

9.2 再看行为路径

打开 trace.jsonl 和最终 diff：

是否先读了测试？
是否找到 docs/identity-contract.md？
运行了哪些命令？
有没有修改文档或测试？
是否产生与任务无关的探索？

generated 条件可能更早看到目录地图，也可能因为“更新文档、增加测试、完整检查”等要求扩大工作。哪一种发生，要看 trace，不要靠猜。

9.3 最后看成本

最有用的不是宣布冠军，而是解释因果路径：

最小文件是否把 Agent 直接带到非显式契约？
宽泛文件是否触发了额外但无收益的动作？
无文件条件是否仍能通过测试和仓库搜索找到答案？
三轮结果是否一致，还是方差大于差异？

实验限制

这个实验只有一个小型 Node.js 任务，不能复制论文，也不能证明你的大型仓库会得到同样结果。

它真正训练的是实验方法：

• 只改变一个主要变量；
• 固定权限和任务；
• 保留执行轨迹；
• 同时测质量与成本；
• 重复运行；
• 不把一个样例写成普遍规律。

10. 什么时候根本不需要 AGENTS.md

反过来，下面几类信息通常值得保留：

• 非标准构建、测试和迁移命令；
• 代码无法表达的业务与安全边界；
• 特定目录的局部所有权和验证方式；
• 一再出现、已观察到的 Agent 失败模式；
• “怎样算完成”的可验证交付合同；
• 关键文档的最短入口，而不是全文复制。

11. 从个人文件走向团队资产

团队使用 AGENTS.md 时，最大变化不是文件更长，而是它需要像代码一样被治理。

11.1 每条规则要有理由

规则变更的 PR 应说明：

观察到了什么重复失败？
为什么现有代码、测试或文档不能解决？
规则作用在哪个目录？
怎样验证它改善了行为？
什么时候应该删除？

11.2 规则变化也要看 diff

自然语言指导会影响后续每一次 Agent 运行。修改它的影响面可能比一处业务代码更广。

至少 review：

• 是否和上级、下级文件冲突；
• 是否复制了 README 或 Lint；
• 是否把一次任务写成长期要求；
• 是否扩大了工具和修改权限；
• 是否有真实命令与验收信号。

11.3 用失败样本维护，不用想象维护

OpenAI 的 Harness Engineering 实践强调把仓库作为系统事实源，并给 Agent 一张可导航的地图。这个思路和本文的结论是一致的：

提供短入口、边界和机械反馈；不要试图用一份不断膨胀的说明书预先描述一切。

当 Agent 再次犯同类错误时，先判断应该修：

代码 / 类型 / 测试 / Lint / CI
README / 架构文档
AGENTS.md
Skill
Prompt
权限与审批

只有确定问题来自“每次都缺少同一条项目指导”，才给 AGENTS.md 增加内容。

12. 发布前可收藏的审计清单

内容

[ ] 每条规则长期有效
[ ] 规则是项目特有信息，不是通用常识
[ ] 代码和现有文档无法轻易表达全部含义
[ ] 每条规则能转成明确动作
[ ] 每条规则有可观察的验收信号

载体

[ ] README 重复项已经删除或改成链接
[ ] 格式和静态规则交给 Formatter / Lint
[ ] 正确性规则尽量交给 test / type / CI
[ ] 多步骤任务流程已经迁移到 Skill 或脚本
[ ] 临时要求留在 Prompt
[ ] 安全边界由 sandbox、approval 和权限继续强制

实证

[ ] 已记录无文件或旧版本基线
[ ] 使用相同任务、模型、权限和项目快照
[ ] 同时记录成功、耗时、Token、命令和改动范围
[ ] 保留 trace 与 diff
[ ] 至少重复三轮并轮换顺序
[ ] 没有把一次运行包装成普遍结论

结语：最好的上下文不是最多，而是最有决策价值

AGENTS.md 当然有用。

它可以让 Agent 更早找到真实命令，避开项目陷阱，遵守局部边界，并按团队认可的方式验证交付。

但它也会让 Agent 更认真地探索、测试、更新和汇报。如果文件里塞满重复事实、格式规则、任务流程和旧约束，这种认真会变成成本。

所以我现在不会用行数评价一份 AGENTS.md，而会问：

没有这条规则，Agent 会反复做错什么？
这个错误能否由代码或工具直接阻止？
规则是否提供了仓库里原本缺失的信息？
我怎样知道它真的改善了结果？
为了这点改善，持续支付了什么成本？

当这五个问题都能回答时，AGENTS.md 才从一份“写给 AI 的 README”，变成真正可评估的 Agent 工程资产。

下一篇可以继续往前一步：不再只评估静态指导，而是讨论 Agent Harness 的可观测性应该记录什么，以及怎样用 trace 把“它这次为什么做对或做错”还原出来。

参考资料

官方资料

• OpenAI Codex：Custom instructions with AGENTS.md
• OpenAI Codex CLI reference
• OpenAI：Harness engineering: leveraging Codex in an agent-first world

研究论文

• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
• On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents
• Configuration Smells in AGENTS.md Files: Common Mistakes in Configuring Coding Agents

社区讨论

• Shubham Saboo：关于 AGENTS.md 研究的讨论串