Codex 的自定义代码审查规则
在使用 Codex 进行代码审查时，有些意见总是反复出现。可能是关于保留较旧的 API 契约、避免将客户数据写入日志，或是避免某个重命名会破坏另一个服务。这些检查很重要，但当相关背景只掌握在少数审查者手中时，很容易被遗漏。
Codex Code Review 现在可以在 AGENTS.md 中使用自定义仓库规则来捕获这些问题，并将作者指向该发现背后的指导原则。如果你已经使用 AGENTS.md 来指导编码任务，同一个文件也可以用来指导审查。当贡献者或编码代理在仓库的陌生部分工作、可能还不了解其历史时，这尤其有用。在本文中，我们将展示仓库规则的定位以及如何编写好它们，包括我们在测试过程中学到的经验。
交付更多代码
编码代理可以承担更大的变更并在更长的时间跨度上工作，帮助团队将更多想法转化为代码。在 OpenAI，自 Q4 以来每周 PR 数量已增长一倍以上，我们在许多客户那里也看到了类似的趋势。更多代码是好事：它帮助团队交付新功能并解决更多问题。这也意味着有更多拉取请求在等待某个知道该看什么的人，代码审查可能很快成为瓶颈。
当多个变更同时到来时，审查会变得更难。一个差异（diff）看起来可能完全合理，却仍然会破坏一个较旧的客户端，或越过作者并不知道的某个边界。必须有人记住这些背景，并在作者还能据此行动时分享出来。
审查瓶颈
当更多拉取请求涌入时，审查者留下的时间更少，难以在给出反馈前弄清每个变更的意图并收集相关背景。一旦作者转向其他事情，即使是很小的修改也可能需要更长时间。快速的反馈能帮助团队充分利用更快的开发速度，而不会让人成为瓶颈。
有些问题仅凭差异也很难察觉。重命名一个响应字段可能看起来只是常规清理，但它可能会破坏仍依赖现有契约的客户端。有经验的审查者可能记得为什么该字段必须保留；而新贡献者或首次在该服务中工作的代理很可能不会。
规则即接口
那么，如何将你的团队通常需要时间才能积累的背景交给编码代理呢？新的仓库规则接口允许你在 AGENTS.md 中放入简洁、有明确范围的审查指导。Codex Code Review 可以应用与该变更相关的规则，并在发现中引用它们。你无需在每个拉取请求中重复相同的解释，而是可以将其放在它所适用的代码附近。
随着编码模型变得越来越可控，一条简短、范围明确的指令可以帮助将漫长的审查聚焦在你的团队真正关心的事情上。Codex 仓库本身就在 AGENTS.md 中保存 Code Review 规则，涵盖诸如模型可见上下文和破坏性变更等关注点。
这里有一个真实的例子：
Codex app-server 会发出一个名为 rawResponseItem/completed 的内部通知。它被标记为实验性，但 Codex Cloud 已经在使用它。仓库的破坏性变更审查规则明确将 rawResponseItem/* 列为审查者应保留的集成界面，即使它仍处于实验阶段。
现有的线上名称在 app-server 协议中定义。假设一次清理改动了一行：
-RawResponseItemCompleted => "rawResponseItem/completed"
+RawResponseItemCompleted => "rawResponseItem/done"这一改动可以编译，但监听现有通知的客户端将停止接收它。相关的仓库规则片段很简洁：
## Code Review Rules
### Breaking changes
Search for breaking changes in external integration surfaces:
- raw response item events (`rawResponseItem/*`), even while experimental对于这个示例差异，代码审查发现可能如下：
保留现有的
rawResponseItem/completed通知。Codex Cloud 消费者监听这个线上名称，因此重命名它会破坏这些消费者，即使该事件是实验性的。请保留现有名称或添加向后兼容的事件，如AGENTS.md中所述。
Codex 团队 专门添加了这条规则来保护 Codex Cloud 消费者。将仓库级规则放在根目录，将服务特定规则放在相关目录中。在审查期间，Codex 可以应用涵盖已更改文件的指导，并将作者指向相关规则；无关的更改不需要 app-server 上下文。
规则与团队已经依赖的其他工具并存。测试和 linter 适用于可以确定性表达的检查；仓库规则有助于捕捉更难编码的判断。兼容性要求和数据边界是很好的起点。作者在进行更改之前不需要了解每一个过去的事件或本地惯例；相关指导已经在那里。
编写经得起考验的规则
我们使用一个包含已知规则违规和安全反例的评估套件，测试了代码审查使用仓库指导的效果。在主套件中，规则引导的变体恢复了 98% 的必需自定义发现，而基线对照组为 58.3%。
发现规则违规只是工作的一部分。我们还想知道当多条规则争夺注意力或拉取请求已经很繁忙时会发生什么。我们测试了重大违规和应该放过的更改，然后围绕四个问题组织结果：
我们评估的内容
覆盖范围
当差异繁忙且规则争夺注意力时，Codex 能否呈现预期的违规？
克制
干净的更改和有效的例外是否避免了不必要的发现？
保留
代码审查是否继续捕捉仓库规则之外的普通 bug？
可操作性
每个发现是否都指明了相关指导、位置和优先级？
我们还尝试了编写指导的常见方式，从简短的项目符号列表到由特定团队负责的部分。
在内部仓库中使用规则时，我们也发现了同样的模式。Codex 可以找到并引用默认审查可能遗漏的本地指导，但宽泛的指令很容易产生噪音。带有明确安全路径的小型、范围限定的规则集帮助 Codex 专注于最有用的内容，而不会将规则应用于每个附近的更改。
从一个重大的、非显而易见的不变量开始。编码审查者反复解释的检查，例如兼容性要求或数据边界。如果删除一条规则不会改变审查结果，就不要包含它。
将规则限定在其管理的代码范围内。将仓库级指导放在根目录，将服务特定指导放在嵌套的 AGENTS.md 中。狭窄的范围可以防止无关指令争夺注意力，并使所有权清晰。
说明不变量和安全路径。rawResponseItem/* 规则识别了兼容性风险。“保留现有名称或添加向后兼容的事件”为作者提供了明确的替代方案。
保持规则持久且最新。描述结果，而不是可能变化的函数名称。审查规则的更新，并缩小或删除反复产生噪音的指导。
将格式化和其他机械性检查保留在 CI 中。将仓库规则保存为审阅者原本需要反复询问的问题。
快速开始
如果你的仓库已经启用了 Codex Code Review，请在适用的 AGENTS.md 文件中添加两三条规则，并打开一个具有代表性的 pull request。如果你是 Code Review 的新用户，Code Review 快速入门 介绍了如何为 GitHub 仓库启用它。你也可以直接使用 @codex review 请求审查。
从审阅者反复重复的解释，或仓库特有的、遗漏会造成严重后果的错误开始。尝试一个应触发该规则的改动、一个安全的反例，以及一个无关的改动。检查第一个是否产生有用的发现，而其他改动不会产生噪音，然后根据观察到的情况完善指导。
Codex Code Review 仍然只是一名额外的审阅者；测试、分支保护和必需的批准仍然提供强制执行。
如果你发现自己花在审查改动上的时间比编写它们还多，就从团队反复重复的一项检查开始。将其添加到 AGENTS.md 中，并在下一个 pull request 上尝试 Codex Code Review。