Codex 做代码审查：如何让 AI 帮你 Review PR，而不是乱改代码

一个 800 行的 PR,标题只写 fix,描述里一句”修了一些问题”就没了。你盯着 diff,不确定哪里是改动重点,也不想逐行翻完整个文件列表。有人在 PR comment 里写了 @codex review for auth bypass and PII logging,几分钟后 inline comment 出现一条指向 logger.info(user.email) 的提示。

你得决定:让 Codex 自动 fix、自己改,还是先问一下业务方这条日志是不是合规。这篇会讲清楚触发条件、Review guidelines 写法、P0/P1 含义、处理流程和人工确认边界。

@codex review 不是一句万能咒语

@codex review 不是让 AI 自动改代码的开关。它只是请求 Codex 读一遍 PR diff,按你的规则发布 review comments。能不能触发、触发后做什么、review 结果怎么处理,都依赖前置条件和人工判断。

GitHub Cloud 触发与设置

用 Codex 做 code review 的前置条件:repository 已设置 Codex Cloud,你有访问 code review settings 的权限。触发方式有两种:在 PR comment 中写 @codex review,或在 settings 里开启 Automatic reviews,让 Codex 在新 PR opened for review 时自动发布 review。

触发后 Codex 会读取 PR diff、遵循 repository guidance(写在 AGENTS.md 里的 Review guidelines),以标准 GitHub code review 形式发布 inline comments。@codex review 不等于 approval,Automatic reviews 不等于自动通过。敏感变更(auth、payment、data migration)仍需人工确认。

你可以在 PR 触发器和 CI 流水线中配置 branch protection 规则,确保 AI review 只是其中一道检查。关于 PR 触发器的配置,参考之前的文章 GitHub Actions PR 触发器基础。

P0/P1 聚焦,而不是流水账

Codex 默认只标记 P0/P1 优先级的问题。P0 是阻断性问题:security regressions、auth bypass、data loss。P1 是需要修复的问题:performance、concurrency、logging sensitive data。

KiloClaw - 企业级 OpenClaw 托管服务，赋能 AI Agent 自动化编排与智能模型路由

立即开始 →推广

这种聚焦是为了避免 review comments 数量爆炸、保持高信号检查、减少低价值噪音。你可以在 AGENTS.md 的 Review guidelines 小节里覆盖默认规则,例如只看 auth bypass、PII logging、concurrency,不关注 code style(交给 Prettier)或 minor performance(非热点路径)。下一节会展开 Review guidelines 的具体写法。

Review guidelines 写在 AGENTS.md,而不是 PR comment

Review guidelines 决定了 Codex review 的聚焦点和优先级。它应该写在 repository 的 AGENTS.md 文件里,而不是每次 PR comment 都重复一遍。

AGENTS.md 分层读取与 Review guidelines 写法

Codex 在开始工作前会读取 AGENTS.md。读取顺序从 Git root 到当前工作目录逐层扫描,更近目录的指导更具体。例如 auth/ 目录下的 AGENTS.md 可以覆盖全项目规则,只关注 auth 相关风险。

一个典型的 Review guidelines 小节:

## Review guidelines

只关注以下风险:
1. Security regressions(auth bypass、path traversal)
2. PII logging(user.email、phone number)
3. Concurrency issues(race condition、deadlock)

不关注:
- Code style(用 Prettier 自动化)
- Minor performance(非热点路径)

这种写法的优势:所有 PR 共享一套规则,避免每次 comment 重复;changed file 所在目录的 AGENTS.md 可以更具体。

需要注意指令文件长度受 project_doc_max_bytes 限制(默认 32 KiB),过长的文件会被截断。AGENTS.md 的完整写法(包括 Project rules、Review guidelines、Coding style)会在 Codex 实战指南的其他文章中展开。本篇只聚焦 Review guidelines 的结构和优先级控制。

Codex app review pane:看清 diff 再决定

Codex app 的 review pane 不是只显示 AI 的改动建议,它反映的是 Git repository 的完整状态。默认聚焦 uncommitted changes,也可以切换到 all branch changes 或 last turn changes。

Inline comments 与 PR context

Review pane 里的 inline comments 直接挂在 diff 行上。你可以基于这些精确反馈决定下一步:让 Codex fix、自己改、还是标记 false positive。执行 /review 后,结果会以 inline comments 形式显示在 review pane 中。

如果 Codex 有 GitHub access 且当前项目在 PR branch 上,app 可以展示 PR context:reviewer feedback、changed files、PR description。前提是已安装并认证 GitHub CLI:gh auth login。缺失时 PR details 可能不出现,只能看到本地 diff。

粒度控制:按 file 或 hunk stage/revert,不要整个 commit revert

Review pane 支持按 entire diff、file、hunk 级别 stage/unstage/revert。不建议一看到 findings 就整个 commit revert,尤其是多 file 改动的场景。按 hunk 粒度处理可以保留安全的改动,只撤销有风险的部分。

处理 review findings:@codex fix 后看 diff、CI、测试,不要自动合并

发现 P0/P1 后,不要直接交给 @codex fix 就完事。你需要判断这个 finding 是否属实、修复方案是否合理、敏感变更是否需要团队确认。

🔥 别在没有需求的产品上白干3个月！用一顿饭的预算，在 Adsterra 快速验证你的 SaaS 卖点 →

立即测试 →推广

Review findings triage 判断表

处理 findings 的可执行流程

确认 finding 是否属实:看 inline comment 指向的 diff 行,确认问题是否真实存在。

判断修复边界:auth、payment、data migration 属敏感变更,必须人工确认;style、minor perf 可忽略或交给工具链。

选择处理方式:

• 让 Codex fix:在 PR comment 中写 @codex fix the P1 issue,Codex 会基于 PR context 启动 cloud task
• 自己改:手动编辑代码,本地测试后再 push
• 要求补测试:开 follow-up issue 或在 comment 中说明
• 标记 false positive:在 comment 中说明原因,避免后续重复报

看 diff 和 CI:即使 @codex fix 有权限 push 回 PR branch,也要看 diff、CI 结果、测试覆盖。Codex 的 fix 不等于自动合并,更不等同于 CI 通过或人工 reviewer approve。

敏感变更人工确认:auth bypass、payment flow、data migration 涉及安全边界,需团队 reviewer 认。不要跳过人工检查。

不要做的事

• 不要自动 push/merge:@codex fix 只是请求 AI 改代码,不是合并许可
• 不要跳过 CI 检查:即使 Codex fix 了问题,CI 仍需运行,确保改动不破坏其他测试
• 不要忽略人工 reviewer 意见:AI review 是第二道检查,不是替代团队 reviewer
• 不要给 Codex 过大权限:main branch push、force push、敏感目录 write access 都应限制

敏感变更的安全边界和权限控制会在 Codex 实战指南的后续文章(安全权限与 Secrets 管理)中展开。关于 CI 流水线的最佳实践,参考之前的 GitHub Actions CI 流水线。

commit message 与 PR description:让 AI 写文案,但不要乱造规范

@codex generate commit message 或 @codex generate PR description 可以让 Codex 基于 diff 和 PR context 生成文案。生成后要人工审核,不要直接 commit。commit message 应遵循 Conventional Commits 规范,不要自己造格式。

Conventional Commits 规范与 commit message 模板

Conventional Commits 格式:<type>[optional scope]: <description>。常见 type:fix 对应 PATCH 版本,feat 对应 MINOR 版本,BREAKING CHANGE footer 或 ! 表示破坏性变更(MAJOR)。

示例:

Vultr - 高性能 NVMe 云服务器，32 个全球节点可选，支持一键部署 Docker

查看定价 →推广

fix(auth): prevent bypass in login flow

- Add session validation before auth redirect
- Reject expired tokens within 5 minutes

Refs: #123

为什么用 Conventional Commits:它是广泛采用的标准,工具链(semantic-release、auto-changelog、commitlint)依赖这个格式自动生成 changelog、判断版本号。自己造规范会导致工具链失效,团队协作成本增加。

PR description 模板

PR description 至少包含五个部分:

1. 背景:为什么做这个改动(用户反馈、性能问题、安全风险)
2. 改动范围:哪些模块受影响(auth、payment、logging)
3. 测试:已验证的场景(本地测试、CI 覆盖、手动验证)
4. 风险:已知边界条件(并发场景、大流量下的表现)
5. 回滚:如何快速回滚(revert commit、feature flag、config toggle)

Codex 生成后,检查这五部分是否完整、描述是否准确、风险和回滚是否遗漏。不要直接 commit 生成的文案,尤其是涉及敏感变更时。

关于 commit message 和 PR description 的生成策略,可以在 PR comment 中写具体的指令,例如 @codex generate commit message following Conventional Commits,让 AI 按标准格式生成。

总结

Codex review 是第二道高信号检查,不是 merge 许可。@codex review 只是请求 AI 读一遍 diff,发布 inline comments;Automatic reviews 只是把触发步骤自动化,不等同于 approval 或合并。

核心流程:

1. 在 AGENTS.md 的 Review guidelines 中聚焦 1-2 个风险(auth bypass、PII logging、concurrency),不要追求大而全
2. P0/P1 是默认聚焦,避免 review comments 爆炸。P0 必须修复,P1 需判断处理方式
3. 发现 finding 后,看 inline comment 指向的 diff 行,确认问题是否属实。敏感变更(auth、payment、data migration)必须人工确认
4. @codex fix 后仍需看 diff、CI 结果、测试覆盖和人工判断。不要自动 push/merge,不要跳过 CI,不要忽略人工 reviewer 意见
5. commit message 用 Conventional Commits 规范,不要乱造格式。工具链依赖标准格式自动生成 changelog 和判断版本号

行动建议:

• 为你的仓库添加 AGENTS.md,写一段 Review guidelines,只关注 1-2 个风险
• 在下一个 PR 中尝试 @codex review,看 inline comments 是否符合你的规则
• 敏感变更场景,先用 Codex 实战指南的后续文章(安全权限与 Secrets 管理、改坏代码与验收复盘)深入理解边界,再决定是否用 @codex fix

相关文章

• GitHub Actions PR 触发器基础:配置 PR 触发器和 branch protection 规则
• GitHub Actions CI 流水线最佳实践:CI 流程中的检查和人工 reviewer 职责
• AI 编程助手横评:Claude Code vs Cursor vs Copilot:AI 编程工具选型对比