237k 星的 Superpowers 插件升级到 6.0.3，token 砍半！90% 的人只用了它 10% 的功能

6 月 16 日，Superpowers 发布 v6.0.0。两天后追了 v6.0.3 修复版。

如果你读过码哥之前那篇「185,000 星的 Superpowers 插件，90% 的人只用了它 10% 的功能」，14 个 Skill 的基本面你已经知道了。那篇写的是 v5.1，拆的是「是什么」和「怎么用」。

这篇是续集。如果想知道如何高效正确使用 Superpowers，那么可以回顾码哥之前那篇「185,000 星的 Superpowers 插件，90% 的人只用了它 10% 的功能」。

本篇只讲一件事：SDD（subagent-driven-development）从底层重写的工程细节。

不是 changelog 翻译。是我扒了 v6.0.3 的 SKILL.md 和所有 prompt 模板原文，提炼出来的 5 个工程设计决策。每一个都有源码引用，每一个都能用在你自己写 Agent 系统的时候。

官方 eval 数据：token 消耗降低约 50%，执行速度提升约 2 倍。 这两个数字是结果，本文拆的是产生这两个数字的原因。

先说 v5.1 的问题：两个 reviewer 为什么是个坏设计

v5.1 的 SDD 有两套独立的 reviewer prompt：spec-reviewer-prompt.md 和 code-quality-reviewer-prompt.md。一个审规格合规，一个审代码质量。听起来合理对吧？分工明确，互相补充。

但实际跑起来，有三个坑。

第一个坑：串行成本翻倍。 两个 reviewer 串行执行，每个 reviewer 都要完整读一遍 diff、加载上下文、输出判断。Token 开销是单 reviewer 的两倍，时间也是。

第二个坑：假独立性。 两个 reviewer 共享同一个上下文窗口。第二个 reviewer 读到的输入已经包含了第一个 reviewer 的输出——它的「独立判断」是打了折扣的。

这就像一个面试环节安排了两个面试官，第二个人进场前已经看到了第一个人的评分表。你可以说第二个人是「参考」了第一个人的意见，也可以说他被「污染」了。区别只在用词，本质是一样的。

第三个坑：判断标准不统一。 两个 prompt 文件各自定义了各自的 severity 等级和判断标准。spec-reviewer 眼里的 Critical 和 code-quality-reviewer 眼里的 Critical，未必是同一个标准。controller 拿到两份报告后还得自己做对齐，这个对齐工作本身就是额外的 cognitive load。

6.0 的解法：砍掉一个，留一个，但让这一个做得更好。

SDD v5.1 vs v6.0 审查流程对比

决策一：Do Not Trust the Report——不信任执行者的自我汇报

新的 task-reviewer-prompt.md 里有这么一段，建议全文背诵：

Treat the implementer's report as unverified claims about the code. It
may be incomplete, inaccurate, or optimistic. Verify the claims against
the diff. Design rationales in the report are claims too: "left it per
YAGNI," "kept it simple deliberately," or any other justification is the
implementer grading their own work. Judge the code on its merits — a
stated rationale never downgrades a finding's severity.

翻译成人话：执行者写的报告一律当「未经验证的声明」处理。

这段话解决了什么问题？在 SDD 的工作流里，子 Agent 执行完任务后会写一份 report，告诉 controller「我做了什么、为什么这么做、效果如何」。reviewer 的职责是审查这份报告和对应的代码 diff。

v5.1 的隐含假设是：执行者的 report 是可信的输入，reviewer 在此基础上做补充审查。

v6.0 把这个假设翻转了：report 本身不能信。 执行者说「我故意用了简单方案（YAGNI 原则）」，这句话不能作为降低问题严重性的理由。reviewer 要看代码本身，而不是看执行者给自己打了多少分。

这个原则的精妙之处在于，它承认了一个现实：让 AI 自己给自己打分，结果永远偏乐观。 不是 AI 在「说谎」，是 prompt 生成的 report 天然有一种自我合理化的倾向——它总能找到一个理由说明自己的选择是对的。6.0 的设计不再对抗这个倾向，而是直接绕过它：你说什么都行，但我只看代码。

子 Agent 报告 vs 代码 diff 的信任关系

决策二：Cannot Verify from Diff——承认自己的视野有限

同一个 reviewer prompt 里还有另一段：

If a requirement cannot be verified from this diff alone (it lives in
unchanged code or spans tasks), report it as a ⚠️ item instead of
broadening your search.

这是一个关于认知边界的设计决策。

reviewer 拿到的是一个任务的 diff，它只能看到这次改动的代码。如果某个需求依赖于没有被改动的代码，或者跨越了多个任务的边界，reviewer 是看不到全貌的。

v5.1 的做法是让 reviewer 自己去搜索相关代码，试图判断这个需求是否被满足。这导致两个问题：reviewer 要花额外的 token 去读无关文件，而且它搜索的范围和深度是不确定的——有时候搜到关键文件判断对了，有时候漏掉了关键文件判断错了。

v6.0 的做法是直接承认：我看不到的东西，我不假装自己能判断。 标记为 ⚠️（无法验证），交给 controller 去处理。

这个设计原则在工程里有个专门的名字——Fail Explicitly。 显式失败永远好于隐式错误。一个 reviewer 说「我无法验证这个需求」，controller 可以安排补充审查；一个 reviewer 错误地说「这个需求已满足」，错误会静默地溜进最终结果。

对写 Agent 系统的人来说，这个启发是：给你的 Agent 明确的「我不知道」的出口。 不是所有问题都应该有答案，承认边界比假装全能更可靠。

决策三：Calibration 校准——让 severity 有统一的尺子

v5.1 的两个 reviewer 各自有一套 severity 标准，合并后需要一个统一的校准机制。6.0 在 reviewer prompt 里加了这段：

Categorize issues by actual severity. Not everything is Critical.
Important means this task cannot be trusted until it is fixed: incorrect
or fragile behavior, a missed requirement, or maintainability damage you
would block a merge over — verbatim duplication of a logic block,
swallowed errors, tests that assert nothing. "Coverage could be broader"
and polish suggestions are Minor.

然后是一条容易被忽略但极有价值的规定：

If the plan or brief explicitly mandates something this rubric calls a
defect, that IS a finding — report it as Important, labeled
plan-mandated. The plan's authorship does not grade its own work; the
human decides.

这里有两层意思。

第一层：severity 要有标准答案。 不是所有问题都是 Critical。代码重复是 Important（该阻断），覆盖率不够是 Minor（可以后补）。reviewer 的工作是分类，不是渲染。

第二层：计划的作者不能同时当裁判。 如果计划本身要求了某个设计，而这个设计恰好是 reviewer 认为的缺陷，reviewer 仍然要报告它——但标注为 plan-mandated。最终决定权在人类手里，不在计划作者（controller）手里，也不在 reviewer 手里。

这本质上是一个三权分立的设计：执行者干活，reviewer 审查，人类拍板。任何一个角色都不应该越权。controller 不能替 reviewer 做判断（后面会讲），reviewer 不能替人类做决策。

SDD 6.0 的三权分立设计

决策四：File Handoffs——别往 prompt 里粘贴一切

这是我在源码里看到的最「教训驱动」的设计。

SDD SKILL.md 里有这么一段：

Everything you paste into a dispatch prompt — and everything a subagent
prints back — stays resident in your context for the rest of the session
and is re-read on every later turn. Hand artifacts over as files.

然后附了一个真实的失败案例：

A dispatch prompt describes one task, not the session's history. Do not
paste accumulated prior-task summaries ("state after Tasks 1-3") into
later dispatches — a real session's dispatch hit 42k chars of which 99%
was pasted history.

42k 字符的 dispatch prompt，99% 是之前任务的历史记录。 只有 1% 是当前任务的描述。

这个数字触目惊心。一个正常的 dispatch prompt 应该只有几百到一两千字符的任务描述。42k 意味着 controller 把前面所有任务的 summary 都粘贴进去了，每次 dispatch 都要带上越来越长的历史包袱。第一个任务 dispatch 1k，第二个 5k，第三个 15k，到后面每个 dispatch 都是几万字符的垃圾信息。

更要命的是，这些粘贴进去的内容会永久驻留在上下文窗口里。每一次后续 turn 都要重新读取这些内容，token 消耗是持续累积的，不是一次性的。

6.0 的解法是把所有中间产物都写成文件，通过文件路径传递。

框架提供了两个脚本：

• scripts/review-package BASE HEAD：生成 diff 文件路径，reviewer 读文件而不是在 prompt 里粘贴 diff
• scripts/task-brief PLAN_FILE N：提取单个任务的文本到文件，controller 传文件路径而不是粘贴任务描述

这个改动对 token 消耗的影响是巨大的。从「每次 dispatch 带上全部历史」到「每次 dispatch 只传当前任务的文件路径」，省掉的不只是当前这一次的 token，还有后续所有 turn 重复读取历史的开销。

如果你在写自己的 Agent 系统，这是最值得借鉴的一条：Agent 之间的通信，永远传文件引用，不传文件内容。 上下文窗口是稀缺资源，一旦填满就没有回旋余地。

文本粘贴 vs 文件传递 token 消耗对比

决策五：Durable Progress——对话压缩后的记忆丢失

这是一个只有在长时间 session 里才会暴露的问题。

SDD SKILL.md 里写道：

Conversation memory does not survive compaction. In real sessions,
controllers that lost their place have re-dispatched entire completed task
sequences — the single most expensive failure observed.

最昂贵的失败：controller 在对话压缩后丢失了记忆，把已经完成的任务又重新 dispatch 了一遍。

LLM 的上下文窗口有限。当一个 SDD session 跑了很长时间（多个子任务），对话历史会接近窗口上限。这时候框架会触发 compaction（对话压缩），把早期的对话历史压缩或丢弃，腾出空间给后续内容。

问题在于，compaction 之后，controller 不再记得哪些任务已经完成了。它看到计划里还有后面的任务没做，就从头开始 dispatch。已经完成的任务被重新执行一次，reviewer 重新审查一次，所有 token 和时间都白费了。

6.0 的解法是在 .superpowers/sdd/progress.md 里维护一个持久化的进度账本。每个完成的任务追加一行：

Task N: complete (commits <base7>..<head7>, review clean)

controller 每次被唤醒（包括 compaction 之后）都会先读这个文件，恢复自己对进度的认知。

这个设计模式叫 Durable Progress——进度信息不依赖对话内存，而是持久化到外部存储。在分布式系统里这叫 WAL（Write-Ahead Log），在数据库里叫 checkpoint，本质是同一个东西：不要信任易失性存储来保存关键状态。

v6.0.3 还做了一个额外的改进，把这个进度文件从 .git/ 目录移到了 .superpowers/sdd/。.git/ 是 Git 的受保护目录，往里面写临时文件虽然方便，但会让有安全意识的开发者不安。这个迁移体现了从「先跑起来」到「做正确的事」的工程成熟度。

Compaction 后的进度恢复机制

决策六：Writing Plans 的结构升级

SDD 依赖 writing-plans skill 来生成任务计划。6.0 对计划的结构做了两个重要的新增。

Global Constraints——全局约束区块。

## Global Constraints
[The spec's project-wide requirements — version floors, dependency limits,
naming and copy rules, platform requirements — one line each, with exact
values copied verbatim from the spec. Every task's requirements implicitly
include this section.]

这个区块列出项目级别的硬性约束，比如「Node 版本 >= 20」「所有 API 路由必须以 /v2 开头」「UI 文案必须用英文」。每个子任务的实现者看到这个区块就知道全局规则，不需要从 spec 里自己去找。

Interfaces——接口声明区块。

**Interfaces:**
- Consumes: [what this task uses from earlier tasks — exact signatures]
- Produces: [what later tasks rely on — exact function names, parameter
  and return types.]

每个任务必须声明自己依赖什么、产出什么。这是任务之间的「合同」。实现者不需要知道整个系统的全貌，只需要知道自己的输入和输出。

这两个设计解决了一个实际问题：子 Agent 的信息隔离。 每个子 Agent 只看到自己的任务和全局约束，看不到其他任务的内部实现。这既减少了 token（不需要加载无关任务的细节），又保证了任务之间的解耦（一个任务的实现变化不会影响其他任务）。

决策七：Controller 不许指导 Reviewer

最后这条规则，我在源码里反复读了三遍才确认自己没理解错。

Do not pre-judge findings for the reviewer — never instruct a reviewer to
ignore or not flag a specific issue. If you believe a finding would be a
false positive, let the reviewer raise it and adjudicate it in the review
loop. If the prompt you are writing contains "do not flag," "don't treat X
as a defect," "at most Minor," or "the plan chose" — stop: you are
pre-judging, usually to spare yourself a review loop.

翻译：controller 在 dispatch reviewer 的时候，不允许在 prompt 里预先排除任何审查项。

不能说「不要检查 X」「Y 最多算 Minor」「这个方案是计划选的，不算缺陷」。如果 controller 觉得某个发现会是误判，正确的做法是让 reviewer 先提出来，然后在 review loop 里讨论。

这个规则的措辞非常尖锐——「stop: you are pre-judging, usually to spare yourself a review loop」。它直接点出了 controller 这么做的真实动机：想省掉一轮 review 循环。

这是个非常人性化的洞察。controller 每跑一轮 review loop 就多花一轮 token 和时间。它天然有动力去减少 review 轮次。而最简单的方式就是在 dispatch 的时候提前告诉 reviewer「有些东西别管了」。但这样做会破坏 reviewer 的独立性——reviewer 的判断是被 controller 的指令过滤过的，它看到的不是全貌。

加上之前讲的「Do Not Trust the Report」和「Cannot Verify from Diff」，6.0 的 reviewer 设计形成了一套完整的独立性保障：

1. 执行者的自我汇报不可信——reviewer 只看代码
2. reviewer 自己的视野有边界——看不到的标记 ⚠️
3. controller 不能提前过滤审查范围——reviewer 独立工作

三个约束从三个方向保护了 reviewer 的独立性。执行者不能影响 reviewer 的判断标准，reviewer 不能假装看到自己看不到的东西，controller 不能缩小 reviewer 的审查范围。

Reviewer 独立性的三重保护机制

那个模型选择的坑

还有一个容易被忽略但直接影响钱的设计，值得单独说。

reviewer prompt 里有这么一行：

model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
       model silently inherits the session's most expensive one]

SDD SKILL.md 对此的解释：

An omitted model inherits your session's model — often the most capable and
most expensive — which silently defeats this section.
Turn count beats token price. Wall-clock and context cost scale with how
many turns a subagent takes, and the cheapest models routinely take 2-3× the
turns on multi-step work — costing more overall.

这里有一个反直觉的结论：最便宜的模型未必最省钱。

便宜模型单次调用的 token 价格低，但它做同一件事可能需要 2-3 倍的轮次。每多一轮就意味着多一轮的上下文加载、多一轮的输出生成。轮次多了之后，省下来的单价被乘以更多的轮次，反而可能花更多。

6.0 的建议是：Turn count beats token price。 优先选轮次少的模型，而不是单价低的模型。如果不确定选什么模型，就显式指定一个，不要留空让框架继承 session 的模型——那通常是全场最贵的那个。

升级建议

已经在用 Superpowers 的：现在就升。 v6.0.3 是稳定修复版，SDD 的重写是内部行为变化，你的 .claude/settings.json 不用动，Skill 文件随安装自动更新，下一次会话生效。

还没用过的：这是个好的入坑时机。 6.0 的 vendor-neutral 改写让 Claude Code、Cursor、Kimi Code 等 11 个平台的体验一致。不锁定平台，用哪个顺手就用哪个。

在写自己的 Agent 系统的： 这篇文章里拆的 5 个设计决策，每一个都可以独立应用到你的系统里。「不信任自我汇报」「显式标记不可验证」「文件传递替代文本粘贴」「持久化进度账本」「不许上游干预审查」——这些都是经过大规模实战验证的 pattern。

FAQ

Q1：SDD 的 50% token 节省，是所有场景都省一半吗？

不是。这个数字来自框架的标准 benchmark eval，在「计划-拆分-并行执行-审查」的完整流程里测出来的。如果你只用 brainstorming + writing-plans，不走 SDD，体感变化不大。SDD 用得越多，省得越多。省下来的 token 主要来自两个地方：reviewer 合并省掉一轮审查、File Handoffs 省掉上下文中的历史堆积。

Q2：那个 42k 字符的 dispatch 事故，是什么情况下触发的？

当 SDD session 跑了很多子任务（比如 8-10 个），controller 习惯性地把前面所有任务的 summary 拼进后续 dispatch 的 prompt 里。第一个任务 dispatch 1k，第二个 5k，第三个 15k……到后面每个 dispatch 都是几万字符。本质上是 controller 没有意识到「粘贴到 prompt 里」和「存到文件里」在 token 消耗上有天壤之别。

Q3：Durable Progress 的 .superpowers/sdd/progress.md 和 Git 有什么关系？

没有关系。这个文件不被 Git 跟踪，它是 SDD 的临时工作文件，只在当前 session 有意义。v6.0.3 之前它放在 .git/ 目录下，后来移到了 .superpowers/sdd/。放在 .git/ 里只是因为那个目录天然不被 Git 跟踪，但安全社区认为这不规范。

Q4：「不许指导 Reviewer」这条规则，如果 controller 确实知道某个 finding 是误判怎么办？

正确做法是让 reviewer 先提出来，然后在 review loop 里讨论。如果讨论后确认是误判，reviewer 会自己降级或撤回。controller 不能在 dispatch 阶段就预先过滤掉——因为你的判断也可能是错的，reviewer 可能看到了你没看到的东西。

Q5：6.0 的 vendor-neutral 改写具体改了什么？

最典型的变化是把所有 Skill 文件里的「use the Task tool to dispatch a subagent」改成了「dispatch a subagent」。去掉了「Task tool」这个 Claude Code 专属术语。这让 Skill 文件读起来像通用工程规范，而不是某个平台的操作手册。

文中用到的完整 Prompt 模板

以上引用了 Superpowers 6.0.3 的 SKILL.md、task-reviewer-prompt.md、writing-plans 等核心源码片段。完整版 Skill 文件（共 14 个，含 reviewer prompt 和 implementer prompt 全文）已整理好。

折腾这么多，就为了让 AI 写代码时少烧一半 token、少翻一次车。6.0 的 SDD 重写证明了一件事，Agent 系统的质量上限不是模型能力，而是工程纪律的设计。

先把基础的跑通，再慢慢扩展，这是码哥对 Superpowers 一贯的建议，6.0 之后依然不变。如果身边有同事也在摸索 AI 编程工具，这篇可以直接甩给他。