Superpowers - 14 从「尽早审查、频繁审查」到系统化流水线：Superpowers 代码审查工作流深度解析

文档级审查（Pre-Implementation）
- 规范文档审查（Spec Document Reviewer）
- 计划文档审查（Plan Document Reviewer）
实现级审查（Per-Task Implementation Reviews）
- 规范合规性审查（Spec Compliance Reviewer）
- 代码质量审查（Code Quality Reviewer）
合并级审查（Pre-Merge Merge Reviews）
- 最终代码审查（Final Code Reviewer + Code Reviewer Agent）

这套设计的关键点是：不同阶段的问题，必须在对应阶段暴露和解决，而不是把所有风险堆在“合并前一次看完”的幻想里。

2. 为什么要分层？

分层带来的核心收益有三点：

降低返工成本：在写代码之前就通过文档审查发现规范缺失、范围模糊等问题。
聚焦不同粒度：文档关注“做什么”，实现关注“是否按规范做”和“做得好不好”，合并关注整体上线安全性。
让自动化 Agent 有“职责边界”：每类审查器的 Prompt 模板都针对特定粒度设计，避免“万能大模型”式的含糊判断。

如果你在做 AI 研发或 Agent 框架，这种按阶段切分审查角色的思路，非常适合作为系统 Prompt 设计基准线。

二、按任务的“两阶段审查关卡”：先问“做对没”，再问“做得好不好”

Superpowers 的核心创新之一，是在“每一个任务（task）层级”引入强制性的两阶段审查关卡，而不是只对大功能或合并进行审查。

在这里插入图片描述

1. 两阶段关卡的结构

在子 Agent 驱动开发（Subagent-driven Development）中，每个任务都要经过这条严格的流水线：

实现者子 Agent（Implementer Subagent）
- 根据计划实现任务、编写测试、提交代码。
规范合规性审查（Spec Compliance Reviewer）
- 独立检查实现是否严格满足需求，禁止“相信实现者自己说的完成度”。
代码质量审查（Code Quality Reviewer）
- 仅在合规检查通过后才会执行，对代码结构、可测试性、文件划分等进行系统评估。
所有缺陷修复后，任务才允许在 TodoWrite 中被标记为完成。

这意味着：每个小任务都要经过“做对了 → 做得好”的两道门，任何一道不过关，都不能进入下一步。

2. 为什么必须先做“规范合规性”再做“代码质量”？

文档中给出的理由非常务实：

对不符合规范的代码检查质量，会浪费审查精力——你只是在评估错误实现的优雅程度。

换句话说：

如果需求理解错了，即便代码写得再优雅、测试再完备，仍然是错误的成果。
先验证“需求对不对”，再讨论“实现优不优”，可以避免团队在错误实现上做大量“形式上的优化”。

在实际团队中，这是一个容易踩坑的地方——很多资深工程师习惯在审查里同时指出“实现不符合业务意图”和“这里可以提取函数”，结果大家在一次 PR 里乱战一团。Superpowers 明确要求把这两类问题拆开，并严格按顺序处理。

3. 规范合规性审查的“强怀疑”姿态

Spec Reviewer 的 Prompt 有一句相当强硬的指令：

实现者完成得快得令人怀疑。他们的报告可能不完整、不准确或过于乐观。你必须独立验证所有内容。

这里体现了 Superpowers 对 Agent / 开发者的一种系统性不信任：任何“我已经完成”的自报告都不可信，必须从代码与需求本身重建事实。

这对现实团队同样有价值：

对“已完成”的任务进行冷静的事实核查，而不是照单全收。
通过审查流程本身鼓励成员“少吹牛，多举证”。

4. 代码质量审查的关注点

Quality Reviewer 的职责不仅是“挑语法问题”或“建议风格统一”，而是系统检查以下方面：

结构健康度：文件是否膨胀、是否违反单一职责、模块划分是否有利于测试。
测试设计：是否覆盖边界条件、是否测试真实逻辑而非只测试 Mock。
与计划文件的对应关系：代码结构是否体现了计划中的模块划分。

换句话说，它关心的是长期可维护性与系统结构稳定性，而不是简单的“有没有 typo”。

三、请求代码审查：什么时候发、发什么、发给谁？

许多团队最大的问题不是“审得不好”，而是“根本没有在正确时间发起审查”。Superpowers 用一个专门的技能 requesting-code-review 来定义这件事：何时请求、如何构造审查任务，以及如何解读结果。

在这里插入图片描述

1. 何时必须审查，何时可以选择性审查？

把触发条件分成“强制”和“可选”两类，并按场景列出：

强制触发：
- 子 Agent 开发中的每个任务完成后（两阶段关卡的一部分）。
- 完成一个主要功能后（做一次范围级检查）。
- 合并到 main 前（最终安全网）。
可选触发：
- 卡住时（求第二视角）。
- 重构前（先形成 baseline 认知）。
- 修复复杂 bug 后（确认没有引入回归）。

一句话总结：避免“憋一个巨大 PR 再一次审完”的反模式，而是让审查贯穿整个开发过程。

2. 审查任务应该包含什么信息？

code-reviewer.md 模板定义了五个关键占位符，用于构造给审查 Agent 的任务：

{WHAT_WAS_IMPLEMENTED}：这次实际做了什么。
{PLAN_OR_REQUIREMENTS}：对应的规范或计划片段。
{BASE_SHA} / {HEAD_SHA}：Git 比对范围。
{DESCRIPTION}：审查者需要知道的额外上下文。

有一个非常重要的设计：审查 Agent 是上下文隔离的，它只看模板数据和 diff，不会看到你之前的对话或思考过程。

这点很多人容易忽略：

如果审查者能看到“实现过程中的挣扎和纠结”，很容易被这些叙事信息干扰，放松对成果本身的判断。
把审查 Agent 严格限制在“对成果本身进行评估”，可以提高审查的一致性与客观性。

3. 审查结果的结构化输出与严重级别

审查结果被要求按如下结构输出：

优点（Highlights）
问题列表：按严重程度分级
建议（Improvements / Refactors）
最终结论（是否推荐合并、前置条件是什么）

严重程度与行动直接绑定：

严重（Critical）：立即阻断所有进度，必须马上修。
重要（Important）：必须在开始下一个任务前修掉。
次要（Minor）：可以记录为后续改进事项。

没有“看见但可以无视”的第四级——每一个被发现的问题都必须落在某个行动路径上，而不是停留在“知道有问题但先不管”的心理安慰区。

对团队管理者而言，这种“严重度→行动”的硬绑定，是避免技术债滚雪球的关键机制。

四、接收代码审查：最难的不是给建议，而是如何对待建议

Superpowers 对“接收审查反馈”下了极大的笔墨，甚至比“如何写审查意见”还多，因为系统观察到：大多数审查规范崩溃在“接收方的行为”上。

在这里插入图片描述

1. 核心原则：技术正确性优先于社交舒适度

receiving-code-review 技能开门见山地给出一句核心原则：

先验证再实现，先提问再假设，技术正确性优于社交舒适度。

这在现实团队中非常具有争议性：

很多工程师害怕“显得不懂”，于是对模糊的反馈选择“点头+随缘实现”。
Superpowers 反其道而行：宁愿多问、不怕反击，也绝不接受“含糊而错误的修改”。

2. 六步响应模式：每条反馈都要过一遍“流水线”

虽然文档中有图示和流程节点，但可以抽象为一个统一的处理逻辑：

先判断你是否真正理解反馈。
- 如果不清楚：立即停下，先问清楚，再决定是否实现。
再判断反馈在当前代码库和上下文中是否技术正确。
- 如果不正确：给出技术理由，并友好地反击。
只有在“理解 + 正确”都成立时，才进入实现与测试环节。

这个模式直接消灭了两种常见反模式：

“盲目实现”：没看清楚就照做。
“默认审查者永远是对的”：不做验证就改掉原本正确的代码。

3. 明确禁止“表演性赞同”

禁止语句与替代写法：

❌ “You’re absolutely right!”
❌ “Great point!” / “Excellent feedback!”
❌ “Let me implement that now”
❌ “Thanks for catching that!”

对应的 ✅ 替代方案是：

直接陈述你需要做什么改动。
提出澄清问题。
先对照代码库验证，再回应如何处理。
说明你具体改了什么以及改在了哪里。

甚至给出了一条刻意强化的行为提醒：

如果你发现自己准备写“Thanks”，删掉它，改成陈述修复方案。

这背后是一个非常重要的设计哲学：只用行为与事实来表达理解和尊重，而不是依赖装饰性的社交语言。

4. 不同来源的反馈要区别对待

Superpowers 把审查来源分为两类：

人类合作伙伴：默认信任，但仍需要在边界不清时提问。
外部审查者（例如其他 Agent、第三方工具）：必须经过至少五项技术验证，包括是否会破坏现有功能、是否考虑现有实现原因、是否跨平台适用、上下文是否完整等。

这等于给接收方一个“安全带”：你可以质疑 Agent，你可以质疑外部工具，你可以甚至质疑文档，只要你的质疑基于技术事实。

5. YAGNI 在审查阶段的硬执行

当审查意见建议“把某个暂时没用的东西做好”时，接收技能要求你先在代码库执行一次 grep：如果没有任何地方调用这个端点或功能，优先动作是“建议移除”，而不是“照着审查意见完善它”。

项目规则是非常干脆的：

你和审查者都向同一个 owner 汇报。如果我们不需要这个功能，就不要添加。

这让 YAGNI（You Aren’t Gonna Need It）从口号变成了可执行的操作规范。

6. 合理反击与纠正自己的反击

不仅允许反击，而且列出了六条合理反击的理由（比如：建议会破坏现有功能、忽视兼容性约束、违反 YAGNI、技术上不适用于当前栈等）。

流程要求是：

使用基于代码和测试的技术论据。
如果是架构层面的分歧，引入你的人类合作伙伴。
如果事后发现自己反击错了，简单陈述你做了哪些检查、发现了什么、现在要怎么改，不需要情绪化道歉表演。

这为“健康的技术冲突”提供了一个清晰的行为边界。

五、文档级审查：避免“文档也是形式主义”

Superpowers 不只审代码，也审文档，而且审得很“务实”。

1. 规范文档（Spec）审查：只关心会导致实现失败的问题

规范审查器检查五类问题：

完整性：是否还存在 TODO、占位符、“TBD”等。
一致性：需求是否自相矛盾。
清晰度：描述是否模糊到可能导致构建错误。
范围：是否一次性涵盖了多个独立子系统。
YAGNI：是否包含未请求的功能或过度设计。

最关键的校准指令是：仅标记那些会在实现阶段造成实际问题的缺陷，不要为了修辞、语气或轻微措辞细节阻塞整个流程。

这直接对抗了很多团队常见的“文档审查形式主义”：

花大量时间讨论标题要不要加个形容词。
对业务理解无影响的小细节拖慢整体推进。

2. 计划文档（Plan）审查：确保“写下来的东西真的能执行”

计划审查器主要看四点：

完整性：不能有 TODO 或未展开的占位符。
与规范对齐：覆盖所有需求、没有明显范围蔓延。
任务拆分：边界清晰，每一步都能由工程师具体执行。
可构建性：工程师能否照着计划一步步完成，而不会卡死在某个“模糊步骤”上。

和规范审查一样，它的校准原则也是：除非缺陷会导致实现失败，否则默认通过。

这是对“计划先行”方法论的一种约束：计划不是写给审查器看的，而是写给执行者用的。

六、Code Reviewer Agent：把资深审查员的人设固化为 Agent

在 Superpowers 中，superpowers:code-reviewer 是一个专门为代码质量审查设计的 Agent 类型。

1. 人设与职责边界

这个 Agent 被描述为“一位在软件架构、设计模式和最佳实践方面具有专长的高级代码审查员”。它的评估框架涵盖六个方面：

计划对齐分析：实现是否遵守原始计划。
代码质量评估：错误处理、命名、测试、安全等。
架构与设计：是否符合 SOLID、关注点分离原则等。
文档与标准：注释、README、代码风格规范等。
问题识别与分级：明确严重度。
沟通方式：先指出优点，再列出问题，保持建设性语气。

2. 模型继承与“用最强模型做最难的事”

Agent 元数据中有一个 model: inherit 指令，意味着它继承调度会话所使用的模型。 Subagent 驱动开发技能建议：在架构与审查任务中使用可用的最强模型。

这隐含着一个很重要的工程决策：把算力投入在“关键决策节点”而不是平均分配到所有步骤。

编写简单代码可以用较轻的模型。
但在做架构评估与质量判断时，必须上更强的模型，以降低“高影响错误”的概率。

对于设计多模型协作系统的读者，这是一个值得借鉴的调度策略。

七、完整审查生命周期：一条从 Spec 到 Merge 的“安全生产线”

把前面的所有组件拼起来，你会看到一个完整的功能开发与审查流水线：

编写规范（Spec） → 规范审查 → 修正规范。
编写计划（Plan） → 计划审查 → 修正计划。
实现任务（按 Plan 拆分）
- 每个任务：实现 → 规范合规性审查 → 质量审查 → 修复 → 标记完成。
所有任务完成后：对整个功能进行最终代码审查。
接收反馈 → 逐条验证、评估、实现或反击。
所有问题解决后：合并分支。

最常见的失败模式，是在接收反馈时跳过验证步骤。
因此 receiving-code-review 技能几乎是这套系统的“保险丝”：任何建议——即便来自受信任的来源——也必须先经过六步响应模式处理，才能进入实现阶段。

八、给工程团队与 Agent 系统设计者的实践建议

结合 Superpowers 的设计，如果你想在自己的团队或 Agent 系统中引入类似的代码审查工作流，可以考虑以下落地步骤：

1. 在团队开发流程中引入“最小可行的两阶段审查”

先挑选“高风险模块”或“新功能开发”，试点：
- 每个任务先做需求合规性检查（可以是简单的 checklist + 同行 review）。
- 再做结构与质量评审。
避免一开始就把所有项目都切换到新流程，以防心理和流程阻力过大。

2. 把“何时请求审查”写进团队工作约定

明确规定：
- 合并前必须有审查。
- 复杂 bug 修复后建议请求审查。
- 重构前先做一次 baseline 审查。
把“卡住时可以请求审查”写成鼓励项，而不是默许“自己硬扛”。

3. 训练团队成员遵守“接收反馈协议”

在 Code Review 文化建设时，重点强调：
- 不鼓励空洞的“Thanks”“Good catch”。
- 鼓励用“复述 + 行动”来表达理解：
  - “我会在 X 文件的 Y 函数里增加对 Z 的校验，并补一个回归测试。”
- 鼓励在发现审查意见有问题时，提出基于事实的反击，而不是闷头照做。