Custom Code Review Rules for Codex

AGENTS.md 不再只指导 coding——现在还能指导审查。把团队隐性知识编码为可引用、可 scope 的 review 指令。

作者: Hari Srikanth 2026-07-22 原文 ↗

问题：审查瓶颈

Coding agent 带来了更多代码产出。OpenAI 内部周 PR 量自 Q4 翻倍，客户中也看到同样趋势。但更多 PR = 更多人等审查。

PR 量翻倍，审查者时间不变 → 瓶颈 Q4 基线 1× PR/周 现在 2.3× PR/周 审查瓶颈 diff 看起来合理 但可能破坏旧 API
Figure 1. 代码量增长速度远超审查者带宽

关键痛点：有些问题从 diff 看不出来。重命名一个 response field 像是例行清理，但可能破坏仍在使用旧契约的客户端。有经验的审查者记得为什么不能改；新 contributor 或首次在此工作的 agent 不会知道。

方案：规则作为接口

Codex Code Review 的新功能：在 AGENTS.md 中写入简洁、限定范围的审查指导。审查时 Codex 自动应用相关规则，在 finding 中引用对应规则——而不是每次 PR 重复解释。

AGENTS.md 的双用途演化 之前 AGENTS.md → 指导 coding agent "怎么写代码"的上下文文件 现在 AGENTS.md → 指导 coding + 审查 编写与审查的双用途接口 + Code Review Rules 章节 PR diff 进来 Codex Code Review 读取匹配的规则 应用 + 引用 AGENTS.md Finding 带规则引用
Figure 2. AGENTS.md 从单向指令进化为双向：既指导写也指导审

真实案例：rawResponseItem/completed

Codex app-server 发出 rawResponseItem/completed 通知。标记为 experimental，但 Codex Cloud 已在消费它。

⚠️ 一个看起来无害的 diff
-RawResponseItemCompleted => "rawResponseItem/completed"
+RawResponseItemCompleted => "rawResponseItem/done"

代码编译通过。但监听旧通知名的客户端会静默断连。

对应的 AGENTS.md 规则非常简洁：

## Code Review Rules

### Breaking changes

Search for breaking changes in external integration surfaces:

- raw response item events (`rawResponseItem/*`), even while experimental

Codex 的 finding 自动引用这条规则：

Keep the existing rawResponseItem/completed notification. Codex Cloud consumers listen for this wire name, so renaming it will break them even though the event is experimental. Keep the existing name or add a backward-compatible event, as described in AGENTS.md.
从 diff 到 finding 的完整链路 1. Diff rename 事件名 → 编译通过 ✓ 2. 匹配规则 AGENTS.md 中 "Breaking changes" 规则被命中 3. 验证 Codex Cloud 消费此事件？ 4. Finding "保留名称" 引用 AGENTS.md 关键：finding 不仅说"这里有问题"，还指向 为什么 和 安全替代方案 "保留现有名称或添加向后兼容的事件"
Figure 3. 规则被命中后，finding 自动生成并引用 AGENTS.md 指导

实验结果

OpenAI 用包含已知违规和安全反例的 eval suite 测试：

自定义 finding 恢复率对比 Baseline（无规则） 58.3% Rule-guided（有规则） 98% +40%
Figure 4. 规则指导将 finding 恢复率从 58.3% 提升到 98%

Eval 还围绕四个维度展开：

维度问题
Coveragediff 很忙、规则竞争注意力时，能 surface 预期违规吗？
Restraint干净修改和有效例外能否避免不必要 finding？
Retention规则之外仍能捕获普通 bug 吗？
Actionability每个 finding 是否标明指导、位置、优先级？
核心发现

Codex 能发现并引用默认 review 可能遗漏的本地指导，但宽泛的指令容易制造噪音。小范围、带明确安全路径的规则集效果最好。

写好规则的四条原则

四条原则——层级关系 ① 从有后果的不变量开始 编码审查者反复解释的检查。删除后不改变审查结果的规则 → 不加 ② 限定到管辖的代码 全仓库指导放根目录，service 专属放嵌套 AGENTS.md → 窄 scope = 少噪音 ③ 陈述不变量 + 安全路径 不只说"别改"，还要说"怎么改才安全"——给作者明确的替代方案 ④ 保持持久且更新 描述结果（outcome），不描述函数名。定期清理反复制造噪音的规则
Figure 5. 四条原则从最重要的"选对不变量"到日常维护

规则在哪一层？

Repository rules 不是替代 CI 和 tests，而是填补 reviewer 需要反复口述的判断空白。

工具适用场景例子
Tests / linters确定性检查格式、类型、测试覆盖
Repository rules难以编码的判断兼容性要求、数据边界、隐性约定
Branch protections硬性门禁required approvals、status checks
Getting Started
  1. 在 AGENTS.md 加 2-3 条规则
  2. 开一个有代表性的 PR
  3. 测试：一个应触发规则的修改 + 一个安全反例 + 一个无关修改
  4. 确认第一个产生有用 finding，后两个不制造噪音
  5. 也可直接 @codex review 触发

来源：Custom Code Review rules for Codex — Hari Srikanth, OpenAI Developers Blog, 2026-07-22