AGENTS.md 团队落地复盘:被 Codex 无视的规范文件如何救活 8 人后端组
老王是一个 8 人后端组的技术负责人。他照着网上的模板,把公司 Java 开发规范整理成一份 200 行的 AGENTS.md 提交进仓库,心想这下团队用 Codex 总算有章可循了。一周后他拉了个新人问:“Codex 现在按咱规范写代码了吧?”新人一脸懵:“啥 AGENTS.md?Codex 该咋写还咋写啊。”——这不是老王一个人的遭遇,而是 90% 团队落地 AGENTS.md 的真实写照:写了一份文件,不等于它生效了。 这篇文章,就是复盘一个团队是怎么从“形同虚设”一步步走到“全员提效”的。
一、模板照搬为何必然失败
先看老王团队踩的第一个坑,也是绝大多数团队的第一反应——从网上找一份“最佳实践模板”粘贴进项目根目录。
老王那份 AGENTS.md 长这样(节选):
# 项目开发规范
我们团队高度重视代码质量,遵循阿里巴巴 Java 开发手册。请大家
在使用 Codex 时,务必保证:
- 编写干净、可维护的代码
- 充分重视单元测试
- 注意数据库安全,避免 SQL 注入
- 优雅地处理异常
- 性能上尽可能优化
结果呢?Codex 该不写测试还是不写测试,该用 SELECT * 还是用 SELECT *。团队成员试了两周,得出了一个结论:“AGENTS.md 这东西,没用。”
失败的真正原因
GitHub 分析过 2500 个包含 AGENTS.md 的仓库,得出一个扎心的结论:大多数 Agent 指令文件失败,不是因为技术限制,而是因为太“模糊”。
老王的文件犯了 AGENTS.md 的四个典型错误:
| 反模式 | 老王文件里的原文 | 为什么无效 |
|---|---|---|
| 散文段落 | “我们高度重视代码质量” | 没有可执行指令,只是模糊偏好 |
| 模糊指令 | “充分重视单元测试” | “充分”没有定义,没法验证 |
| 模糊指令 | “尽可能优化性能” | “尽可能”不是触发条件 |
| 无强制执行 | “遵循阿里手册” | 没有 lint 命令,Agent 无法自检合规 |
记住这条铁律(上一篇文章讲过,这里再强调一次,因为它是团队落地的命门):没有验证命令的指令是“建议”,不是“规则”。 Agent 读到“重视测试”这种话,会把它标记成一个模糊偏好,然后继续按自己的来。
关键认知转变:AGENTS.md 是给机器执行的操作策略,不是给人看的文档。人和机器理解“规范”的方式完全不同——人靠领悟,机器靠命令。
二、诊断:怎么证明你的 AGENTS.md 没生效
老王团队进入第二阶段前,先做了一件特别重要的事——验证 AGENTS.md 到底有没有被读进去。
很多人写完 AGENTS.md 就默认它生效了,其实根本没有。验证的方法很简单,叫“背诵测试”:
# 让 Codex 复述它当前收到的指令
codex --ask-for-approval never "Summarize your current instructions"
# 问它具体的完成标准
codex --ask-for-approval never "What is your definition of done?"
老王让 Codex 背诵项目的构建命令,结果 Codex 支支吾吾说不出来。结论:文件要么没被读取,要么内容太长被挤出上下文窗口了。
团队级的诊断清单
老王把这个测试固化成团队 checklist,每次更新 AGENTS.md 后必跑:
- • 让 Codex 背诵构建命令,能逐字复述
- • 让 Codex 说出“完成定义”,能答出具体退出码
- • 文件总长度 ≤ 150 行(Codex 默认上限 32 KiB,但太长会被截断)
- • 每条规则都附带可执行的验证命令
Codex 背不出来的规则,等于没写。 这是团队落地最实用的一句话。
三、重构:按“命令优先 + 完成定义”重写
诊断清楚了,老王团队开始动刀。重构的核心是把每一条“模糊建议”改写成“可验证命令”。
Before / After 对比
测试相关:
❌ Before:充分重视单元测试
✅ After:
测试命令:mvn test
完成定义:mvn test 退出码为 0 且无失败
代码规范相关:
❌ Before:遵循阿里巴巴 Java 开发手册
✅ After:
Lint 命令:mvn checkstyle:check
完成定义:mvn checkstyle:check 退出码为 0
数据库安全相关:
❌ Before:注意数据库安全,避免 SQL 注入
✅ After:
禁止:拼接 SQL 字符串,必须使用 MyBatis-Plus 的 QueryWrapper 或参数化查询
验证:新写的 Mapper 方法必须能在 src/test 下找到对应的单元测试
重构后的 AGENTS.md(团队版)
下面是老王团队重构后的完整版本,他们提交进了仓库根目录,作为全组共享标准:
# 订单服务 AI 编程指南
## 技术栈
- Java 17 + Spring Boot 3.x + MyBatis-Plus
- MySQL 8 + Redis + Maven
## 构建和测试命令
- 编译:mvn clean compile
- 打包:mvn clean package -DskipTests=true
- 测试:mvn test
- 代码检查:mvn checkstyle:check
- 完整验证:mvn clean compile && mvn test && mvn checkstyle:check
## 完成定义(Definition of Done)
一个任务完成,当且仅当以下全部通过:
1. mvn clean compile 退出码为 0
2. 涉及改动的模块 mvn test 全部通过
3. mvn checkstyle:check 无违规
4. 改动文件已提交,信息遵循 type(scope): description 格式
## 写代码时
- 实体类使用 lombok 简化(@Data @Builder)
- 表名遵循 _config/_info/_log 后缀规范(阿里巴巴 Java 开发手册)
- 所有表必须包含 id、created_at、updated_at 三个标准字段
- 查询禁止拼接 SQL,必须用 QueryWrapper 或参数化
## 遇到阻碍时
- 编译连续失败 3 次:停下来,附完整报错再报告
- 依赖缺失:先查 pom.xml,再问我
- 绝对不要:删其他模块代码消错、跳过 checkstyle、强制 push
注意几个关键变化:
- 开头就是命令,不是公司价值观
- “完成”被定义成具体的退出码,挡住了 Codex“没验证就报告完成”
- 加了“遇到阻碍时”的升级规则和 Never 列表,防止 Codex 卡住时瞎搞
这一版上线后,团队第一次感受到“Codex 真的按规矩干活了”。
来源:AGENTS.md 模式:哪些做法真正改变了智能体行为、Codex 入门最佳实践(OpenAI 官方)
四、分层落地:多服务团队的三层配置
老王的组不止一个服务——订单、支付、用户三个微服务,共用一个 Git 仓库(单体仓库 monorepo)。这时新的问题来了:三个服务的技术栈和约束不一样,一份根目录 AGENTS.md 装不下。
这就用上了 Codex 的三层配置体系。
三层配置怎么分
| 层级 | 位置 | 作用域 | 谁维护 | 是否提交 git |
|---|---|---|---|---|
| 全局层 | ~/.codex/AGENTS.md | 个人所有项目 | 个人 | ❌ 不提交 |
| 项目层 | 仓库根目录 AGENTS.md | 全团队 | 技术负责人 | ✅ 提交 |
| 服务层 | 子目录/AGENTS.md | 单个服务 | 服务 owner | ✅ 提交 |
就近原则:Codex 从根目录遍历到当前工作目录,把路径上的每个 AGENTS.md 合并起来,越靠近工作目录的优先级越高。
老王团队的目录结构
order-platform/
├── AGENTS.md ← 项目层:全组通用规范
├── services/
│ ├── order/
│ │ └── AGENTS.md ← 订单服务:业务规则
│ ├── payment/
│ │ ├── AGENTS.md ← 支付服务:常规规则
│ │ └── AGENTS.override.md ← 支付服务:安全覆盖(Codex 独有)
│ └── user/
│ └── AGENTS.md ← 用户服务
└── ~/.codex/AGENTS.md ← 个人全局:个人偏好(不提交)
重点:AGENTS.override.md(Codex 独有能力)
支付服务涉及资金,安全要求远高于其他服务。普通 AGENTS.md 是“追加”父级规则,而 AGENTS.override.md 是“替换”父级规则——这是 Codex 独有的机制,其他工具没有。
<!-- services/payment/AGENTS.override.md -->
# 支付服务规则(覆盖父级)
本服务有额外安全要求,以下规则覆盖项目级默认值:
- 所有改动必须:mvn test -Dtest=Payment* 通过(支付相关测试全过)
- 所有 SQL 必须经过 Code Review,禁止 Codex 自动提交
- 未经明确批准,不得升级任何依赖版本
- 审批策略:untrusted(每个写操作都要人工确认,支付服务最高安全)
什么时候用 override:发布冻结期、线上事故应急、或像支付这种安全约束需要盖过项目默认值的服务。
OpenAI 自家的 Codex 仓库,在单体仓库里用了 88 个独立的 AGENTS.md 文件——每个服务、每个包各一份。多服务团队就该这么分层。
五、驾驶舱:用 config.toml 管住 Codex 的“手”
AGENTS.md 管“怎么写代码”,还有一个文件管“Codex 能干什么、要不要先问我”——它就是 config.toml。这是团队落地的另一半,很多人忽略。
两个关键开关:审批策略 + 沙箱
config.toml 里有两个最影响团队安全的配置:
| 配置项 | 作用 | 团队建议值 |
|---|---|---|
approval_policy | Codex 执行命令前要不要先问你 | 新手用 untrusted,日常用 on-request |
sandbox_mode | Codex 能读写哪些目录(OS 级隔离) | workspace-write (只能写工作目录) |
审批策略(approval_policy)当前有三档有效值(从严到松),外加一个已弃用的旧值:
| 策略 | 含义 | 适用场景 |
|---|---|---|
untrusted | 任何写操作都要确认(默认) | 新人、敏感项目 |
on-request | 由模型自己判断何时问你 | 团队日常推荐 |
never | 全自动,不问 | 受信任的隔离环境、CI |
on-failure | 失败时才问 | 已弃用 ,官方建议改用 on-request |
小贴士:很多 2025 年的老教程还在推荐
on-failure,但 OpenAI 在当前配置文档里已把它标记为弃用(DEPRECATED)。记住:交互式用on-request,自动化用never。
沙箱是操作系统级别的:macOS 用 Seatbelt、Linux 用 landlock,不是 Codex 自己实现的软隔离。这意味着即使 Codex 想乱来,系统层也挡得住。
老王团队的 config.toml
# .codex/config.toml(项目级,提交 git)
model = "gpt-5.1-codex"
approval_policy = "on-request" # 模型自行判断何时问,平衡效率和安全
sandbox_mode = "workspace-write" # 只能写工作目录
[history]
persistence = "save-all"
# ~/.codex/config.toml(个人级,不提交)
model = "gpt-5.1-codex"
approval_policy = "never" # 老王自己熟练,用全自动
团队规范:项目级 config.toml 提交 git,统一审批和沙箱策略;个人偏好放 ~/.codex/ 各自配置,互不干扰。
注意一个坑:Codex 的 CLI、IDE 插件、桌面 App 共享同一套配置层。很多“质量问题”其实是配置问题——工作目录不对、缺写权限、模型默认值不合适。
六、工程化:Skills + MCP 把重复流程打包
到了这一步,AGENTS.md 已经能让 Codex 按规矩写代码了。但老王团队发现一个新痛点:有些工作流,每个新人都要反复教 Codex 一遍——比如怎么按团队格式写发布说明、怎么审查一个 PR、怎么分析线上日志。
这就是 Skills(SKILL.md) 的用武之地。
三件套的团队定位
到这里,团队的完整配置图景清晰了:
| 文件 | 定位 | 团队用法 |
|---|---|---|
| AGENTS.md | 项目宪法(全局规则) | 根目录提交,全员共享 |
| SKILL.md | 操作手册(具体工作流) | .agents/skills/ 提交,按需加载 |
| config.toml | 驾驶舱(权限和行为) | .codex/ 提交,管审批和沙箱 |
老王团队打包的 3 个 Skills
Skill 1:PR 审查技能
<!-- .agents/skills/pr-review/SKILL.md -->
---
name: pr-review
description: 按团队标准审查一个 PR。当用户说“审查 PR”或“review”时触发。
---
## 审查步骤
1. 运行 git diff --name-only origin/main 列出改动文件
2. 对每个文件运行 mvn checkstyle:check
3. 检查是否有单元测试覆盖新逻辑
4. 检查是否拼接了 SQL(违反安全规范)
5. 输出:通过/拒绝 + 具体问题清单
Skill 2:发布说明起草技能——读取最近一周的 commit,按团队模板生成 changelog。
Skill 3:线上日志分析技能——接入监控系统的报错日志,按团队排查 SOP 定位问题。
Skills 的核心原则:每个技能只做一件事,描述要写清楚“做什么”和“什么时候用”(包含用户会说的触发词)。用
/skill-creator可以快速生成初版。
MCP:连接代码库之外的世界
Skill 3 那个“日志分析”技能,需要读监控系统数据——这些数据在代码库之外。这时用 MCP(模型上下文协议) 把 Codex 连到外部系统。
# .codex/config.toml 里配置 MCP 服务器
[mcp_servers.prometheus]
command = "mcp-prometheus" # stdio 是默认传输方式,HTTP 服务器需另配
老王团队接了 3 个 MCP:监控(Prometheus)、工单(Jira)、日志(ELK)。这样 Codex 分析线上问题不用人去复制粘贴日志,直接调。
团队原则:MCP 要有节制,只在能真正打通某个工作流时才加。 从一两个能明确减少手动操作的工具开始。
七、制度化:让 AGENTS.md 成为团队基础设施
前面六步都是“配置”,最后一步是“固化”——让 AGENTS.md 不依赖某个人的维护,成为团队长期运转的基础设施。这是很多团队倒在最后一公里的原因。
老王团队的 4 条制度
1. /init 脚手架 + 模板仓库
新服务初始化时,统一用 codex /init 生成 AGENTS.md 骨架,再从团队模板仓库填充。避免每个服务各写各的。
2. 新人 onboarding 流程
新人入职的 AI 编程第一课:
- • 第 1 天:读根目录 AGENTS.md,跑“背诵测试”确认生效
- • 第 3 天:学会用 on-request 审批策略,在沙箱里改第一个 bug
- • 第 1 周:独立用一个 Skill 完成一次 PR 审查
3. CI 校验
在 CI 里加一道检查:AGENTS.md 改动必须经过技术负责人 review,且改动后能通过“背诵测试”脚本(自动化版本)。
4. 定期复盘更新
每月一次“AGENTS.md 复盘会”:收集本月 Codex 反复犯的错,更新进 AGENTS.md。OpenAI 官方的建议正是如此——发现 Codex 反复犯同一个错误,就让它做复盘,然后更新 AGENTS.md。
还要配一份 code_review.md
团队另外维护一份 code_review.md,在 AGENTS.md 里引用:
## 代码审查规范
详见 code_review.md。Codex 在 /review 时会遵循这份规范。
这样 /review 命令、CI 里的 Codex 自动审查、人工审查,三方遵循同一套标准。OpenAI 内部 100% 的 PR 都经过 Codex 审查,靠的就是这种“审查规范固化进文件”的模式。
八、落地效果:数据说话
老王团队跑了一个季度,复盘的数据(脱敏):
| 指标 | 落地前 | 落地后 | 变化 |
|---|---|---|---|
| Codex 生成代码的返工率 | ~45% | ~12% | ⬇️ 73% |
| 新人第一次独立提交 PR 的时间 | 5-7 天 | 2 天 | ⬇️ 60%+ |
| PR 审查平均轮次 | 3.2 轮 | 1.8 轮 | ⬇️ 44% |
| 团队“Codex 不听话”的吐槽 | 每周多次 | 几乎消失 | — |
注:以上为一个团队的内部复盘数据,仅供参考,不同团队、不同项目基础不同,效果会有差异。
最关键的变化是最后一条——当 AGENTS.md 真正生效,团队对 Codex 的态度从“不靠谱的玩具”变成了“按规矩干活的队友”。
九、团队落地路线图 + 踩坑清单
落地路线图(5 个阶段)
把前面整个过程浓缩成一张可复制的路线图:
| 阶段 | 做什么 | 产出 | 周期 |
|---|---|---|---|
| 阶段 0:诊断 | 跑“背诵测试”,确认现状 | 一份诊断报告 | 1 天 |
| 阶段 1:重构 | 命令优先 + 完成定义重写根目录文件 | 项目级 AGENTS.md | 2-3 天 |
| 阶段 2:分层 | 多服务团队上三层配置 + override | 完整目录结构 | 1 周 |
| 阶段 3:工程化 | 打包 Skills + 接 MCP + config.toml | 工作流技能库 | 2-3 周 |
| 阶段 4:制度化 | 脚手架、onboarding、CI、复盘机制 | 长期运转机制 | 持续 |
OpenAI 官方点名的 8 个团队级踩坑
这些是团队落地时最容易踩的,老王团队全踩过:
- 把持久性规则堆进提示词,而不是写进 AGENTS.md(每个人都要重复教)
- 没告诉 Codex 怎么跑构建和测试(它看不到自己的工作结果)
- 跳过复杂任务的规划阶段就开干
- 没搞清工作流就给 Codex 开放完整权限(审批策略直接上
never) - 同一批文件并行跑多个会话却不用 git worktree(互相冲突)
- 任务还不稳定就把它自动化
- 像监工一样盯着 Codex 一步步执行(而不是让它并行工作)
- 一个线程对应一个项目而不是一个任务(上下文膨胀、效果变差)
团队 vs 个人的关键差异
最后总结一下,团队落地和单人使用 AGENTS.md 的核心区别:
| 维度 | 个人使用 | 团队落地 |
|---|---|---|
| 文件归属 | 一个人维护 | 分层 + 各自 owner |
| 配置复用 | 一份够用 | 全局/项目/服务三层 |
| 权限管理 | 自己说了算 | 统一审批 + 沙箱策略 |
| 工作流 | 提示词重复 | 打包成 Skills 共享 |
| 质量保障 | 靠自觉 | CI 校验 + 审查规范 |
| 知识传承 | 靠口口相传 | onboarding 流程 + 复盘机制 |
写在最后
回到开头老王的故事。他后来在公司内部分享时说了一句话,我觉得是对“团队落地 AGENTS.md”最好的总结:
“写一份 AGENTS.md 只要 10 分钟,但让它在一个团队里真正运转起来,是一个季度的工程。”
个人用 AGENTS.md,是“写好一份文件”;团队落地 AGENTS.md,是“搭一套基础设施”。后者难得多,也值钱得多。
记住团队落地的三个核心判断:
- 写完不等于生效——用“背诵测试”验证,而不是想当然
- 配置要分层——全局管偏好、项目管规范、服务管特例,用 override 处理安全敏感
- 要制度化——脚手架、onboarding、CI、复盘,让它不依赖任何一个人
当这套东西跑起来,Codex 就不再是“每个人的私人玩具”,而是一个真正按团队规矩干活、可传承、可复制的 AI 队友。这才是 AGENTS.md 这个开放标准,给团队带来的真正价值。
上一篇(《一份让 Codex 不再“自由发挥”的 AGENTS.md》)教你怎么写好,这一篇教你团队怎么用起来。两篇配套,就是一份完整的 AGENTS.md 落地手册。
参考来源:
- • Codex 入门最佳实践(OpenAI 官方)
- • AGENTS.md 模式:哪些做法真正改变了智能体行为 - Blake Crosley(含 GitHub 2500 仓库分析)
- • Codex CLI 权威技术参考 - Blake Crosley
- • Codex 0.46.0 实战手册
- • Codex 审批、沙箱、权限与网络 - codex-docs.com
- • Advanced Configuration – Codex | OpenAI Developers