二、AGENTS.md 核心结构：写清楚什么，执行就不跑偏
结构
一份长期可用的 AGENTS.md，我建议至少有这六块：
- 项目结构
- 构建和测试命令
- 代码和改动规则
- 风险边界
- 输出格式
- 例外情况
如果你仓库复杂一些，再往上加模块级补充。
为什么先讲结构
因为很多团队不是不会写规则，而是规则写得东一条西一条，最后谁都找不到重点。
你今天补一条“必须跑测试”，明天补一条“不要动 CI”，后天又补一条“接口变更要写说明”。
这些话单看都对，但没有结构，最后阅读成本会越来越高。
AI 也是一样。它不是不能看长文档，而是结构越乱，执行越容易抓错重点。
第一块：项目结构
这一块最容易写得太浅。
很多人会这样写：
- src
- tests
- scripts
这几乎没信息量。
更好的写法是把目录职责写出来：
## 目录结构
- src/: 生产代码统一放这里
- tests/: 测试目录按 src 的结构去对应
- scripts/: 开发脚本放这里，脚本要能重复执行
- docs/: 设计说明和决策记录放这里
这样 AI 至少知道：
- 生产代码去哪改。
- 测试应该往哪补。
- 脚本目录不是随便扔实验代码的地方。
第二块：构建和测试命令
这一块的目标不是“列全命令”，而是“给唯一入口”。
比如你们团队平时有人用 pytest，有人用 make test，还有人自己拼一长串参数。
如果你不统一，AI 每次都可能选不一样的命令。
建议写成这样：
## 常用命令
- setup: make setup
- lint: make lint
- test: make test
好处很直接：
- 人和 AI 都有统一入口。
- 后面命令真变了，只改一处。
- 最终汇报里也更容易统一口径。
第三块：代码和改动规则
这是 AGENTS.md 最容易失控的一块。
原因很简单，团队脑子里“想管的事”太多了。
我的建议是只保留两类：
- 高频返工点
- 高风险改动点
比如下面这些就很常见：
## 改动规则
- 修 bug 必须补回归测试
- 改公开接口时要写清兼容性说明
- 能复用现成组件就不要另起一套
- 改动范围只围着这次任务走
这类规则有两个特点：
- 能直接指导当前任务怎么做。
- Review 时能拿来判断，不是纯主观表态。
第四块：风险边界
这一块非常值钱，但很多团队写得最少。
其实很多事故都出在这里。
比如这些话，如果不提前写清楚，AI 很容易踩雷：
- 不要动权限模块。
- 不要改 CI。
- 不要跑会覆盖历史的 git 命令。
- 没确认前不要改公共数据库迁移。
你可以这样写：
## 风险边界
- 不要执行会覆盖历史的 git 命令
- 动权限、计费、CI、基础设施文件之前先确认
- 不要直接改环境变量文件和密钥文件
这不是“保守”，这是把高风险动作从默认允许改成默认确认。
第五块：输出格式
这一块经常被忽略，但它对协作体验影响很大。
因为很多时候，问题不在代码本身，而在结果汇报太散。
有的人写一大段解释，有的人只说“已完成”，还有的人只贴命令输出。
久了以后，review 和交接都会累。
我很建议固定成三段：
## 输出格式
- 先说改了什么
- 再说怎么验证的
- 最后说剩余风险
如果团队主要说中文，也可以直接写中文版本：
## 输出格式
- 先说改了什么
- 再说怎么验证的
- 最后说剩余风险
第六块：例外情况
这块不是必须每个仓库都有，但一旦项目比较忙，最好加。
因为现实里总会有“来不及按标准流程”的时候。
如果不提前定义例外，最后就会变成谁着急谁说了算。
可以写得很短：
## 例外情况
- 紧急修复可以先不补文档
- 但必须带上问题单或故障链接
- 后续清理动作要留下记录
这就够了。重点不是把例外写复杂，而是让例外也有边界。
一个比较顺手的完整例子
# AGENTS.md## 目录结构
- src/: 正式代码目录
- tests/: 测试目录，结构跟着 src 走
- scripts/: 自动化脚本目录## 常用命令
- setup: make setup
- lint: make lint
- test: make test## 改动规则
- 修 bug 必须补回归测试
- 改动范围只围绕当前需求
- 有现成抽象就先复用，不要顺手新建一层## 风险边界
- 不要执行会覆盖历史的 git 命令
- 动权限、CI、基础设施、计费相关内容前先确认## 输出格式
- 改了什么
- 怎么验证的
- 剩余风险## 例外情况
- 紧急修复可以先不补文档，但必须带上问题链接
这份已经足够支撑很多仓库起步了。
什么时候该拆成多层规则
如果你们仓库已经有这些特点，就不要只靠根目录一份文件了：
- 前后端在同一个 monorepo 里。
- 不同子目录差异很大。
- 同一个仓库里既有产品代码，也有基础设施代码。
这时候建议用分层写法：
- 根目录放全局规则。
- 子目录放局部规则。
比如：
repo/AGENTS.mdapps/web/AGENTS.mdservices/api/AGENTS.md
根目录管通用边界，比如 Git、安全、输出格式。
子目录管本模块自己的规则，比如前端组件复用、后端迁移约束。
哪些内容不建议写进 AGENTS.md
这里顺手提醒几类常见废话。
1. 太抽象的话
例如：
请保持优雅、专业、现代化。
这类词没有明确执行边界，很容易变成摆设。
2. 明显过期的规则
比如命令早改了，文件还没更新。这个伤害很大，因为它会直接降低团队对文档的信任。
3. 纯背景介绍
产品背景、公司愿景、商业目标，不是不能写，但那更适合 README 或 docs。
AGENTS.md 要优先让执行者知道“现在该怎么做”。
一个很实用的维护原则
我很建议你每次 review 时问自己一句：
“今天这条 review 评论，下次还会不会再说一遍？”
如果答案是“会”，那这事就值得进 AGENTS.md。
这比闭门造车想规则有效得多。
小结
好的结构不是为了好看，而是为了让规则长期能用、能维护、能快速找到。
你只要先把这六块搭起来，AGENTS.md 就已经从“随手记一页”变成“能协作的工程文件”了。