AGENTS.md 上下文文件

AGENTS.md 上下文文件

AGENTS.md 是面向 coding agents 的仓库级说明文件约定：把 setup commands、测试命令、code style、项目约束、workflow expectations 放在 agent 可以稳定发现的位置。

它的关键价值不是“再加一个 prompt 文件”，而是把 repo context 变成可版本化的基础设施。上下文文件让隐性规则可检查、可共享，也能跨 agent 复用；这和 Context-Engineering 的核心思想一致：上下文不是临时 prompt，而是长期工程资产。

应该写什么

• 真实可用的 setup 和 test commands。
• 会影响修改方式的 code style 与架构约束。
• verification gates，以及明确的 “do not” 规则。
• 指向更深文档的链接，而不是把所有内容塞进一个文件。
• 测试失败、服务不可用、缺少 credentials 时的 recovery rules。

证据提醒

论文 Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? 问了一个重要问题：这类仓库级 context file 是否真的提升 coding agent 的任务完成率？摘要显示，它评估了 SWE-bench 风格任务以及已有开发者提交 context files 的真实仓库。对 Agent-Benchmarks 来说，结论是：context files 需要被 benchmark 和维护，不能把它当成自动生效的 prompt 魔法。

设计原则

好的 AGENTS.md 应该是 thin routing layer，而不是 wiki、tests 或 specs 的替代品。它应该告诉 agent 去哪里看、通过什么 gates。大型或可复用流程仍然应该放在 skills、specs 或链接文档里。