codex-code-review

Codex 代码审查循环

概述

此技能负责协调 codex Agent 对待审查代码的完整修复工作流。它会处理：

• 使用 codex --full-auto c CLI 请求审查
• 解析审查输出，识别 P0（安全性／正确性）、P1（可靠性）和 P2-P4（质量）问题
• 通过最多 3 轮审查－修复－审查循环修复严重问题
• 将质量改进延期到待办事项，并附上实施计划和 origin:ai-review 标签
• 与其他 Agent 协作时，进行单体仓库处理，选择性提交文件
• 如果 3 轮后 P0/P1 问题仍未解决，则触发断路器升级处理

何时使用

当代码需要 codex 审查时，触发此技能。常见用法：

• “codex review this code” —— 对当前更改启动审查循环
• “run codex review on my changes” —— 同上
• “codex review --uncommitted” —— 审查所有未提交的更改
• “codex review --commit ” —— 在单体仓库中审查指定提交
• 关于 codex 的问题（例如“codex 如何工作？”）—— 不要触发此技能；直接回答

不要因提问而触发。 仅在用户明确请求审查时启用。

---

审查循环：分步说明

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

循环管理

• 第 1 轮：实现完成后进行初次审查
• 第 2 轮：首次修复后进行审查
• 第 3 轮：第二次修复后进行审查
• 第 3 轮之后：如果仍有 P0/P1 问题，则停止。总结发现并询问用户是否要继续（这种情况很少见，通常说明问题出在设计层面）

---

决策树：处理发现的问题

审查发现 P0/P1 问题时（结论：REQUEST CHANGES）

1. 阅读 codex 审查 Markdown 文件
2. 提取每个 P0 和 P1 问题，并记录：
   • 问题 ID 和标题
   • 文件位置
   • 建议的修复方案
3. 仅修复代码中指出的问题
4. 不要重构，也不要引入新功能
5. 如果修复需要重大的设计更改，请注明，并让 codex 在下一轮重新评估
6. 修改现有提交或新建提交（由用户通过 git config 选择；默认修改现有提交，以便最终只保留一个提交）
7. 增加循环计数器，然后重新运行 codex 审查

审查发现 P2-P4 问题时（结论：APPROVE 或 PASS WITH ISSUES）

1. 对每个 P2/P3 问题，决定：

   • 立即修复：你可以自行决定；在同一轮中实施改进
   • 延期：创建待办事项，并添加：
     • 类型标签：remediation
     • 严重性标签：P2 或 P3
     • 自定义标签：origin:ai-review
     • 基于 codex 建议方案的实施计划
     • 审查中列出的验收标准

2. 示例：

   # 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"
   

审查未发现问题时（结论：APPROVE）

退出循环。代码没有问题。继续进行测试审查（如适用），或提交以便合并。

---

单体仓库处理

在有多个 Agent 协作的单体仓库中，应选择要提交的内容，并控制审查范围。

场景 1：只有你的更改

如果工作目录中只有你的更改：

codex --full-auto c --uncommitted

审查循环完成后提交你的更改。

场景 2：混合更改（你和其他 Agent）

如果存在其他 Agent 留下的未跟踪或未提交更改：

1. 首先只提交你的文件：

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

2. 记录提交 SHA
3. 对你的提交运行审查：

   codex --full-auto c --commit <SHA>
   

4. 修改你的提交以修复问题：

   git add <fixed-files>
   git commit --amend --no-edit
   

   （保留原始提交消息；修改提交时会加入修复内容）
5. 按常规流程返回审查循环

结果： 一个包含你的更改和修复内容的干净提交。其他 Agent 的工作仍保持独立。

---

文件位置

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

---

随附参考资料

参见 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 数量
• 快速提取结论

---

关键规则

1. 退出循环前必须修复所有 P0/P1。 不得例外。
2. P2-P4 可以延期处理，纳入待办事项，也可以酌情修复。
3. 每个问题单独创建一个事项——不要把无关的 P2/P3 问题合并到同一个事项中。
4. 延期事项必须包含计划——codex 已指出问题；你需要提供结构化的解决方案。
5. 在修复期间修改现有提交（不要创建新提交），以确保最终只有一个干净的提交。
6. 最多进行 3 轮审查——第 3 轮后，如果仍有 P0/P1 问题，请总结情况并询问用户是否继续。
7. 在单体仓库中有选择地提交——只审查和修复你改动过的文件。

---

升级处理：断路器触发时

进行 3 轮审查后，如果仍有 P0/P1 问题：

1. 停止修复。不要尝试进行第 4 轮。
2. 提供一份结构化摘要，内容包括：
   • 每轮尝试了什么
   • 仍未解决的 P0/P1 问题
   • 问题持续存在的原因（Agent 的评估——是设计问题、需求冲突，还是规格含糊？）
   • 建议采取的人工操作
3. 向用户展示此摘要，并询问接下来如何处理。

升级处理通常表明原始任务规格需要澄清，或代码需要进行超出修复范围的架构调整。

---

与其他技能集成

• backlog-md：使用带有 origin:ai-review 标签的 backlog task create，为延期处理的 P2/P3 问题创建待办事项
• git-ops：处理单体仓库中的提交、修改提交和选择性暂存
• requesting-code-review：codex 审查循环完成后，如果还需要人工代码审查，则使用此技能

---

快速参考：完整工作流

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