Superpowers：用工程流程纪律驯化 Claude Code 实现可靠交付

它关注的核心问题包括：

• 如何系统澄清需求和设计（brainstorming 类技能）。
• 如何生成带验证计划的执行方案（writing-plans）。
• 如何按计划执行，而不是临时起意（execute-plan / executing-plans）。
• 如何系统地调试和验证（systematic-debugging、test-driven-development、verification-before-completion 等）。

3.2 核心流程：brainstorm → plan → implement → review → verify → ship

Superpowers 背后的典型工程流程可以抽象为这一串：brainstorm → plan → implement → review → verify → ship。

• brainstorming：围绕需求展开结构化讨论，生成小规格说明（目标、非目标、约束、验收标准）。
• writing-plans：将需求拆解成一系列「可执行、可验证」的任务，包含修改文件、接口、数据结构以及对应验证方式。
• implement（通常通过 execute-plan 系列技能）：根据计划逐项实施，每一步之后进行局部验证。
• review：对变更进行审查，检查是否满足规格、是否符合代码质量和架构约束。
• verify（verification-before-completion）：在宣布完成前执行必要的测试、检查和验证，并保存证据。
• ship：将结果纳入仓库、合并 PR 或标记任务完成。

注意：Superpowers 并不强制你永远走完整的长流程，它支持根据任务风险适度简化，但默认假设「严肃变更应该走完流程」。

四、Superpowers 工作流详解：从想法到可验证交付

这一部分我们结合典型技能，按顺序走一遍完整工作流。具体命令名、调用方式会因集成方式不同略有差别，但思路是一致的。

4.1 需求澄清与方案设计：brainstorming

第一步是帮 Claude 把「你脑中的需求」变成「结构化的规格」。

你可以给出一个相对粗糙的目标，例如：

「在现有的后端服务中增加一个导出报表的接口，支持按时间范围和用户等级过滤。」

调用 brainstorming 类技能后，它会引导生成一个包含以下要素的规格草案：

• 背景与目标：为什么需要这个接口，它解决什么问题。
• 非目标：本次不处理的数据种类、极端性能优化、某些特殊过滤条件等。
• 约束条件：接口安全性要求、响应时间、调用频率限制、与现有权限系统的兼容性。
• 输入与输出：请求参数、字段类型、返回结构、错误码设计。
• 验收标准：哪些用例通过，才算「功能完成」。

好处在于：

• 你可以直接对这份草案进行修改、评论，然后再让 AI 更新一版规格。
• 后续所有步骤都可以引用这份规格，以减少「需求解读偏差」。

4.2 生成可执行计划：writing-plans

当规格基本达成共识后，就可以调用 writing-plans 类技能，让 AI 把需求拆解成一系列执行步骤。

一个典型的计划会包含：

• 要修改 / 新增的文件列表（例如 controller、service、repository、测试文件、配置等）。
• 每个步骤要做的具体事情（例如「在 XController 中新增 GET /reports/export 接口」「在 ReportService 中增加 assembleExportData 方法」）。
• 对应的验证方式：每一步如何确认成功（单测、集成测试、手动调用、日志检查等）。

这里有一个重要原则：

没有写明「如何验证」的计划步骤，视为不完整。

这可以强迫 AI 在计划阶段就思考「证明自己没写错」的方法，而不是等出问题再补救。

4.3 按计划执行：execute-plan / executing-plans

计划确认后，就可以使用 execute-plan / executing-plans 之类的技能按步骤推进实现。 特征包括：

• 分批执行：每次只处理计划中的一小部分（例如一个文件或一组相关改动），降低风险。
• 每步结束后执行对应验证操作，如运行特定单测、构建项目、启动服务并调用接口。
• 避免随意跨文件、跨模块地「自由发挥」，保持与计划一致。

在实践中，你可以选择「全自动」或「半自动」：

• 全自动：让 AI 直接执行与计划对应的修改命令（如果集成了编辑器/CLI）。
• 半自动：AI 提供 patch / diff，由人工审阅后再应用到代码库。

对于多文件重构、接口门面调整这类高风险改动，分批执行 + 分步验证的收益非常明显。

4.4 系统化调试与 Bug 修复：systematic-debugging

修改过程中或者线上出现问题时，可以启用 systematic-debugging 类技能来替代「猜测式调试」。

典型的调试流程包括：

1. 定义问题与最小复现：让 AI 帮你整理「问题在什么环境、什么输入下出现」，并尝试构造最小复现用例。
2. 范围收窄：根据日志、调用链、最近变更记录，锁定可能相关的模块与文件。
3. 提出假设列表：列出几种可能的根因，每个假设都要附带「如何验证」。
4. 逐一验证与修复：选择一个假设，设计实验或增补日志来验证，如果确认，就设计对应修复并再次验证。

这一系列动作的关键，不是「一次就猜对」，而是「每一步都有记录、有验证」，你甚至可以回放 AI 的调试过程，查出哪一步的假设是错误的。

4.5 验证优先：verification-before-completion

在传统 AI 使用方式里，模型很容易在代码写完后马上说「完成了」，却不给任何证据。verification-before-completion 类技能的目标，就是在「宣布完成」前强制走验证步骤。

常见的验证项包括：

• 静态检查：lint、format、类型检查。
• 自动测试：核心单元测试、关键集成测试。
• 核心用户路径：例如关键 API 的调用路径、主要页面的交互流程。

通过 skill，可以要求 AI：

• 显式列出本次执行了哪些验证步骤。
• 尽可能附上关键输出片段（测试结果、日志摘要），而不是只说「我跑过了」。

这一步可以大大减少「完成了，但其实没跑起来」的情况。

4.6 代码审查与规范审核：请求 review 的正确姿势

Superpowers 还鼓励将「实现」与「审查」分离，通常由不同的技能/agent 完成：

• 规格符合性审查：检查当前实现是否满足之前的规格说明（目标、约束、验收标准）。
• 代码质量审查：关注命名、结构、可维护性、错误处理、边界情况等。

这种拆分有两个好处：

• 容易发现「功能看起来 OK，但偏离原始意图」的问题。
• 更接近真实团队里的 code review 流程，便于接入现有开发规范。

五、实战案例：为后端服务新增导出报表接口

下面我们用一个相对简单但足够完整的例子，把上面的流程串起来。这里不会贴出大段代码，而是重点展示流程和关键交互。

5.1 场景设定

假设你有一个基于某主流框架（例如 Spring Boot）的后端服务，需要新增一个导出报表的接口，支持按时间范围和用户等级过滤，并输出 CSV 文件。

你的目标是：

• 在不破坏现有接口的前提下增加新功能。
• 确保接口有测试、有权限校验、有基本性能保障。

5.2 需求澄清（brainstorming）

你向 Claude Code 描述大致需求，然后调用 brainstorming 技能。输出的规格草案可能包含：

• 目标：
  • 新增一个 GET /reports/export 接口，支持通过 query 参数指定时间范围与用户等级。
• 非目标：
  • 不做复杂 BI 分析，只提供原始数据导出。
• 约束：
  • 接口需要走现有的认证与权限系统。
  • 导出数据量最多限定在某个范围内，超过时需要提示用户缩小条件。
• 验收标准：
  • 在测试环境中可通过若干示例请求得到正确格式的 CSV。
  • 对越界条件（无权限、参数不合法、数据量过大）有明确错误响应。

你可以在这个基础上进行增删，然后让 AI 更新一版最终规格。

5.3 生成实现计划（writing-plans）

确定规格后，调用 writing-plans，让 Claude 生成带验证步骤的实现计划。

可能的计划结构：

1. 在 ReportController 中新增 /reports/export 路由与参数解析逻辑，验证方式：编写一个简单集成测试，调用该接口并检查 HTTP 状态与响应头。
2. 在 ReportService 中新增 exportReport 方法，封装业务逻辑，验证方式：编写单测，对不同参数组合检查返回数据集合。
3. 在 ReportRepository 中新增查询方法，支持按时间与用户等级过滤，验证方式：使用测试数据构建几个典型场景，编写单测。
4. 新增 CSV 序列化工具类，将数据转为 CSV 字符串，验证方式：给定固定输入，检查输出字符串是否符合预期格式。
5. 在安全配置中注册接口权限校验，验证方式：用带权限/无权限 token 分别调用接口，检查响应。

每一步都有对应的「怎么验证」，后续执行过程就有据可依。

5.4 按计划执行（execute-plan）

接下来可以按计划逐步执行，每完成一步就做对应的验证。

例如执行步骤 1：

• 让 Claude 生成 ReportController 的改动 diff，你审查后应用。
• 让它生成一个基础集成测试，发起对 /reports/export 的请求，检查路由是否工作。
• 跑测试（手动或让 AI 触发），如果失败，就重新进入 systematic-debugging。

依次推进，直到所有计划步骤都完成并通过各自的验证。

5.5 系统化调试与补强（systematic-debugging）

假设在大数据量场景下，接口响应超时。你可以启用 systematic-debugging，让 AI 根据日志和代码行为分析瓶颈来源：

• 它可能提出几个假设，例如：
  • 查询无分页，导致一次性加载大量数据。
  • CSV 序列化使用了低效的字符串拼接方式。
• 对每个假设，设计验证方法：
  • 加日志统计查询耗时和返回数据量。
  • 针对序列化部分编写微基准测试。

确认根因后，将「分页查询 + 流式写出」纳入新的实现计划，再通过 execute-plan 执行与验证。

5.6 验证与交付（verification-before-completion）

在你准备合并改动前，调用 verification-before-completion 类型技能，让 AI 汇总本次改动经历的所有验证步骤：

• 单测：列出增加或修改了哪些测试用例，以及它们的运行结果。
• 集成测试：列出覆盖的接口场景。
• 安全检查：列出权限验证、错误处理等关键点。

你可以要求它输出类似「验证报告」的小结，作为 PR 描述的一部分，让团队成员一眼看到这次改动的质量保障措施。

六、与其他方案的对比：Superpowers 不只是「更好的 prompt」

下面用一个表格，对比几种常见的 AI 编程使用方式。

不同 AI 编程方式的关键差异

Superpowers 的位置，大致介于「通用规划工具」和「完全自研 Agent 系统」之间：

• 比一条长 prompt 更标准化、更可验证。
• 比完全自研的多 Agent 架构轻量，易于个人开发者和小团队采用。

七、实践建议：如何在团队里落地 Superpowers

7.1 安装与集成的基本思路

具体安装方式会依赖你使用的工具链（例如 CLI、编辑器扩展、云端 Agent 平台等），但整体思路类似：

• 将 Superpowers 作为一套技能库引入 Claude Code 运行环境。
• 在项目级别配置一些默认约定，比如：
  • 哪些任务必须走完整流程（需求澄清 → 计划 → 实施 → 审查 → 验证）。
  • 哪些可以走简化流程（例如单文件文案修改）。

你可以从官方仓库和示例配置入手，然后根据自身项目特点调整技能参数和默认行为。

7.2 将 brainstorming 输出接入团队文档

一个实用的小技巧是：不要让 brainstorming 的输出「只活在聊天记录里」。

• 每次生成的规格草案，整理后可以直接存到项目的设计文档目录（wiki、docs 文件夹等）。
• PR 中可以引用本次变更关联的规格链接，方便后续维护者理解上下文。

这样，Superpowers 不仅帮你写代码，还在持续产出结构化的设计文档。

7.3 把 verification-before-completion 对接到 CI

在成熟团队里，验证逻辑往往已经包含在 CI 流水线中，例如运行单测、静态分析等。

你可以：

• 在计划和验证步骤中，明确指出需要通过哪些 CI 任务。
• 让 AI 在本地先模拟执行关键验证（例如运行对应测试集），减少 CI 红灯次数。
• 在 PR 描述中引用验证-before-completion 的汇总结果，与 CI 状态相互印证。

这样可以让 AI 的本地验证和团队的 CI 流程形成闭环。

7.4 何时走全流程，何时适度简化

并不是每个任务都需要完整的 Superpowers 流程，否则成本过高。

可以参考以下粗略分级：

• 高风险变更（核心业务逻辑、跨模块重构、安全相关改动）：必须走完 brainstorm → plan → implement → review → verify 全流程。
• 中等风险变更（单模块新功能、中等规模重构）：允许在明确小规格的前提下精简 brainstorm，但保留 plan + verify。
• 低风险变更（文案调整、单测试数据更新、小范围样式修改）：可以使用轻量流程或直接人工修改。

关键是：默认要有一个清晰的「流程等级」约定，而不是临时凭感觉决定。

7.5 常见坑与防御性设计

一些团队在实践类似工作流时，容易踩到这些坑：

• 只用了一部分技能：只用 planning，不用 verification-before-completion，导致「计划很好，交付很随意」。
• 把 skill 当成「提示词快捷方式」，而不是约束流程的工具。
• 放弃规格审查，只做简单代码 review，久而久之实现与需求偏离。

对应的防御性策略包括：

• 在团队内部明确：对于某类任务，必须调用哪些技能，并在 PR 模板里要求贴上输出摘要。
• 定期回顾几次关键交付的完整历史，检查哪一步最容易被忽略，然后针对性加强。

八、结语：用流程驯化 AI，而不是靠运气

Superpowers 代表的一类实践，把焦点从「模型多聪明」移到了「工程流程多扎实」。在这个视角下，Claude Code 不再只是一个会写代码的聊天机器人，而是一个被编排在工程工作流里的「流程参与者」：

• 它在每个环节都有明确的职责和产出（规格、计划、实现、审查、验证报告）。
• 它的行为受技能与流程约束，而不仅仅依赖 prompt 灵感。

对于个人开发者，这意味着你可以在一个人身兼「产品 + 开发 + 测试」的情况下，借助 AI 把流程跑得更像一个小团队。对于团队来说，Superpowers 这样的技能库则是一条更现实的路径：先用可控的方式把 AI 纳入现有流程，再逐步演化出更复杂的多 Agent 系统。

如果你已经在用 Claude Code 写代码，不妨从最简单的一步开始：下次不要直接说「帮我写」，而是先让它和你一起 brainstorm 与写计划，再实施和验证。你会很直观地感受到，从「能写」走向「能交付」的差别。