Codex Code Review 工作流：让 AI 帮你审 PR

30 秒了解：让 AI 审 PR 到底有用吗

Codex Code Review 的核心场景：每个 PR 一开就触发 Codex 自动审一遍，写一段评论指出明显的 bug / 安全问题 / 风格不一致——人审之前先过一轮 AI 筛。 这不是「让 AI 决定 merge」，而是「让 AI 当初审同事，把低级问题先挑出来」。

为什么 Code Review 是 AI 的好场景？

任务有边界（只看这一个 PR 的 diff）
输入清晰（diff + 项目上下文）
输出格式固定（一段评论 / 分点列表）
人最终拍板，AI 错了没大事
解放人审 review 精力做架构判断

但「让 AI 审 PR」也有自己的雷区：AI 容易给出无价值的「样板评论」（「建议加注释」「考虑性能」）、容易过分挑刺、容易漏掉真正的业务逻辑问题。关键在于 prompt 怎么写、规则怎么订。

这篇按 OpenAI cookbook 的 build_code_review_with_codex_sdk 例子 + 实战，给你一份完整的 Codex Code Review 工作流。前置阅读：Codex 是什么。

准备工作：先想清楚 3 件事

1. AI Review 不替代人 Review

AI Review 的定位是「过一遍筛 + 引出讨论点」，不是替代人。Merge 决策必须人做。如果团队对此没共识，先开 30 分钟会对齐再开始配置——免得部署后吵架。

2. Codex SDK 跟 Codex CLI 是两回事

Codex CLI：你本机终端跑的命令行工具
Codex SDK：跑在 CI / 服务端的代码库，让你能写脚本调 Codex 能力

Code Review 自动化用 Codex SDK，不是 CLI。装法：

npm install @openai/codex-sdk
# 或
pip install openai-codex-sdk

3. 团队的 review 标准要文档化

让 AI 审之前，得告诉它「我们认为好的代码长什么样」。把团队约定写进文档（最好就是 AGENTS.md / CONTRIBUTING.md），AI 才能审得贴。

第 1 步：写一份 `.codex/review-rules.md`

review 规则文件相当于「给 AI 看的 review 检查表」，长这样：

# Codex Review Rules

## 必须报告的问题（红线）

- 任何 SQL 注入风险（拼接 user input 进 SQL）
- 硬编码 secret（API key / token / password）
- 删除测试或降低测试覆盖率
- 未处理的 promise rejection / 漏掉 await
- 已知有内存泄漏的写法（setInterval 不 clear 等）
- 改了 prisma schema 但没加 migration
- 改了 API 接口但没更新前端调用

## 建议关注的问题（黄线）

- 复制粘贴的代码（明显的 DRY 违反）
- 函数超过 50 行
- 圈复杂度过高的函数
- console.log / debugger 残留
- 任何 TODO/FIXME 注释
- 直接改 production config

## 不要报告的（避免噪音）

- 单纯的代码风格（有 prettier / eslint 管）
- 「建议加注释」这种空泛建议
- 已经在 prettier 范围内的格式问题
- 现存的、跟本 PR 无关的问题

## 评论格式

每条评论按这个结构：

[级别: 🔴 红线 / 🟡 黄线 / 💡 建议]
[问题简述]
[文件:行号]
[为什么是问题]
[建议改法]

## 整体评论

PR 末尾加一段总评：

- 总体风险评估（低 / 中 / 高）
- 必须改的项数量
- 建议关注的项数量
- 给人审 reviewer 的提示：重点看什么

这份文件比 prompt 本身更重要——它决定了 AI review 的「品味」。规则越清晰，AI 越靠谱。

第 2 步：写自动化触发的 GitHub Actions

在 .github/workflows/codex-review.yml：

name: Codex Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get PR diff
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > /tmp/pr.diff
          echo "Diff size: $(wc -l < /tmp/pr.diff) lines"

      - name: Run Codex Review
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          node scripts/codex-review.js \
            --diff /tmp/pr.diff \
            --rules .codex/review-rules.md \
            --pr $PR_NUMBER

scripts/codex-review.js 大致逻辑：

import { CodexClient } from '@openai/codex-sdk';
import fs from 'fs';

const diff = fs.readFileSync('/tmp/pr.diff', 'utf-8');
const rules = fs.readFileSync('.codex/review-rules.md', 'utf-8');

const client = new CodexClient({ apiKey: process.env.OPENAI_API_KEY });

const review = await client.review({
  diff,
  rules,
  context: { repo: process.env.GITHUB_REPOSITORY }
});

// 把 review 评论 post 到 PR
await postToGitHub(process.env.PR_NUMBER, review);

具体 API 以 Codex SDK 最新文档为准。

第 3 步：给 Codex 写「Review Prompt」

scripts/codex-review.js 里给 Codex 的 prompt 决定 review 质量。一份能用的 prompt：

📋 Prompt 模板

你是这个项目的 senior code reviewer。下面是一个 Pull Request 的 diff，请按规则审查。

review-rules.md 的内容如下：

[这里注入 review-rules.md 内容]

项目上下文（AGENTS.md）：

[这里注入 AGENTS.md 内容]

PR diff：

[这里注入 diff]

review 时遵循：

严格按 review-rules.md 的「必须报告」「建议关注」「不要报告」三档分类
每条评论必须指明文件:行号 + 为什么是问题 + 建议改法
不要给「样板评论」（“建议加注释”、“考虑性能”这种）
不要重复 lint / prettier 已经管的问题
关注业务逻辑、安全、可维护性 > 关注代码风格

输出格式：

总评

风险等级：[低/中/高]
必须改：N 项
建议关注：M 项
给人 reviewer 的提示：[2-3 句话]

红线问题（必须改）

[按 review-rules.md 格式]

黄线问题（建议关注）

[按 review-rules.md 格式]

建议

[按 review-rules.md 格式]

如果整个 PR 干净，输出「无问题，建议人 review 关注：[2-3 个值得讨论的设计点]」。

注意几个关键设计：

「不要给样板评论」明确写出来——这是 AI review 最大的痛点
输出格式固定——便于程序化处理（也便于看）
「干净 PR」也要有输出——告诉人 reviewer 该看啥

第 4 步：第一次试跑

开一个故意有 bug 的 PR 试链路：

新 branch test-codex-review
故意改一个文件加几个明显的问题（如硬编码 API key、SQL 拼接、删个测试）
提 PR
等 Codex Review 工作流跑
看 PR 评论里 Codex 写的 review 对不对

第一次大概率有问题——格式乱、漏掉明显 bug、加了无意义建议。按结果调 review-rules.md 和 prompt，跑 2-3 次就稳了。

第 5 步：用「人 review 时怎么用 AI review」

Codex 提的评论不要无脑接受或忽略。建议团队约定：

AI 评论级别	人 reviewer 该做什么
🔴 红线	必须确认；同意 → 让作者改；不同意 → 解释为什么忽略
🟡 黄线	自由判断；同意可以让改，不影响 merge
💡 建议	当成 nice-to-have；不阻塞 merge
总评	当成 review 起点，重点关注 AI 提到的 2-3 个设计点

「人确认 AI 评论」这一步不能省——AI review 必然有假阳性，靠人筛掉。

4 个 Code Review Prompt 模板

模板 1：聚焦安全的 review

📋 Prompt 模板

请只 review 安全相关的问题，忽略其他：

SQL 注入 / NoSQL 注入
XSS 风险
CSRF 漏洞
硬编码 secret
不安全的依赖
权限校验缺失
路径遍历漏洞
每条评论格式：[严重程度] [文件:行号] [漏洞类型] [攻击场景] [修复建议]
无安全问题就输出「无安全风险，主要变更是 X，建议人 reviewer 重点看 Y」。

模板 2：聚焦性能的 review

📋 Prompt 模板

请只关注性能问题：

N+1 查询
循环里跑昂贵操作
无谓的数据库往返
大数据量没分页
同步阻塞主线程的操作
内存泄漏风险（setInterval/listener 没清）

不要管代码风格、注释、命名。

模板 3：聚焦测试覆盖的 review

📋 Prompt 模板

请评估这个 PR 的测试覆盖情况：

新加/改的函数有没有对应测试
测试是否覆盖正常路径 + 边界情况 + 错误路径
有没有 mock 写错或 mock 过度
有没有降低整体覆盖率

输出：测试评分（A/B/C/D）+ 改进建议。

模板 4：聚焦架构一致性的 review

📋 Prompt 模板

请检查这个 PR 是否符合项目架构约定（见 AGENTS.md）：

新代码是否放在对的目录
命名是否符合项目约定
是否绕开了既有抽象层
是否引入了未来难维护的耦合
是否引入了团队没用过的新依赖

不要管细节代码风格。

常见坑 + 解决办法

现象	原因	解决
AI review 全是样板话	prompt 没明确禁止	加「不要样板评论」+ 给反例
AI 漏掉明显 bug	上下文不够（diff 太大或没给 AGENTS.md）	大 PR 分段审、必给项目上下文
AI 评论太多噪音	「建议关注」标准太松	收紧 review-rules.md
AI 重复评论同一个问题	diff 里同样模式多处出现	prompt 加「同类问题只报告 1 次」
API 费用爆	每次 push 都触发	加 debounce、跳过 draft PR

Codex Code Review vs GitHub Copilot Review

维度	Codex Review (SDK 自建)	GitHub Copilot Review
灵活度	高（自己写规则）	中（用 GitHub 默认）
部署成本	要写脚本 + 配 Secret	一键开启
模型	GPT-5 codex	取决于 Copilot 版本
跟团队约定贴合度	高（自己定 rules）	中
适合	中大型团队、有特殊 review 要求	小团队、能用默认就行

详见 GitHub Copilot 是什么。

下一步

Codex 整体介绍 → Codex 是什么
Codex CLI 上手 → Codex CLI 怎么用
Codex 改老代码 → Codex 改写老代码
Codex 自动修 CI → Codex 修 CI
Codex 长任务规划 → Codex PLANS.md 怎么写
GitHub Copilot 对比 → GitHub Copilot 是什么
AI 编程全景 → AI 写代码完全指南

常见问题

Q：让 AI 审 PR 会不会替代代码 reviewer 同事的工作？ A：不会，至少这一代 AI 不会。AI 擅长「机械、可枚举」的检查（安全模式、复制粘贴、明显遗漏），不擅长「架构判断、业务理解、团队上下文」。最好的用法是 AI 当初审，人审专注做 AI 做不好的判断。

Q：AI review 错了导致人没看出来真 bug 怎么办？ A：这就是为什么 AI review 不能替代人 review，只能作补充。团队的 SLA 要清楚：人 reviewer 仍负有最终责任，AI review 是 nice-to-have。

Q：每个 PR 一审，API 钱很贵吗？ A：取决于 PR 大小。中型 PR（500 行 diff）一次 review 大概几美分到几十美分。一个中等活跃团队一月几十到几百美元。如果觉得贵，限制只在「PR 大于 100 行才触发」或「只在 ready-for-review 时触发，draft 不审」。

Q：能让 Codex review 中文 PR 描述吗？ A：能。Codex 多语言能力很强，PR description / commit message 中文英文都能理解。review 评论可以指定输出中文，团队读起来更顺。

Q：跟 Claude Code 比，PR review 哪个强？ A：两个都能用——Claude SDK 同样能写自动 review 脚本。差别主要是模型偏好和成本，没有一边碾压另一边。建议同时跑两个 1-2 周看哪个跟你团队约定更贴。

30 秒了解：让 AI 审 PR 到底有用吗

准备工作：先想清楚 3 件事

1. AI Review 不替代人 Review

2. Codex SDK 跟 Codex CLI 是两回事

3. 团队的 review 标准要文档化

第 1 步：写一份 .codex/review-rules.md

第 2 步：写自动化触发的 GitHub Actions

第 3 步：给 Codex 写「Review Prompt」

总评

红线问题（必须改）

黄线问题（建议关注）

建议

第 4 步：第一次试跑

第 5 步：用「人 review 时怎么用 AI review」

4 个 Code Review Prompt 模板

模板 1：聚焦安全的 review

模板 2：聚焦性能的 review

模板 3：聚焦测试覆盖的 review

模板 4：聚焦架构一致性的 review

常见坑 + 解决办法

Codex Code Review vs GitHub Copilot Review

下一步

常见问题

第 1 步：写一份 `.codex/review-rules.md`