| name | code-review |
| description | Use ONLY when the user asks to review, verify, or re-examine reported code defects/issues before fixing, OR to verify completeness after a batch code change. Covers a 6-phase workflow from independent verification of claims, through classification and strict grouping, decision preparation, post-implementation verification, to rule perpetuation. Triggers on "review defects", "verify issues", "复核", "复查", "验证缺陷", "代码审查", "残留扫描", "交叉核验". |
代码复核与验证工作流
规范 AI 智能体执行缺陷复核、分类决策、实施后核验的流程。与 code-workflow（管"怎么实现"）互补：本 skill 管"怎么验证和决策"。核心：代码是最高真相，二手报告不可盲信，矛盾用直接证据裁决。
一、流程总览
Phase 0 独立验证（并行 subagent）-> Phase 1 分类先行 -> Phase 2 严格分组
-> Phase 3 决策准备 -> Phase 4 实施后核验 -> Phase 5 规则永久化
Phase 0-3 是 code-workflow Phase 0 的前置深化；Phase 4-5 是 code-workflow Phase 4-5 的后置深化。
二、各阶段
Phase 0: 独立验证
禁止直接按记录修复，每条断言对照实际代码独立验证。 先 git fetch 检查跨 session 冲突。启动并行 subagent：每条缺陷读标注位置、核实断言（位置准确？行为存在？严重性合理？）、查阅设计文档确认意图、查阅测试确认覆盖，返回 ✅属实 / ⚠️部分属实 / ❌不实。矛盾时亲自读代码取直接证据，不靠"谁更可信"裁决。警惕：陈旧文档、前提错误、过度定性、混淆"死代码"与"预留接口"。
Phase 1: 分类先行
分类决定动作，误分类导致错误动作：
| 分类 | 定义 | 正确动作 |
|---|
| 真 bug | 代码行为与设计意图不符 | 修复 |
| 死代码 | 存在但永不执行（零调用点、前提不存在） | 删除 |
| 有效死代码 | 当前不可达但约束变化后可变为可达 | 改为 fail-fast 断言 |
| 功能空壳 | 有调用点但核心逻辑为空 | 删除（违架构时）或实现（有需求时） |
| 半接通特性 | 框架已落地但职责分离未完成 | 禁用默认路径 + 并入专项重做 |
| 预留接口未激活 | 已声明、有设计意图、但无消费者 | 激活（加消费者、修类型契约） |
| 设计限制 | 不是 bug，是设计决策后果 | 文档化到已知限制 |
| 需讨论 | 无法单独决断 | 进入 Phase 2-3 |
辨别方法："死代码" vs "预留接口"用 grep 消费者 + git 历史 + 设计文档 + 类型契约；"真 bug" vs "设计限制"查已知限制与架构文档；"半接通" vs "完整"查规范文档设计意图。
Phase 2: 严格分组
只有三重标准全一致才可合并讨论：问题本质（根源是否相同）+ 修复方案（改动方式是否一致）+ 架构层级（同一层吗）。任一不一致即独立。"同文件" / "同主题" / "修复 A 减少 B 风险"均不构成分组理由。全部独立也要明确报告（确认无遗漏的架构关联）。
Phase 3: 决策准备
决策者须先充分理解问题。对每个需决策的组准备完整叙述：问题是什么 / 从哪里来 / 本质是什么 / 最初设计思路 / 涉及代码（file:line）/ 与现有约束的关系 / 在 pending 工作中的位置。检验"不迁就现状"（推翻现状是否更优）与半修复风险（级联是否全覆盖）。给推荐方案及理由，不提供"最快速修复"（除非它即最佳）。自主决策：触及 AGENTS.md "自主工作循环"上报阈值的项向用户确认方向后再实现；自主范围内的按推荐方案直接推进。
Phase 4: 实施后核验
"subagent 说做完了"不等于做完了。 残留扫描：扫描所有应被替换/删除的旧模式，范围须超出 subagent 分配范围（subagent 可能遗漏范围外文件），pattern 从项目书写准则禁止项派生，零残留后才提交。subagent 遗漏检查：对照已处理清单逐一确认落地，检查跳过项与范围外文件。文档同步：按 AGENTS.md 单点真理表同步对应治理文档。测试：运行 python -m pytest tests/，测试断言引用旧模式时同步更新（改革的一部分，非测试重构）。差距分析：每条遗漏须有理由。
Phase 5: 规则永久化
一次性清洁不够，规则须写入治理文档使未来始终遵循。识别本次变更产生的通用规则，写入对应位置（代码层规则 -> 治理文档；硬规则 -> AGENTS.md；工作流规则 -> 本 skill 或 code-workflow）。提供自查 grep 命令覆盖本次发现的违规模式。更新 AGENTS.md 指针（如有新 skill / 文档章节）。清理临时任务文档。
三、关键模式
- 矛盾裁决顺序：源代码 > 测试 > 设计文档 > 标记"待验证"不擅裁。禁止靠"哪个 subagent 更可信"或"哪个报告更详细"裁决。
- 死代码 vs 预留接口：grep 消费者 +
git log -p --all -S 历史 + 设计文档未来计划 + 类型契约一致性。无意图无计划无历史消费者 -> 删除；有意图有计划且契约破损 -> 激活。
- 不迁就现状检验：从零设计会用现方案吗？有为不破坏现状的妥协吗？推翻是否更优？推翻明显更优则推荐推翻，改动更大不是反对理由。
- 残留扫描覆盖范围：扫描须超出实施者分配范围，对全仓做全量扫描，确认零残留才提交。
四、何时用哪个 skill
- code-review：拿到缺陷报告需验证 / 批量变更后核验完整性 / 准备决策材料 / 将一次性清洁规则永久化。
- code-workflow：需求明确直接实现 / 修复已验证单一 bug / 重构已确认方向。
- 两者都用：复杂缺陷（先 review 验证决策，再 workflow 实现，最后 review 核验）/ 大规模整改（先 review 分类分组，再 workflow 批量实施，最后 review 核验永久化）。
