codex-review
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCodex 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 alone only shows AI "what was done (Implementation)".
Recording intention first tells AI "what you wanted to do (Intention)".
codex review --uncommitted"Code changes + intention description" as combined input is the most effective way to improve AI code review quality.
单独运行仅会向AI展示“已完成的内容(实现)”。
先记录意图则会告知AI“你想要完成的目标(意图)”。
codex review --uncommitted将“代码变更 + 意图描述”作为组合输入是提升AI代码审核质量的最有效方式。
Skill Architecture
技能架构
This skill operates in two phases:
- Preparation Phase (current context): Check working directory, update CHANGELOG
- Review Phase (isolated context): Invoke Task tool to execute Lint + codex review (using context: fork to reduce context waste)
该技能分为两个阶段运行:
- 准备阶段(当前上下文):检查工作目录,更新CHANGELOG
- 审核阶段(独立上下文):调用Task工具执行Lint + codex审核(使用fork上下文以减少上下文浪费)
Execution Steps
执行步骤
0. [First] Check Working Directory Status
0. [第一步] 检查工作目录状态
bash
git diff --name-only && git status --shortDecide 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
undefinedCheck 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:**
```markdowngit 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:**
- Detected CHANGELOG not updated
- Run git diff --stat, found handlers/responses.go modified (+88 lines)
- Run git diff to analyze details: added CompactHandler function
- Auto-generate entry:
Added
- Added endpoint for conversation context compression
/v1/responses/compact - Supports multi-channel failover and request body size limits
- Added
- Use Edit tool to write to CHANGELOG.md
- Continue with lint and codex review
undefined- 功能描述:解决的问题或实现的功能
- 影响文件:主要修改的文件/模块
**示例 - 自动生成流程:**
- 检测到CHANGELOG未更新
- 运行git diff --stat,发现handlers/responses.go被修改(新增88行)
- 运行git diff分析细节:新增了CompactHandler函数
- 自动生成条目:
Added
- 新增端点用于对话上下文压缩
/v1/responses/compact - 支持多通道故障转移和请求体大小限制
- 新增
- 使用Edit工具写入CHANGELOG.md
- 继续执行Lint和codex审核
undefined2. [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
undefinedCheck for new files
检查是否存在新文件
git status --short | grep "^??"
**If there are new files, automatically execute:**
```bashgit status --short | grep "^??"
**如果存在新文件,自动执行:**
```bashSafely 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 reviewgit 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
undefinedCount 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:
```bashgit diff --stat | tail -1
**难度评估标准:**
**高难度任务**(满足任一条件):
- 修改文件数 ≥ 10
- 代码变更总行数(插入+删除)≥ 500行
- 单一指标:插入行数 ≥ 300行 或 删除行数 ≥ 300行
- 涉及核心架构/算法变更
- 跨模块重构
- 配置:`model_reasoning_effort=xhigh`,超时时间30分钟
**常规任务**(其他情况):
- 配置:`model_reasoning_effort=high`,超时时间10分钟
**评估方法:**
必须正确解析`git diff --stat`的输出以确定难度:
```bashGet 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)
undefined4. 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
完整审核流程
- [GATE] Check CHANGELOG - Auto-generate and write if not updated (leverage current context to understand change intention)
- [PREPARE] Stage Untracked Files - Add all new files to git staging area (avoid codex P1 error)
- [EXEC] Task → Lint + codex review - Invoke Task tool to execute Lint and codex (isolated context, reduce waste)
- [FIX] Self-Correction - Fix code or update description when intention ≠ implementation
- [关卡] 检查CHANGELOG - 若未更新则自动生成并写入(利用当前上下文理解变更意图)
- [准备] 暂存未跟踪文件 - 将所有新文件添加到git暂存区(避免codex P1错误)
- [执行] 任务 → Lint + codex审核 - 调用Task工具执行Lint和codex审核(独立上下文,减少浪费)
- [修复] 自我修正 - 当意图≠实现时,修复代码或更新描述
Codex Review Command Reference
Codex审核命令参考
Basic Syntax
基本语法
bash
codex review [OPTIONS] [PROMPT]Note: parameter cannot be used with , , or .
[PROMPT]--uncommitted--base--commitbash
codex review [OPTIONS] [PROMPT]注意:参数不能与、或同时使用。
[PROMPT]--uncommitted--base--commitCommon Options
常用选项
| Option | Description | Example |
|---|---|---|
| Review all uncommitted changes in working directory (staged + unstaged + untracked) | |
| Review changes relative to specified base branch | |
| Review changes introduced by specified commit | |
| Optional commit title, displayed in review summary | |
| Override configuration values | |
| 选项 | 描述 | 示例 |
|---|---|---|
| 审核工作目录中所有未提交的变更(已暂存 + 未暂存 + 未跟踪) | |
| 审核相对于指定基准分支的变更 | |
| 审核指定提交引入的变更 | |
| 可选的提交标题,会显示在审核摘要中 | |
| 覆盖配置值 | |
Usage Examples
使用示例
bash
undefinedbash
undefined1. 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"
undefinedcodex review --uncommitted -c model="o3"
undefinedImportant Limitations
重要限制
- ,
--uncommitted,--baseare mutually exclusive, cannot be used together--commit - parameter is mutually exclusive with the above three options
[PROMPT] - 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
- Difficult tasks: 30 minutes (
- 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
- 高难度任务:30分钟(
- codex命令必须正确配置并已登录
- 对于大规模变更,codex会自动分批处理
- CHANGELOG.md必须在未提交变更中,否则Codex无法看到意图描述
Design Rationale
设计理念
Why separate contexts?
- CHANGELOG update needs current context: Understanding user's previous conversation and task intention to generate accurate change description
- Codex review doesn't need conversation history: Only needs code changes and CHANGELOG, more efficient to run independently
- Reduce token consumption: codex review as independent subtask, doesn't carry irrelevant conversation context
为什么要分离上下文?
- CHANGELOG更新需要当前上下文:理解用户之前的对话和任务意图,以生成准确的变更描述
- Codex审核不需要对话历史:仅需代码变更和CHANGELOG,独立运行效率更高
- 减少token消耗:将codex审核作为独立子任务,无需携带无关的对话上下文