一、认识 AGENTS.md：为什么它是协作底座

一、认识 AGENTS.md：为什么它是协作底座

先把结论说清楚

很多人第一次看到 AGENTS.md，会以为它只是另一份 README，或者一份写给 AI 的提示词。

这两个理解都不算准。

AGENTS.md 更像是一份“项目内协作说明书”。它不是介绍项目是什么，而是告诉执行者：

1. 这个仓库怎么做事。
2. 哪些规则必须守。
3. 什么叫做“这次任务做完了”。

只不过这个执行者既包括人，也包括 AI。

为什么团队一用 AI 就容易乱

原因通常不是模型不行，而是项目自己的规则没有落成文字。

现实里常见的情况是这样的：

1. 老成员心里知道什么地方不能碰，但没人写出来。
2. 团队默认知道哪些命令要跑，但没人固定下来。
3. 评审时总说“这个不符合我们习惯”，可到底什么叫“符合”，没有明文。

人和人之间还可以靠默契补一补，AI 不行。你不给它明确边界，它就只能根据概率猜。

一靠猜，结果就不稳定。

今天改得不错，明天同样的活又偏了。你会以为是模型抽风，其实更多时候是规则没说清。

README 和 AGENTS.md 到底有什么区别

这个问题必须分清，不然后面文件会越写越乱。

README 主要回答这些问题：

1. 这是什么项目。
2. 怎么启动。
3. 主要功能是什么。
4. 外部使用者应该知道什么。

AGENTS.md 主要回答这些问题：

1. 改代码之前先看哪里。
2. 哪些目录能改，哪些目录不要碰。
3. 改完以后至少跑哪些检查。
4. 提交结果时应该怎么汇报。
5. 遇到危险操作时应该停下来确认什么。

一句话讲，README 是项目介绍，AGENTS.md 是项目内作业规则。

一个没有 AGENTS.md 的现场会发生什么

拿一个很普通的任务举例：给后台系统补一个导出按钮。

没有 AGENTS.md 的时候，常见过程是这样的：

1. 有人让 AI 先改前端按钮。
2. AI 顺手把接口字段名也改了。
3. 另一个同事发现后端联不通，又自己修了一版。
4. Review 的时候又有人说，我们项目里按钮不是这么写的。
5. 最后还得再补一轮测试。

这不是谁能力差，而是所有人都在补规则空白。

如果前面就有一份明确的 AGENTS.md，至少会写清楚：

1. UI 组件必须复用现有组件。
2. 接口字段变更需要同步更新契约说明。
3. 改动完成后必须跑某几个测试。
4. 最终汇报格式要包含风险和验证结果。

这样一来，很多返工在第一轮就能拦住。

AGENTS.md 最核心的价值，不是“指导 AI”，而是“固定团队共识”

这是我最想强调的一句。

如果一份 AGENTS.md 只有 AI 会看，而团队自己都不按它做，那它很快就会废掉。

真正有效的 AGENTS.md，一定先服务团队自己。

也就是说，它应该是：

1. 新人看得懂的。
2. 老人愿意用的。
3. AI 按它执行时不会明显跑偏的。

这三条里，前两条比第三条还重要。

写 AGENTS.md 时最容易犯的三个错

1. 写成口号

比如：

请保持高质量代码。

这句话本身没错，但它几乎没有执行价值。

什么叫高质量？是必须补测试，还是必须过类型检查，还是不允许改公共接口？

没写清楚，就等于没写。

2. 写成百科

有些团队一上来想一步到位，恨不得把所有规范都塞进去。

结果就是文档长得吓人，但没人真的会看第二遍。

一份刚开始落地的 AGENTS.md，最重要的是“够用”，不是“包打天下”。

3. 写完就不管

这也很常见。

第一周大家很认真，后面项目变了、目录变了、命令变了、规则还是旧的。

一旦文档和现实对不上，团队对它的信任就会掉得很快。

所以 AGENTS.md 必须是活的。

什么样的 AGENTS.md 算一个合格起点

我建议最开始只保留四类东西：

1. 目录职责
2. 必跑命令
3. 禁止事项
4. 输出格式

比如下面这样就够用了：

# AGENTS.md

## 目录说明
- src/: 业务代码放这里
- tests/: 测试目录和 src 对应
- scripts/: 日常开发脚本统一放这里

## 必跑命令
- make lint
- make test

## 不要做的事
- 没写兼容性说明，不要改公开接口
- 不要执行会覆盖历史的 git 命令
- 没明确要求，不要去改 CI 文件

## 最终汇报
- 先说做了什么
- 再说验证结果
- 最后说风险和下一步

这份不长，但已经能挡掉一批低级返工。

什么项目最该尽快补 AGENTS.md

如果你们符合下面任意两条，就应该尽快写：

1. 同类 review 评论一遍又一遍出现。
2. AI 每次输出风格都不一致。
3. 新人经常不知道该从哪个命令开始。
4. 仓库里目录很多，职责分界不明显。
5. 团队已经开始用 AI 改代码，但质量忽高忽低。

这不是“以后可以做”的优化项，而是很快会影响效率的基础设施。

AGENTS.md 最适合怎么维护

我的建议很简单：

1. 别闭门写大而全版本。
2. 先从最近三次返工里找共性。
3. 每次只补一两条最值钱的规则。

一个很实用的办法是：

只要 review 里同一句话出现了三次，就考虑把它写进 AGENTS.md。

这样写出来的规则通常最接地气，也最不容易变成摆设。

一个更像实战的例子

假设你们团队最近总遇到这几类问题：

1. 修 bug 不补回归测试。
2. 改接口不写兼容性说明。
3. 最终汇报不说验证结果。

那 AGENTS.md 就可以直接补成这样：

## 质量门槛
- 修 bug 必须补回归测试
- 动接口时要把兼容性说明写出来

## 最终输出
- 先说改了什么
- 再说跑了哪些检查
- 最后说还剩什么风险

这就比“请保持高质量”有效得多。

一开始别追求完美

很多团队卡在第一步，是因为总觉得要写一份“像公司制度一样完整”的文档。

其实不用。

你先把最常出事的地方写清楚，它就已经开始产生价值了。

第一版只要能做到这三件事，就已经不错：

1. 让 AI 少犯明显错误。
2. 让 review 少说重复的话。
3. 让任务结束时的汇报更统一。

后面再慢慢加。

小结

AGENTS.md 不是为了把流程搞复杂，而是为了让协作少靠猜。

如果你把它理解成“把团队经验写成明确规则”，后面的很多写法都会顺起来。