codex-review

Codex 代码审查技能

触发条件

当用户输入包含以下内容时触发：

• “代码审核”“代码审查”“审查代码”“审核代码”
• “review”“code review”“review code”“codex 审核”
• “帮我审核”“检查代码”“审一下”“看看代码”

核心概念：意图与实现

单独运行 codex review --uncommitted 只会向 AI 展示“做了什么（实现）”。 先记录意图，才能告诉 AI“你想做什么（意图）”。

将“代码更改 + 意图描述”作为组合输入，是提升 AI 代码审查质量的最有效方式。

技能架构

此技能分为两个阶段：

1. 准备阶段（当前上下文）：检查工作目录，更新 CHANGELOG
2. 审查阶段（隔离上下文）：调用 Task 工具执行 Lint + codex review（使用 context: fork 减少上下文浪费）

执行步骤

0. [首先] 检查工作目录状态

git diff --name-only && git status --short

根据输出决定审查模式：

• 有未提交的更改 → 继续执行步骤 1-4（常规流程）
• 工作目录干净 → 直接调用 codex-runner：codex review --commit HEAD

1. [必须] 检查 CHANGELOG 是否已更新

任何审查开始前，都必须检查 CHANGELOG.md 是否包含当前更改的说明。

# Check if CHANGELOG.md is in uncommitted changes
git diff --name-only | grep -E "(CHANGELOG|changelog)"

如果 CHANGELOG 尚未更新，必须自动执行以下操作（不要要求用户手动处理）：

1. 分析更改：运行 git diff --stat 和 git diff 获取完整更改
2. 自动生成 CHANGELOG 条目：根据代码更改生成符合要求的条目
3. 写入 CHANGELOG.md：使用 Edit 工具将条目插入 [Unreleased] 部分的顶部
4. 继续审查流程：更新 CHANGELOG 后立即继续后续步骤

自动生成的 CHANGELOG 条目格式：

## [Unreleased]

### Added / Changed / Fixed

- Feature description: what problem was solved or what functionality was implemented
- Affected files: main modified files/modules

示例——自动生成流程：

1. Detected CHANGELOG not updated
2. Run git diff --stat, found handlers/responses.go modified (+88 lines)
3. Run git diff to analyze details: added CompactHandler function
4. Auto-generate entry:
   ### Added
   - Added `/v1/responses/compact` endpoint for conversation context compression
   - Supports multi-channel failover and request body size limits
5. Use Edit tool to write to CHANGELOG.md
6. Continue with lint and codex review

2. [关键] 暂存所有新文件

调用 codex review 前，必须将所有新文件（未跟踪文件）添加到 git 暂存区，否则 codex 会报告 P1 错误。

# Check for new files
git status --short | grep "^??"

如果存在新文件，请自动执行：

# Safely stage all new files (handles empty list and special filenames)
git ls-files --others --exclude-standard -z | while IFS= read -r -d '' f; do git add -- "$f"; done

说明：

• -z 使用空字符分隔文件名，能正确处理包含空格或换行符的文件名
• while IFS= read -r -d '' 逐个读取文件名
• git add -- "$f" 使用 -- 分隔符，能正确处理以 - 开头的文件名
• 没有新文件时，循环体不会执行，会安全跳过
• 这不会暂存已修改的文件，只处理新文件
• codex 需要文件由 git 跟踪，才能正确进行审查

3. 评估任务难度并调用 codex-runner

统计更改规模：

# Get summary line for ALL changes (staged + unstaged)
# IMPORTANT: Must use 'HEAD' as base to include both staged and unstaged changes
git diff --stat HEAD | tail -1

为何使用 git diff --stat HEAD：

• git diff --stat 只显示未暂存的更改
• git diff --cached --stat 只显示已暂存的更改
• git diff --stat HEAD 会显示已暂存和未暂存更改的合计
• 最后一行（tail -1）是汇总行，包含文件总数和行更改数

难度评估标准：

模型与推理力度组合：

仅推荐 gpt-5.3-codex；根据任务复杂度选择 model_reasoning_effort 和超时时间。

组合	质量	时间	超时时间	推荐用途
model=gpt-5.3-codex model_reasoning_effort=xhigh	高	~8-20 分钟	15-40 分钟	困难任务、关键代码、架构更改
model=gpt-5.3-codex model_reasoning_effort=high	良好	~5-6 分钟	10 分钟	常规任务（默认）

关键任务（符合任一条件时，使用最高推理力度）：

• 修改的文件数 ≥ 30
• 代码更改总量（新增行数 + 删除行数）≥ 2000 行
• 涉及核心架构/算法更改（用户明确提及）
• 配置：--config model=gpt-5.3-codex --config model_reasoning_effort=xhigh，超时时间 40 分钟

困难任务（符合任一条件）：

• 修改的文件数 ≥ 10
• 代码变更总量（新增行数 + 删除行数）≥ 500 行
• 单项指标：新增行数 ≥ 300 行，或删除行数 ≥ 300 行
• 跨模块重构
• 默认配置：--config model=gpt-5.3-codex --config model_reasoning_effort=xhigh，超时 15 分钟

普通任务（其他情况）：

• 默认配置：--config model=gpt-5.3-codex --config model_reasoning_effort=high，超时 10 分钟

评估方法：

你必须正确解析 git diff --stat HEAD 的输出，以确定难度：

# Get the summary line (last line of git diff --stat HEAD)
git diff --stat HEAD | tail -1
# Example outputs:
# "20 files changed, 342 insertions(+), 985 deletions(-)"
# "1 file changed, 50 insertions(+)"  # No deletions
# "3 files changed, 120 deletions(-)"  # No insertions

关键：为什么汇总行很重要：

• 每个文件都会显示单独的统计信息：file.go | 171 ++++++++++++++++++++-
• 只有最后一行包含总计：6 files changed, 1341 insertions(+), 18 deletions(-)
• 必须使用 tail -1 提取最后一行，以获取准确的总数

解析规则：

1. 从 “X file(s) changed” 中提取文件数（兼容 “1 file” 和 “N files”）
2. 如果存在，从 “Y insertion(s)(+)” 中提取新增行数（兼容 “1 insertion” 和 “N insertions”），否则为 0
3. 如果存在，从 “Z deletion(s)(-)” 中提取删除行数（兼容 “1 deletion” 和 “N deletions”），否则为 0
4. 计算变更总量 = 新增行数 + 删除行数

重要边界情况：

• 单个文件：“1 file changed”（单数形式）
• 没有新增行：Git 会完全省略 “insertions(+)” → 视为 0
• 没有删除行：Git 会完全省略 “deletions(-)” → 视为 0
• 纯重命名：可能显示 “0 insertions(+), 0 deletions(-)”，也可能两者都省略

判断逻辑（按顺序检查，首个匹配项优先）：

• 如果 file_count >= 30 或 total_changes >= 2000 → 关键任务（gpt-5.3-codex + xhigh）
• 如果 file_count >= 10 → 困难任务（gpt-5.3-codex + xhigh）
• 如果 total_changes >= 500 → 困难任务（gpt-5.3-codex + xhigh）
• 如果 insertions >= 300 或 deletions >= 300 → 困难任务（gpt-5.3-codex + xhigh）
• 否则 → 普通任务（gpt-5.3-codex + high）

示例情况：

• ⭐ “50 files changed, 2000 insertions(+), 1500 deletions(-)” → 关键任务，使用 model=gpt-5.3-codex model_reasoning_effort=xhigh，超时 40 分钟（核心架构变更）
• ✅ “20 files changed, 342 insertions(+), 985 deletions(-)” → 困难任务，使用 model=gpt-5.3-codex model_reasoning_effort=xhigh，超时 15 分钟
• ✅ “5 files changed, 600 insertions(+), 50 deletions(-)” → 困难任务，使用 model=gpt-5.3-codex model_reasoning_effort=xhigh，超时 15 分钟
• ❌ “3 files changed, 150 insertions(+), 80 deletions(-)” → 普通任务，使用 model=gpt-5.3-codex model_reasoning_effort=high，超时 10 分钟
• ❌ “1 file changed, 50 insertions(+)” → 普通任务，使用 model=gpt-5.3-codex model_reasoning_effort=high，超时 10 分钟

调用 codex-runner 子任务：

使用 Task 工具调用 codex-runner，并传入完整命令（包括 Lint + codex review）：

Task parameters:
- subagent_type: Bash
- description: "Execute Lint and codex review"
- timeout: 2400000 (40 minutes for critical tasks) / 900000 (15 minutes for difficult tasks) / 600000 (10 minutes for normal tasks)
- prompt: Choose corresponding command based on project type and difficulty

Go project - Critical task:
  go fmt ./... && go vet ./... && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 2400000)

Go project - Difficult task:
  go fmt ./... && go vet ./... && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 900000)

Go project - Normal task:
  go fmt ./... && go vet ./... && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=high
  (timeout: 600000)

Node project - Critical task:
  npm run lint:fix && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 2400000)

Node project - Difficult task:
  npm run lint:fix && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 900000)

Node project - Normal task:
  npm run lint:fix && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=high
  (timeout: 600000)

Python project - Critical task:
  black . && ruff check --fix . && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 2400000)

Python project - Difficult task:
  black . && ruff check --fix . && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=xhigh
  (timeout: 900000)

Python project - Normal task:
  black . && ruff check --fix . && codex review --uncommitted --config model=gpt-5.3-codex --config model_reasoning_effort=high
  (timeout: 600000)

Clean working directory:
  codex review --commit HEAD --config model=gpt-5.3-codex --config model_reasoning_effort=high
  (timeout: 600000)

4. 自我纠正与基于严重程度的修复

如果 Codex 发现 Changelog 描述与代码逻辑不一致：

• 代码错误 → 修复代码
• 描述不准确 → 更新 Changelog

如果 Codex 报告 P0 / P1 / P2 问题，你必须立即主动修复，而不能只报告问题。

必须执行的操作：

1. 存在 P0 / P1 / P2 问题 → 直接修改代码或相关文件以修复问题
2. 修复后 → 重新运行必要的 lint / 验证 / review 命令，确认问题已解决
3. 仅在复查后报告完成 → 清楚说明修复了什么，以及哪些验证已通过
4. P3 或更低级别 / 仅为建议 → 可以只报告，不自动修改，除非用户明确要求进一步清理

修复优先级：

• P0：阻塞、安全、数据丢失、正确性故障 → 必须优先修复
• P1：影响较大的功能或逻辑错误 → 必须修复
• P2：重要的可维护性 / 正确性问题，且有明确修复方案 → 应在同一轮中主动修复

约束：

• 修复应尽可能精简，并直接针对报告的问题
• 不要将范围扩展到无关重构
• 除非问题要求进行结构调整，否则应保留现有风格和架构

完整审查流程

1. [GATE] 检查 CHANGELOG - 如有更新，自动生成并写入（利用当前上下文了解变更意图）
2. [PREPARE] 暂存未跟踪文件 - 将所有新文件添加到 git 暂存区（避免 codex P1 错误）
3. [EXEC] 任务 → Lint + codex 审查 - 调用 Task 工具执行 Lint 和 codex（隔离上下文，减少浪费）
4. [FIX] 按严重程度自行修正 - 当意图 ≠ 实现时，修复代码或更新描述；主动修复 P0/P1/P2 问题并重新运行检查

Codex 审查命令参考

基本语法

codex review [OPTIONS] [PROMPT]

注意：[PROMPT] 参数不能与 --uncommitted、--base 或 --commit 一起使用。

常用选项

选项	描述	示例
--uncommitted	审查工作目录中的所有未提交更改（已暂存 + 未暂存 + 未跟踪）	codex review --uncommitted
--base <BRANCH>	审查相对于指定基分支的更改	codex review --base main
--commit <SHA>	审查指定提交引入的更改	codex review --commit HEAD
--title <TITLE>	可选的提交标题，显示在审查摘要中	codex review --uncommitted --title "feat: add JSON parser"
-c, --config <key=value>	覆盖配置值	codex review --uncommitted -c model="gpt-5.3-codex"

使用示例

# 1. Review all uncommitted changes (most common)
codex review --uncommitted

# 2. Review latest commit
codex review --commit HEAD

# 3. Review specific commit
codex review --commit abc1234

# 4. Review all changes in current branch relative to main
codex review --base main

# 5. Review changes in current branch relative to develop
codex review --base develop

# 6. Review with title (title shown in review summary)
codex review --uncommitted --title "fix: resolve JSON parsing errors"

# 7. Review using the recommended model
codex review --uncommitted -c model="gpt-5.3-codex"

重要限制

• --uncommitted、--base 和 --commit 互斥，不能同时使用
• [PROMPT] 参数与上述三个选项互斥
• 必须在 git 仓库目录中执行

重要说明

• 确保在 git 仓库目录中执行
• 根据任务难度自动调整超时时间：
  • 关键任务：40 分钟（timeout: 2400000）
  • 困难任务：15 分钟（timeout: 900000）
  • 普通任务：10 分钟（timeout: 600000）
• 必须正确配置并登录 codex 命令
• 对于大型更改，codex 会自动分批处理
• CHANGELOG.md 必须包含在未提交更改中，否则 Codex 无法看到意图描述

设计理由

为什么要隔离上下文？

1. 更新 CHANGELOG 需要当前上下文：理解用户之前的对话和任务意图，以生成准确的变更描述
2. Codex 审查不需要对话历史：只需要代码更改和 CHANGELOG，独立运行效率更高
3. 减少 Token 消耗：将 codex 审查作为独立子任务执行，不携带无关的对话上下文