Claude Code 实战 Superpowers：从"会写代码"升级到"会做工程"
仓库：https://github.com/obra/superpowers
作者：Jesse Vincent（Anthropic Hackathon 冠军）
一、为什么需要 Superpowers
用 Claude Code 写代码，90% 的场景是爽的：补全、解释、重构、查 bug 都很快。但只要让它做完整工程——“帮我加个用户登录功能”、“这个 API 重构一下”——就会发现它有几个通病：
- 拿到需求就开干：不问清楚需求、不画架构图、不确认设计，直接
git init起项目 - 不做 TDD：写完代码再补测试，甚至不写测试
- 不复用上下文：5 千字对话里"我们已经决定用 PostgreSQL"在第 6 千字时完全忘掉
- 不会 review 自己的代码：写完就交差，不会回头检查规范、安全、性能
Superpowers 就是为解决这些问题而生的。它不是一个"代码生成工具"，而是一套完整的软件开发方法论 + 强制流程——通过 13 个可组合的 Skills，让你的 AI 编码代理在写代码前必须先做：
- 跟你 brainstorming（苏格拉底式提问）
- 拆解任务为 2-5 分钟的小步骤
- 严格 TDD（先写失败测试）
- 子代理执行 + 两阶段代码审查
最关键的是：Skills 是强制触发的。using-superpowers 这条总纲 Skills 里有这么一句话：
“If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill. This is not negotiable.”
翻译成人话：只要你觉得有 1% 的可能用得上某个 Skill，就必须调用它。这相当于在代理的"系统提示"里装了"按规矩办事"的人格补丁。
二、安装（以 Claude Code 为例）
Superpowers 支持 8 个工具：Claude Code、Codex CLI/App、Factory Droid、Gemini CLI、OpenCode、Cursor、GitHub Copilot CLI。这里只讲 Claude Code。
方法一：官方 Marketplace（推荐）
Anthropic 官方插件市场已经收录了 Superpowers：
/plugin install superpowers@claude-plugins-official
方法二：Superpowers 自己的 Marketplace
想用最新功能（包括作者实验性插件）：
# 先注册市场
/plugin marketplace add obra/superpowers-marketplace
# 再装插件
/plugin install superpowers@superpowers-marketplace
装完后不需要重启 Claude Code。下次启动会话，Skills 会自动加载。
验证是否装好
随便开一个新会话，问代理：
请用 brainstorming 技能帮我设计一个 Todo List 命令行工具
如果它开始问你问题而不是立刻 git init，就说明 Superpowers 已经生效。
三、13 个 Skills 全景图
Superpowers 把所有方法论拆成 13 个可独立调用的 Skills，分 4 类：
3.1 Testing（1 个）
| Skill | 作用 |
|---|---|
test-driven-development |
强制 TDD：RED → GREEN → REFACTOR 循环；附带"测试反模式"参考 |
3.2 Debugging（2 个）
| Skill | 作用 |
|---|---|
systematic-debugging |
4 阶段根因排查流程，附带 root-cause-tracing、defense-in-depth、condition-based-waiting 技巧 |
verification-before-completion |
完成前自检：是真的修好了，还是测试用例本身写错了？ |
3.3 Collaboration（8 个，核心）
| Skill | 作用 | 何时触发 |
|---|---|---|
brainstorming |
苏格拉底式需求澄清 + 设计输出 | 任何写代码前（哪怕是改一行） |
using-git-worktrees |
创建独立工作分支，避免污染主分支 | 设计批准后 |
writing-plans |
拆解为 2-5 分钟小任务，每步有明确文件路径 + 代码 | 有 spec 后 |
subagent-driven-development |
每个任务派一个新子代理，两阶段审查（规范 → 质量） | 有 plan 后，且任务独立 |
executing-plans |
批量执行（带人工检查点） | 任务耦合度高时 |
dispatching-parallel-agents |
并行调度子代理 | 任务可并行时 |
requesting-code-review |
任务间自检 | 任务完成后 |
receiving-code-review |
如何响应别人代码审查的反馈 | 收到 review 后 |
finishing-a-development-branch |
收尾：merge / PR / keep / discard | 所有任务完成后 |
3.4 Meta（2 个）
| Skill | 作用 |
|---|---|
writing-skills |
教你怎么写新 Skill（按 TDD 方式） |
using-superpowers |
总纲，告诉代理"任何任务开始前先看相关 Skill" |
特别注意
using-superpowers：它会在每个会话最开头被自动触发，相当于在代理的"系统提示"里写了"先查 Skills 再动手"。
四、7 步基础工作流（重点）
这是 Superpowers 的核心节奏，任何任务都按这个顺序跑：
① brainstorming ← 把"模糊想法"变成"明确设计"
↓
② using-git-worktrees ← 隔离分支，不污染主分支
↓
③ writing-plans ← 拆解为可执行小任务
↓
④ subagent-driven- ← 每个任务派子代理 + 两阶段审查
development
↓
⑤ test-driven- ← TDD 铁律：先写失败测试
development
↓
⑥ requesting-code-review ← 任务间代码审查
↓
⑦ finishing-a-development-branch ← 收尾决策
4.1 第一步：Brainstorming（最容易被忽略但最重要）
打开 README 你会发现一个 HARD-GATE：
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
也就是说：哪怕你只是要改一个配置文件，也必须先 brainstorming 出一个设计并得到批准。作者专门有个反模式叫"this is too simple to need a design"，明确说"每个项目都必须走这个流程"。
Brainstorming 的 9 步 Checklist（来自 SKILL.md）：
- Explore project context — 先看项目文件、文档、近期 commits
- Offer visual companion（如果涉及视觉问题）— 单独一条消息，不能和澄清问题混
- Ask clarifying questions — 一次只问一个，多用多选题
- Propose 2-3 approaches — 给出方案 + 权衡 + 你的推荐
- Present design — 按章节展示，每节得到用户确认
- Write design doc — 存到
docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md - Spec self-review — 自查占位符、矛盾、模糊点
- User reviews written spec — 让用户审 spec 文件
- Transition to writing-plans — 唯一的下一步
4.2 第二步：using-git-worktrees
设计批准后立刻创建独立 worktree：
- 跑测试基线（确认 main 是绿的）
- 创建新分支
feature/<topic> - 后续所有改动都在 worktree 里做
4.3 第三步：writing-plans
把 spec 拆成 2-5 分钟的"小步快跑"任务。每个任务都必须包含：
- 精确的文件路径
- 完整代码（不写"补全相关函数"这种模糊描述）
- 验证步骤（怎么测试）
- commit message
例如 writing-plans SKILL.md 里给的"颗粒度"示例：
- “Write the failing test” - step
- “Run it to make sure it fails” - step
- “Implement the minimal code to make the test pass” - step
- “Run the tests and make sure they pass” - step
- “Commit” - step
每个 step 都是 1 个动作，2-5 分钟内能完成。
4.4 第四步：subagent-driven-development（最强大的部分）
这是 Superpowers 区别于普通"AI 编程工具"的核心机制。
核心思想：每个 task 派发全新的子代理，不继承主会话的上下文。主代理手工构造子代理需要的最小上下文（任务描述 + spec 片段 + 文件路径），子代理在隔离环境里完成实现 + 自测 + 提交。
两阶段审查（每个任务完成后）：
- Spec 审查：
./spec-reviewer-prompt.md派一个审查代理，确认"代码是不是按 spec 写的"——审查是否符合规范 - 代码质量审查：
./code-quality-reviewer-prompt.md派另一个审查代理，审查代码质量（命名、可读性、安全、性能）
模型选择策略（节流）：
| 任务类型 | 推荐模型 |
|---|---|
| 机械实现（孤立函数、清晰 spec、1-2 个文件） | 快速便宜模型（Haiku） |
| 集成/判断（多文件协调、模式匹配、debug） | 标准模型（Sonnet） |
| 架构/设计/审查 | 最强模型（Opus） |
4.5 第五步：test-driven-development（铁律）
test-driven-development 的开头就是一句话：
If you didn’t watch the test fail, you don’t know if it tests the right thing.
Iron Law：
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
如果你已经写了代码但没写测试？删掉，重写。
不允许"留着参考"、“边写测试边调整”、“看一眼”——删除就是删除。
完整循环：
RED → 写一个失败的测试
VERIFY → 确认它**因为正确的原因**失败
GREEN → 写最少代码让它通过
VERIFY → 确认所有测试都过
REFACTOR → 重构，保持绿色
关键点：“Verify fails correctly”——如果测试因为 typo 失败、因为环境问题失败、因为 import 路径错失败，不是有效的 RED。需要修测试，让它因为代码逻辑不存在而失败。
4.6 第六步：requesting-code-review
每个任务完成后、进入下一个前，必须审查：
- 规范一致性（按 plan 做的吗）
- 代码质量（命名/可读/可测/可改）
- 关键问题会阻塞进度
4.7 第七步：finishing-a-development-branch
所有任务完成时，跑这个 Skill：
- 验证所有测试过
- 给你 4 个选项：merge / PR / keep / discard
- 清理 worktree
五、实战经验与避坑指南
我用了一周把 Superpowers 跑通 3 个真实项目（小工具 + 中型业务代码 + 老项目重构），以下是纯实战的总结：
5.1 brainstorming 真的有用，但有代价
正面：我用它设计了一个 API 网关，原本以为"加个限流中间件"完事，brainstorming 走了 12 个回合，发现还需要考虑：
- 限流维度（IP? 用户? API key? 组合?）
- 限流算法（token bucket / sliding window?）
- 失败行为（限流后返回什么？重试策略？）
- 监控指标（哪些指标要导出？）
这些问题如果不问，写完代码一周内肯定要返工。
代价：对话来回会增加 3-5 倍。对简单的"加一行配置"不划算。
避坑：如果改动真的就 1-2 行，直接说"this is a trivial change, skip brainstorming"。但作者明确说"simple projects are where unexamined assumptions cause the most wasted work"——所以要谨慎判断"simple"。
5.2 subagent-driven-development 适合什么场景
适合：
- 重构（任务间独立）
- 新功能模块（明确边界）
- 批量修复（每个修复独立）
不适合：
- 跨文件耦合严重的改动
- 需要全局架构感知的任务
- 涉及配置文件、数据库 schema 变更的（这些往往是耦合源）
5.3 TDD 铁律的反直觉之处
"先写测试"听起来慢，但实际跑下来：
- 简单业务代码（CRUD）：TDD 反而更快——你不用反复想"这个函数怎么写"，测试本身就是规格说明
- 复杂逻辑（算法、并发）：TDD 显著更慢——你得先把测试设计清楚，可能要 mock 一堆东西
避坑：对"未知领域"（你不熟悉业务），TDD 让你边写边学；对"已知领域"，TDD 让你写完不返工。两种情况都推荐。
5.4 Skills 冲突时的优先级
using-superpowers 明确写了优先级：
1. 用户的明确指令（CLAUDE.md / AGENTS.md / 直接要求） ← 最高
2. Superpowers skills ← 覆盖默认行为
3. 默认系统提示 ← 最低
也就是说：如果你在 CLAUDE.md 里写"这个项目不用 TDD"，那即使 TDD Skill 触发了也不会被执行——用户配置优先。这点很关键，避免"装了插件就失去控制"。
5.5 Skills 触发的"1% 原则"陷阱
using-superpowers 要求"只要 1% 可能用得上就调用 Skill"。这会导致：
问题：每次会话开头代理都要先"评估"——“这个任务需要 TDD 吗？需要 brainstorming 吗？”——有 100ms ~ 1s 的延迟。
避坑：高频小任务（修个 typo、查个 log）会让 Skills 评估显得啰嗦。但你不应该关掉 using-superpowers，而是主动明确：“这是个 trivial 改动，不需要 brainstorming”。
5.6 调试类的 Skills 救过我两次
systematic-debugging 的 4 阶段流程：
- Root Cause Investigation（根因调查）
- Hypothesis Formation（假设形成）
- Hypothesis Testing（假设验证）
- Implementation（实施修复）
我有个 bug：API 偶发 500 错误。代理一开始就直接"加个 try-catch 兜底"——这是症状修复，没用。走 systematic-debugging 后：
- Phase 1：翻日志、看监控、问 10 个"什么时候发生/不发生"的问题
- Phase 2：定位到特定用户请求触发
- Phase 3：用日志确认是连接池耗尽
- Phase 4：改连接池配置，不是加 try-catch
没有 systematic-debugging 这套流程，代理会一直给你"再加一层 try-catch"的建议。
六、与其他 AI 编程工具的对比
| 工具 | 方法论 | 强制 TDD | 强制 brainstorming | 子代理 | 学习曲线 |
|---|---|---|---|---|---|
| Claude Code + Superpowers | ✅ 完整 | ✅ 铁律 | ✅ 强制 | ✅ 隔离 | ⭐⭐⭐ 中等 |
| Claude Code 原生 | ❌ 无 | ❌ | ❌ | ⚠️ Task tool | ⭐ 容易 |
| everything-claude-code (ECC) | ✅ 类似 | ✅ | ✅ | ✅ | ⭐⭐⭐⭐ 较高 |
| Cursor | ❌ 无 | ❌ | ❌ | ❌ | ⭐ 容易 |
| Aider | ⚠️ 部分 | ⚠️ | ❌ | ❌ | ⭐⭐ 较易 |
注意：ECC（everything-claude-code）和 Superpowers 有重叠，定位略不同——ECC 更偏"工具集合"（38 个 Agent + 156 个 Skill + 72 个命令），Superpowers 更偏"工作流强制"（13 个 Skill 但每个都深度集成流程）。
七、什么时候该装 Superpowers
推荐装：
- 你做中型以上项目（>1 万行代码）
- 你的项目需要长期维护（不是一次性的脚本）
- 你希望 AI 代理和你协作而不是"替你写完就忘"
- 你所在团队需要统一的 AI 协作规范
不推荐装：
- 你只是写一次性脚本
- 你的工作流和 TDD / 严肃工程不沾边
- 你希望 AI “更自由地发挥”（Superpowers 会让 AI 更"按规矩"，可能感觉"死板"）
八、总结
Superpowers 不是"另一个 AI 编程工具"，它是**“AI 编程的工程纪律”**。它的价值不在于让 AI 写更多代码，而在于让 AI 不写不该写的代码。
如果你已经用腻了 Claude Code 的"自由发挥"，想让 AI 代理"按规矩办事"——Superpowers 是当前最成熟、最成体系的方案。
三句话总结：
- 方法论先行：13 个 Skills 把"软件工程该怎么做"形式化
- 强制执行：不是建议，是必须——"1% 原则"宁滥勿缺
- 隔离 + 审查：子代理 + 两阶段审查让质量稳定
参考资料：
