在使用 Codex 进行代码审查时，有些意见会反复出现。它们可能涉及保留旧版 API 契约、避免将客户数据写入日志，或避免因重命名而导致其他服务出错。这些检查很重要，但如果只有少数审查者了解相关背景，就很容易遗漏。
现在，Codex 代码审查可以使用 AGENTS.md 中的自定义代码仓库规则来发现这些问题，并向作者指出审查意见所依据的指导。如果您已经使用 AGENTS.md 来指导编程任务，同一个文件也可以用来指导审查。当贡献者或编程智能体在代码仓库中不熟悉的部分开展工作、可能还不了解其历史时，这尤其有用。本文将介绍代码仓库规则的适用场景、如何写好这些规则，以及我们在测试中获得的经验。
交付更多代码
编程智能体能够承担更大规模的变更，持续处理耗时更长的工作，帮助团队将更多想法变成代码。在 OpenAI，每周 PR 数量自第四季度以来已增至两倍以上，我们也在许多客户中看到了类似趋势。更多代码是件好事：它帮助团队交付新功能、解决更多问题。但这也意味着有更多 Pull Request 等待熟悉审查要点的人来处理，代码审查很快就可能成为瓶颈。
多项变更同时到来时，审查会变得更难。一份代码差异看起来可能完全合理，却仍然会导致旧版客户端出错，或越过作者并不了解的边界。需要有人记得这些背景，并在作者还来得及据此调整时分享出来。
审查瓶颈
当更多 Pull Request 到来时，审查者在给出反馈前，用来理解每项变更意图、收集相关背景的时间就更少了。一旦作者转去处理其他工作，即使是小幅修改也可能花更长时间。及时反馈能帮助团队充分发挥开发提速的优势，避免让人工审查成为瓶颈。
有些问题也很难仅凭代码差异发现。重命名响应字段看起来可能只是常规清理，却可能导致仍依赖现有契约的客户端出错。经验丰富的审查者也许记得为什么必须保留这个字段；新贡献者或首次处理该服务的智能体则很可能不知道。
以规则为接口
那么，如何让编程智能体掌握团队通常需要长期积累才能了解的背景？新的代码仓库规则接口让您可以在 AGENTS.md 中写入简明且适用范围明确的审查指导。Codex 代码审查可以应用与某项变更相关的规则，并在审查意见中引用它们。您可以将这些说明放在适用代码附近，无需在每个 Pull Request 中反复解释。
随着编程模型越来越容易通过指令引导，一条简短、适用范围明确的指令就能帮助模型在漫长的审查中聚焦团队真正关心的问题。Codex 自身的代码仓库也将代码审查规则保存在 AGENTS.md 中，涵盖模型可见的上下文、破坏性变更等方面。
下面是一个真实示例：
Codex app-server 会发出名为 rawResponseItem/completed 的内部通知。它被标记为实验性功能，但 Codex 云端已经在使用它。代码仓库中的破坏性变更审查规则明确指出，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 云端的使用方会监听这个传输层名称，因此即使该事件是实验性的，重命名也会导致它们无法正常工作。请按照AGENTS.md中的说明，保留现有名称，或添加一个向后兼容的事件。
Codex 团队专门添加了这条规则，以保护 Codex 云端的使用方。将适用于整个代码仓库的规则放在根目录，将服务专用规则放在相关目录。审查时，Codex 可以应用适用于已更改文件的指导，并向作者指出相关规则；无关的变更不需要 app-server 的背景信息。
规则可以与团队已经依赖的其他工具配合使用。对于能够用确定性逻辑表达的检查，测试和代码检查工具很有效；代码仓库规则则有助于记录那些较难用代码表达的判断依据。兼容性要求和数据边界都是不错的起点。作者无需在变更前了解过去的每一次事故或代码各处的约定，相关指导已经写在那里。
编写经得起检验的规则
我们使用包含已知违规情况和安全反例的评测套件，测试代码审查利用代码仓库指导的效果。在主要评测套件中，使用规则指导的方案检出了 98% 的预期自定义问题，而基线对照组为 58.3%。
发现违规情况只是工作的一部分。我们还想了解，当多条规则需要同时关注，或一个 Pull Request 已经包含大量变更时，会发生什么。我们既测试了影响重大的违规情况，也测试了不应提出问题的变更，然后围绕四个问题整理结果：
我们的评测内容
覆盖能力
当代码差异繁杂、多条规则需要同时关注时，Codex 能否发现预期的违规情况？
克制程度
对于没有问题的变更和合理的例外情况，能否避免提出不必要的审查意见？
原有能力保持
代码审查能否继续发现代码仓库规则未涵盖的常规缺陷？
可操作性
每条审查意见是否指出了相关指导、问题位置和优先级？
我们还尝试了常见的指导编写方式，从简短的要点列表到由特定团队负责的章节。
在内部代码仓库中使用规则时，我们也发现了同样的规律。Codex 能够找到并引用默认审查可能遗漏的代码仓库内的指导，但宽泛的指令很容易产生干扰信息。数量少、范围明确且写清安全做法的规则集，有助于 Codex 聚焦最有价值的问题，而不是将一条规则套用到附近的每项变更上。
从重要但不明显的不变条件入手。 将审查者反复解释的检查项写成规则，例如兼容性要求或数据边界。如果删除某条规则不会影响审查，就不必保留它。
让规则的适用范围与其约束的代码一致。 将适用于整个代码仓库的指导放在根目录，将服务专用指导放在子目录的 AGENTS.md 中。缩小范围可以避免无关指令分散注意力，也能明确由谁负责。
说明不变条件和安全做法。 rawResponseItem/* 规则指出了兼容性风险。“保留现有名称，或添加一个向后兼容的事件”为作者提供了明确的替代方案。
让规则长期有效，并及时维护。 描述预期结果，而不是可能变化的函数名称。审查规则的更新，并缩小反复产生干扰信息的指导的适用范围，或将其删除。
将格式检查和其他机械性检查留在 CI 中。代码仓库规则应当用来回答审查者原本需要反复追问的问题。
入门
如果您的代码仓库已经启用 Codex 代码审查，请在适用的 AGENTS.md 文件中添加两三条规则，并创建一个有代表性的 Pull Request。如果您刚开始使用代码审查，代码审查快速入门介绍了如何为 GitHub 代码仓库启用该功能。您也可以通过 @codex review 直接请求审查。
从审查者反复给出的解释入手，或选择一种代码仓库特有、遗漏后会造成重大影响的错误。尝试一项应触发规则的变更、一个安全反例和一项无关变更。确认第一项能产生有用的审查意见，而其余两项不会产生干扰信息，再根据观察结果完善指导。
Codex 代码审查仍然是一位补充审查者；测试、分支保护和必需的审批继续提供强制保障。
如果您发现自己审查变更的时间比编写变更还多，不妨从团队反复执行的一项检查开始。将它添加到 AGENTS.md 中，并在下一个 Pull Request 中试用 Codex 代码审查。