用 Codex 做代码审查

看到 OpenAI 新发的《Custom Code Review rules for Codex》时，我一开始以为它讲的是 GitHub PR 里的 @codex review。实际试着梳理文档后才发现，Codex 里至少有三种容易混在一起的代码审查入口：交互式 /review、非交互式 codex review，以及 GitHub PR 中的云端审查。

它们都叫 Code Review，但运行位置、输入范围和输出去向并不相同。AGENTS.md 又在其中增加了一层：除了告诉 Codex 怎样写代码，现在也可以告诉它审查时要特别留意什么。

三种 Code Review 入口

先说结论：本地使用 Codex 做代码审查，不受代码托管平台限制；如果想让它直接在 PR 里触发审查并回写评论，目前官方只提供了 GitHub 集成。

入口	运行位置	审查对象	是否依赖 GitHub
`/review`	Codex CLI、IDE 扩展、桌面 App	未提交修改、基础分支 diff、当前仓库	否
`codex review`	Shell、脚本、CI	未提交修改、基础分支、指定 commit	否
`@codex review` / Automatic reviews	Codex Cloud + GitHub PR	Pull Request diff	是

交互式 `/review`

在 Codex 里看到下面的命令提示：

/review

Codex 会让你选择审查范围。CLI、IDE 扩展和桌面 App 的具体界面略有不同，但常见选项包括：

审查当前未提交的修改
与某个基础分支比较
审查指定 commit
输入自定义审查要求

这个命令要求当前项目位于 Git 仓库中。它会启动一个专门的 reviewer，读取选定的 diff，给出带优先级、可以采取行动的 findings，默认不会修改工作区。

这意味着，无论代码托管在 GitLab、Bitbucket 还是 Gitea，甚至根本没有接入代码托管平台，都可以用 /review 检查本地 Git diff。它依赖的是 Git 仓库，不是 GitHub API。

非交互式 `codex review`

如果不想进入交互界面，可以直接从 Shell 运行审查：

# 审查 staged、unstaged 和 untracked 变更
codex review --uncommitted

# 审查当前分支相对 main 的变化
codex review --base main

# 审查某个 commit 引入的变化
codex review --commit 8f41c2a

也可以把一段自定义要求作为 prompt 传入：

codex review "重点检查向后兼容性、日志中的敏感数据和错误处理"

这里有一个容易踩的边界：--uncommitted、--base、--commit 和自定义 prompt 是互斥的，一次只能选择一个审查目标。脚本需要更复杂的组合时，最好先用 Git 明确生成要审查的范围，再分次调用，而不是把几个参数硬塞在一起。

codex review 适合放进本地 Git hook、团队脚本或 CI。不过“运行 Codex 得到 findings”和“把 findings 发布成 GitLab MR inline comments”是两件事。后者仍需要自己调用代码托管平台的 API。

GitHub PR 中的 `@codex review`

GitHub 原生集成提供的是另一套体验。仓库配置好 Codex Cloud 并开启 Code Review 后，可以在 PR 评论中写：

@codex review

Codex 会读取 PR diff，像团队成员一样发布标准 GitHub Review。目前 GitHub 模式只报告 P0 和 P1 问题，目的是把评论集中在高优先级风险上。还可以在设置里开启 Automatic reviews，让新 PR 自动触发审查。

如果只想临时增加一个检查重点，可以写：

@codex review for security regressions

发现问题后，还能继续在同一个 PR 里要求 Codex 修复：

@codex fix the P1 issue

截至本文写作时，OpenAI 官方文档只明确描述了 GitHub 的这套 PR 触发、自动审查和回写流程。GitLab 或 Bitbucket 仓库仍然可以在本地使用 /review 或 codex review，但若要获得同样的 Merge Request 机器人体验，需要自行搭建 CI 和评论回写。

用 AGENTS.md 保存“只有老 reviewer 才知道”的规则

默认代码审查能发现通用 bug，却不知道每个仓库的历史。比如：

某个看似 experimental 的事件已经被线上客户端使用
某类日志绝不能出现客户标识符
一个旧字段拼写虽然不理想，却已经成为外部协议的一部分
某个服务只能通过指定的兼容层访问数据库

这些知识经常只存在于少数 reviewer 的记忆里。新成员看到 diff 时，很难从代码本身推导出背后的事故和兼容性要求。

Codex Code Review 现在可以从 AGENTS.md 中读取专门的审查规则。仓库级规则放在根目录；只适用于某个服务的规则，放在离相关代码最近的嵌套 AGENTS.md 中：

repo/
├── AGENTS.md
└── services/
    └── payments/
        ├── AGENTS.md
        └── src/

可以在文件里增加 ## Code Review Rules：

## Code Review Rules

### API compatibility

- Treat existing JSON field names and webhook event names as public contracts.
  Safe path: preserve the old name, or add a backward-compatible alias and a migration test.

### Customer data

- Do not write account IDs, email addresses, access tokens, or raw request bodies to logs.
  Safe path: use the existing redaction helper and log an opaque request ID.

这段规则有两个值得保留的写法。

第一，它描述的是稳定结果，而不是某个可能下个月就改名的函数。第二，它不只说“不要做什么”，还给出 safe path。Codex 因此能区分真正的违规和合理例外，也能告诉作者应该怎样修改。

OpenAI 文章里的真实例子来自 Codex app-server。它有一个名为 rawResponseItem/completed 的通知，虽然标记为 experimental，却已经被 Codex Cloud 使用。把它清理成更顺眼的 rawResponseItem/done 可以正常编译，却会让现有消费者收不到事件。

这种问题很难靠编译器发现，也不一定已经有完整的契约测试，但资深 reviewer 会知道不能随便改。它正适合进入仓库审查规则。

什么应该写进规则，什么应该留在 CI

AGENTS.md 不是另一套 linter 配置。可以确定性表达的要求，继续交给 CI：

格式化
lint
类型检查
单元测试和集成测试
schema 校验
secret scanning

审查规则更适合那些需要项目背景和判断力的问题：

向后兼容性
数据边界
不明显的副作用
跨服务集成约束
审查者反复解释的历史原因

判断一条规则值不值得加入，可以问一个简单的问题：删掉它，会不会改变审查结果？ 如果不会，它多半只是在增加上下文噪音。

规则也不是越多越好。根目录的宽泛规则会影响整个仓库，容易和真正相关的要求争夺注意力。服务专属约束应该尽量下沉到对应目录，并定期删除反复产生误报、已经过时或已经被 CI 接管的规则。

规则有效不能只看“命中过一次”

OpenAI 用包含已知违规和安全反例的 eval suite 测试了自定义规则。在主要评估集中，规则引导版本找回了 98% 的必需自定义 findings，基线是 58.3%。这个数字说明仓库上下文确实能帮助 Codex 找到默认审查容易遗漏的问题，但它不能单独证明规则写得好。

完整评估还要看四个维度：

维度	要检查的事情
Coverage	diff 很忙、规则很多时，应该发现的问题有没有被发现
Restraint	干净变更和合法例外是否避免了多余评论
Retention	加入自定义规则后，普通 bug 是否仍能被发现
Actionability	finding 是否指出位置、风险、规则和安全修改路径

所以每加一条规则，至少准备三个例子：

一个必须触发的违规
一个不应触发的安全反例
一个与规则无关的变更

只拿第一个例子跑通，很容易得到一条“到处都能命中”的宽泛规则。后两个例子才真正检验它是否克制。

一套比较实际的审查流程

如果团队已经同时使用本地 Codex、CI 和 GitHub，可以把它们放在不同层次，而不是让几种检查互相重复：

开发过程中：用 /review 检查未提交修改，尽早发现明显问题。
提交前或脚本中：用 codex review --base main 做一次完整分支 diff 审查。
CI 中：运行测试、lint、类型检查和其他确定性门禁。
GitHub PR 中：用 @codex review 或 Automatic reviews 检查高优先级问题，并应用 AGENTS.md 中的仓库规则。
合并前：保留 branch protection 和必要人工审批。

这里最重要的边界是：Codex Code Review 仍然只是一名额外 reviewer。自然语言规则可以把团队经验带进审查，但不能替代测试、分支保护和 required approvals。

总结

/review 解决的是本地 Git diff 审查，codex review 提供非交互入口，@codex review 才是目前与 GitHub PR 深度集成的云端体验。把三者分开以后，Codex Code Review 的适用范围就清楚了：本地能力不绑定代码托管平台，原生 PR 自动化目前绑定 GitHub。

AGENTS.md 的价值也不只是“给 Agent 写编码规范”。更值得写进去的，是那些后果严重、不容易从 diff 看出来、又总要靠资深 reviewer 重复解释的项目约束。规则写得少一点、作用域窄一点，并把安全路径说清楚，通常比一份巨大的审查清单更有用。

三种 Code Review 入口

交互式 /review

非交互式 codex review

GitHub PR 中的 @codex review