Superpowers 使用指南

如果只先记住一个结论，那么可以记这句：

Superpowers 不是单纯的“代码增强插件”，而是一套把软件开发最佳实践内化为可执行工作流的方法论插件。

它的价值不在于“帮你多补几行代码”，而在于通过一组技能系统，把设计、计划、执行、测试、审查、调试和收尾这些环节串成一个更稳定的开发闭环。

本文会系统回答几个问题：

Superpowers 到底是什么
它和普通代码辅助工具有什么本质区别
它的完整工作流怎么跑
什么时候该自动触发，什么时候适合手动调用
使用中最容易踩的坑是什么

1. Superpowers 到底是什么#

Superpowers 是一个面向 Claude Code 的开发流程插件。它不是把一堆零散命令简单打包，而是把软件工程中的一整套高质量实践，组织成可自动触发、可组合、可审查的工作流。

和常见“你提需求，我给代码”的工具相比，它有几个明显不同点：

它会优先帮助你澄清需求，而不是立刻开写
它强调计划拆解，而不是一次性生成大段实现
它默认引入 TDD、代码审查和系统化调试
它允许通过子代理并行处理任务
它把“验证是否真的完成”看得和“写出代码”同样重要

换句话说，Superpowers 关注的不只是产出代码，而是产出一个更可控、更可验证的开发过程。

2. 核心理念是什么#

Superpowers 背后最重要的不是某个命令，而是它坚持的几条工程原则。

2.1 测试驱动开发优先#

它默认推崇 TDD，也就是经典的 RED -> GREEN -> REFACTOR 循环：

先写一个失败的测试
再写最少的代码让测试通过
最后在测试保护下重构

这会强迫开发从“想当然实现”切换到“先定义预期行为，再补实现”。

2.2 系统化优于临时应对#

遇到问题时，它更倾向于：

明确定位问题
收集证据
找根因
用流程和验证收束结果

而不是简单地“试一下这个改法能不能过”。

2.3 简单性优先于复杂炫技#

Superpowers 的方法论倾向非常明确：复杂度不是能力的证明，能把问题拆到足够小、足够清楚，才是真正可维护的工程能力。

2.4 验证优先于宣称#

“已经修好了”“应该可以了”“理论上没问题”这类表述，在它的工作流里都不算真正完成。必须通过测试、审查、验证或复现消除，结果才算站得住。

3. 它和普通代码辅助工具有什么不同#

可以用下面这张表快速理解它的定位：

维度	普通代码辅助工具	Superpowers
主要目标	更快生成代码	更稳地完成完整开发流程
默认行为	直接根据需求写实现	先设计、再计划、再执行
测试态度	可有可无	默认强制引入 TDD
代码审查	往往依赖人工补充	工作流内建审查机制
调试方式	偏经验式试错	强调系统化根因分析
适用对象	单次编码任务	需要流程质量保证的开发任务

所以，Superpowers 更像是“开发过程的组织者”，而不只是“生成代码的助手”。

4. 它是怎么工作的#

当你描述一个开发需求时，Superpowers 的典型反应通常不是直接产出代码，而是先把整个过程带入一个更可控的结构。

一个标准链路大致如下：

先澄清需求与边界
基于确认后的设计拆出计划
将计划拆成足够小、足够清晰的任务
在实现过程中引入 TDD
在阶段之间引入代码审查
在遇到问题时使用系统化调试
最后统一验证、合并或清理分支

这意味着它真正自动化的，不只是“代码生成”，而是“工程节奏”。

5. 完整开发流程：7 个阶段#

Superpowers 的主流程可以理解为 7 个阶段。

5.1 阶段一：头脑风暴（`brainstorming`）#

触发时机#

当你开始描述一个新功能、改造需求或 bug 修复目标时，通常会先进入这一阶段。

这个阶段做什么#

通过提问把模糊需求变清楚
探索可能的技术方案
明确实现边界和验收标准
输出一个可被继续规划的设计基础

它为什么重要#

很多返工并不是因为写代码太慢，而是因为一开始问题就没有被定义清楚。brainstorming 的价值就在于尽量把“想做什么”说透，而不是一上来就开写。

示例#

用户：我想添加用户认证功能

Claude：先一起把需求细化一下：
1. 认证方式是 JWT、Session，还是 OAuth？
2. 是否需要第三方登录？
3. 密码强度和找回流程有什么要求？
...

5.2 阶段二：使用 Git 工作树（`using-git-worktrees`）#

触发时机#

设计被确认之后，就可以进入隔离工作空间的准备阶段。

这个阶段做什么#

创建独立的工作树或分支
在隔离环境中初始化项目
检查当前测试基线是否干净

适合场景#

并行开发多个功能
隔离实验性修改
避免直接污染主开发分支

5.3 阶段三：编写计划（`writing-plans`）#

触发时机#

当设计已经清晰，并且准备进入实现阶段时，会开始写计划。

这个阶段做什么#

把一个模糊的大目标拆成多个小任务，每个任务通常控制在 2 到 5 分钟可完成的粒度内。

一个高质量任务通常要包含：

精确的文件路径
明确的目标
需要补充或修改的代码
具体验证方式
清晰的完成标准

为什么要把任务拆这么细#

因为细粒度任务有几个优势：

更容易验证
更容易回滚
更适合并行执行
更适合做阶段性审查

示例计划结构#

## 任务 1：创建用户模型
- 文件：`src/models/user.py`
- 验证：运行 `pytest tests/test_user.py`
- 预期：测试通过

## 任务 2：实现认证端点
- 文件：`src/api/auth.py`
- 验证：运行 `pytest tests/test_auth.py`
- 预期：测试通过

5.4 阶段四：执行计划（`executing-plans` / `subagent-driven-development`）#

两种主要执行方式#

方式 A：分批执行（`executing-plans`）#

特点是：

分批推进
每批执行后保留人工检查点
更适合对关键步骤需要持续确认的任务

方式 B：子代理驱动（`subagent-driven-development`）#

特点是：

为不同任务启动独立子代理
可以并行处理多个小任务
每个任务都可独立审查

如果任务拆得足够清晰，子代理驱动通常能显著提升吞吐量。

5.5 阶段五：测试驱动开发（`test-driven-development`）#

这是整个流程里最有“纪律感”的一环。

Superpowers 倾向强制执行下面这个循环：

RED：先写失败测试
GREEN：写最少实现让测试通过
REFACTOR：在测试保护下重构

示例#

def test_user_authentication():
    user = authenticate("admin", "password123")
    assert user.is_authenticated is True

先运行测试，此时它应该失败，因为实现还不存在。
然后写最小实现让它通过，最后再进行结构优化。

为什么这个步骤不能省#

因为如果一开始就直接写实现，很容易陷入：

功能看起来跑通了
但行为边界并没有被明确定义
重构时也没有足够保护

5.6 阶段六：请求代码审查（`requesting-code-review`）#

Superpowers 把代码审查看成主流程的一部分，而不是“有空再做”的补充动作。

审查的几个维度#

是否符合最初设计
代码质量是否达标
测试是否足够
是否存在明显安全风险

严重程度划分#

Critical：必须修复，否则阻断进度
Major：强烈建议修复
Minor：建议改进
Suggestion：可选优化

这个分级很重要，因为它让“审查反馈”从情绪判断变成了更可执行的工程判断。

5.7 阶段七：完成开发分支（`finishing-a-development-branch`）#

当所有任务完成后，流程还没有结束。最后一个阶段通常会做：

验证测试是否全部通过
确认是否创建 Pull Request
选择是否合并到主分支
清理工作树和临时分支

这一步的意义在于：不要把“功能写完了”和“开发任务真正闭环了”混为一谈。

6. 辅助技能：为什么它不只是主流程 7 步#

除了主线流程，Superpowers 还内建了几类辅助技能，用来补足真实开发中常见的中断、调试和修复场景。

6.1 系统化调试（`systematic-debugging`）#

这是最值得重视的辅助技能之一。它强调四个步骤：

重现问题
缩小范围
找到根因
修复并验证

这套方法最大的价值是：避免一上来就乱改代码，把调试从“碰运气”变成“可解释的分析过程”。

6.2 完成前验证（`verification-before-completion`）#

这个技能负责确认：

问题是否真的修复
测试是否覆盖到了关键路径
是否引入了回归

它的作用是防止“看起来修好了，但其实没有彻底解决”。

6.3 接收代码审查（`receiving-code-review`）#

当审查反馈回来后，这个技能会帮助处理：

反馈归类
修改请求响应
修复后的再验证

它让“被审查”不再只是被动挨批，而变成一个结构化的改进流程。

6.4 调度并行代理（`dispatching-parallel-agents`）#

这个技能适合在任务天然可拆、且互相依赖较少时使用。它会帮助：

划分并发任务
分配子代理
汇总结果

如果任务足够独立，并行执行确实能省下不少时间；但如果任务边界不清，并发反而会制造更多协调成本。

7. 手动调用技能时怎么用#

虽然 Superpowers 会自动触发，但手动调用也很有价值，尤其是在你想明确控制节奏时。

开发流程相关#

/brainstorming
/writing-plans
/executing-plans
/subagent-driven-development

测试与调试相关#

/test-driven-development
/systematic-debugging
/verification-before-completion

审查与分支管理相关#

/requesting-code-review
/receiving-code-review
/using-git-worktrees
/finishing-a-development-branch
/dispatching-parallel-agents

什么时候适合手动调用#

你已经有成熟设计，只想直接进入计划阶段
你只想单独调试某个问题
你需要强行插入一次代码审查
你想控制并行代理的使用时机

8. 一个典型工作流示例#

下面用“添加用户认证功能”举一个更完整的例子。

第一步：提出需求#

我想添加用户认证功能

此时不会立即开写，而是先被引导澄清：

认证方式是什么
是否需要第三方登录
密码策略如何设计
是否有限流和安全审计要求

第二步：生成设计与计划#

在需求明确后，系统可能会生成类似这样的任务拆解：

任务 1：创建用户模型
任务 2：实现注册接口
任务 3：实现登录接口
任务 4：添加 JWT 中间件
任务 5：补齐测试与错误处理

第三步：执行并审查#

每个任务在推进过程中会配套：

失败测试
最小实现
重构
阶段性审查

第四步：收尾#

最后统一做：

覆盖验证
审查收口
PR 创建或合并
工作树清理

这样一个流程的优点是：它不要求你在脑中同时维护全部复杂度，而是把复杂度分配给了流程本身。

9. 最常见的误区与陷阱#

这类方法论工具最大的风险，不是不会用，而是“自以为在用，实际上一直在绕过核心价值”。

9.1 误区一：把它当成更强的代码生成器#

错误心态通常是：

直接帮我写完，不用问那么多。

但这正好绕开了 Superpowers 最值钱的部分：设计澄清、任务拆解、验证与审查。

9.2 误区二：跳过测试#

如果你默认认为“先写代码，测试后面再补”，那实际上已经背离了它的 TDD 核心。

省掉测试，短期看更快，长期通常意味着：

更高返工率
更脆弱的重构能力
更容易漏掉边界情况

9.3 误区三：排斥代码审查#

很多人会本能地觉得审查拖慢进度，但真正的关键问题如果在这个阶段没被拦住，后面付出的代价往往更大。

Superpowers 把审查放进流程，不是为了增加仪式感，而是为了尽量把风险前置。

9.4 误区四：任务拆得太大#

比如下面这种任务描述就很危险：

任务 1：实现完整用户系统（预计 2 小时）

问题在于它：

难验证
难回滚
难并行
难清晰审查

更合理的做法，是拆成多个可独立验证的小任务。

9.5 误区五：对流程缺乏耐心#

很多人会觉得“先花 5-10 分钟澄清需求”是在拖节奏，但真实经验往往相反：前面少花这几分钟，后面多返工几十分钟甚至几小时。

10. 最佳实践建议#

如果你想把 Superpowers 用得顺一点，我会建议优先做到下面几件事。

10.1 尽量把需求描述具体#

例如不要只说：

我想做登录功能

更好的表达是：

我想做登录功能，要求：
- 使用 JWT
- 支持邮箱和手机号登录
- 密码加密存储
- 接入 Google 和 GitHub 第三方登录
- 有速率限制

需求越具体，后续设计与计划质量通常越高。

10.2 接受设计引导#

如果工具在设计阶段提出质疑、追问或建议，不要急着把它看成“阻碍”。很多时候这些追问恰恰是在帮你提前暴露模糊点。

10.3 信任细粒度任务拆解#

2 到 5 分钟粒度的小任务，虽然看起来碎，但它通常更适合：

快速验证
阶段性交付
并行推进
快速回滚

10.4 把审查当成保护机制#

越早发现关键问题，越便宜。尤其是安全、边界和测试覆盖问题，越适合前置解决。

10.5 合理使用并行代理#

并行不等于永远更快。只有当任务天然独立时，并发才是收益项；否则，它很可能只是更快地制造混乱。

11. 它适合什么，不适合什么#

更适合的场景#

新功能开发
Bug 修复
代码重构
性能优化
技术债治理

不那么适合的场景#

一次性小脚本
很短的临时实验
紧急 hotfix

最后这类场景并不是“不能用”，而是完整流程的收益未必大于成本。

12. 总结#

Superpowers 最核心的价值，不在于它提供了多少命令，而在于它把优秀工程实践从“口头原则”变成了“可执行流程”。

它做的事情可以概括为四点：

用流程把质量前置
用自动化降低认知负荷
用任务拆解提升执行稳定性
用测试、审查和验证减少返工

如果你本来就重视 TDD、代码审查、系统化调试和分阶段交付，那么 Superpowers 会像一个很顺手的“流程放大器”；如果你习惯跳过设计、跳过测试、跳过审查，那它给你的第一感受可能不会是更轻松，而是更有纪律。

但也正因为这种纪律，它更有机会把“会写代码”推进成“能稳定地完成开发工作流”。

1. Superpowers 到底是什么#

2. 核心理念是什么#

2.1 测试驱动开发优先#

2.2 系统化优于临时应对#

2.3 简单性优先于复杂炫技#

2.4 验证优先于宣称#

3. 它和普通代码辅助工具有什么不同#

4. 它是怎么工作的#

5. 完整开发流程：7 个阶段#

5.1 阶段一：头脑风暴（brainstorming）#

触发时机#

这个阶段做什么#

它为什么重要#

示例#

5.2 阶段二：使用 Git 工作树（using-git-worktrees）#

触发时机#

这个阶段做什么#

适合场景#

5.3 阶段三：编写计划（writing-plans）#

触发时机#

这个阶段做什么#

为什么要把任务拆这么细#

示例计划结构#

5.4 阶段四：执行计划（executing-plans / subagent-driven-development）#

两种主要执行方式#

方式 A：分批执行（executing-plans）#

方式 B：子代理驱动（subagent-driven-development）#

5.5 阶段五：测试驱动开发（test-driven-development）#

示例#

为什么这个步骤不能省#

5.6 阶段六：请求代码审查（requesting-code-review）#

审查的几个维度#

严重程度划分#

5.7 阶段七：完成开发分支（finishing-a-development-branch）#

6. 辅助技能：为什么它不只是主流程 7 步#

6.1 系统化调试（systematic-debugging）#

6.2 完成前验证（verification-before-completion）#

6.3 接收代码审查（receiving-code-review）#

6.4 调度并行代理（dispatching-parallel-agents）#

7. 手动调用技能时怎么用#

开发流程相关#

测试与调试相关#

审查与分支管理相关#

什么时候适合手动调用#

8. 一个典型工作流示例#

第一步：提出需求#

第二步：生成设计与计划#

第三步：执行并审查#

第四步：收尾#

9. 最常见的误区与陷阱#

9.1 误区一：把它当成更强的代码生成器#

9.2 误区二：跳过测试#

9.3 误区三：排斥代码审查#

9.4 误区四：任务拆得太大#

9.5 误区五：对流程缺乏耐心#

10. 最佳实践建议#

10.1 尽量把需求描述具体#

10.2 接受设计引导#

10.3 信任细粒度任务拆解#

10.4 把审查当成保护机制#

10.5 合理使用并行代理#

11. 它适合什么，不适合什么#

更适合的场景#

不那么适合的场景#

12. 总结#

5.1 阶段一：头脑风暴（`brainstorming`）#

5.2 阶段二：使用 Git 工作树（`using-git-worktrees`）#

5.3 阶段三：编写计划（`writing-plans`）#

5.4 阶段四：执行计划（`executing-plans` / `subagent-driven-development`）#

方式 A：分批执行（`executing-plans`）#

方式 B：子代理驱动（`subagent-driven-development`）#

5.5 阶段五：测试驱动开发（`test-driven-development`）#

5.6 阶段六：请求代码审查（`requesting-code-review`）#

5.7 阶段七：完成开发分支（`finishing-a-development-branch`）#

6.1 系统化调试（`systematic-debugging`）#

6.2 完成前验证（`verification-before-completion`）#

6.3 接收代码审查（`receiving-code-review`）#

6.4 调度并行代理（`dispatching-parallel-agents`）#