codex-review

使用 Codex CLI 进行跨模型代码审查

直接使用 codex 二进制文件进行跨模型验证。Claude 编写代码，Codex 审查代码。架构不同、训练数据分布不同，也不存在自我批准偏差。

核心观点： 单模型自我审查存在系统性偏差。跨模型审查能发现不同类别的 bug，因为审查者与作者有着根本不同的盲点。

如实界定独立性声明的范围： 使用不同模型只能消除自我审查偏差，仅此而已。它无法发现训练数据中共有的过时信息（无论有多少模型认同，涉及版本、SOTA 和生态系统的说法都需要实时的一手来源），也无法发现从需求说明中继承的意图误读（将用户的原话带入提示词，并要求审查者质疑对需求的理解）。

如何阅读此技能： 以下模式和决策表都是指南。选择合适的方式，必要时组合使用。标记为 ⚠️ 的规则有所不同：它们是 codex CLI 的真实行为，而非流程上的形式要求。跳过作用域标志确实会导致调用挂起；通过管道传给 tail 确实会丢失输出。请将 ⚠️ 规则视为工具行为事实，而非对工作流的看法。

前提条件： 必须安装并完成身份验证的 codex CLI。使用 codex --version 验证。用户默认设置位于 ~/.codex/config.toml；请遵循这些设置。

在 Pi 中： 如果已安装 pi-nova xreview 扩展，请优先使用 /xreview — 它会通过标准输入关闭的外部 codex exec --sandbox read-only 执行审查，并返回结构化的 Verdict/Findings/Fix Queue。从 Pi 手动调用 bash 时，也必须遵循以下相同的 ⚠️ 规则。

方向： 仅限 Claude → Codex。如需使用双向技能（也支持 Codex → Claude，并处理 yield_time_ms 和可变参数标志相关的 claude -p 注意事项），请改用 /hyperskills:cross-model-review。

---

⚠️ 不可妥协的规则：始终为 codex review 指定作用域标志

不带作用域的 codex review 是导致失败的首要原因：它会挂起或产生 100KB 以上的海量输出。始终且仅指定一个作用域标志：

要审查的内容	命令
自 main 以来的分支	codex review --base main
单个提交	codex review --commit <SHA>
工作树（未暂存）	codex review --uncommitted

带作用域的 codex review 也接受作为末尾 [PROMPT] 参数的自定义指令（截至 2026 年 7 月：codex review --base main "focus on error handling"），因此，聚焦审查也能保留结构化审查行为。仅当审查对象根本不是差异时，才使用 codex exec "PROMPT" — 例如规范文档、版本控制之外的单个文件、开放式调查 — 切勿使用不带作用域的 codex review。

如果 codex review 的输出超过约 100KB，说明差异过大，无法一次审查完毕。请按提交拆分，或使用范围更窄的提示词调用 codex exec（“仅审查错误处理”）。大型 codex exec 的交互记录则是另一回事 — 请参阅「审查挂起时」。

固定审查范围，冻结审查目标。 在存在未提交更改或多个工作流的分支上，请明确列出文件，或将精确的差异通过管道传给 codex exec — 未限定范围的审查者会漫无目的地浏览差异。审查期间不要编辑被审查的代码；等待时请处理相对于被审查差异只读的工作。给出结论后进行的任何编辑都会使审查结论失效：请针对精确的改动重新审查，确保阻塞问题确实得到解决，而不是含糊带过。

---

⚠️ 将输出捕获到文件：不要管道传给 tail

切勿将审查结果通过 | tail -N 管道传递。这样做有三种失败模式：

1. 管道会缓冲，直到 EOF。 tail 会读取整个流后才输出内容，因此直到 codex 退出或超时，Agent 才能看到任何内容，审查过程中也没有进度信号。
2. 审查结论通常在开头，而不是结尾。 发现项按严重性排序（BLOCKER 优先），所以 tail -300 会恰好截掉你需要的部分。
3. 文件可以让人实时查看进度。 在另一个终端运行 tail -f /tmp/review.txt，即可实时接收审查结果，完全不依赖 Agent 的调用。

正确做法： 选择一个不冲突的文件名，重定向输出，然后再读取文件。

# mktemp so parallel/repeat reviews don't clobber each other.
# Bake the scope into the slug so it's self-describing under tail -f.
out=$(mktemp -t codex-review-pre-pr.XXXXXX) && echo "$out"

codex review --base main > "$out" 2>&1
codex exec --sandbox read-only "PROMPT" > "$out" 2>&1

如果不方便使用 mktemp：out=/tmp/codex-review-$$-$(date +%s).txt。重定向前先输出文件路径，让运行 tail -f 的人知道该查看哪里。进程退出后，使用 Read（或 cat）读取文件。文件会在不同轮次间保留，应重新读取，而不是重新运行。

相邻的工具注意事项：在 --sandbox read-only 模式下，Codex 无法写入提示词要求生成的报告文件，且不会发出提示。请通过重定向或 --output-last-message 捕获输出，切勿要求“将报告写入 X”。

---

审查挂起时

即使审查范围设置正确，也可能挂起——这是实际使用中最常见的运行故障。输出文件是判断进程是否仍在运行的工具：应根据文件增长情况和进程状态判断，绝不要只看已用时间。输出持续增长但速度较慢，往往是质量信号——对于大型代码范围，快速敷衍通过反而可疑。

信号	处理方式
输出文件持续增长	继续等待；进程正在工作
文件为空，进程树仍存活	再等一个时间窗口，然后隔离变量（截至 2026 年 7 月，通常是 MCP 服务挂起或启动钩子导致问题）
文件为空，进程挂起	仅终止该进程树；减少自由度后重试一次——通过 stdin 输入准确的 diff、缩小文件列表、降低投入。同一个问题，减少负载
重试后仍然卡住	预先声明放弃条件，如实记录审查失败

切勿在现有审查进程仍运行时再启动一个重复进程——应先结束已有进程。文件大小本身也不是失败信号：codex exec 的记录超过 1MB，可能代表成功进行了深入探索，且结论位于末尾——应搜索结论和严重性标记，而不是倾倒整个跟踪记录。真正的失败表现是输出不再增长，或虽然增长却始终没有接近结论。

---

调用 Codex 的两种方式

模式	命令	最适合用于
codex review	结构化 diff 审查，并按优先级列出发现项	PR 前审查、提交审查、WIP 检查
codex exec	自由形式的非交互式深入分析，可完全控制提示词	安全审计、架构分析、重点调查、规格说明

范围标志（仅适用于 codex review）

标志	用途
--base <BRANCH>	与基础分支进行 diff
--commit <SHA>	审查特定提交
--uncommitted	审查工作树中的更改

沙箱与易用性标志（两种模式均适用）

标志	使用时机
--sandbox read-only	默认用于审查工作，不进行写入
--sandbox workspace-write	审查并应用建议的修复
--full-auto	--ask-for-approval never --sandbox workspace-write 的别名
--dangerously-bypass-approvals-and-sandbox	最后手段；仅在用户明确请求时使用
-C <DIR> / --cd <DIR>	无需使用 cd，即可在另一个工作树中运行
--skip-git-repo-check	从 /tmp 或任何非仓库目录运行时（会触发 git 信任检查）
--add-dir <DIR>	扩展对另一条路径的读取权限
--ephemeral	一次性会话，不持久化
--json / --output-last-message <FILE>	将结构化输出保存到文件
-c model_reasoning_effort="xhigh"	仅用于 Spec/RFC 审查（参见“努力程度策略”）

努力程度覆盖策略

审查对象	努力程度标志
代码（提交 / 差异 / PR / WIP）	无，遵循 ~/.codex/config.toml
Spec / RFC / 设计文档	-c model_reasoning_effort="xhigh"

Spec 的风险高于差异；细微的架构错误会在后续实现中不断累积。代码差异的范围较小，使用用户配置的努力程度即可。

先确定范围，再考虑努力程度。 努力程度会放大既定范围；xhigh 覆盖适用于范围明确的 Spec 审查。范围不明的“验证所有内容”提示即使设为 xhigh，也只会发散，而非深入（曾观察到：生成 80k 行记录，却没有结论）。审查必须得出结论时，应缩小范围，并考虑降低努力程度，而不是提高——在提示中明确设定收敛目标（“精简审查，得出结论”）。

绝不要指定 --model、-m 或 -c model= 来覆盖模型本身。用户配置具有最高优先级。这个关卡的价值在于拥有仓库访问权限的完整 Agentic Codex，而不是一次性 API 调用。

---

审查模式

模式 1：PR 前全面审查（默认）

创建 PR 前的标准审查。适用于任何非简单改动。

Step 1, structured review (catches correctness + general issues):
  codex review --base main

Step 2, security deep-dive (if code touches auth, input handling, or APIs):
  codex exec "<security prompt from references/prompts.md>"

Step 3, fix findings, then re-review carrying the ledger (see Pattern 5):
  codex review --base main

相同的模式也适用于单次提交（codex review --commit <SHA>）以及开发过程中对工作树的审查（codex review --uncommitted）。

模式 2：针对性调查

针对具体问题（错误处理、并发、数据流）进行精确深入的分析。

codex exec --sandbox read-only \
  "You are a senior <DOMAIN> engineer. Analyze <CONCERN> in the changes
   between main and HEAD. For each issue: cite file and line, explain the
   risk, suggest a concrete fix. Confidence threshold: 0.7."

模式 3：Spec / RFC 审查

在编写代码之前审查文档（Markdown 设计文档）。

codex exec -c model_reasoning_effort="xhigh" --sandbox read-only \
  "You are a senior staff engineer doing a candid pre-implementation review of
   <PATH>. The author wants sharp, unsentimental analysis. For each finding:
   severity (BLOCKER / HIGH / MEDIUM / LOW), confidence (>= 0.7 only), location
   (file path + section heading), the issue, a concrete fix.
   End with a one-paragraph go/no-go verdict."

模式 4：单文件 / 指定路径审查

审查单个文件或目录，而非完整差异。

codex exec --sandbox read-only \
  "Review only <PATH> for <CONCERN>. Skip style and ergonomics.
   Return PASS if no real issues; otherwise concise FAIL findings with
   file:line evidence."

模式 5：Ralph 循环（实现 → 评审 → 修复）

通过迭代把关质量。第 1 轮范围宽泛且严格。之后每一轮都附上记录：逐字列出上一轮的发现以及声称已完成的修复，并要求评审者：(a) 提供证据验证每项修复；(b) 检查修复引入的缺陷；(c) 不要重新争论已经定论的取舍。每轮逐步缩小范围：从全面检查 → 仅检查阻塞问题 → 通过一句话约定进行收敛检查（“PASS / NEEDS_CHANGES：<一句话>”）。对于规格说明，在产物的 Review History 部分记录各轮结果——循环状态保存在产物中，而不是冗长的聊天记录中。复审模板见 references/prompts.md。

预算取决于是否收敛，而不是轮数。 只要每轮都产生新的已确认发现或验证了一项修复，就继续迭代；当各轮开始反复摇摆或重提旧议题时，就停止。默认预期为 3 轮，但不是硬性上限——第 5 轮发现了真实缺陷也没问题，而第 3 轮还在重新争论第 1 轮的问题，就已经超出预算。此预算适用于你主导的循环；每一轮都要重新分诊外部机器人或人工反馈流，且绝不设上限。

修复循环是逐步收紧范围的机制。 每轮结束后、修改代码之前：将阻塞问题与后续事项分诊，预先声明文件预算（“三个文件，除非测试需要更多”），并将说明为何不修改视为处理缺失问题的一种合理方式。阻塞问题必须能归因于变更行；建议可以涉及附近的风险；既有技术债应转为后续任务，而不是在循环中修复。无节制地响应评审意见，会让循环最终改动 120 个文件。

---

多轮检查策略

相比一次含糊的检查，分多轮进行有针对性的检查更有助于彻底评审。单轮检查会分散对各个维度的注意力，导致每个维度的发现都很浅。每轮都应设定明确的评审角色和关注领域。

轮次	重点	模式
正确性	缺陷、逻辑、边界情况、竞态条件	codex review
安全性	OWASP Top 10:2025、注入、身份验证、密钥	使用安全提示词运行 codex exec
架构	耦合、抽象、API 一致性	使用架构提示词运行 codex exec
性能	O(n²)、N+1 查询、内存泄漏	使用性能提示词运行 codex exec

如果评审期间差异内容仍在变化，应按顺序执行各轮，并在轮次之间修复严重问题。对于已冻结的产物，可以并行进行视角锁定的检查（每轮只关注一个方面，并明确排除项），这样能得到互为补充且不重复的发现，也能更快完成。

行数只是粗略参考；应根据风险和影响范围安排检查，而不是机械计算：

变更规模	策略
< 50 行，单一关注点	单轮 codex review
50-300 行，功能开发	codex review + 安全检查
300+ 行或架构变更	完整的 4 轮检查
安全敏感（身份验证、支付、加密）	始终包含安全检查

---

处理审查发现

审查者的输出是输入，不是命令。进行任何编辑前，都要依据事实依据重新核实每项发现——代码、Git 历史、实时数据。始终报告三种处理结果：立即修复／有意保留并说明具体理由／无法核实，标记给人工处理。“已核实，无需更改代码”也是合理结果；有一次审查否定了 4 项发现中的 3 项，最终没有做任何更改。要用证据驳回错误的发现，绝不能默默忽略。两位各自收到独立简报的审查者得出相同结论，可将问题升级为已确认。

首先检查 Codex 特有的常见漏检：

失效模式	检查内容
时间范围	它审查的是该发现所指的提交状态吗？
相近名称混淆	引用的对象是实际发生更改的那个吗？
编造标志或 API	建议的标志或函数确实存在吗？运行 --help
修复时已过时	该问题在审查时成立，但现在已经解决了吗？

从两个方向闭环：修复某类缺陷时，将其纳入仓库长期使用的审查提示词或 CI 门禁，让下一位审查者也能据此检查。如果审查者反复幻觉出同一个不存在的问题，就修正审查者读取的内容——清理它不断导入的过时文档。还要从记忆中为下一次审查提供以往的注意事项；它们能构成一份精准的假设清单。

---

提示词工程启发

这些不太显而易见的手段能稳定提升审查结果的质量：

1. 说明要跳过什么。“跳过格式、命名风格和轻微的文档缺漏”可避免纠缠于细枝末节
2. 要求提供置信度评分，且只处理评分 ≥ 0.7 的发现
3. **每轮只审查一个领域。**仅审查安全性、仅审查架构
4. 要求给出判定。“判定：补丁正确／不正确”或“通过／不通过”

完整的简报结构（逐字请求、核心主张、假定已通过的证据、反迎合要求、无记忆说明）以及可直接使用的模板见 references/prompts.md。

---

反模式

反模式	失败原因	修正方案
直接运行 codex review（未指定范围标志）	卡住或生成大量输出	恰好指定一个范围标志——参见 ⚠️ 范围规则
将审查输出管道传给 tail -N	会缓冲直到 EOF；截断审查结论	重定向到文件——参见 ⚠️ 捕获规则
timeout 30 codex review	审查通常需要 30 秒至 5 分钟	不设超时，或至少使用 timeout 300
将转录内容大小视为失败信号	codex exec 的转录内容超过 1 MB，也可能是一次成功的深入分析	根据内容增长和结论收敛情况判断（审查卡住时）
“Review this code”（没有具体要求）	描述含糊，容易引发无谓争论	结合角色设定，使用针对具体领域的提示词
所有内容只审查一轮	上下文被稀释，各个维度的审查都流于表面	分多轮审查，每轮只关注一个问题
自我审查（Claude 审查 Claude 编写的代码）	存在系统性偏见，模型会认可自己惯用的模式	跨模型协作：Claude 编写，Codex 审查
没有置信度阈值	噪声淹没有效信号，0.3 的置信度会浪费时间	只处理置信度 ≥ 0.7 的问题
在审查中评论风格	大模型默认会纠结风格问题	“跳过：格式、命名、轻微文档问题”
在多轮审查中反复争论已解决的问题	无论轮数多少都会超出预算	预算取决于收敛情况——当各轮结论开始摇摆时就停止，而不是按轮数停止
不了解项目上下文就进行审查	建议泛泛而谈，与代码库脱节	从仓库根目录运行
审查者反复产生幻觉	幻觉通常源自审查者读取的某份文档	清理过时文档；不要每轮都重新争论
用 MCP 封装 codex	在 CLI 二进制程序外增加了不必要的间接层	通过 Bash 直接调用 codex
将 --model / -m / -c model= 硬编码	覆盖用户配置；模型名称可能过时	使用 ~/.codex/config.toml 中的配置
日常代码审查时覆盖推理力度	浪费 token，忽略用户默认设置	-c model_reasoning_effort="xhigh" 仅用于规格审查
纯审查时使用 --full-auto	授予审查并不需要的写入权限	审查时使用 --sandbox read-only；仅在应用修复时使用 --full-auto

---

Codex 无法运行时

这道门槛不可替代。无法运行时（配额用尽、CLI 卡死、MCP 故障），应依次采用保障较弱的替代方案，并明确说明其保障水平：使用新上下文进行同模型审查是最低保障，不同模型系列则是更高保障。在总结和 PR 正文中披露替代方案，并由人工决定是否继续。审查通道受阻时，绝不能给出 PASS。

---

此技能不是什么

• 不是人工审核的替代品。 跨模型审核可以发现 Bug，但无法评估产品方向或用户体验。
• 不是代码检查工具。 不要用 Codex 审核格式或风格。
• 不是时效性检查。 无论有多少模型达成一致，版本和 SOTA 声明都需要通过实时一手来源核实。
• 并非万无一失。 5–15% 的误报率很正常。请对发现的问题进行分级处理（参见「处理发现的问题」）。
• 不用于自我审批。 跨模型验证才是重点。不要用 Claude 审核 Claude 编写的代码。

参考资料

如需可直接使用的提示词模板，请参阅 references/prompts.md。