1. superpowers

把“review”从零散的代码审查动作，升级成覆盖设计、计划、实现、集成、产品和运行时验证的全流程质量控制系统

1.1. 核心思想

1.1.1. Review 前移：从事后纠错到上游控制

Review 不应发生在实现完成之后，而应嵌入到设计与规划阶段，作为风险控制的前置机制，提前暴露问题，而不是事后修补。

1.1.2. 分层 Review：针对不同问题使用不同机制

Review 不能“一次性覆盖所有问题”，而应按层次拆分，每一层解决不同类型的风险：

• 设计层：spec review
• 规划层：plan review
• 任务层：task spec compliance review
• 实现层：code quality review
  Tip

  1. 问题分层 → review 分层 → 风险可控
  2. Review 是系统级质量保障，而不只是代码检查

1.1.3. 证据驱动：从“看起来对”到“可验证正确”

Agent 很容易“看起来完成”，但系统必须追求 可验证正确性（verifiable correctness）。Review 必须基于证据，而不是主观判断：

• 3-example rule（多样例验证）
• TDD 证据（测试先行 + 测试通过）
• git history verification（行为轨迹）
• smoke check 结果
• full-feature diff review
  👉 核心转变： feels correct → proven correct

1.1.4. Gate 化：Review 必须具备阻断能力

Review 不能停留在“建议”，必须具备 执行约束力。模糊建议（如“建议检查一下”）会被忽略，必须转化为 明确的 pass / fail gate。未通过 review → 不允许进入下一阶段
👉 本质：Review = 控制点，而不是意见

1.2. 设计阶段 review

目标是：

• 防止 spec 本身有空洞、歧义、TODO、范围漂移
• 防止 plan 与 spec 脱节
• 防止 plan 虽然看起来完整，但一执行就卡住
• 防止设计文档过早坍塌成实现细节

1.2.1. brainstorming阶段

1.2.1.1. 动机

• 在 brainstorming 结束后，对生成出的 spec 文档做一次独立审查，判断它是否已经“完整、一致、清晰、范围合理、不过度设计”，从而可以安全进入 planning 阶段
• spec 质量没有独立门禁，设计缺陷太晚暴露。review 的目的不是润色，而是阻止 flawed spec 进入下游。如果 spec 有 TODO、含糊表述、范围漂移，问题会一路放大到 plan 和实现。如果到 implementation 才发现 spec 漏了关键约束，返工成本高。

1.2.1.2. checklist

编写完规范文档后，让AI AGENT用全新的视角自己审视一遍：

• Placeholder scan：是否存在 TODO、placeholder、TBD(ToBeDetermined)、不完整段落
• Internal Consistency：各章节之间是否存在矛盾？架构是否与功能描述相符？
• Scope check：这是否足以制定一个单一的实施计划，还是需要进行分解？
• Ambiguity check：任何要求是否可能有两种不同的解释？如果是，请选择其中一种并明确说明。

1.2.1.3. 执行方式

目前spec review的方式是inline Self-Review checklist，自己跑一遍 checklist

1.2.2. writing plans

1.2.2.1. 动机

• 对 plan 做文档级 review，确认它已经“对齐 spec、任务拆分合理、步骤可执行、不会让 implementer 卡住”
• 很多 plan 看起来逻辑通顺，但实际一执行就会遇到“步骤模糊”、“责任边界不清”、“实现者需要自己补关键判断”
• 如果 plan 本身不可靠，后面越自动化，错得越快

1.2.2.2. checklist

• Spec coverage: 需求有没有遗漏，Spec里的每个需求，有没有对应的实现任务？
• Placeholder scan: 计划里有没有“假装写了其实没写”的内容。如：TODO: refine this，add validation later
• Type consistency: 前后任务之间的接口是否一致? A function called clearLayers() in Task 3 but clearFullLayers() in Task 7 is a bug.

1.2.2.3. 执行方式

目前plan review的方式也是inline Self-Review checklist，自己跑一遍 checklist

1.3. 实现阶段 review

目标是：

• 防止 task 级实现偏离 spec
• 防止代码质量问题在多轮 agent 自动执行中累积
• 防止跨 task 集成问题被 per-task review 漏掉
• 防止“看起来完成了”但实际上 runtime / product 层面仍然是坏的
• 防止 agent 只声称遵守了 TDD，却没有证据

1.3.1. 两阶段评审

1.3.1.1. 原理

核心是“上下文隔离 + 分阶段质量门禁”：
避免上下文污染：repo 里反复强调 reviewer 和 implementer 都不应继承你整段会话历史，而是拿到“精确构造”的上下文；这样 reviewer 关注的是 work product，而不是你的思路、措辞或先前讨论噪音。
第二，尽早发现问题，防止问题级联。
requesting-code-review 明说 “Review early, review often”，并要求在 subagent-driven development 中“after each task”就审；这意味着错误不会累积到最后才一起爆炸。(GitHub)
把“需求正确”与“实现质量”分开： spec reviewer 专门查是否偏题、漏做、过度实现；code reviewer 专门查质量、架构、测试、生产可用性。这样 reviewer 的注意力不会混在一起。(GitHub)
反对盲目服从 review：receiving-code-review 的底层价值观是“external feedback = suggestions to evaluate, not orders to follow”，也就是 review 建议不是命令，必须先验证再改。这个设计能防止 reviewer 因为上下文不完整而提出错误建议，尤其在复杂或遗留代码里。(GitHub)

1.3.1.2. 标准

每个 task 完成后，不是直接认定 DONE，至少要经历：

• spec compliance review：是否按 task spec 实现
• code quality review：实现方式是否合理、干净、可维护
  这解决的是自动化实现流程最基础的问题：
• agent 很容易“做了某个东西”，但不一定是要求的那个东西
• 即使功能对了，实现质量也可能较差

1.3.1.3. 工作流程

• subagent-driven-development是总流程编排器：它规定“每个任务都用一个全新的 implementer subagent 来做”，并且在任务完成后，必须先做 spec compliance review，再做 code quality review。它还明确把 requesting-code-review 列为集成工作流之一。
• requesting-code-review是“怎么发起 code review”的标准化 skill：告诉你要取哪些上下文（实现了什么、需求是什么、git diff 范围是什么），以及用哪个 reviewer 模板去派发 reviewer subagent。
• receiving-code-review 是“收到 review 之后怎么处理”的标准化 skill：它要求先理解、再验证、再决定是否采纳，反对表演式认同和盲改。
  更具体地说，这三者在 subagent-driven-development 下的配合顺序是这样的：

1. 先派 implementer subagent 做一个 task。
2. implementer 做完后，派 spec reviewer 检查“是否严格按任务/计划实现，既不少做也不多做”。
3. 只有 spec review 通过后，才派 code quality reviewer 做质量审查；这里 subagent-driven-development 明确写了“Only dispatch after spec compliance review passes”。
4. 如果 reviewer 提了问题，就回到 implementer 修；修完后要 重新 review，而不是口头接受后直接往下走。subagent-driven-development 对 spec review 和 quality review 都要求这种 review loop。
5. 在 implementer 收到 review 意见、准备修改时，receiving-code-review 就成了“行为准则”：先验证建议是否对这个 codebase 真的成立，再决定修、问、还是 push back。

1.3.1.4. 子代理原则

• 每个 task 都交给一个“fresh subagent”，不给它继承主会话历史，而是由 controller 精确提供任务全文和必要上下文，这样可以让 subagent 保持聚焦，也能保护主会话上下文不被实现细节污染
• review 被拆成两个阶段：先查 spec compliance，再查 code quality。这样能避免“代码写得很漂亮，但其实需求做错了”的情况；先保证“做的是对的事”，再保证“把事做对”。subagent-driven-development 也明确把 spec reviewer 的目的写成 “nothing more, nothing less”。
• quality review 本身不重新发明 prompt，而是复用 requesting-code-review/code-reviewer.md 这个通用 reviewer 模板，只是在 subagent-driven-development 里额外附加几条检查项，比如文件职责是否单一、是否遵守 plan 里的文件结构、有没有把文件膨胀得太大。

1.3.1.5. 提示词模板

1) implementer-prompt.md
这是给实现子代理的模板。它要求 controller 把 任务全文 和 场景上下文 直接贴进去，不允许让 subagent 自己去读 plan 文件；它还规定 implementer 在开工前可以提问、实现后要写测试、提交代码、做 self-review，并按 DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT 报告状态。(GitHub)
它的作用是把“实现 task”这件事标准化： 不是“你去试试看”，而是“拿着完整任务和边界去做，遇到不清楚的先问，做完自检再回报”。

2) spec-reviewer-prompt.md
这是给规格符合性 reviewer 的模板。它的重点不是代码优雅，而是逐条比对“需求 vs 实现”，并且特别强调 不要相信 implementer 的报告，要自己读代码核实，检查有没有漏项、误解、或额外加戏。(GitHub)
它的作用是卡住“方向性错误”：
防止实现者说“我做完了”，其实少做了一条 acceptance criteria，或者顺手加了 spec 没要的功能。

3) code-quality-reviewer-prompt.md
这是给质量 reviewer 的模板。它不会自己定义完整的审查格式，而是要求用 requesting-code-review/code-reviewer.md 这个通用 reviewer 模板，并补充一些针对 subagent-driven development 的额外检查项，比如文件职责、拆分粒度、是否遵守计划文件结构、这次改动有没有把文件做得太大。(GitHub)
作用: 把“质量检查”统一到一个通用 code-review 机制上，同时保留该工作流关心的结构化约束。