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 的四个典型错误：

记住这条铁律（上一篇文章讲过，这里再强调一次，因为它是团队落地的命门）：没有验证命令的指令是“建议”，不是“规则”。 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

注意几个关键变化：

1. 开头就是命令，不是公司价值观
2. “完成”被定义成具体的退出码，挡住了 Codex“没验证就报告完成”
3. 加了“遇到阻碍时”的升级规则和 Never 列表，防止 Codex 卡住时瞎搞

这一版上线后，团队第一次感受到“Codex 真的按规矩干活了”。

来源：AGENTS.md 模式：哪些做法真正改变了智能体行为、Codex 入门最佳实践（OpenAI 官方）

四、分层落地：多服务团队的三层配置

老王的组不止一个服务——订单、支付、用户三个微服务，共用一个 Git 仓库（单体仓库 monorepo）。这时新的问题来了：三个服务的技术栈和约束不一样，一份根目录 AGENTS.md 装不下。

这就用上了 Codex 的三层配置体系。

三层配置怎么分

就近原则：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）当前有三档有效值（从严到松），外加一个已弃用的旧值：

小贴士：很多 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） 的用武之地。

三件套的团队定位

到这里，团队的完整配置图景清晰了：

老王团队打包的 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 审查，靠的就是这种“审查规范固化进文件”的模式。

八、落地效果：数据说话

老王团队跑了一个季度，复盘的数据（脱敏）：

注：以上为一个团队的内部复盘数据，仅供参考，不同团队、不同项目基础不同，效果会有差异。

最关键的变化是最后一条——当 AGENTS.md 真正生效，团队对 Codex 的态度从“不靠谱的玩具”变成了“按规矩干活的队友”。

九、团队落地路线图 + 踩坑清单

落地路线图（5 个阶段）

把前面整个过程浓缩成一张可复制的路线图：

OpenAI 官方点名的 8 个团队级踩坑

这些是团队落地时最容易踩的，老王团队全踩过：

1. 把持久性规则堆进提示词，而不是写进 AGENTS.md（每个人都要重复教）
2. 没告诉 Codex 怎么跑构建和测试（它看不到自己的工作结果）
3. 跳过复杂任务的规划阶段就开干
4. 没搞清工作流就给 Codex 开放完整权限（审批策略直接上 never）
5. 同一批文件并行跑多个会话却不用 git worktree（互相冲突）
6. 任务还不稳定就把它自动化
7. 像监工一样盯着 Codex 一步步执行（而不是让它并行工作）
8. 一个线程对应一个项目而不是一个任务（上下文膨胀、效果变差）

团队 vs 个人的关键差异

最后总结一下，团队落地和单人使用 AGENTS.md 的核心区别：

写在最后

回到开头老王的故事。他后来在公司内部分享时说了一句话，我觉得是对“团队落地 AGENTS.md”最好的总结：

“写一份 AGENTS.md 只要 10 分钟，但让它在一个团队里真正运转起来，是一个季度的工程。”

个人用 AGENTS.md，是“写好一份文件”；团队落地 AGENTS.md，是“搭一套基础设施”。后者难得多，也值钱得多。

记住团队落地的三个核心判断：

1. 写完不等于生效——用“背诵测试”验证，而不是想当然
2. 配置要分层——全局管偏好、项目管规范、服务管特例，用 override 处理安全敏感
3. 要制度化——脚手架、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