Codex Code Review 支持在 AGENTS.md 中编写自定义仓库审查规则

在使用 Codex 进行代码审查时，有些评论会反复出现。可能是关于保留旧的 API 契约、避免将客户数据写入日志，或者避免重命名会破坏另一个服务。这些检查很重要，但当上下文只掌握在少数审查者手中时，很容易被忽略。

Codex Code Review 现在可以使用 AGENTS.md 中的自定义仓库规则来捕获这些问题，并引导作者查看发现背后的指导。如果你已经使用 AGENTS.md 来指导编码任务，同一个文件也可以帮助指导审查。当贡献者或编码代理在仓库中不熟悉的部分工作时，这一点尤其有用，因为他们可能还不了解其历史。在这篇文章中，我们将展示仓库规则的适用范围以及如何编写好它们，包括我们在测试它们时学到的东西。

交付更多代码

编码代理可以承担更大的变更并在更长的时间跨度内工作，帮助团队将更多想法转化为代码。在 OpenAI，自第四季度以来每周 PR 数量增加了一倍多，我们许多客户也看到了类似的趋势。更多代码是好事：它帮助团队交付新功能并解决更多问题。这也意味着更多拉取请求在等待知道该看什么的人，代码审查可能很快成为瓶颈。

当多个变更同时到达时，审查会变得更加困难。一个 diff 可能看起来完全合理，但仍然会破坏旧客户端或越过作者不知道的边界。必须有人记住这些上下文，并在作者仍能采取行动时分享出来。

审查瓶颈

当更多拉取请求涌入时，审查者用来弄清楚每个变更试图做什么并在留下反馈之前收集相关上下文的时间就更少。一旦作者转向其他事情，即使是很小的修订也可能需要更长时间。快速反馈帮助团队充分利用更快的开发，而不必让人成为瓶颈。

有些问题也仅从 diff 中很难发现。重命名响应字段可能看起来像是例行清理，但它可能会破坏仍然依赖现有契约的客户端。有经验的审查者可能记得为什么该字段需要保留；新贡献者或第一次在该服务中工作的代理可能不会。

规则作为接口

那么，你如何给编码代理提供团队通常随时间积累的上下文？新的仓库规则接口允许你将简洁、有范围的审查指导放在 AGENTS.md 中。Codex Code Review 可以应用对变更重要的规则，并在发现中引用它们。与其在每个拉取请求中重复相同的解释，你可以将其保留在它所适用的代码附近。

随着编码模型变得更加可引导，一个简短、范围明确的指令可以帮助将长时间审查集中在团队真正关心的事情上。Codex 仓库本身将 Code Review 规则保存在 AGENTS.md 中，涵盖模型可见上下文和破坏性变更等问题。

这里有一个真实的例子：

Codex app-server 发出一个名为 rawResponseItem/completed 的内部通知。它被标记为实验性的，但 Codex Cloud 已经在消费它。仓库的破坏性变更审查规则明确将 rawResponseItem/* 列为审查者应保留的集成面，即使它仍是实验性的。

现有的 wire 名称定义在 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

对于那个示例性 diff，一条 Code Review 发现可以这样写：

保留现有的 rawResponseItem/completed 通知。 Codex Cloud 的使用方会监听这个线上名称，因此即使该事件是实验性的，重命名它也会破坏他们的使用。请保留现有名称，或添加一个向后兼容的事件，如 AGENTS.md 所述。

Codex 团队专门添加了这条规则来保护 Codex Cloud 的使用方。将仓库范围的规则放在根目录，将服务特定的规则放在相关目录中。在审查期间，Codex 可以应用覆盖已更改文件的指导，并指引作者查看相关规则；无关的改动不需要 app-server 上下文。

规则与其他团队已经依赖的工具并存。测试和 linter 非常适合你能够确定性地表达的检查；仓库规则有助于捕捉那些更难编码的判断。兼容性要求和数据边界是很好的起点。作者在做出改动之前不需要了解每一次过往事故或本地约定；相关指导已经在那里了。

编写经得起考验的规则

我们用一个评估套件测试了 Code Review 使用仓库指导的效果，该套件包含已知的规则违规和安全的反例。在主要套件中，规则引导的变体恢复了 98% 所需的定制发现，而基线对照组为 58.3%。

发现规则违规只是工作的一部分。我们还想知道当多条规则争夺注意力，或者一个拉取请求已经很繁忙时会发生什么。我们测试了有后果的违规和应当保持原样的改动，然后围绕四个问题组织结果：

我们评估了什么

覆盖度

当 diff 很繁忙且规则相互竞争时，Codex 能否发现预期的违规？

克制

干净的改动和有效的例外是否能避免不必要的发现？

保留

Code Review 是否继续捕捉仓库规则之外的普通 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。