AI 编程代理流行后，许多团队开始在仓库里自动生成 AGENTS.md，似乎只要有了这份说明，代理就能更聪明地工作。但自动生成的仓库说明往往并不提升质量，反而可能让代理更慢、更贵。
真正有价值的不是把代码目录复述一遍，而是记录代理无法自行发现的关键经验。
自动说明很容易变成噪声
一个代理进入仓库后，本来就能扫描目录、读取配置、查看测试脚本和依赖文件。如果 AGENTS.md 只是重复这些信息，就会占用上下文窗口，增加成本，还可能让代理过度相信过时说明。
代码已经变化，说明没有同步，代理就会被带偏。更糟糕的是，单一根目录说明无法覆盖复杂仓库。
大型项目通常有多个模块、不同测试方式、历史遗留约束和局部约定。把所有内容塞进一个文件，会让前端、后端、数据脚本和部署规则混在一起。
代理执行具体任务时，得到的上下文既多又杂，反而不利于判断。
好说明应该只写不可发现信息
AGENTS.md 的价值在于补足隐藏知识。比如某个测试必须先启动本地服务，某个目录不能直接改生成文件，某个接口看似无用但被外部客户依赖，某个脚本在 Windows 下有路径限制。
这类信息无法通过简单扫描稳定发现，却会决定任务成败。理想状态下，说明文件应分层存在。
根目录只写全局原则，模块目录写本模块的构建、测试、边界和禁区。这样代理在处理局部任务时，只读取相关上下文，不被无关信息干扰。
说明还应定期维护，把已经被代码、脚本或配置表达清楚的内容删除。
配置不是治理，维护才是治理
许多团队把生成 AGENTS.md 当成一次性设置，实际上它更像代码库的风险清单。文件里每一条说明都在提醒团队：这里存在尚未被自动化、类型系统、测试或清晰结构解决的问题。
长期看，最好的做法不是让说明越来越厚，而是通过工程改进让说明变薄。AI 编程代理需要上下文，但上下文不是越多越好。
有效上下文应当准确、局部、可执行、可维护。自动生成文件带来的安全感很廉价，真正的工程质量来自人类对系统边界、风险和约束的持续整理。
别迷信 AGENTS 文件，关键是让代理看到该看的信息，并让团队真正修掉不该长期依赖文字提醒的问题。
让说明文件变少才是进步
一个健康仓库不应依赖大段说明维持秩序。能被测试固定的规则，就写进测试；能被脚本保证的流程，就写进脚本；能被类型和接口表达的约束，就放进代码。
AGENTS.md 应只保留少数关键提醒。它越精短、越具体、越靠近相关目录，越能帮助代理完成任务。
把所有经验堆成文档，只会制造新的维护负担。
延伸判断
团队还要警惕说明文件带来的虚假治理感。文档写得再长，也不能替代自动化检查和清晰架构。
代理真正需要的是少量高价值约束，而不是把仓库常识重新抄一遍。能被机器验证的规则，就不该长期只靠文字提醒。
从这个角度看，最好的说明不是越写越多，而是持续删除无效信息。每次减少一条无用提醒，都代表仓库治理更成熟一步。
研究结论并不简单
相关研究给出的结论并非单向否定。Lulla 团队在 124 个真实 GitHub 拉取请求上做配对实验，加入由人维护的 AGENTS.md 后，中位运行时间下降 28.64%，输出 token 消耗下降 16.58%。
这说明高质量、有人维护、包含隐性约束的说明文件确实能帮代理少走弯路。ETH Zurich 团队的最新版研究显示，LLM 自动生成的上下文文件并没有显著提高任务成功率。
在 SWE-bench 和 CTXbench 上，平均成功率分别下降约 0.5% 和 2%，与此同时推理成本平均增加约 20% 和 23%。
开发者提供的上下文文件平均提高约 2.4% 成功率，但相较完全不用上下文文件，这一提升也没有达到统计显著；它们的成本最高增加约 19%。真正比较明确的结果，是开发者维护的文件明显优于机器自动生成版本。
热门跟贴