如果说 CLAUDE.md 是记忆,那 AGENTS.md 就是行动手册。当 AI 编程助手(AI Coding Agent)被投入到某个项目时,这份文件会告诉它:"在这里就该这么干活"。而这份已经被超过 6 万个开源项目采用的文件,如果你还没写过 — 现在就是开始的好时机。
这是什么?
AGENTS.md 是放在项目根目录的一份 markdown 文件。你可以把它理解为写给 AI 编程助手的 README。人类通过看 README.md 来理解项目,而 AI Agent 则通过 AGENTS.md 来搞清楚"在这个项目里该怎么工作"。
它最早由 OpenAI Codex 团队在 2025 年 8 月提出,现在已经成为由 Linux Foundation 旗下 Agentic AI Foundation 维护的开放标准。关键在于一份文件就能覆盖所有 AI 工具。以前 .cursorrules、.builderrules 这些工具专属配置文件把项目根目录搞得乱七八糟,有了 AGENTS.md 就清爽了。
它和 CLAUDE.md 有什么区别?
CLAUDE.md 是 Anthropic 的 Claude 产品专用的。AGENTS.md 则是跨工具的通用标准。想两份都用?在 CLAUDE.md 里加一句 Strictly follow the rules in./AGENTS.md,或者直接用符号链接连起来就行。
它支持的工具清单已经非常庞大。GitHub Copilot、Cursor、Windsurf、Codex、VS Code、Gemini CLI、Devin、Junie(JetBrains)、Amp、Aider、Zed、goose、Roo Code…… 市面上主流的 AI 编程工具几乎全部覆盖。
有什么不同?
没有 AGENTS.md 的时候,AI Agent 每次都得当一回探险家。它要探索项目结构、猜测构建命令、琢磨代码风格,白白浪费时间和 token。而且大概率还会猜错。
Builder.io 的 Steve Sewell 亲自做过一个实验,结果挺有说服力。他在没有 AGENTS.md 的情况下让 Agent 把 Figma 设计稿转成代码 — Agent 引用了错误的 MUI 版本导致样式崩了、用 useState 替代了项目内部的状态管理库(mobx)、还漏掉了暗色模式的 token。加上 AGENTS.md 之后呢?同样的提示词下,UI 准确度、token 消耗、代码风格都有了明显改善。
| 没有 AGENTS.md | 有 AGENTS.md | |
|---|---|---|
| 理解项目 | 每次会话都要重新探索结构 | 直接引用关键文件位置 |
| 构建/测试 | 跑完整构建(耗时数分钟) | 文件级命令,几秒钟完成验证 |
| 代码风格 | 版本引用错误、库选择失误 | 一次就用对版本和模式 |
| 安全性 | 擅自安装包、删文件 | 允许/禁止的行为边界清晰 |
| 一致性 | 不同 Agent 结果不同 | 任何工具都遵循同一套规则 |
GitHub 的 Matt Nigh 分析了超过 2,500 份 AGENTS.md 文件,总结出成功模式。结论很明确 — 好用的 AGENTS.md 都包含 6 个必备部分:运行命令、测试、项目结构、代码风格、Git 工作流,以及边界(Boundaries)。
反过来,失败案例也有共同点。像"You are a helpful coding assistant"这种含糊的指示、把技术栈一股脑全列出来的冗长描述、只有抽象说明而没有具体命令的内容。Ben Tossell 也分享了一组有意思的数据 — 有研究显示,把技术栈、核心文件、架构都写得很详细的 AGENTS.md,反而会拖慢性能、把成本抬高 20%。因为这些东西 Agent 其实自己就能搞清楚。
"AGENTS.md should be pretty empty. It should be your preferences and nudges to correct agent behaviour."
— Ben Tossell,Ben's Bites
上手指南:好 AGENTS.md 怎么写
- 先从 Do/Don't 清单开始
这是最有效的起点。让 AI Agent 干活,每出现一次你不满意的地方,就加一行规则。比如"使用 MUI v3 兼容代码"、"不要硬编码颜色值"之类的。关键是用具体的指令代替抽象描述。 - 加入文件级命令
与其跑整个构建,不如提供只验证单个文件的快速命令,让 Agent 的反馈循环从几分钟压缩到几秒钟。比如npm run tsc --noEmit path/to/file.tsx这样。命令又快又便宜,你就可以放心告诉它"每次都跑一遍"。 - 用三层结构定义边界(Boundaries)
这是 GitHub 分析中最有效的模式。分成允许(Always do)、确认后执行(Ask first)、绝对禁止(Never do)三层。其中出现频率最高的约束是"绝不要提交 secret"。 - 指向优秀示例文件
2,500 份文件分析的结论是:一个真实的代码示例胜过三段文字说明。"表单请参考app/components/DashForm.tsx"、"不要沿用遗留文件Admin.tsx的 class 组件写法" — 就这样把好文件和坏文件直接点出来。 - 发现反复出错就加一行
AGENTS.md 不是一次性的成品,而是一份活文档。Agent 犯同样的错误第二次时,再把规则加进去就行。不要一上来就想着写得完美。实战经验告诉我们:迭代比前期规划更有效。
常见错误:写太多
把技术栈、架构、文件清单全写进去反而适得其反。AI Agent 可以通过探索项目自己搞清楚这些。你只需要写它可能会搞错的部分 — 偏好的库、代码约定、绝对不能动的区域这类东西。
如果你在用 monorepo,还有一条建议。可以在每个子目录里嵌套 AGENTS.md。Agent 会优先匹配距离当前工作文件最近的那份 AGENTS.md。OpenAI Codex 的仓库里就有 88 份 AGENTS.md。根目录放通用规则,子包里放该包专属的规则,就这么简单。
