codex-review

Codex Review

将 Codex 内置的代码审查作为收尾检查。此处指代码审查（codex review），而非 Guardian auto_review 审批路由。

适用于：

• 用户要求进行 Codex 审查／autoreview／第二模型审查
• 完成非简单的代码修改后，在最终提交／提交代码／发布之前
• 修复后审查本地分支或 PR 分支

约定

• 将审查输出视为建议，绝不可盲目照做。
• 阅读实际代码路径及相邻文件，核实每条发现。
• 如果发现依赖外部行为，请阅读依赖项的文档／源码／类型定义。
• 驳回不切实际的边缘情况、推测性风险、大范围重写，以及会让代码库复杂化的修复。
• 优先在正确的责任边界进行小幅修复；除非重构能明确改善此类错误，否则不要重构。
• 持续处理，直到 Codex review 不再返回已采纳／可执行的发现。
• 如果由审查触发的修复改动了代码，请重新运行针对性测试，并再次运行 Codex review。
• 对于安全审计的抑制变更，请确认已采纳的发现仍可审计：被抑制的发现仍保留在结构化输出中，活动输出保留不可抑制的抑制通知，且汇总发现不会掩盖无关的活动风险。
• 绝不切换或覆盖审查模型。如果审查遇到模型容量限制，请使用同一模型多次重试同一命令。默认情况下，helper 会以 yolo／完全访问模式运行嵌套审查；仅在有意测试沙盒行为时使用 --no-yolo。
• 一旦审查命令／helper 以状态码 0 退出且没有已采纳／可执行的发现，就立即停止。不要为了得到更好看的“clean”提示、更全面的第二意见或更清晰的收尾措辞，再额外直接运行一次 codex review。
• 即使底层 Codex CLI 输出很简短，也应将 helper 成功退出且没有可执行发现视为审查通过。
• 如果驳回某项发现，认为这是有意为之／不值得修复，仅当行内代码注释能说明未来审查者需要了解的真实不变量或责任边界时，才添加简短注释。
• 如果 gh／Gitcrawl 报告 database disk image is malformed，请运行一次 gitcrawl doctor --json，让便携缓存先行修复，再重试审查；除非修复失败且需要最新数据，否则不要绕过 shim。
• 如果 Gitcrawl 报告便携清单不匹配、源／运行时数据库健康错误或便携存储检出过期，请运行 gitcrawl doctor --json，并在改用实时 GitHub 之前检查 source_db_health、runtime_db_health 和 portable_store_status。
• 不要仅为审查而推送。只有用户要求推送／发布／更新 PR 时才推送。

选择目标

本地有未提交的工作：

codex review --uncommitted

仅当补丁确实在当前检出中处于未暂存／已暂存／未跟踪状态时才使用此方式。对于已提交、已推送或 PR 中的工作，应让 Codex 检查提交或分支差异；不要仅仅因为 helper 文档先提到了未提交工作，就强制使用 --mode local／--uncommitted。对干净工作区使用 --uncommitted 进行审查，只能证明本地没有补丁。

分支／PR 工作：

git fetch origin
codex review --base origin/main

不要在 --base 后传入任何提示词。某些版本的 Codex CLI 会拒绝行内提示词和 stdin 提示词，包括类似 codex review --base <ref> - 的 helper 命令，并报错：--base <BRANCH> cannot be used with [PROMPT]。如果 helper 遇到此错误，请运行普通的 codex review --base <ref>，并说明已跳过 helper 提示词注入。

如果存在未关闭的 PR，请使用其实际基准分支：

base=$(gh pr view --json baseRefName --jq .baseRefName)
codex review --base "origin/$base"

单个已提交变更：

codex review --commit HEAD

或使用 helper：

/Users/steipete/Projects/agent-scripts/skills/codex-review/scripts/codex-review --mode commit --commit HEAD

对于已经合并或推送到 main 的工作，请使用提交审查。推送后，用 origin/main 对比干净的 main 通常会得到空差异。对于较小的提交序列，可逐一明确审查每个提交，或在合并前使用 --base 审查整个分支。

并行收尾

如果格式化可能改变行号，先进行格式化。之后可以并行运行测试和审查：

scripts/codex-review --parallel-tests "<focused test command>"

权衡：测试可能要求修改代码，导致审查结果过时。如果测试或审查导致代码修改，请重新运行受影响的测试并再次审查，直到没有已接受／可执行的发现为止。重新运行干净结束后就停止；不要为了冗余确认再进行一轮漫长的审查。

上下文效率

Codex 审查通常会产生很多噪声。如果有子 Agent，默认使用子 Agent 过滤。让它运行审查，并且只返回：

• 它接受的可执行发现
• 它拒绝的发现及一句话理由
• 需要重新运行的具体文件／测试

仅当改动很小或没有可用的子 Agent 时，才直接运行。

辅助工具

捆绑的辅助工具：

~/.codex/skills/codex-review/scripts/codex-review --help

如果从 agent-scripts 安装，路径为：

/Users/steipete/Projects/agent-scripts/skills/codex-review/scripts/codex-review --help

该辅助工具：

• 优先选择有未提交改动时的 --uncommitted
• 否则，如果 gh pr view 可用，则使用当前 PR 的基准
• 否则，对于非 main 分支使用 origin/main
• 当仓库包含 package.json、pnpm-lock.yaml、node_modules 和 check 脚本时，会并行自动运行 PNPM_CONFIG_PM_ON_FAIL=ignore PNPM_CONFIG_VERIFY_DEPS_BEFORE_RUN=false PNPM_CONFIG_OFFLINE=true pnpm run check；可通过 CODEX_REVIEW_AUTO_TESTS=0 禁用
• 对于已提交的工作，尤其是合并后干净的 main，使用 --mode commit --commit <ref>
• PR／分支工作应保留 --mode auto，或强制使用 --mode branch；提交后不要强制使用 --mode local
• 除非设置了 --output 或 CODEX_REVIEW_OUTPUT，否则只写入标准输出
• 支持 --dry-run、--parallel-tests 和提交引用
• 默认使用 --dangerously-bypass-approvals-and-sandbox 运行嵌套审查
• 在 Codex CLI 版本因拒绝 --base 与辅助工具的标准输入提示组合而导致分支模式失败时，遇到该特定解析器错误，应改为重新运行 codex review --base <ref>，而不是退回到非 Codex 审查器
• 仍接受 --full-access；使用 --no-yolo 或 CODEX_REVIEW_YOLO=0 可选择退出
• 当所选审查命令以 0 退出时，会输出 codex-review clean: no accepted/actionable findings reported

最终报告

包括：

• 使用的审查命令
• 运行的测试／验证
• 已接受／拒绝的发现及简要理由
• 最终辅助工具／审查运行得出的干净结果，或者有意拒绝某项遗留发现的原因

不要仅仅为了润色最终报告而再次运行 Codex 审查。如果最终辅助工具运行以 0 退出且没有产生已接受／可执行的发现，就如实报告该次运行干净。