superpowers 技能集的场景化使用流程
一、目标
superpowers 是 Jesse Vincent(obra)维护的 Claude Code skills 集合包(MIT 协议),把「需求澄清 → 设计文档 → 实施计划 → 隔离执行 → 代码审查 → 分支收尾」整条开发流程编码为 15 个按条件自动触发的 skill。本文记录它在典型场景下的调用顺序、每个环节的产出物与必须人工拍板的确认点,作为日常使用手册。
二、环境前提与安装
- Claude Code(支持 skills / plugin 机制)。
- 官方安装:
/plugin install superpowers@claude-plugins-official,此时 skill 以superpowers:brainstorming这样的命名空间调用。 - 手动安装:把各 skill 目录直接放进
~/.claude/skills/(本机当前方式),直接以/brainstorming调用。 - 生效机制:SessionStart hook 在每次会话注入 using-superpowers,会话压缩后自动重注入。
三、15 个 skills 速览
| skill | 触发时机 | 一句话用途 |
|---|---|---|
| using-superpowers | 每次会话开始 | 自举:任何回应前先查 skill |
| brainstorming | 任何创造性工作之前 | 苏格拉底式澄清需求,产出设计文档 |
| writing-plans | 有 spec/需求要做多步任务时 | 把设计写成可执行计划 |
| executing-plans | 人选择内联执行计划时 | 本会话自己当执行者 |
| subagent-driven-development | 执行含独立任务的计划(推荐) | 每任务派新 implementer 加审查门 |
| dispatching-parallel-agents | 2 个以上互不依赖的任务 | 并行派发独立 agent |
| test-driven-development | 实现任何功能或修复之前 | 强制红绿循环 |
| systematic-debugging | 遇到任何 bug/测试失败/异常行为 | 先根因后修复 |
| requesting-code-review | 完成任务/大功能/合并前 | 派独立 reviewer 验收 |
| receiving-code-review | 收到审查反馈时 | 技术严谨地消化反馈 |
| verification-before-completion | 即将声称完成之前 | 拿当前消息里的验证证据说话 |
| using-git-worktrees | 需要隔离工作区的功能开发前 | 建隔离 worktree |
| finishing-a-development-branch | 实现完成且测试全绿后 | 分支整合菜单 |
| writing-skills | 创建/编辑 skill 时 | 用 TDD 方法写 skill |
| diagnosing-superpowers | 会话跑偏要查原因时 | 只读取证出报告 |
自举规则(using-superpowers):任何回应(包括澄清提问)之前先查 skill,只要有 1% 可能适用就必须调用;调用时宣布「Using [skill] to [purpose]」;process skill(brainstorming、systematic-debugging)优先于 implementation skill。优先级链:用户指令(CLAUDE.md / AGENTS.md / 直接要求)> skills > 默认行为,只有人明示才能跳过 skill 流程。
四、场景流程
场景 1:新项目从零开始
/brainstorming ──► /writing-plans ──► /using-git-worktrees ──► /subagent-driven-development
(设计硬门) (审计划+选方式) (建隔离区) 或 /executing-plans
│
▼
/finishing-a-development-branch
/brainstorming:先读项目上下文再提问;一次只问一个问题,先问 why;覆盖目标、非目标、反目标、先例与现状;随后单独一条消息列出 2-3 个方案、取舍与推荐,由人拍板;按规模产出设计文档docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md;项目级设计再派 subagent 做 builder check(扮演拿不到作者的建筑师来审读)。- HARD-GATE:设计文档获人批准之前禁止任何构建。spike(一次性原型)是唯一例外,其成果要保留就必须重新过 gate。
/writing-plans:把批准的设计转成计划docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md。关键动作:每个 task 自带测试循环、可独立交付;步骤粒度等于一个可检查动作;Global Constraints 从 spec 逐字复制;附 Review Focus(spec 未覆盖但最可能咬人的 5 类输入,各配测试)。写完请人审计划,并选择执行方式(Subagent-driven 或内联)。/using-git-worktrees:先检测是否已在隔离区;不在则征得同意后创建(原生 worktree 工具优先,回退git worktree add .worktrees/<branch> -b <branch>),装依赖、跑基线测试;基线红就报告并问是否继续。- 执行(二选一):
/subagent-driven-development(推荐):每个 task 派一个全新 implementer,dispatch 只带定位一行、brief 路径、早期任务接口、人工裁决与报告契约,不贴会话历史;报告四状态 DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED;DONE 后派 task reviewer 审 diff,不过则进 fix loop(最多 5 轮:1-3 轮 resume 原 implementer,4-5 轮换更强的新 implementer);全部完成后用最强模型做整分支终审。模型分档:机械任务最便宜档、集成中档、架构与终审最强档;永不并行派多个 implementer。/executing-plans(内联):自己在.superpowers/sdd/workspace 里按 ledger(progress.md)逐 task 执行,中途不请示;只有四件事停下来问人:不可逆/破坏性操作、安全敏感、worktree 外副作用(merge/push/发布)、计划烂到全是猜。- 两者全程内嵌
/test-driven-development:先写最小失败测试并亲眼验证它以正确原因失败(报错不算失败,RED),再最小实现到整个测试套件全绿(GREEN),最后 REFACTOR;先写了代码就删掉重来。
/finishing-a-development-branch:全套测试必须绿;确认 base 分支(合错很贵);原样呈上菜单(1 本地 merge 回 base / 2 push 加建 PR / 3 保留分支),等用户选择;merge 后在合并结果上重跑测试,绿了才删 worktree 与分支。
人工确认点:方案选择、设计文档批准(硬门)、计划审批与执行方式、worktree 创建、整合方式菜单。
场景 2:已有项目开发新功能
链路与场景 1 相同,差别在 /brainstorming 的第一步:先 Look Before You Ask——读现有代码和先例再开口提问,问题围绕现状与约束展开。
场景 3:修复 bug
/systematic-debugging ──► /test-driven-development(复现测试)──► /verification-before-completion ──► /requesting-code-review
/systematic-debugging:Iron Law——NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST。四阶段顺序不可跳:根因调查(逐字读错误、稳定复现、查最近变更、边界埋点、反向追踪数据流)→ 模式分析(找同库能跑的类似实现并列出全部差异)→ 假设与最小验证(一次只改一个变量,失败就换假设而非叠加修复)→ 实现(先写复现测试,单一修复,不捎带重构)。- 3 次修复失败等于架构问题,停下来与人讨论,不要继续叠补丁。
- 验证与提交前审查同上。多个互不相关的测试失败可配
/dispatching-parallel-agents并行处理。
场景 4:代码审查
- 发起
/requesting-code-review:取任务起点BASE_SHA(禁用HEAD~1)与HEAD_SHA,按模板派只读 reviewer subagent(审查永远派 subagent 而非自己看 diff,省 context);反馈分级处理:Critical 立即修、Important 修完才继续、Minor 记录、reviewer 判断错误可以技术性反驳。 - 收到反馈(无论来自人还是 reviewer)一律
/receiving-code-review:READ → UNDERSTAND → VERIFY(对照代码库现实)→ EVALUATE → RESPOND → IMPLEMENT;禁止表演性附和(“You’re absolutely right!” 之类);多项不清晰时全部问清之前一项都不动手(条目可能相关)。
场景 5:并行独立任务
/dispatching-parallel-agents:仅用于 2 个以上无共享状态、无顺序依赖的独立问题(典型:多个测试文件各自失败)。一个问题域一个 agent、在同一条回复里全部派发;prompt 四要素:单一 scope、自足上下文(贴报错原文)、明确约束(如 Do NOT change production code)、指定返回格式。回收后查冲突并跑全套测试。失败相关联、需要全局理解、还在探索的问题不要并行。
场景 6:编写自己的 skill
/writing-skills:Iron Law——NO SKILL WITHOUT A FAILING TEST FIRST(编辑已有 skill 也算)。RED 阶段在不带 skill 的情况下跑压力场景(时间/沉没成本/权威/疲惫组合),逐字记录 agent 的 rationalization;GREEN 针对这些具体理由写最小 skill,description 只写触发条件(Use when…)不写流程摘要;措辞逐变体做 micro-test。形式匹配失败类型:纪律失败用禁令加 rationalization 表,输出形状错用正面 recipe(禁令在形状问题上适得其反)。
五、关键约定与产物路径
| 产物 | 路径 |
|---|---|
| 设计文档 | docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md |
| 实施计划 | docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md |
| 执行 workspace(ledger 为 progress.md) | <repo-root>/.superpowers/sdd/<plan-basename>/(git 忽略) |
| worktree | .worktrees/<branch> |
| 诊断工作区 | ~/.superpowers/diagnosing-superpowers/<session-id>/ |
六、验证
- skill 是否生效:新会话输入
/查看自动补全列表;正常时 Claude 会先宣布「Using [skill] to [purpose]」再干活。 - 流程自带三道验证门:TDD 的 Verify RED / Verify GREEN(必须整套测试全绿,别家红测试也要点名上报);verification-before-completion 的「没在当前消息里跑过的验证不算数」;finishing 前的全套测试加 merge 后重跑。
- 回归测试要求 red-green 证明:写测试 → 通过 → revert 修复 → 必须失败 → 恢复 → 通过。
七、常见问题
- skill 没触发:直接输入
/skill-name或在消息里点名 skill;仍不生效则重开会话(依赖 SessionStart hook 注入)。 - 会话跑偏(重复工作、无视计划、太贵、太慢、skill 没响):
/diagnosing-superpowers只读取证,产出每条 finding 都带path:line引用的报告,必要时做脱敏 bundle 供提 issue;它本身不改 skill、不给建议。 - SDD 报告异常:NEEDS_CONTEXT 补上下文重派;BLOCKED 换更强模型、拆小任务或裁计划。
- 执行中 Claude 突然停下来问:正常,executing-plans 只在四件事上停(见场景 1 第 4 步)。
八、回滚与恢复
- 卸载:
/plugin管理界面卸载 superpowers;手动安装的则删除~/.claude/skills/下对应目录,重启会话即失效。 - 残留清理:
.superpowers/sdd/与.worktrees/均为 git 忽略的临时产物,可整目录删除;docs/superpowers/下的 spec 与 plan 是正式文档,按需保留。 - 丢弃分支必须应明确要求且逐字输入
discard确认,不会静默删除。 - 合并出问题:finishing 流程规定合并结果测试失败即停,worktree 与分支原地保留供排查;worktree 内有未提交文件时清理会被拒绝,此时列出文件由人决定,不允许自行
--force。