Superpowers Skill 配套使用指南：完整工作流全解析

superpowers 是 Vercel Labs 推出的 AI Agent 技能集合，包含 12 个协同工作的技能，覆盖从需求分析到代码审查的完整开发流程。正确掌握使用顺序，能显著提升开发效率与代码质量。

概述

superpowers 是由 Vercel Labs 维护的一套 AI Agent 技能体系，旨在为 AI 编程助手提供结构化、可复用的工作方法论。该技能集目前包含 12 个独立技能，累计安装量超过 200K，展现了其在开发者社区中的广泛认可度。

这些技能并非孤立存在，而是构成了一个完整的开发工作流。理解它们之间的协作关系和使用顺序，是充分发挥 superpowers 威力的关键。

技能总览与职责划分

在深入使用顺序之前，先理解每个技能的职责定位：

技能	安装量	核心职责
brainstorming	34.4K	需求分析、设计探索
writing-plans	17.0K	任务规划、计划编写
test-driven-development	15.4K	测试驱动开发
executing-plans	14.4K	执行已完成的计划
requesting-code-review	13.7K	代码审查请求
using-superpowers	12.9K	技能查找与加载
subagent-driven-development	11.6K	子代理驱动的开发执行
receiving-code-review	11.0K	代码审查反馈处理
verification-before-completion	11.0K	完成前验证
using-git-worktrees	10.6K	Git 工作树隔离
writing-skills	10.6K	技能编写与测试
dispatching-parallel-agents	10.0K	并行子代理调度

核心工作流：五阶段开发模型

superpowers 的设计遵循一个清晰的五阶段开发模型，每个阶段由特定技能支撑，阶段之间存在明确的依赖关系。

第一阶段：需求与设计（Brainstorming）

使用技能： brainstorming → writing-plans

当用户提出一个新的功能需求或开发任务时，首先触发的是 brainstorming 技能。这个技能的核心职责是通过结构化对话帮助 AI 理解需求、探索方案、形成设计。

brainstorming 技能的强制执行流程如下：

1. 探索项目上下文 — 检查现有文件、文档、最近的提交记录
2. 提出澄清问题 — 逐个提问，理解目的、约束、成功标准
3. 提出 2-3 种方案 — 附带权衡分析和建议方案
4. 展示设计 — 按复杂度分节展示，获取用户逐节确认
5. 编写设计文档 — 保存至 docs/plans/YYYY-MM-DD-<topic>-design.md
6. 过渡到实现阶段 — 调用 writing-plans 技能创建实施计划

这一阶段的关键原则是「一次只问一个问题」，并优先使用选择题而非开放式问题。设计文档完成后，必须通过 writing-plans 技能创建实现计划，而非直接跳转到实现技能。

第二阶段：任务规划（Planning）

使用技能： writing-plans

writing-plans 技能负责将已批准的设计文档转化为可执行的实现计划。该技能的核心价值在于将大型、模糊的任务拆解为具体的、可操作的小任务，并为每个任务提供清晰的上下文。

虽然该技能的详细文档在官方站点显示为「No SKILL.md available」，但根据其他技能的交叉引用，可以确定其核心功能：

• 读取设计文档
• 提取所有可执行任务
• 为每个任务附加完整上下文
• 创建结构化的任务列表

输出结果是一个包含多个独立任务项的实施计划，每个任务项都有明确的交付标准和上下文信息。这些任务随后由 executing-plans 或 subagent-driven-development 技能执行。

第三阶段：环境准备（Isolation）

使用技能： using-git-worktrees

在任何实现工作开始之前，必须先创建隔离的工作环境。using-git-worktrees 技能负责这一关键步骤，其核心原则是：「系统化的目录选择 + 安全验证 = 可靠的隔离」。

该技能的完整执行流程：

1. 检测现有目录 — 按优先级检查 .worktrees 或 worktrees
2. 检查 CLAUDE.md — 如有明确偏好则直接使用
3. 询问用户 — 如无预设则让用户选择
4. 安全验证 — 确保目录已被 gitignore 忽略
5. 创建工作树 — 使用新分支创建 worktree
6. 运行项目初始化 — 自动检测并运行 npm install、cargo build 等
7. 验证基线 — 运行测试确保环境干净

安全验证是至关重要的一步。对于项目本地的目录（.worktrees 或 worktrees），必须先使用 git check-ignore 确认目录已被忽略，再创建 worktree。这一步防止 worktree 内容被意外提交到仓库。

第四阶段：执行与实现（Implementation）

使用技能组合： subagent-driven-development / executing-plans + test-driven-development + verification-before-completion

这是开发流程中最复杂的阶段，涉及多个技能的协同工作。

子代理驱动开发（推荐）

subagent-driven-development 是执行实施计划的首选方式，特别适合在同一会话中连续执行多个任务。其核心工作模式是：

1. 读取计划文件 — 提取所有任务及完整上下文
2. 创建 TodoWrite — 跟踪所有任务状态
3. 逐个任务执行 — 每个任务经历以下循环：
   • 调度实现子代理
   • 实现子代理提问？→ 回答问题后重试
   • 实现子代理实现、测试、提交、自我审查
   • 调度规范合规审查
   • 规范审查通过？→ 否 → 返回修复 → 重新审查
   • 调度代码质量审查
   • 质量审查通过？→ 否 → 返回修复 → 重新审查
   • 标记任务完成
4. 所有任务完成后 — 调度最终代码审查
5. 完成开发分支 — 调用 finishing-a-development-branch 技能

关键设计：每个任务经历两阶段审查。首先是规范合规审查（spec reviewer），确认代码实现了设计要求且没有添加额外功能。然后是代码质量审查（code quality reviewer），确保代码符合质量标准。

为什么不是 executing-plans？ executing-plans 适用于需要跨会话执行或需要人类在任务之间做决策的场景。subagent-driven-development 在同一会话中连续执行，效率更高但需要更强的质量控制机制。

测试驱动开发（TDD）

在整个实现过程中，test-driven-development 技能贯穿始终。该技能强制执行 RED-GREEN-REFACTOR 循环：

• RED — 编写失败的测试
• GREEN — 编写最简代码使测试通过
• REFACTOR — 重构优化代码

核心铁律：「没有先写失败测试的生产代码」。如果代码先于测试编写，必须删除并重新开始。这一规则看似严苛，但其核心逻辑是：只有亲眼看到测试失败，才能证明测试真正验证了所需功能。

完成前验证

verification-before-completion 技能要求在任何声称工作完成之前，必须独立运行验证命令并展示证据。该技能的核心理念是：「证据在断言之前」。

执行流程：

1. 识别 — 确定什么命令能证明该断言
2. 运行 — 执行完整命令（全新、完整）
3. 读取 — 完整输出，检查退出码，统计失败数
4. 验证 — 输出是否确认了断言？
5. 然后 — 做出断言

禁止使用「应该能工作」「看起来正确」「之前通过了」等模糊表述。必须展示实际的命令输出作为证据。

第五阶段：审查与反馈（Review）

使用技能组合： requesting-code-review + receiving-code-review

代码审查是质量控制的最后一道防线，涉及两个互补的技能。

请求代码审查

requesting-code-review 技能定义了何时以及如何请求代码审查：

必须请求审查的时机：

• subagent-driven-development 中每个任务完成后
• 完成主要功能后
• 合并到主分支前

可选但有价值的时机：

• 陷入困境时（寻求新视角）
• 重构前（基线检查）
• 复杂 bug 修复后

审查流程使用专门的 code-reviewer 子代理，需要提供：实现内容、计划/需求、基准 SHA、头部 SHA、描述等信息。

接收代码审查反馈

receiving-code-review 技能定义了如何处理审查反馈：

1. 阅读 — 完整阅读反馈，不立即反应
2. 理解 — 用自己的话复述需求（或提问）
3. 验证 — 对照代码库实际状况检查
4. 评估 — 对当前代码库在技术上是否合理？
5. 响应 — 技术性确认或有理有据地反对
6. 实现 — 逐项实现，每项测试

关键原则：验证后再实现，而非盲目服从。对于外部审查者的建议，需要检查：技术上是否正确？是否破坏现有功能？是否理解当前实现的原因？

并行任务处理

使用技能： dispatching-parallel-agents

当面临 2 个或更多相互独立、无共享状态、无顺序依赖的任务时，dispatching-parallel-agents 技能允许并行调度多个子代理。

该技能的典型应用场景：

• 并行读取多个不同模块的代码
• 同时搜索多个不同的模式
• 并行获取多个外部资源

并行调用的优势在于显著节省时间，因为各子代理同时运行而非顺序执行。

技能创建与扩展

使用技能： writing-skills

当需要将团队的开发实践或特定技术方案固化为可复用技能时，writing-skills 技能提供完整的方法论。

该技能的核心洞见是：「编写技能即是将测试驱动开发应用于流程文档」。

创建流程遵循 RED-GREEN-REFACTOR：

1. RED — 不使用技能运行压力测试场景，记录基线行为
2. GREEN — 编写解决具体问题的技能文档
3. REFACTOR — 封闭漏洞，重新测试直到技能完备

关键要求：必须先看到代理在没有技能时失败，才能编写技能。这确保了技能真正解决了实际问题，而非纸上谈兵。

完整工作流示例

一个完整的功能开发流程如下：

用户：添加用户认证功能

↓

[brainstorming]
- 探索项目结构
- 询问：认证方式？JWT 还是 Session？是否需要 OAuth？
- 提出方案：方案 A（JWT + HttpOnly Cookie）、方案 B（Session）
- 建议方案 A，说明权衡
- 用户确认方案 A
- 编写设计文档

↓

[writing-plans]
- 读取设计文档
- 拆解任务：1. 用户模型 + 注册登录接口 2. JWT 令牌生成验证 3. 认证中间件 4. 密码哈希
- 创建包含 4 个任务项的计划

↓

[using-git-worktrees]
- 检查 .worktrees 目录
- 创建 feature/auth 分支的 worktree
- 运行 npm install
- 运行测试，确认基线通过

↓

[subagent-driven-development]
Task 1: 用户模型 + 注册登录接口
  - 调度实现子代理
  - 子代理实现、测试、提交
  - 规范审查通过
  - 代码质量审查通过
  - 标记完成

Task 2: JWT 令牌生成验证
  - [同上流程]

Task 3: 认证中间件
  - [同上流程]

Task 4: 密码哈希
  - [同上流程]

所有任务完成
  - 最终代码审查
  - 调用 finishing-a-development-branch

↓

[verification-before-completion]
- 运行完整测试套件
- 运行构建命令
- 展示输出证据

↓

[requesting-code-review]
- 获取 git SHA
- 调度 code-reviewer 子代理
- 审查通过，准备合并

技能依赖关系图

brainstorming
    ↓
writing-plans
    ↓
using-git-worktrees ←── required before implementation
    ↓
subagent-driven-development
    ├── test-driven-development (子代理使用)
    ├── verification-before-completion (每任务使用)
    └── requesting-code-review (每任务使用)
            ↓
receiving-code-review (处理反馈)

dispatching-parallel-agents 可在任何阶段并行调用，用于处理独立任务。

writing-skills 是独立的元技能，用于创建新技能，与主工作流正交。

总结

superpowers 技能体系的核心价值在于为 AI 编程助手提供了一套经过验证的开发方法论。理解并正确使用这些技能的配套关系，能显著提升开发效率、代码质量和团队协作效率。

关键要点：

1. 从 brainstorming 开始 — 永远不要跳过需求分析阶段
2. 使用 writing-plans 转化设计 — 设计必须转化为可执行计划
3. 用 using-git-worktrees 隔离环境 — 实现前必须创建干净的工作空间
4. subagent-driven-development 是主力 — 推荐使用两阶段审查确保质量
5. verification-before-completion 是纪律 — 证据在断言之前，永不跳过
6. 代码审查不可省略 — 早审查、常审查
7. dispatching-parallel-agents 提升效率 — 独立任务并行处理

掌握这套工作流，AI 编程助手能够像资深工程师一样进行结构化、高质量的软件开发。

参考资源

• superpowers 官方技能库
• GitHub: obra/superpowers
• Vercel Labs AI Agent Skills