好 AGENTS.md 不让 Codex 更聪明，但少让它走偏

1. 写可执行事实，不写正确的废话

「保持代码简洁」「遵循最佳实践」「确保高质量」看起来没有错，但对 Codex 几乎没有约束力。

更有效的写法是：

1
- 修改 TypeScript 文件后运行 `pnpm lint` 和 `pnpm typecheck`。
2
- 新增业务逻辑时，在同目录补充 `*.test.ts`。
3
- 单个函数超过 60 行时，优先拆分；不要仅为满足行数机械拆分。

判断一句规则是否有用，可以问自己：任务结束时，我能不能根据它明确判断 Codex 做到了还是没做到？如果不能，它大概率只是一句口号。

2. 告诉它「怎么验证」，不只是「怎么修改」

编码智能体最危险的状态，不是写不出来，而是写完后误以为已经完成。

因此，AGENTS.md 至少要写清四件事：

1. 最小检查命令是什么；
2. 哪些改动需要扩大测试范围；
3. 什么情况可以跳过测试；
4. 无法验证时应该如何汇报。

例如：

1
## Verification
2

3
- 文档改动：运行 `pnpm lint:docs`。
4
- 单个包改动：运行 `pnpm --filter <package> test`。
5
- 共享类型或公共包改动：运行 `pnpm test:affected`。
6
- 如果本地缺少依赖或服务，说明未运行的检查、原因和潜在风险；不要声称验证通过。

最后一句尤其重要。它把「诚实报告验证边界」也纳入了完成标准。

3. 写清边界和禁区

有些动作技术上可以执行，流程上却不应由 Codex 自行决定，例如升级生产依赖、重写历史迁移、提交密钥、删除兼容代码。

不要只写「谨慎操作」，而要明确触发条件：

1
## Guardrails
2

3
- 未经明确要求，不新增生产依赖。
4
- 不修改已经发布的数据库迁移；需要变更时创建新的迁移文件。
5
- 不读取、输出或提交 `.env`、密钥及真实客户数据。
6
- 不执行生产部署、数据删除、密钥轮换和远程 Git 推送。

好的边界不是让 Codex 什么都不敢做，而是把「可自主完成」和「必须停下来确认」分开。

4. 给地图，不要复制整本说明书

AGENTS.md 应该帮 Codex 快速找到重点，而不是把 README、架构文档和编码规范全部复制进去。

可以写：

1
## Repository map
2

3
- `apps/web/`：Vue 3 管理端。
4
- `services/api/`：Node.js API 服务。
5
- `packages/contracts/`：前后端共享类型，改动可能影响所有应用。
6
- `docs/architecture.md`：系统边界与关键设计决策。
7
- `docs/review.md`：代码审查清单。

官方文档提醒，Codex 合并加载的项目说明默认有 32 KiB 上限。文件越长，不仅越难维护，也越可能让真正关键的规则被噪声淹没。主文件保持短小，需要时指向更具体的文档，通常更可靠。

5. 用分层覆盖解决差异，不堆条件句

假设仓库里前端用 Vitest，支付服务用 pytest。如果所有规则都塞在根目录，最终会出现大量「如果在 A 目录就……如果在 B 目录就……」的条件。

更清楚的做法是：

1
repo/
2
├── AGENTS.md
3
├── apps/web/
4
│   └── AGENTS.md
5
└── services/payments/
6
    └── AGENTS.override.md

根目录只写全局规则，apps/web/AGENTS.md 写前端规则，支付服务用 AGENTS.override.md 覆盖不适用的通用命令。局部规则越靠近代码，越不容易被误用。

需要注意：Codex 通常在一次运行或 TUI 会话开始时构建指令链。修改 AGENTS.md 后，如果当前会话没有体现新规则，启动一个新会话再验证。

6. 把它当成会演进的工程资产

不要试图第一次就写出完美版本。更实用的方法是：先覆盖高频任务，然后根据真实返工持续更新。

每当 Codex 重复犯错，可以追问三个问题：

1. 它缺少的是项目事实、操作命令，还是决策边界？
2. 这条信息只对当前任务有效，还是以后还会复用？
3. 它应该放在根目录，还是某个子目录？

如果同类错误发生两次，就值得把修正写进 AGENTS.md。它不应成为愿望清单，而应成为项目经验的压缩包。

场景 1：在成熟项目里开发新功能

成熟项目最怕「功能完成了，但破坏了既有边界」。这时需要强调先找相似实现、控制改动范围，以及公共接口的同步责任。

1
## Feature development
2

3
- 实现前先查找同类功能，沿用现有分层和数据流。
4
- 优先扩展现有模块，不新建平行抽象，除非现有设计无法满足需求。
5
- 修改公共 API 时，同步更新 schema、客户端类型、测试和变更说明。
6
- 新功能必须覆盖成功路径、权限失败和无效输入。

这组规则能避免 Codex 在仓库里「另起炉灶」，尤其适合已经形成稳定架构的项目。

场景 2：修复一个难复现的线上 Bug

修 Bug 时，最大的诱惑是看见异常就直接改代码。但没有复现证据的修复，往往只是把症状移到别处。

1
## Bug fixes
2

3
- 修改实现前，先用现有日志、调用链或测试证明根因。
4
- 能稳定复现时，先添加失败的回归测试，再修改代码。
5
- 修复应针对根因，不通过吞掉异常、扩大重试或删除校验掩盖问题。
6
- 如果无法复现，列出已验证事实、假设和仍需观测的数据。

这里的重点，是强制把「事实」和「推测」分开。即便最终没能修复，也会留下可继续推进的诊断结果。

场景 3：Monorepo 中只修改一个包

Monorepo 的常见浪费，是一个小改动跑整库测试；常见事故，则是误以为只影响一个包。

1
## Monorepo scope
2

3
- 修改前检查目标包的 `package.json`、依赖方和局部 `AGENTS.md`。
4
- 包内改动先运行 `pnpm --filter <package> test`。
5
- 修改 `packages/contracts/`、`packages/config/` 或公共类型后，运行 `pnpm test:affected`。
6
- 不修改无关包的锁文件、生成物或格式。

一份好的规则既要控制验证成本，也要指出哪些目录具有「爆炸半径」。

场景 4：数据库迁移和高风险操作

数据库相关任务不能只强调 SQL 是否正确，还要约束兼容窗口、回滚方式和执行权限。

1
## Database changes
2

3
- 不修改已经在任何环境执行过的迁移文件。
4
- 破坏性 schema 变更采用 expand-migrate-contract 三阶段，不在一次发布中删除旧字段。
5
- 迁移必须说明回滚或前向修复方案，并评估锁表和大表扫描风险。
6
- 只生成和测试迁移；未经明确授权，不连接生产库、不执行生产迁移。

这里要明确区分「编写迁移」和「执行迁移」。前者通常属于开发任务，后者可能是不可逆的生产操作。

场景 5：前端页面还原与交互开发

前端任务容易出现两个极端：只追求截图相似，忽略状态和可访问性；或者为了抽象组件，把一个页面改成半个设计系统。

1
## Frontend work
2

3
- 优先复用现有设计令牌和组件，不创建近似重复组件。
4
- 页面必须处理 loading、empty、error 和 disabled 状态。
5
- 交互元素支持键盘操作，并保留可见焦点状态。
6
- 至少检查 375px、768px 和 1440px 三个宽度。
7
- 视觉改动提供截图或明确说明人工检查路径。

这类规则把「看起来完成」变成「在真实状态和真实设备上可用」。

场景 6：让 Codex 做 Pull Request 审查

代码审查不是复述 diff，更不是罗列所有风格差异。它应该优先发现会造成实际后果的问题。

1
## Review guidelines
2

3
- 优先报告正确性、安全性、数据损坏、兼容性和明显性能回归。
4
- 每个问题说明触发条件、用户或系统影响，并标注具体文件位置。
5
- 检查新增行为是否有测试，测试是否真的覆盖失败场景。
6
- 不报告现有代码中的无关问题，不把个人风格偏好列为缺陷。
7
- 如果没有发现问题，明确说明仍未覆盖的测试或环境风险。

Codex 官方文档说明，代码审查会寻找仓库中的 AGENTS.md，并遵循其中的 Review guidelines。对于支付、鉴权、隐私等特殊目录，还可以在更深层放置专门的审查规则，让检查标准跟着风险走。