为 Codex 定制代码审查规则

为 Codex 定制代码审查规则

原文：Custom Code Review rules for Codex

为 Codex 提供更详细的规则，让它在代码审查时发现问题，并更好地遵循你的约定。

*文章封面：Codex 自定义代码审查规则。*

⚠️ 图片多次重试后仍下载失败；已保留原始远程 URL，需手动获取。

使用 Codex 做代码审查时，有些意见总会反复出现。可能是要保留旧版 API 契约，不让客户数据进入日志，或避免某次重命名破坏另一个服务。这些检查很重要，但如果相关背景只掌握在少数审查者手中，就很容易被遗漏。

现在，Codex Code Review（代码审查）可以读取 AGENTS.md 中的自定义仓库规则，发现这些问题，并向代码作者指出每条审查发现背后的规则依据。如果你已经使用 AGENTS.md 指导编码任务，同一个文件也能指导代码审查。当贡献者或编码智能体在仓库的陌生区域工作、还不了解其历史背景时，这项能力尤其有用。本文将介绍仓库规则应当放在哪里、怎样写好规则，以及我们在测试中总结出的经验。

交付更多代码

编码智能体可以承担规模更大的改动，也能处理更长周期的任务，帮助团队把更多想法变成代码。在 OpenAI，自第四季度以来，每周的 PR 数量已经增长到两倍以上；许多客户也呈现出类似趋势。代码增多是好事：团队可以交付新功能、解决更多问题。但这也意味着，会有更多 Pull Request（PR）等待那些知道该看什么的人来审查，代码审查很快就可能成为瓶颈。

*每周 Pull Request 数量连续三个季度增长。*

⚠️ 图片多次重试后仍下载失败；已保留原始远程 URL，需手动获取。

多项改动同时到来时，审查会变得更困难。一个 diff 看起来可能完全合理，却仍会破坏旧客户端，或越过作者并不知道的边界。必须有人记得这些背景，并在作者仍来得及采取行动时及时告知。

审查瓶颈

随着更多 Pull Request 涌入，审查者留给每项改动的时间越来越少：他们既要弄清改动意图，又要收集相关背景，之后才能提出反馈。一旦作者转去处理其他工作，即使只是很小的修改，也可能拖得更久。快速反馈能帮助团队充分利用开发提速带来的收益，而不必让人类审查者成为新的瓶颈。

还有一些问题，仅凭 diff 很难发现。重命名响应字段看起来可能只是常规清理，却会破坏仍然依赖现有契约的客户端。有经验的审查者或许记得这个字段为何必须保留；新贡献者，或首次参与该服务工作的智能体，多半不会知道。

把规则当作接口

那么，怎样才能把团队在长期实践中积累的背景信息交给编码智能体？新的仓库规则接口允许你把简洁、作用域明确的审查指引写入 AGENTS.md。Codex Code Review 可以选用与本次改动相关的规则，并在审查发现中引用它们。这样，你不必在每个 Pull Request 中反复解释同一件事，而是可以把说明放在它所约束的代码附近。

随着编码模型变得更容易引导，一条简短且作用域清晰的指令，就能让漫长的审查聚焦于团队真正关心的事情。Codex 仓库本身就在 AGENTS.md 中维护 Code Review 规则，涵盖模型可见上下文、破坏性变更等问题。

来看一个真实案例：

Codex app-server 会发出名为 rawResponseItem/completed 的内部通知。虽然它被标记为实验性功能，但 Codex Cloud 已经在使用它。仓库的破坏性变更审查规则明确指出，rawResponseItem/* 属于审查者应当保留的集成接口面，即使它仍处于实验阶段也不例外。

现有的线上协议名称（wire name）定义在 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%。

发现规则违规只是工作的一部分。我们还想知道：当多条规则争夺注意力，或一个 Pull Request 本身已经非常复杂时，会发生什么？我们同时测试了后果严重的违规，以及本应不作处理的改动，然后把结果归纳为四个问题：

覆盖率（Coverage） 当 diff 很繁杂、多条规则争夺注意力时，Codex 能否找出预期的违规？

克制性（Restraint） 面对干净的改动和有效的例外，能否避免产生不必要的审查发现？

保持能力（Retention） 除了仓库规则所描述的问题，Code Review 是否仍能继续发现普通 bug？

可操作性（Actionability） 每条审查发现是否都能指出相关指引、具体位置和优先级？

我们还尝试了几种常见的指引写法，从简短的项目符号列表，到由特定团队负责的独立章节。

在内部仓库中使用规则时，我们观察到了同样的模式。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。