古法编程

SuperPowers 的代码审查闭环由两个独立技能构成：requesting-code-review 负责在任务完成后强制派发 code-reviewer 子代理进行结构化审查；receiving-code-review 则规范了接收反馈时的技术验证流程，禁止表演性同意。两者结合，确保每个开发单元在合并前都经过独立的质量评估。

SuperPowers 代码审查工作流：requesting-code-review 与 receiving-code-review

在 SuperPowers 为 coding agents 定义的质量体系中，代码审查不是一个可选的社交环节，而是一个由技能严格定义的强制性技术流程。它由两个互补的技能共同驱动：requesting-code-review 负责在适当时机发起结构化审查，receiving-code-review 则规定了代理接收和处理外部反馈时必须遵循的严谨态度与技术动作。理解并正确执行这两端的流程，是 AI 代理产出可靠、可维护代码的关键质量门禁。

一、 请求审查：使用 requesting-code-review 技能

该技能的核心目标是：在问题扩散之前，派发一个独立的、仅基于代码变更的审查子代理进行客观评估。

1. 何时必须触发审查

根据 requesting-code-review/SKILL.md，以下场景必须发起代码审查：

  • 在 subagent-driven-development 流程中：每个子任务（task）完成后。
  • 完成一个主要功能后。
  • 在合并到 main 分支之前。

这是“尽早审查，频繁审查”原则的体现。审查子代理不承载你冗长的会话历史，这保证了它专注于工作产物（代码变更）本身，也保护了你自身的上下文以继续后续工作。

2. 派发审查子代理的具体步骤

派发过程需要精确的上下文输入，通常分为三步。

第一步：获取变更的 Git SHA 范围 审查必须基于具体的代码提交。你需要计算变更的起始提交 (BASE_SHA) 和结束提交 (HEAD_SHA)。起始点可以是上一个任务的提交或主分支的最新状态。

BASE_SHA=$(git rev-parse HEAD~1)  # 上一个提交，或 origin/main
HEAD_SHA=$(git rev-parse HEAD)    # 当前提交

第二步：派发 code-reviewer 子代理 使用 Task 工具，以 general-purpose 类型（v5.1.0 统一为此，取代了之前的 named agent）派发审查子代理。你需要根据 code-reviewer.md 模板填充以下关键信息：

  • {DESCRIPTION}：本次构建内容的简要摘要。
  • {PLAN_OR_REQUIREMENTS}：对应的计划文档或需求描述。
  • {BASE_SHA} 与 {HEAD_SHA}：上一步获取的 Git 提交范围。

第三步：处理审查子代理的反馈 审查子代理（其详细检查清单定义在 agents/code-reviewer.md）会返回一份结构化报告，其中包含 Strengths（优点）和按严重性分类的 Issues（问题）。requesting-code-review 技能要求你依据分类采取行动：

  • Critical（必须修复）：立即修复。通常是 Bug、安全漏洞（如 SQL 注入）或功能损坏。
  • Important（应该修复）：在继续下一步工作前必须修复。包括架构问题、功能缺失、错误处理不当或测试缺口。
  • Minor（可以改进）：记录下来，稍后处理。例如代码风格、优化机会或文档润色。
  • 评估为 “Ready to merge”：审查结论中必须包含此明确裁决。如果子代理给出错误的否定结论，你可以进行技术性反驳。

二、 接收与处理反馈：使用 receiving-code-review 技能

当代理（无论是人类伙伴、自动化工具还是社区审查者）给出审查反馈时，receiving-code-review 技能要求代理以技术专家的态度进行处理，而非社交性的客套。

1. 必须遵循的六步响应模式

该技能强制规定了一个六步响应流程，确保反馈得到严谨的技术评估：

  1. READ：完整阅读所有反馈，不做即时反应。
  2. UNDERSTAND：用自己的话复述反馈要求，或对模糊点提出澄清问题。
  3. VERIFY：对照当前代码库的实际情况，检查反馈所述问题是否存在。
  4. EVALUATE：评估该建议在技术上是否对当前代码库可行，是否会破坏现有功能。
  5. RESPOND：给出技术性的确认，或基于推理和证据进行反驳。
  6. IMPLEMENT：一次只处理一个条目，并在实施后进行测试，避免批量修改引入新错误。

核心禁令：技能明确禁止“表演性同意”。诸如“您说得太对了！”、“非常好的反馈！”这类话术被明令禁止。正确的做法是陈述技术要点或直接用行动（代码变更）体现。

2. 对外部审查反馈保持战略性怀疑

对于非人类伙伴（如自动化静态分析工具或外部贡献者）的反馈，技能要求代理保持审慎：

  • 在实施前，必须验证该建议是否适用于当前的代码库状态。
  • 检查该建议是否会破坏已有的功能。
  • 尝试理解当前实现背后可能的原因。
  • 评估该建议在所有目标平台或版本上是否可行。
  • 确认审查者是否理解了完整的上下文。

如果经过验证后发现建议似乎不正确，应使用技术性推理进行反驳。

3. YAGNI 原则检查

当审查者建议“更专业地实现”某个功能时，代理必须先在代码库中搜索实际的使用情况。

  • 如果未被使用：可以提出质疑：“这个端点没有被调用。是否需要移除它（YAGNI）？”
  • 如果确有使用：再进行正确实现。 这避免了为不存在的场景过度设计。

4. 处理不明确的反馈与 GitHub 回复规范

如果反馈中有任何部分不清楚，代理必须停止，不要开始实施任何内容。应首先针对不明确的项请求澄清，因为条目之间可能存在关联，部分理解会导致错误的实施。

当在 GitHub 的 Pull Request 中回复内联审查评论时，应在评论所在的线程中回复（使用 gh api 命令），而不是发表一个顶级的 PR 评论，这保持了讨论的上下文清晰。

三、 闭环工作流与质量门禁

将两端技能串联，并嵌入整体开发流程，就形成了一个严格的质量闭环：

  1. 计划阶段：通过 brainstorming 和 writing-plans 产出设计和可执行计划。
  2. 执行阶段：通过 subagent-driven-development 或 executing-plans 按任务执行。
  3. 审查阶段：每个任务完成后，强制使用 requesting-code-review 派发审查子代理。审查子代理依据 code-reviewer.md 中的检查清单（覆盖代码质量、架构、测试、需求符合度、生产就绪性）进行评估，并给出 “Ready to merge” 的明确结论。
  4. 反馈阶段：代理使用 receiving-code-review 技能处理反馈，严格验证后实施修复。
  5. 验证阶段：所有修复完成后，还需通过 verification-before-completion 技能拿出新鲜证据证明工作完成，最后才能进入收尾流程。

PR 模板（.github/PULL_REQUEST_TEMPLATE.md）中的 Rigor 与 Human review 字段进一步强化了这一闭环。它要求提交 PR 的代理证明其更改经过了对抗性压力测试（例如使用 writing-skills 技能并进行评估），并且有人类在提交前审查了完整的变更集。这确保了最终的质量控制不仅依赖于 AI，也嵌入了人类的监督。

该项目的集成测试（如 test-requesting-code-review.sh）通过植入 SQL 注入、密码哈希明文日志等安全缺陷，验证审查子代理是否能够有效捕获并分类这些 Critical 级别的问题，从而保证了审查流程本身的有效性。

FAQ

Q: 审查子代理和我正在编码的子代理是同一个吗？它们的会话历史会相互干扰吗？ A: 不是同一个。requesting-code-review 技能会专门派发一个独立的 superpowers:code-reviewer 子代理。它的输入只有你的任务描述和 Git 差异范围，不包含你之前的会话历史。这既保证了审查的客观性，也保护了你自己的上下文以继续工作。

Q: 如果我不同意审查子代理的结论，可以直接忽略 Critical 或 Important 问题吗？ A: 绝对不能。技能明确禁止忽略这些问题。正确的做法是遵循 receiving-code-review 的步骤，先验证问题是否真实存在。如果经过技术验证后你认为子代理结论有误，可以进行“推回”，但必须提供技术性理由（如工作测试、架构约束）来支持你的观点，而不是沉默跳过。

Q: 为什么 receiving-code-review 技能禁止说“谢谢”或“你说得对”？ A: 这是为了杜绝“表演性同意”，确保代理的反馈是基于技术评估而非社交礼貌。该技能要求代理用行动（修复代码、技术性确认）而非语言来回应反馈。代码本身的变化就是对有效反馈最好的确认。