codex-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Codex Code Review Skill

Codex代码审核技能

Trigger Conditions

触发条件

Triggered when user input contains:
  • "代码审核", "代码审查", "审查代码", "审核代码"
  • "review", "code review", "review code", "codex 审核"
  • "帮我审核", "检查代码", "审一下", "看看代码"
当用户输入包含以下内容时触发:
  • "代码审核", "代码审查", "审查代码", "审核代码"
  • "review", "code review", "review code", "codex 审核"
  • "帮我审核", "检查代码", "审一下", "看看代码"

Core Concept: Intention vs Implementation

核心概念:意图与实现

Running
codex review --uncommitted
alone only shows AI "what was done (Implementation)". Recording intention first tells AI "what you wanted to do (Intention)".
"Code changes + intention description" as combined input is the most effective way to improve AI code review quality.
单独运行
codex review --uncommitted
仅会向AI展示“已完成的内容(实现)”。 先记录意图则会告知AI“你想要完成的目标(意图)”。
将“代码变更 + 意图描述”作为组合输入是提升AI代码审核质量的最有效方式。

Skill Architecture

技能架构

This skill operates in two phases:
  1. Preparation Phase (current context): Check working directory, update CHANGELOG
  2. Review Phase (isolated context): Invoke Task tool to execute Lint + codex review (using context: fork to reduce context waste)
该技能分为两个阶段运行:
  1. 准备阶段(当前上下文):检查工作目录,更新CHANGELOG
  2. 审核阶段(独立上下文):调用Task工具执行Lint + codex审核(使用fork上下文以减少上下文浪费)

Execution Steps

执行步骤

0. [First] Check Working Directory Status

0. [第一步] 检查工作目录状态

bash
git diff --name-only && git status --short
Decide review mode based on output:
  • Has uncommitted changes → Continue with steps 1-4 (normal flow)
  • Clean working directory → Directly invoke codex-runner:
    codex review --commit HEAD
bash
git diff --name-only && git status --short
根据输出结果决定审核模式:
  • 存在未提交变更 → 继续执行步骤1-4(常规流程)
  • 工作目录干净 → 直接调用codex-runner:
    codex review --commit HEAD

1. [Mandatory] Check if CHANGELOG is Updated

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

Before any review, must check if CHANGELOG.md contains description of current changes.
bash
undefined
在进行任何审核之前,必须检查CHANGELOG.md是否包含当前变更的描述。
bash
undefined

Check if CHANGELOG.md is in uncommitted changes

检查CHANGELOG.md是否在未提交变更中

git diff --name-only | grep -E "(CHANGELOG|changelog)"

**If CHANGELOG is not updated, you must automatically perform the following (don't ask user to do it manually):**

1. **Analyze changes**: Run `git diff --stat` and `git diff` to get complete changes
2. **Auto-generate CHANGELOG entry**: Generate compliant entry based on code changes
3. **Write to CHANGELOG.md**: Use Edit tool to insert entry at top of `[Unreleased]` section
4. **Continue review flow**: Immediately proceed to next steps after CHANGELOG update

**Auto-generated CHANGELOG entry format:**

```markdown
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条目格式:**

```markdown

[Unreleased]

[Unreleased]

Added / Changed / Fixed

Added / Changed / Fixed

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

**Example - Auto-generation Flow:**
  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
undefined
  • 功能描述:解决的问题或实现的功能
  • 影响文件:主要修改的文件/模块

**示例 - 自动生成流程:**
  1. 检测到CHANGELOG未更新
  2. 运行git diff --stat,发现handlers/responses.go被修改(新增88行)
  3. 运行git diff分析细节:新增了CompactHandler函数
  4. 自动生成条目:

    Added

    • 新增
      /v1/responses/compact
      端点用于对话上下文压缩
    • 支持多通道故障转移和请求体大小限制
  5. 使用Edit工具写入CHANGELOG.md
  6. 继续执行Lint和codex审核
undefined

2. [Critical] Stage All New Files

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

Before invoking codex review, must add all new files (untracked files) to git staging area, otherwise codex will report P1 error.
bash
undefined
在调用codex审核之前,必须将所有新文件(未跟踪文件)添加到git暂存区,否则codex会报告P1错误。
bash
undefined

Check for new files

检查是否存在新文件

git status --short | grep "^??"

**If there are new files, automatically execute:**

```bash
git status --short | grep "^??"

**如果存在新文件,自动执行:**

```bash

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

**Explanation:**

- `-z` uses null character to separate filenames, correctly handles filenames with spaces/newlines
- `while IFS= read -r -d ''` reads filenames one by one
- `git add -- "$f"` uses `--` separator, correctly handles filenames starting with `-`
- When no new files exist, loop body doesn't execute, safely skipped
- This won't stage modified files, only handles new files
- codex needs files to be tracked by git for proper review
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. Evaluate Task Difficulty and Invoke codex-runner

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

Count change scale:
bash
undefined
统计变更规模:
bash
undefined

Count number of changed files and lines of code

统计变更文件数量和代码行数

git diff --stat | tail -1

**Difficulty Assessment Criteria:**

**Difficult Tasks** (meets any condition):

- Modified files ≥ 10
- Total code changes (insertions + deletions) ≥ 500 lines
- Single metric: insertions ≥ 300 lines OR deletions ≥ 300 lines
- Involves core architecture/algorithm changes
- Cross-module refactoring
- Config: `model_reasoning_effort=xhigh`, timeout 30 minutes

**Normal Tasks** (other cases):

- Config: `model_reasoning_effort=high`, timeout 10 minutes

**Evaluation Method:**

You MUST parse the `git diff --stat` output correctly to determine difficulty:

```bash
git diff --stat | tail -1

**难度评估标准:**

**高难度任务**(满足任一条件):

- 修改文件数 ≥ 10
- 代码变更总行数(插入+删除)≥ 500行
- 单一指标:插入行数 ≥ 300行 或 删除行数 ≥ 300行
- 涉及核心架构/算法变更
- 跨模块重构
- 配置:`model_reasoning_effort=xhigh`,超时时间30分钟

**常规任务**(其他情况):

- 配置:`model_reasoning_effort=high`,超时时间10分钟

**评估方法:**

必须正确解析`git diff --stat`的输出以确定难度:

```bash

Get the summary line (last line of git diff --stat)

获取摘要行(git diff --stat的最后一行)

git diff --stat | tail -1
git diff --stat | tail -1

Example outputs:

示例输出:

"20 files changed, 342 insertions(+), 985 deletions(-)"

"20 files changed, 342 insertions(+), 985 deletions(-)"

"1 file changed, 50 insertions(+)" # No deletions

"1 file changed, 50 insertions(+)" # 无删除

"3 files changed, 120 deletions(-)" # No insertions

"3 files changed, 120 deletions(-)" # 无插入


**Parsing Rules:**
1. Extract file count from "X file(s) changed" (handle both "1 file" and "N files")
2. Extract insertions from "Y insertion(s)(+)" if present (handle both "1 insertion" and "N insertions"), otherwise 0
3. Extract deletions from "Z deletion(s)(-)" if present (handle both "1 deletion" and "N deletions"), otherwise 0
4. Calculate total changes = insertions + deletions

**Important Edge Cases:**
- Single file: `"1 file changed"` (singular form)
- No insertions: Git omits `"insertions(+)"` entirely → treat as 0
- No deletions: Git omits `"deletions(-)"` entirely → treat as 0
- Pure rename: May show `"0 insertions(+), 0 deletions(-)"` or omit both

**Decision Logic (ANY condition triggers xhigh):**
- IF file_count >= 10 → xhigh
- IF total_changes >= 500 → xhigh
- IF insertions >= 300 → xhigh
- IF deletions >= 300 → xhigh
- ELSE → high

**Example Cases:**
- ✅ "20 files changed, 342 insertions(+), 985 deletions(-)" → xhigh (files=20≥10, total=1327≥500, deletions=985≥300)
- ✅ "5 files changed, 600 insertions(+), 50 deletions(-)" → xhigh (total=650≥500, insertions=600≥300)
- ✅ "12 files changed, 100 insertions(+), 50 deletions(-)" → xhigh (files=12≥10)
- ✅ "1 file changed, 400 deletions(-)" → xhigh (deletions=400≥300)
- ❌ "3 files changed, 150 insertions(+), 80 deletions(-)" → high (all conditions fail)
- ❌ "1 file changed, 50 insertions(+)" → high (no deletions, total=50<500)

**Invoke codex-runner Subtask:**

Use Task tool to invoke codex-runner, passing complete command (including Lint + codex review):
Task parameters:
  • subagent_type: Bash
  • description: "Execute Lint and codex review"
  • timeout: 1800000 (30 minutes for difficult tasks) or 600000 (10 minutes for normal tasks)
  • prompt: Choose corresponding command based on project type and difficulty
Go project - Difficult task: go fmt ./... && go vet ./... && codex review --uncommitted --config model_reasoning_effort=xhigh (timeout: 1800000)
Go project - Normal task: go fmt ./... && go vet ./... && codex review --uncommitted --config model_reasoning_effort=high (timeout: 600000)
Node project - Difficult task: npm run lint:fix && codex review --uncommitted --config model_reasoning_effort=xhigh (timeout: 1800000)
Node project - Normal task: npm run lint:fix && codex review --uncommitted --config model_reasoning_effort=high (timeout: 600000)
Python project - Difficult task: black . && ruff check --fix . && codex review --uncommitted --config model_reasoning_effort=xhigh (timeout: 1800000)
Python project - Normal task: black . && ruff check --fix . && codex review --uncommitted --config model_reasoning_effort=high (timeout: 600000)
Clean working directory: codex review --commit HEAD --config model_reasoning_effort=high (timeout: 600000)
undefined

**解析规则:**
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(-)"`或同时省略两者

**决策逻辑(任一条件触发xhigh):**
- 若 file_count ≥ 10 → xhigh
- 若 total_changes ≥ 500 → xhigh
- 若 insertions ≥ 300 → xhigh
- 若 deletions ≥ 300 → xhigh
- 否则 → high

**示例案例:**
- ✅ "20 files changed, 342 insertions(+), 985 deletions(-)" → xhigh(文件数=20≥10,总变更=1327≥500,删除行数=985≥300)
- ✅ "5 files changed, 600 insertions(+), 50 deletions(-)" → xhigh(总变更=650≥500,插入行数=600≥300)
- ✅ "12 files changed, 100 insertions(+), 50 deletions(-)" → xhigh(文件数=12≥10)
- ✅ "1 file changed, 400 deletions(-)" → xhigh(删除行数=400≥300)
- ❌ "3 files changed, 150 insertions(+), 80 deletions(-)" → high(所有条件均不满足)
- ❌ "1 file changed, 50 insertions(+)" → high(无删除,总变更=50<500)

**调用codex-runner子任务:**

使用Task工具调用codex-runner,传入完整命令(包含Lint + codex审核):
Task参数:
  • subagent_type: Bash
  • description: "执行Lint和codex审核"
  • timeout: 1800000(高难度任务30分钟)或600000(常规任务10分钟)
  • prompt: 根据项目类型和难度选择对应的命令
Go项目 - 高难度任务: go fmt ./... && go vet ./... && codex review --uncommitted --config model_reasoning_effort=xhigh (超时时间: 1800000)
Go项目 - 常规任务: go fmt ./... && go vet ./... && codex review --uncommitted --config model_reasoning_effort=high (超时时间: 600000)
Node项目 - 高难度任务: npm run lint:fix && codex review --uncommitted --config model_reasoning_effort=xhigh (超时时间: 1800000)
Node项目 - 常规任务: npm run lint:fix && codex review --uncommitted --config model_reasoning_effort=high (超时时间: 600000)
Python项目 - 高难度任务: black . && ruff check --fix . && codex review --uncommitted --config model_reasoning_effort=xhigh (超时时间: 1800000)
Python项目 - 常规任务: black . && ruff check --fix . && codex review --uncommitted --config model_reasoning_effort=high (超时时间: 600000)
干净的工作目录: codex review --commit HEAD --config model_reasoning_effort=high (超时时间: 600000)
undefined

4. Self-Correction

4. 自我修正

If Codex finds Changelog description inconsistent with code logic:
  • Code error → Fix code
  • Description inaccurate → Update Changelog
如果Codex发现Changelog描述与代码逻辑不一致:
  • 代码错误 → 修复代码
  • 描述不准确 → 更新Changelog

Complete Review Protocol

完整审核流程

  1. [GATE] Check CHANGELOG - Auto-generate and write if not updated (leverage current context to understand change intention)
  2. [PREPARE] Stage Untracked Files - Add all new files to git staging area (avoid codex P1 error)
  3. [EXEC] Task → Lint + codex review - Invoke Task tool to execute Lint and codex (isolated context, reduce waste)
  4. [FIX] Self-Correction - Fix code or update description when intention ≠ implementation
  1. [关卡] 检查CHANGELOG - 若未更新则自动生成并写入(利用当前上下文理解变更意图)
  2. [准备] 暂存未跟踪文件 - 将所有新文件添加到git暂存区(避免codex P1错误)
  3. [执行] 任务 → Lint + codex审核 - 调用Task工具执行Lint和codex审核(独立上下文,减少浪费)
  4. [修复] 自我修正 - 当意图≠实现时,修复代码或更新描述

Codex Review Command Reference

Codex审核命令参考

Basic Syntax

基本语法

bash
codex review [OPTIONS] [PROMPT]
Note:
[PROMPT]
parameter cannot be used with
--uncommitted
,
--base
, or
--commit
.
bash
codex review [OPTIONS] [PROMPT]
注意
[PROMPT]
参数不能与
--uncommitted
--base
--commit
同时使用。

Common Options

常用选项

OptionDescriptionExample
--uncommitted
Review all uncommitted changes in working directory (staged + unstaged + untracked)
codex review --uncommitted
--base <BRANCH>
Review changes relative to specified base branch
codex review --base main
--commit <SHA>
Review changes introduced by specified commit
codex review --commit HEAD
--title <TITLE>
Optional commit title, displayed in review summary
codex review --uncommitted --title "feat: add JSON parser"
-c, --config <key=value>
Override configuration values
codex review --uncommitted -c model="o3"
选项描述示例
--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="o3"

Usage Examples

使用示例

bash
undefined
bash
undefined

1. Review all uncommitted changes (most common)

1. 审核所有未提交变更(最常用)

codex review --uncommitted
codex review --uncommitted

2. Review latest commit

2. 审核最新提交

codex review --commit HEAD
codex review --commit HEAD

3. Review specific commit

3. 审核指定提交

codex review --commit abc1234
codex review --commit abc1234

4. Review all changes in current branch relative to main

4. 审核当前分支相对于main分支的所有变更

codex review --base main
codex review --base main

5. Review changes in current branch relative to develop

5. 审核当前分支相对于develop分支的所有变更

codex review --base develop
codex review --base develop

6. Review with title (title shown in review summary)

6. 带标题的审核(标题会显示在审核摘要中)

codex review --uncommitted --title "fix: resolve JSON parsing errors"
codex review --uncommitted --title "fix: resolve JSON parsing errors"

7. Review using specific model

7. 使用指定模型进行审核

codex review --uncommitted -c model="o3"
undefined
codex review --uncommitted -c model="o3"
undefined

Important Limitations

重要限制

  • --uncommitted
    ,
    --base
    ,
    --commit
    are mutually exclusive, cannot be used together
  • [PROMPT]
    parameter is mutually exclusive with the above three options
  • Must be executed in a git repository directory
  • --uncommitted
    --base
    --commit
    三者互斥,不能同时使用
  • [PROMPT]
    参数与上述三个选项互斥
  • 必须在git仓库目录中执行

Important Notes

重要说明

  • Ensure execution in git repository directory
  • Timeout automatically adjusted based on task difficulty:
    • Difficult tasks: 30 minutes (
      timeout: 1800000
      )
    • Normal tasks: 10 minutes (
      timeout: 600000
      )
  • codex command must be properly configured and logged in
  • codex automatically processes in batches for large changes
  • CHANGELOG.md must be in uncommitted changes, otherwise Codex cannot see intention description
  • 确保在git仓库目录中执行
  • 根据任务难度自动调整超时时间:
    • 高难度任务:30分钟(
      timeout: 1800000
    • 常规任务:10分钟(
      timeout: 600000
  • codex命令必须正确配置并已登录
  • 对于大规模变更,codex会自动分批处理
  • CHANGELOG.md必须在未提交变更中,否则Codex无法看到意图描述

Design Rationale

设计理念

Why separate contexts?
  1. CHANGELOG update needs current context: Understanding user's previous conversation and task intention to generate accurate change description
  2. Codex review doesn't need conversation history: Only needs code changes and CHANGELOG, more efficient to run independently
  3. Reduce token consumption: codex review as independent subtask, doesn't carry irrelevant conversation context
为什么要分离上下文?
  1. CHANGELOG更新需要当前上下文:理解用户之前的对话和任务意图,以生成准确的变更描述
  2. Codex审核不需要对话历史:仅需代码变更和CHANGELOG,独立运行效率更高
  3. 减少token消耗:将codex审核作为独立子任务,无需携带无关的对话上下文