---
date: 2026-04-06 20:46
created: 2026-04-06 20:46
updated: 2026-04-06 20:46
categories:
tags:
---
# 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
> [!note]
> superpowers官方[release note](https://github.com/obra/superpowers/blob/main/RELEASE-NOTES.md)中说明`subagent review loop`增加大量耗时，但质量没有明显提升
### 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](https://raw.githubusercontent.com/obra/superpowers/main/skills/requesting-code-review/SKILL.md "raw.githubusercontent.com"))
**把“需求正确”与“实现质量”分开**： spec reviewer 专门查是否偏题、漏做、过度实现；code reviewer 专门查质量、架构、测试、生产可用性。这样 reviewer 的注意力不会混在一起。([GitHub](https://raw.githubusercontent.com/obra/superpowers/main/skills/subagent-driven-development/spec-reviewer-prompt.md "raw.githubusercontent.com"))
**反对盲目服从 review**：`receiving-code-review` 的底层价值观是“external feedback = suggestions to evaluate, not orders to follow”，也就是 review 建议不是命令，必须先验证再改。这个设计能防止 reviewer 因为上下文不完整而提出错误建议，尤其在复杂或遗留代码里。([GitHub](https://raw.githubusercontent.com/obra/superpowers/main/skills/receiving-code-review/SKILL.md "raw.githubusercontent.com"))
#### 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](https://raw.githubusercontent.com/obra/superpowers/main/skills/subagent-driven-development/implementer-prompt.md "raw.githubusercontent.com"))
它的作用是把“实现 task”这件事标准化：  不是“你去试试看”，而是“拿着完整任务和边界去做，遇到不清楚的先问，做完自检再回报”。

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

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