如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
Jul 20, 2026 Codex

为 Codex 自定义代码审查规则

为 Codex 提供更具体的规则,帮助它在代码审查中发现问题,更好地遵循团队约定。

作者: Hari Srikanth

为 Codex 自定义代码审查规则

使用 Codex 审查代码时,有些意见会反复出现。审查者可能需要提醒作者保留旧版 API 契约、避免将客户数据写入日志,或指出某次重命名会导致其他服务出错。这些检查很重要,但如果只有少数审查者了解背后的原因,其他人就很容易漏掉它们。

现在,Codex 代码审查可以根据 AGENTS.md 中的自定义代码仓库规则发现这类问题,并向作者指出审查意见的依据。如果您已经使用 AGENTS.md 来指导编码任务,同一个文件也可以用来指导代码审查。当贡献者或编码智能体修改代码仓库中不熟悉的部分、还不了解相关历史时,这一点尤其有用。本文将结合我们的测试经验,介绍代码仓库规则适合解决哪些问题,以及如何编写有效的规则。

交付更多代码

编码智能体可以承担规模更大的改动,也能持续处理耗时更长的任务,让团队把更多想法写成代码。自第四季度以来,OpenAI 每周的 PR 数量已增长到原来的两倍以上。我们也在许多客户那里看到了类似的趋势。更多代码有助于团队推出新功能、解决更多问题。这也意味着更多 pull requests 在等待熟悉审查要点的人处理,代码审查很快就可能成为瓶颈。

三个季度中每周 PR 数量的上升趋势

多项改动同时提交时,审查会变得更困难。一项改动从代码差异上看可能完全合理,却会导致旧版客户端出错,或越过作者并不知情的边界。需要有人记得这些背景,并在作者还来得及调整时提醒对方。

代码审查的瓶颈

提交的 pull requests 越多,审查者在给出反馈前就越难抽出时间弄清每项改动的目的、收集相关背景。一旦作者转去处理其他任务,即使只需小改一下,也可能花费更长时间。及时反馈能让团队充分享受开发提速的好处,避免大家都卡在等待人工审查这一步。

有些问题仅看代码差异也很难发现。重命名一个响应字段可能看起来只是例行清理,却会导致仍依赖现有契约的客户端出错。有经验的审查者也许记得为什么必须保留这个字段,新贡献者或第一次修改这项服务的智能体往往并不清楚。

通过规则传递审查要求

团队成员平时靠经验逐渐熟悉的背景知识,怎样才能让编码智能体也了解?通过新的代码仓库规则接口,您可以在 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 能找到并引用默认审查可能忽略的局部规则,但范围过宽的指令很容易产生无关的审查意见。只保留少量规则,限定各自的适用范围,并明确安全的做法,有助于 Codex 聚焦于最有用的问题,避免把一条规则套用到附近的每一处改动上。

先写下容易忽略、违反后会造成严重后果的约束。 把审查者反复解释的检查项写成规则,例如兼容性要求或数据边界。如果去掉某条规则并不会影响审查结果,就无需保留它。

让规则的适用范围与代码对应。 将适用于整个代码仓库的审查要求放在根目录中,将特定服务的要求写入相应子目录的 AGENTS.md。限定范围既能减少无关指令的干扰,也能让人清楚该由谁维护规则。

说明必须满足的约束,以及怎样改才安全。 rawResponseItem/* 规则指出了兼容性风险。“保留现有名称,或添加一个向后兼容的事件”则让作者知道有哪些可行的做法。

让规则经得起代码变化,并及时更新。 写清楚需要保证的结果,避免依赖可能变化的函数名。审查对规则本身的修改。对于反复产生无关意见的规则,请缩小其适用范围或将其移除。

代码格式等机械性检查继续由 CI 处理。代码仓库规则应留给那些原本需要审查者反复过问的问题。

开始使用

如果您的代码仓库已启用 Codex 代码审查,请在适用的 AGENTS.md 文件中添加两三条规则,然后创建一个有代表性的 pull request。如果您是第一次使用代码审查,代码审查快速入门介绍了如何为 GitHub 代码仓库启用这项功能。您也可以使用 @codex review 直接请求审查。

先从审查者反复给出的说明入手,或挑一个代码仓库特有、漏掉就会造成严重后果的错误。选三项改动来测试规则:一项应触发规则,一项作为安全的反例,一项与规则无关。确认第一项得到了有用的审查意见,另外两项都没有引发多余的意见,然后根据结果完善规则。

Codex 代码审查可以为团队多提供一位审查者。测试、分支保护和必需的审批仍负责强制执行相关要求。

如果您花在审查改动上的时间已经超过编写代码的时间,可以先选一项团队反复执行的检查,将它写入 AGENTS.md,然后在下一个 pull request 中试用 Codex 代码审查。