codex-code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex Code Review Loop

Codex代码审查循环

Overview

概述

This skill orchestrates the complete remediation workflow for code under review by the codex agent. It handles:

Requesting reviews from codex using the
```
codex --full-auto c
```
CLI
Parsing review output to identify P0 (security/correctness), P1 (reliability), P2-P4 (quality) findings
Remediating critical issues through up to 3 review-fix-review cycles
Deferring quality improvements to backlog with implementation plans and
```
origin:ai-review
```
labels
Monorepo handling for selective file commits when working alongside other agents
Circuit breaker escalation after 3 cycles if P0/P1 issues persist

该Skill可协调codex agent审查代码的完整修复工作流。它负责处理以下内容：

发起codex审查：使用
```
codex --full-auto c
```
CLI命令
解析审查输出：识别P0（安全/正确性）、P1（可靠性）、P2-P4（质量）类问题
修复关键问题：通过最多3轮“审查-修复-审查”循环
推迟质量改进任务：将相关任务添加到待办事项，并附上实现方案和
```
origin:ai-review
```
标签
单仓（Monorepo）处理：当与其他agent协同工作时，支持选择性提交文件
熔断升级机制：若经过3轮循环后P0/P1问题仍存在，则触发升级流程

When to Use

使用场景

Trigger this skill when code requires codex review. Common usage patterns:

"codex review this code" — Initiate review loop on current changes
"run codex review on my changes" — Same as above
"codex review --uncommitted" — Review all uncommitted changes
"codex review --commit <SHA>" — Review specific commit in monorepo
Questions about codex (e.g., "how does codex work?") — Do not trigger this skill; answer directly

Do not trigger on questions. Only activate for direct review requests.

当代码需要codex审查时触发该Skill。常见使用模式：

"codex review this code" — 针对当前变更启动审查循环
"run codex review on my changes" — 与上述命令功能相同
"codex review --uncommitted" — 审查所有未提交的变更
"codex review --commit <SHA>" — 审查单仓中的特定提交
关于codex的问题（例如："how does codex work?"）— 不触发该Skill，直接回答问题

请勿针对问题触发。仅在收到明确的审查请求时激活。

The Review Loop: Step by Step

审查循环：分步说明

ENTRY: User requests codex review or skill is triggered by "codex review" in a message

┌──────────────────────────┐
│ 1. INVOKE CODEX REVIEW   │ ← Run: codex --full-auto c [--uncommitted|--commit <SHA>|--base <BRANCH>]
└──────┬───────────────────┘   Output goes to .agent/reviews/review-<timestamp>.md
       │
       ▼
┌──────────────────────────┐
│ 2. READ & PARSE REVIEW   │ ← Read markdown file, extract P0/P1/P2-P4 findings and verdict
└──────┬───────────────────┘
       │
       ├─────────────────────────────────────────┐
       │                                         │
       ▼                                         ▼
  ANY P0/P1?              NO         FILE P2-P4 ISSUES → Exit loop
       │                              (via backlog CLI)
       │ YES                         Create issue per finding with
       │                             - label: origin:ai-review
  ┌────────────────┐                - Implementation plan
  │ 3. REMEDIATE   │                - Priority (P2 or P3)
  │ P0/P1 FINDINGS │
  └────┬───────────┘
       │ (amend commit or new changes)
       │
       ▼
  ┌──────────────────────┐
  │ 4. LOOP CHECK        │
  │ Cycle count < 3?     │
  └────┬───────────────┬─┘
       │ YES           │ NO
       │               └─→ SUMMARIZE & ASK USER TO CONTINUE
       │                   (or exit if user declines)
       ▼
  Re-run codex review (step 1, same files/scope)
  Loop back to step 2

ENTRY: User requests codex review or skill is triggered by "codex review" in a message

┌──────────────────────────┐
│ 1. 调用CODEX审查        │ ← 执行命令: codex --full-auto c [--uncommitted|--commit <SHA>|--base <BRANCH>]
└──────┬───────────────────┘   输出保存至 .agent/reviews/review-<timestamp>.md
       │
       ▼
┌──────────────────────────┐
│ 2. 读取并解析审查结果    │ ← 读取markdown文件，提取P0/P1/P2-P4类问题及审查结论
└──────┬───────────────────┘
       │
       ├─────────────────────────────────────────┐
       │                                         │
       ▼                                         ▼
  是否存在P0/P1问题?       否         处理P2-P4类问题 → 退出循环
       │                              (通过待办事项CLI)
       │ 是                          为每个问题创建待办事项，包含：
       │                             - 标签: origin:ai-review
  ┌────────────────┐                - 实现方案
  │ 3. 修复P0/P1问题 │                - 优先级（P2或P3）
  └────┬───────────┘
       │（修改提交或新增变更）
       │
       ▼
  ┌──────────────────────┐
  │ 4. 循环检查          │
  │ 循环次数 < 3?        │
  └────┬───────────────┬─┘
       │ 是             │ 否
       │               └─→ 总结结果并询问用户是否继续
       │                  （若用户拒绝则退出）
       ▼
  重新执行codex审查（步骤1，相同文件/范围）
  返回步骤2循环

Cycle Management

循环管理

Cycle 1: Initial review after implementation
Cycle 2: After first remediation
Cycle 3: After second remediation
After Cycle 3: If P0/P1 remain, stop. Summarize findings and ask user if they want to continue (rare; usually indicates design-level issues)

第1轮循环：实现完成后的初始审查
第2轮循环：首次修复后的审查
第3轮循环：第二次修复后的审查
第3轮循环后：若P0/P1问题仍存在，则停止循环。总结问题并询问用户是否继续（这种情况很少见，通常表明存在设计层面的问题）

Decision Tree: Handling Findings

决策树：问题处理方式

When review shows P0/P1 findings (verdict: REQUEST CHANGES)

当审查结果显示存在P0/P1问题（结论：REQUEST CHANGES）

Read the codex review markdown file
Extract each P0 and P1 finding with:
- Finding ID and title
- File location
- Suggested fix
Fix ONLY the cited findings in the code
Do NOT refactor, do NOT introduce new functionality
If a fix requires significant design changes, note this and let codex re-evaluate on next cycle
Amend your commit OR create a new one (user's choice via git config; by default amend to keep one commit at end)
Increment cycle counter and re-run codex review

读取codex审查的markdown文件
提取每个P0和P1问题，包含：
- 问题ID和标题
- 文件位置
- 建议修复方案
仅修复代码中被指出的问题
请勿重构，请勿引入新功能
若修复需要重大设计变更，请记录此情况并让codex在下一轮循环中重新评估
修改提交记录（amend）或创建新提交（用户可通过git配置选择；默认使用amend以最终保留单个提交）
增加循环计数器并重新执行codex审查

When review shows P2-P4 findings (verdict: APPROVE or PASS WITH ISSUES)

当审查结果显示存在P2-P4问题（结论：APPROVE或PASS WITH ISSUES）

For each P2/P3 finding, decide:
- Fix now: You have discretion; implement the improvement in the same cycle
- Defer: Create a backlog issue with:
  - Type label:
```
remediation
```
  - Severity label:
```
P2
```
    or
```
P3
```
  - Custom label:
```
origin:ai-review
```
  - Implementation plan based on codex's suggested approach
  - Acceptance criteria from the review

Examples:

# P2 finding deferred to backlog
backlog task create "Code clarity: add docstring to validateInput()" \
  -d "Review finding: missing documentation on public function" \
  -l remediation -p 2 \
  --ac "Add docstring explaining parameter types and return value" \
  --plan "Add JSDoc comment above function definition per project style"

针对每个P2/P3问题，决定：
- 立即修复：您可自行决定；在同一循环中实现改进
- 推迟处理：创建待办事项，包含：
  - 类型标签:
```
remediation
```
  - 严重程度标签:
```
P2
```
    或
```
P3
```
  - 自定义标签:
```
origin:ai-review
```
  - 基于codex建议方案的实现计划
  - 审查中提出的验收标准

示例：

# 推迟到待办事项的P2问题
backlog task create "Code clarity: add docstring to validateInput()" \
  -d "Review finding: missing documentation on public function" \
  -l remediation -p 2 \
  --ac "Add docstring explaining parameter types and return value" \
  --plan "Add JSDoc comment above function definition per project style"

When review shows no findings (verdict: APPROVE)

当审查结果无问题（结论：APPROVE）

Exit the loop. Code is clean. Proceed to test review (if applicable) or commit for merge.

退出循环。代码已符合要求。继续进行测试审查（如有需要）或提交以合并代码。

Monorepo Handling

单仓（Monorepo）处理

In a monorepo with multiple agents, be selective about what you commit and what scope you review.

在包含多个agent的单仓中，需谨慎选择提交内容和审查范围。

Scenario 1: Only Your Changes

场景1：仅包含您的变更

If the working directory has ONLY your changes:

bash

codex --full-auto c --uncommitted

Commit your changes once review loop completes.

若工作目录中仅有您的变更：

bash

codex --full-auto c --uncommitted

审查循环完成后提交您的变更。

Scenario 2: Mixed Changes (You + Other Agents)

场景2：混合变更（您+其他Agent）

If there are untracked or uncommitted changes from other agents:

Commit ONLY your files first:

bash

git add <your-files-only>
git commit -m "Your commit message"

Note the commit SHA
Run review on your commit:
bash
```
codex --full-auto c --commit <SHA>
```
Remediate by amending your commit:
bash
```
git add <fixed-files>
git commit --amend --no-edit
```
(Preserve the original message; the amend adds the fixes)
Loop back to review as normal

Result: One clean commit with your changes and fixes. Other agents' work remains separate.

若存在其他agent的未跟踪或未提交变更：

仅提交您的文件：

bash

git add <your-files-only>
git commit -m "Your commit message"

记录提交的SHA值
针对您的提交执行审查：
bash
```
codex --full-auto c --commit <SHA>
```
通过修改提交记录修复问题：
bash
```
git add <fixed-files>
git commit --amend --no-edit
```
（保留原始提交信息；amend操作会添加修复内容）
正常返回审查循环

结果：最终得到一个包含您的变更和修复内容的干净提交。其他agent的工作将保持独立。

File Locations

文件位置

Review output:
```
.agent/reviews/review-<timestamp>.md
```
(relative to project root)
One review file per cycle — new file created on each
```
codex --full-auto c
```
invocation
Always read the latest file — check the timestamp to ensure you're reading the current cycle's review

审查输出：
```
.agent/reviews/review-<timestamp>.md
```
（相对于项目根目录）
每轮循环生成一个审查文件 — 每次执行
```
codex --full-auto c
```
都会创建新文件
始终读取最新文件 — 检查时间戳以确保读取的是当前循环的审查结果

Bundled References

附带动手册

See
references/codex-cli-reference.md
for:

Complete codex CLI syntax and invocation patterns
How to select
```
--uncommitted
```
vs.
```
--commit
```
vs.
```
--base
```
When to use each mode

See
references/review-format.md
for:

Structure of the review markdown output
How to parse P0/P1/P2/P3 sections
How to identify the verdict (APPROVE / REQUEST CHANGES / BLOCKED)
Example review output

See
references/backlog-integration.md
for:

How to create backlog issues from deferred findings
Label and priority conventions
Implementation plan templates
Examples of issues filed from reviews

See
scripts/parse_codex_review.sh
for:

Helper script to extract findings from review markdown
Counts P0/P1/P2/P3 per cycle
Quick verdict extraction

请查看
references/codex-cli-reference.md
获取：

codex CLI完整语法和调用模式
如何选择
```
--uncommitted
```
、
```
--commit
```
或
```
--base
```
参数
各模式的适用场景

请查看
references/review-format.md
获取：

审查markdown输出的结构
如何解析P0/P1/P2/P3部分
如何识别审查结论（APPROVE / REQUEST CHANGES / BLOCKED）
审查输出示例

请查看
references/backlog-integration.md
获取：

如何将推迟处理的问题创建为待办事项
标签和优先级约定
实现计划模板
从审查结果创建待办事项的示例

请查看
scripts/parse_codex_review.sh
获取：

从审查markdown文件提取问题的辅助脚本
统计每轮循环的P0/P1/P2/P3问题数量
快速提取审查结论

Key Rules

核心规则

All P0/P1 must be fixed before exiting the loop. No exceptions.
P2-P4 can be deferred to backlog or fixed at your discretion.
File one issue per finding — do not batch unrelated P2/P3s into one issue.
Deferred issues must include a plan — codex identified the problem; you provide the structured approach.
Amend commits (not new commits) during remediation so you end with one clean commit.
Max 3 review cycles — after cycle 3, if P0/P1 remain, summarize and ask user to continue.
In monorepos, commit selectively — review and fix only the files you touched.

所有P0/P1问题必须修复后才能退出循环。无例外。
P2-P4问题可推迟处理到待办事项，或根据您的判断立即修复。
每个问题创建一个待办事项 — 请勿将不相关的P2/P3问题批量合并为一个待办事项。
推迟处理的问题必须包含实现计划 — codex已识别问题，您需提供结构化的解决思路。
修复时修改提交记录（而非创建新提交），以便最终得到一个干净的提交。
最多3轮审查循环 — 第3轮循环后，若P0/P1问题仍存在，总结结果并询问用户是否继续。
在单仓中，选择性提交 — 仅审查和修复您修改过的文件。

Escalation: When Circuit Breaker Triggers

升级机制：熔断触发时

After 3 review cycles, if P0/P1 findings persist:

Stop remediating. Do not attempt a 4th cycle.
Produce a structured summary including:
- What was attempted in each cycle
- What P0/P1 findings remain
- Why they persist (agent assessment — design issue? conflicting requirements? ambiguity in spec?)
- Recommended human action
Present this summary to the user and ask how to proceed.

Escalation usually indicates the original task spec needs clarification or the code requires architectural changes beyond remediation scope.

经过3轮审查循环后，若P0/P1问题仍存在：

停止修复。请勿尝试第4轮循环。
生成结构化总结，包含：
- 每轮循环中尝试的修复操作
- 剩余的P0/P1问题
- 问题持续存在的原因（agent评估 — 设计问题？需求冲突？规格不明确？）
- 建议的人工干预操作
将此总结呈现给用户并询问后续处理方式。

升级通常表明原始任务规格需要澄清，或代码需要超出修复范围的架构变更。

Integration with Other Skills

与其他Skill的集成

backlog-md: File deferred P2/P3 findings using
```
backlog task create
```
with
```
origin:ai-review
```
label
git-ops: Commit handling, amending, and selective staging in monorepos
requesting-code-review: Use after codex review loop completes if human code review is also required

backlog-md：使用
```
backlog task create
```
命令并添加
```
origin:ai-review
```
标签，将推迟处理的P2/P3问题创建为待办事项
git-ops：处理提交、修改提交记录，以及单仓中的选择性暂存操作
requesting-code-review：若还需要人工代码审查，可在codex审查循环完成后使用该Skill

Quick Reference: The Full Workflow

快速参考：完整工作流

1. User: "codex review"
        │
        ▼
2. Invoke: codex --full-auto c --uncommitted
        │
        ▼
3. Read: .agent/reviews/review-<timestamp>.md
        │
        ├─────────────────────────────────────────┐
        ▼                                         ▼
   P0/P1 FOUND?              NO         FILE P2-P4 ISSUES
   ├─ YES: Fix + Loop ────────────────► backlog task create ... --plan "..."
   └─ NO: File P2-P4 → Exit            (each finding = one issue)
        │
        ├─ Cycle 1 → Fix → Review
        ├─ Cycle 2 → Fix → Review
        ├─ Cycle 3 → Fix → Review
        │
        └─ If P0/P1 remain → Summarize + Ask User
                │
                └─► Continue? (rare) / Stop & Escalate

1. 用户: "codex review"
        │
        ▼
2. 调用: codex --full-auto c --uncommitted
        │
        ▼
3. 读取: .agent/reviews/review-<timestamp>.md
        │
        ├─────────────────────────────────────────┐
        ▼                                         ▼
   存在P0/P1问题?           否         处理P2-P4类问题
   ├─ 是: 修复 + 循环 ───────────────► backlog task create ... --plan "..."
   └─ 否: 处理P2-P4 → 退出            （每个问题对应一个待办事项）
        │
        ├─ 第1轮循环 → 修复 → 审查
        ├─ 第2轮循环 → 修复 → 审查
        ├─ 第3轮循环 → 修复 → 审查
        │
        └─ 若P0/P1问题仍存在 → 总结结果并询问用户
                │
                └─► 是否继续?（罕见）/ 停止并升级