Superpowers 的 SDD:子代理驱动开发,以及 spec 放在哪里

在 Superpowers 里,“SDD” 指的是子代理驱动开发(subagent-driven development):这个 skill 按写好的计划执行,每个任务派一个全新的实现子代理,每个任务做完后有一个审查者检查。它不是规格驱动开发,Superpowers 仓库里从没用过这个说法。不过 Superpowers 确实有 spec,就是 brainstorming skill 写出的设计文档,每个任务都要对照指回这份文档的计划来检查。本文讲清楚 spec 和计划放在哪里、一个任务要经过哪些步骤、在我们记录的两次运行里 SDD 和更便宜的 Native 模式有什么差别,以及想要可核对的验收标准时该补什么。

statusreviewedpublished2026-11-21last-review2026-11-21read11 分钟author编辑部policy编辑政策

本文是独立的说明文章,Spec Coding 与 Superpowers、Jesse Vincent 和 Prime Radiant 都没有关联。skill 的行为对照的是 Superpowers v7.0.2 的源码(2026-11-03 发布,到 2026-11-21 仍是最新版)。运行数据来自我们 2026-11-17 记录的两次 bridge 实测,那两次是在 OpenSpec 里使用 Superpowers;引用这些数字前请先看那一节的说明。

SDD 在 Superpowers 里是什么意思

Superpowers 仓库里所有的 “SDD” 都指子代理驱动开发。发布说明把相关内容放在 “Subagent-Driven Development and Executing Plans” 这个标题下。这个 skill 维护的进度文件第一行是 # SDD ledger。它的辅助脚本叫 sdd-workspace 和 sdd-repo,临时目录是 .superpowers/sdd/。在 v7.0.2 的源码里搜 “spec-driven”,一条结果都没有。

“spec” 这个词倒是出现在两个要紧的地方。brainstorming 写的设计文档存在一个叫 specs/ 的目录里,README 也说 agent 会“从对话里梳理出一份 spec”。另外,SDD 的每次任务审查都有一个“规格符合度”(spec compliance)结论,它拿 diff 去对照这个任务要求的内容,也就是任务简报和计划里的全局约束,而不是一份单独的需求文件。

所以搜 “Superpowers SDD” 的人大概想找两样东西之一。想了解这个执行 skill,看接下来三节。想知道 Superpowers 算不算规格驱动开发,直接跳到 Superpowers 算规格驱动开发吗?

从需求到合并:spec 和计划放在哪里

Superpowers 是一组会自动触发的 skill。它的引导 skill 告诉 agent:只要有“哪怕 1% 的可能”某个 skill 适用,就必须用它;“我们来做 X” 要先进入 brainstorming。按 README 给出的顺序,一个功能会经过这些 skill:

Skill产出关口
brainstorming一份设计文档,小改动写简短版,项目写完整版,路径是 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md,并且会提交。内容包括意图、目标、不做什么、约束,以及考虑过的两三种方案和最终选了哪种。“设计文档没被你批准之前,什么都不会构建。”简单明确的任务(它举的例子是改一个图标的颜色)直接做。
using-git-worktrees一个隔离的 worktree,并确认测试基线是干净的在普通 checkout 里创建前会先问你
writing-plans一份计划,路径是 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md:头部写明设计文档的路径,下面是编号的任务,每个任务写清文件、接口和先写测试的步骤先按清单自查,再由人审计划并选择执行方式
subagent-driven-development 或 executing-plans一个任务一个任务地提交SDD 每个任务都审查;两种方式每个任务都先写测试
test-driven-development写任何生产代码之前先有一个失败的测试“NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST”(没有先失败的测试,就不写生产代码)
requesting-code-review由一个子代理用它的 code-reviewer.md 提示词做审查Critical 问题立刻修,Important 问题修完再继续
finishing-a-development-branch只给三个选项:本地合并、推送并开 PR、保留分支先跑通完整测试套件;要丢弃分支必须你亲手输入 discard

这两个路径都是默认值。brainstorming 说你自己的偏好优先于它的默认位置;引导 skill 也规定,CLAUDE.md、AGENTS.md、GEMINI.md 里的指令优先于任何 skill。OpenSpec bridge 就是靠这一点把设计文档改写到自己的变更目录里的,你也可以用同样的方法加自己的规则(见下文)。

SDD 读的是计划,所以计划的头部值得了解。writing-plans 要求头部写明:目标、架构、技术栈、一行 Spec: 写设计文档的路径、从设计文档原样抄过来的带具体数值的全局约束,以及审查重点,也就是设计里隐含、但没有任何任务的测试覆盖到的输入或失败情况。每个任务写明涉及的文件、它依赖或提供的函数签名,然后列出先写测试的步骤。下面是我们按这个格式手写的头部和第一个任务,用的是本站其他地方用过的优惠券例子:

**Goal:** Signed-in shoppers can apply one coupon code before payment.
**Architecture:** Validation in packages/billing; checkout calls it before
creating the payment intent.
**Tech Stack:** TypeScript, Node 22, Vitest
**Spec:** docs/superpowers/specs/2026-11-20-checkout-coupons-design.md
**Global Constraints:** one coupon per order; codes are case-insensitive;
a discount never takes the total below 0.00
**Review Focus:** a code that expires between validation and payment;
two tabs applying the same single-use code

### Task 1: Validate a coupon code
**Files:** Create packages/billing/coupons.ts
           Test packages/billing/coupons.test.ts
**Interfaces:** Produces validateCoupon(code, orderId): CouponResult
- [ ] Write a failing test: an expired code returns { ok: false, reason: "expired" }
- [ ] Run it and confirm it fails
- [ ] Implement validateCoupon
- [ ] Run it and confirm it passes, with the rest of the suite
- [ ] Commit

这个 skill 用一句话划定计划的分寸:“计划是实现者自己做不了的那些决定。一份比它描述的代码还长的计划,等于已经把代码写了。”反过来,“处理边界情况”“加上合适的校验”这类句子也算失败,因为它们什么都没决定。

子代理驱动开发对每个任务做了什么

skill 自己的概括是:“按计划执行,每个任务派一个全新的实现子代理,每个任务之后做一次任务审查(规格符合度 + 代码质量),最后做一次覆盖整个分支的审查。”具体步骤:

  1. 建工作区。每份计划有一个被 git 忽略的目录 .superpowers/sdd/<计划名>/,里面放记录文件(progress.md)、任务简报、报告和审查包。用 skill 的话说,记录文件就是“你的记忆”:哪个任务做完了、一路上做过哪些裁定,都记在里面。
  2. 把计划和它指向的设计文档各读一遍。skill 的原话是“spec 是计划立论的依据”。第一个任务开始前,先做一次冲突预检。
  3. 为一个任务写简报。一个脚本把这个任务单独抄进一个文件。“绝不让子代理去读整份计划。”
  4. 派一个全新的子代理去实现。实现者不能再派自己的子代理;skill 也禁止并行运行多个实现者,任务一次只做一个。
  5. 审查。一个脚本把 diff 写进文件,由一个任务审查者给出两个结论:规格符合度和任务质量。“实现者的自查永远代替不了任务审查。”(README 仍把这描述成两个审查者的两阶段审查,这在 6.0 已经改了,以 skill 文件为准。)
  6. 修复,最多五轮。第一到三轮交回原来的实现者,第四、五轮换一个全新的、能力更强的模型,每轮之后做一次限定范围的复审。到了上限,还没解决的问题要书面裁定,“禁止悄悄丢掉”。
  7. 中途不停下来问人。skill 要求 agent 在任务之间不要暂停确认。只有四种情况会让它停下:不可逆或破坏性的操作、涉及安全的操作、会影响 worktree 之外的副作用,以及计划烂到每条路都只能靠猜。其他判断都以 Ruling: 的形式写进记录文件。
  8. 审查整个分支。最后一个任务完成后,用能找到的最强模型审一遍整个分支。由一个修复子代理处理它的发现,然后只做一次限定范围的复审。
  9. 汇报并清理。最后一条消息在 “Rulings I made” 下列出所有裁定,删掉工作区(“现在 git 历史就是记录”),再由 finishing-a-development-branch 给出那三个选项。

skill 还要求每次派子代理都明确指定模型。在我们的运行里,实现者和任务审查者用的是 Sonnet,整分支审查用的是主控的模型 Opus。

选 SDD 还是 Native:两次实测说明了什么

从 6.4.1 起,计划交接时会给出两种执行方式。Subagent-driven 是“最彻底;每个任务、每次审查都要一个新上下文”。Native 也就是 executing-plans skill,是“最便宜也最快;到最后才有独立审查”:当前会话按测试驱动开发自己实现所有任务,用同一份记录文件,最后由一个全新的审查者审整个分支,再一次性修完它发现的问题,不做复审。

我们的两次 OpenSpec + Superpowers bridge 实测恰好各走了一条路。同一个需求、同一个仓库、同样的版本(Superpowers 7.0.2、OpenSpec 2.1.0、Claude Code 2.1.326,主控是 Opus 5.5),用同一套八项隐藏检查打分:

运行 A:子代理驱动运行 B:Native
执行方式怎么定的没给选择:“这个项目的工作流规定了执行方式”给了选择;agent 推荐 Native(“只有三个小任务”),人同意了
计划里的任务数43
子代理11 个:Sonnet 上的四个实现者和四个任务审查者,Opus 上的一次整分支审查,一轮修复,一次复审1 个:Opus 上的整分支审查
每个任务的检查先写测试,然后一次给出两个结论的任务审查先写测试;agent 在实现前逐个确认测试确实失败
原有的 __proto__ id 漏洞四次任务审查都没发现,整分支审查发现了整分支审查发现了
整场会话的时间和花费21 分 25 秒,$6.2816 分 3 秒,$5.18(合并时 $3.12)
结束后仓库里的测试数40合并时 32,最后 35
隐藏检查通过8/86/8

这不是一次对照 SDD 和 Native 的受控测试,最后一行也不是对两者的评判。两次运行里的“人”也不一样:运行 A 的人按案例的 spec 回答问题,运行 B 的人提什么批什么。运行 B 丢的两项都能追溯到 brainstorming,那时还没写任何代码:agent 提议只给校验错误加 details,并把 X-Request-Id 请求头当作“和一致性无关的另一个功能”排除在外,两条提议都被批准了。被批准的设计漏掉的需求,换哪种执行方式都补不回来。

这两次运行能说明 SDD 本身的几点:

我们由此得出的经验:计划只有几个小任务时,像这次一样让 agent 推荐 Native 就行;计划长到某个任务跑偏了、到最后才发现会很贵,或者主控的上下文本身就紧张时,选子代理驱动。不管选哪种,真正决定分数的是批准设计文档那一步。

Superpowers 算规格驱动开发吗?

算一半。它是设计先行、测试先行的,还有一道硬关口:书面的设计文档没被你批准之前,不写产品代码、不搭脚手架、不装依赖、也不调用实现类 skill;每份计划都带着指回这份文档的路径。和通常被归为规格驱动开发的工具相比,它缺的是这些:

Superpowers 7.0.2OpenSpec 2.1
Spec 产物每次变更一份文字设计文档,加上计划一个变更目录:proposal、spec 增量、design、tasks
需求格式没有;文档是写给“这个领域里一位能干的构建者”看的### Requirement: 加上 WHEN/THEN 形式的 #### Scenario:
合并之后设计文档和计划留在原处;执行记录被删除变更被归档,spec 增量合并进 openspec/specs/

所以该问的不是 Superpowers 有没有 spec,而是它的 spec 能不能拿来核对。一份文字设计文档可以批准,但很难拿 diff 去逐条核对。bridge 补的就是这块:OpenSpec 或 Spec Kit 提供需求和归档,Superpowers 提供执行纪律。我们的 OpenSpec、Superpowers、Spec Kit 对比讲了两种 bridge,实测记录完整跑了其中一种。

不加新工具,补上验收标准

如果你想要可核对的标准,又不想再引入一套框架,就把规则放在 Superpowers 最先看的地方。它的引导 skill 把你的指令文件排在它的 skill 之上,所以在 AGENTS.md(或 CLAUDE.md)里加三行,就能改变 brainstorming 写什么、writing-plans 往下传什么:

## Design docs (Superpowers)
- Every design doc in docs/superpowers/specs/ ends with "## Acceptance criteria":
  numbered AC-1..n, each one observable behaviour, never a file name.
- Every plan task lists the AC ids it serves; every AC is served by a task.
- Test names start with the AC id they prove, e.g. "AC-2: used code is rejected".

这样设计文档的结尾会是下面这样,计划里的审查重点和测试名都可以引用这些编号:

## Acceptance criteria
AC-1: An expired code shows an inline error and the total does not change.
AC-2: A single-use code already applied to another order is rejected.
AC-3: The payment intent amount equals the discounted total.

这是我们自己的约定,不是 Superpowers 的功能;agent 是把它当指令而不是 schema 来执行的,所以要检查它写出的第一份设计文档。好处体现在审查时:“这个任务服务哪条 AC?”有了答案,没有对应任务或测试的标准会在合并前暴露出来,而不是合并后。怎么写好这些标准,见AI 编码的验收标准。

安装并确认它在工作

在 Claude Code 里,可以从官方插件市场安装:/plugin install superpowers@claude-plugins-official;也可以先用 /plugin marketplace add obra/superpowers-marketplace 添加项目自己的插件市场,再运行 /plugin install superpowers@superpowers-marketplace。README 还写了另外十五种工具的安装方式,包括 Codex CLI(/plugins 后搜索)、Cursor(/add-plugin superpowers)和 Gemini CLI(gemini extensions install https://github.com/obra/superpowers)。

README 给的检查方法:开一个新会话,提一个类似 “Let's make a react todo list” 的需求。装好的话,它会在写任何代码之前先进入 brainstorming。Superpowers 使用 MIT 许可证。它的 brainstorming 可视化助手会加载一个上报插件版本的 logo,设置 SUPERPOWERS_DISABLE_TELEMETRY 可以关掉。

常见问题

Superpowers 里的 SDD 是什么意思?

子代理驱动开发,也就是 subagent-driven-development 这个 skill。它按写好的计划执行,每个任务派一个全新的实现子代理,每个任务之后由一个审查者检查。仓库里从没出现过“规格驱动开发”这个说法。

Superpowers 把 spec 存在哪里?

brainstorming 把设计文档写到 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 并提交。writing-plans 把计划存到 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md,头部有一行 Spec: 指回设计文档。你自己指定的位置优先于这两个默认值。

subagent-driven-development 和 executing-plans 有什么区别?

subagent-driven-development 给每个任务一个全新的实现者,再由一个任务审查者给出两个结论。executing-plans 在交接时显示为 Native,由当前会话按测试驱动开发自己实现所有任务,最后由一个全新的审查者审整个分支。两者共用工作区、记录文件和最终审查。

Superpowers 算规格驱动开发工具吗?

算一半。设计文档没被批准前它不会构建,每份计划也都指回这份文档。但它没有验收标准格式,合并后也不维护持续更新的 spec。可以和 OpenSpec 或 Spec Kit 搭配,或者自己在设计文档里加编号的标准。

子代理驱动开发能并行执行任务吗?

不能。skill 明确要求不要并行派出多个实现者。想找一个会把互不依赖的工单并排执行、最后统一审查一次的 skill,见 implement-spec skill。

参考资料

2026-11-21 对照 obra/superpowers v7.0.2(提交 22f0b46)核对。引文出自上面链接的文件。运行数据来自 2026-11-17 记录的运行数据包。