结论先行:AGENTS.md 是给 AI 看的项目说明书,写法应该对标"给新入职工程师的 onboarding 文档"——构建命令、目录结构、项目约定、禁区清单,全部用最短篇幅讲清楚。它有效的原因是零工具成本:纯文本约定,任何 Agent 都会读,不需要专门适配。写坏的常见方式有两种:写成百科全书(太长没人读,包括模型),写成口号集(全是原则没有可执行信息)。
为什么是纯文本约定
Agent 进入项目后的第一个动作通常是找上下文:这是什么项目、怎么构建、怎么测试、有什么规矩。AGENTS.md 就是把这个答案固化在仓库根目录,靠文件名约定被发现。它的价值在于:和代码同仓库、走 code review、随分支演进——项目约定本身也需要版本管理,这点比任何"配置平台"都可靠。
对比一下替代方案就明白它为什么赢:放 wiki,Agent 不会主动去查,内容过时也没人发现;放知识库工具,要给 Agent 配专门的检索工具,多一层维护和多一份 token 开销;放数据库加检索,工程成本更高还引入一致性问题。纯文本放在约定路径上,是所有方案里唯一"零接入成本、随仓库分发、天然版本化"的。约定被模型读到的确定性也最高——主流 harness 都会默认加载它,不需要模型自己想起来去搜。
还有一个常被忽略的属性:AGENTS.md 同时是写给人的。团队里的人类新人、接手的维护者、甚至未来回看仓库的你自己,都会从这份文件受益——写它的过程强迫团队把隐性的口头约定显性化,这个动作本身就是梳理。很多团队写着写着发现,文档质量提升的不只是 Agent 的表现,还有新人的上手速度。一份文件服务两类读者,这在工程实践里是少有的高性价比投资。
该写什么:可执行的命令优先
按优先级排:第一是构建/测试/lint 命令(模型最常犯的错就是用错命令);第二是目录结构和分层规则;第三是项目特有约定(命名、异常处理、日志口径);第四是禁区。一个可用的骨架:
# 项目约定
## 构建与测试
- 构建:./gradlew clean build -x test
- 跑单个测试:./gradlew test --tests "com.foo.BarTest"
- 改动完成后必须跑相关测试,红着不许报完成
## 目录结构
- controller/api → service → dao,mapper XML 在 src/main/resources/mapper/
- 跨服务调用走 msdao(Feign),fallback 放 service/fallback/
## 约定
- 新增字段必须有注释,对外的 DTO 字段注释即接口文档
- 禁止在 controller 层写业务逻辑
## 禁区
- 不改 pom/gradle 依赖版本,需要时在 PR 里说明
- 不动 test-env 下的配置文件
关键特征:每条都是模型可以直接执行的指令或可以验证的边界。“代码要优雅"这种话没有任何约束力,“禁止在 controller 层写业务逻辑"模型真的会遵守。逐条自检的办法很简单:这条写完,模型能据此做出一个和之前不一样的具体动作吗?能,就留;不能,就删。
写法上还有两条口径纪律。一是用祈使句写,不用描述句写:写给模型的是指令,“跑测试用这条命令"比"本项目使用这条命令测试"的遵从度更高,模型会把描述当背景信息,把指令当行动依据。二是避免二义性:一个约定如果有两种理解,模型两种都会试出来,与其让它在边界上摇摆,不如把边界一次写死——“改动超过三个文件时先列改动清单再动手"就比"大改动要先规划"可执行得多。
分层:全局、项目、子目录
和 .gitignore 一样,AGENTS.md 支持叠加:全局文件放个人通用偏好(比如"用中文回复"“不主动 commit”),项目根放项目约定,子目录放局部规则。就近覆盖远处。别把所有内容塞进根文件——根文件每轮都会占上下文,子目录的说明只在模型进入那个目录工作时才该被看到:
~/project/
├── AGENTS.md # 根:构建命令、分层规则、全局禁区(每轮可见)
├── src/main/java/com/foo/
│ ├── controller/AGENTS.md # 只写 controller 特有规则(进该目录才加载)
│ ├── service/AGENTS.md # 事务边界、fallback 约定
│ └── dao/AGENTS.md # MyBatis 注意事项、mapper 手写规范
└── docs/AGENTS.md # 文档目录的写作口径
划分的原则和缓存分层一样:访问频率越高(每轮都要用的构建命令)放越外层,访问频率越低(只在特定目录工作才需要)放越内层。全局文件控制个人偏好,团队共享的部分进仓库——个人文件不进 git,团队约定必须进 git,两者的边界在 review 流程里天然分清。
反模式清单
- 写成长篇历史:为什么当年选了 Eureka 不选 Nacos,写三段——模型不需要产品设计史,需要当前结论。历史决策压缩成一行结论放进约定。
- 复制公开知识:怎么写 Java 异常处理这类通识,模型比文档懂得多,写了纯浪费上下文预算。只写"这个项目里和大家不一样的地方”。
- 和现实脱节:文档说分层 A,代码实际是分层 B,模型会混乱甚至两头讨好。约定改了就同步改 AGENTS.md,把它当代码的一部分对待。
- 禁区不写原因:加上一句为什么(“mapper XML 由 DBA 统一管理”),模型在遇到边界情况时才能做出正确判断,而不是死板撞墙。
对比一组条目写法,感受什么叫"可执行”:
<!-- 错误写法:口号,无约束力 -->
- 代码要简洁优雅,注重质量
- 注意安全问题
- 性能要足够好
<!-- 正确写法:可执行、可验证 -->
- 方法长度超过 80 行必须拆分,拆分维度按业务动作而非技术分层
- 禁止在日志里打印用户手机号全文,脱敏规则见 SecurityUtil.mask()
- 列表查询接口必须分页,单页上限 200 条
内容优先级与篇幅预算
| 优先级 | 内容 | 理由 | 篇幅占比(示意) |
|---|---|---|---|
| 1 | 构建/测试/lint 命令 | 模型最常用,最易错 | 20% |
| 2 | 目录结构与分层规则 | 决定改动落点是否正确 | 25% |
| 3 | 项目特有约定 | 通用知识模型都会,特有约定才稀缺 | 35% |
| 4 | 禁区清单及原因 | 防事故,原因保证边界判断 | 20% |
| 不该有 | 历史决策长文、公开通识、口号 | 浪费上下文,稀释关键信息 | 0% |
一个经验值:多数项目 50~150 行足够。写完自己读一遍——如果你能想象一个新工程师靠它第一周不踩坑,那它就是合格的。
维护机制上建议绑定两个既有流程,而不是发明新流程。一是 code review:约定变更和代码变更走同一条 PR 通道,评审人看 diff 时自然看得到"这次的约定改动是什么”,过时的约定有人在改代码时顺手就修了。二是复盘:每次 Agent 犯了"怪模型"的错,先查一遍是不是说明书没写或写错了——如果是,修复动作不是改 prompt,是改 AGENTS.md。这两个挂点让文档始终跟着项目走,不需要专门的"文档维护日”。
实战场景
一个多模块 Java 仓库接入 Agent 的过程很说明问题:最初根目录只有一份 300 行的"大而全"说明书,把所有子系统的口径都塞在一起,结果模型做 A 模块任务时被 B 模块的规则干扰,还因为文件太长,后半段的禁区几乎不被遵守。按分层重写后,根文件缩到 80 行(构建命令、全局分层、四个禁区),六个子目录各自一份 10~20 行的局部说明。改完之后两个变化很明显:模型不再把 B 模块的命名风格带进 A 模块;“改完跑哪个测试"从每次要人提醒变成了默认动作(以上为使用观察,非量化评测)。另一个连带收益是人的:新入职工程师说这份文件比原来的 onboarding 文档好用——因为写它时被迫把"约定"和"理由"分开了,而人恰好也需要这两样。
检查清单
- 第一部分就是可直接复制执行的构建/测试/lint 命令
- 每条约定都能让模型做出与之前不同的具体动作,口号全部删除
- 分层加载:根文件只放每轮都需要的全局内容,局部规则下沉到子目录
- 禁区条目附带原因,让模型在边界情况下能正确判断
- 全文 50~150 行,没有历史长文和公开通识
- 约定与代码同步演进,AGENTS.md 的修改走 code review
- 写完用新工程师视角通读一遍,确认第一周不踩坑