# Codex 用 AGENTS.md 规则将代码审查召回率从 58% 提升至 98%

- 来源：meng shao (@shao__meng)
- 发布时间：2026-07-22 09:35
- AIHOT 分数：44
- AIHOT 链接：https://aihot.virxact.com/items/cmrvfgqlp01q6bihbfqnh0qiw
- 原文链接：https://x.com/shao__meng/status/2079742073440473422

## AI 摘要

OpenAI 为 Codex Code Review 新增 AGENTS.md 自定义规则功能，将隐性知识（如“某字段不能改名”等兼容性约束）写入仓库级或目录级规则文件。在评测集中，带规则的审查召回率从 58.3% 跃升至 98%，且规则不替代测试与 linter，而是补充其难以编码的判断类检查。官方建议从 reviewer 反复解释的“有后果且不显眼”的不变量开始，并配合三元测试验证规则效果。

## 正文

从 58% 到 98%：Codex Code Review 用一份 AGENTS.md 补上 AI 代码审查的最大短板
https://developers.openai.com/blog/custom-code-review-rules-for-codex

# 代码产量在暴涨，但审查能力没有同步增长

OpenAI 内部的周 PR 量自去年 Q4 以来翻了一倍以上，客户侧趋势类似。代码写得越快，code review 就越容易成为新的瓶颈。

更麻烦的是，有一类问题从 diff 本身根本看不出来。典型例子：把一个响应字段或事件名重命名，代码能编译、看起来是常规清理，但会悄悄破坏仍依赖旧契约的下游客户端。这类知识（"为什么这个字段不能动"）传统上只存在于少数资深 reviewer 的脑子里--而恰恰是新贡献者和 coding agent 最缺这种历史上下文。

# 核心机制：把 reviewer 的隐性知识写进 AGENTS.md

新能力允许团队在 AGENTS.md 里写下简短、有作用域的审查规则，Codex Code Review 会在审查时应用与改动文件相关的规则，并在 finding 中引用规则出处。这样解释不用在每个 PR 里重复一遍，而是常驻在它所约束的代码旁边。

OpenAI 给的真实案例很有代表性：Codex app-server 有一个标记为 experimental 的内部通知 rawResponseItem/completed，但 Codex Cloud 已经在消费它。仓库规则明确写了"即使是 experimental，rawResponseItem/* 也是需要保护的集成面"。假如有人把 wire name 从 completed 改成 done，编译通过、diff 看似无害，但下游会静默失联--规则让 Codex 能抓住这类改动，并给出安全替代方案（保留旧名，或增加向后兼容的新事件）。

值得注意的定位判断：规则是对测试和 linter 的补充，不是替代。能确定性表达的检查（格式、机械规范）留给 CI；规则用来承载难以编码的"判断类"知识--兼容性要求、数据边界（比如客户数据不能进日志）是最好的起点。

# 评测数据与四个维度

在包含已知规则违规和安全反例的评测集里，带规则的审查召回了 98% 的目标 finding，基线只有 58.3%。这个提升幅度说明：模型不缺发现问题的能力，缺的是"该看什么"的上下文。

但作者刻意强调"找到违规只是一半"，评测围绕四个维度组织，这个框架本身值得借鉴：
· Coverage（覆盖）：diff 很杂、多条规则竞争注意力时，还能不能抓住目标违规
· Restraint（克制）：干净的改动和合理例外，会不会被误报制造噪音
· Retention（保持）：加了规则后，规则之外的普通 bug 还能不能照常发现
· Actionability（可操作性）：每个 finding 是否指明依据的规则、位置和优先级

其中 Restraint 和 Retention 是最容易被忽视的：内部实测发现宽泛的指令很容易制造噪音--规则会被套到每个"沾边"的改动上。

# 怎么写好规则（方法论精华）

1. 从"有后果且不显眼"的不变量开始。选 reviewer 反复解释的那条检查。判断标准很干脆：如果删掉这条规则不会改变审查结果，就不要写。
2. 作用域对齐代码。仓库级规则放根目录，服务级规则放对应目录的嵌套 AGENTS.md。窄作用域减少规则间的注意力竞争，也让归属清晰。
3. 既说不变量，也给安全路径。不只说"不能改名"，还要说"保留旧名或加向后兼容事件"--给作者明确的替代方案。
4. 描述结果而非实现细节。不要绑定可能变化的函数名，规则才耐久；持续收窄或删除反复产生噪音的规则。
5. 机械检查留在 CI。规则只留给"reviewer 否则要反复回答的问题"。

# 上手路径

OpenAI 建议的验证方法是一个小型三元测试：加两三条规则后，开一个应触发规则的改动、一个安全反例、一个无关改动，检查第一个产生有用 finding、后两个不产生噪音，再据此迭代。

### 引用推文

> OpenAI Developers：Codex Code Review can now use custom repository rules in AGENTS.md. Start with a check your reviewers keep repeating. Keep it concise and scoped so Codex can ca...