Superpowers 的工作流程到底是什么

0030 秒速览：读完你能做什么

读完这一篇，你能做出三个判断：一次改动该走哪条路径（选错会白干）；代理说"做完了"时该信谁（评审，不是它的自述）；以及它的进度会不会在上下文被压缩后丢掉（取决于有没有那个文件）。

按你现在的处境，直接跳到对应那一节

"读完你应该能"：四条自检

• 能用自己的话说出这套流程在防什么：防的不是"写错代码"，而是"没人独立看过就说做完了"和"进度活在记忆里"（见 01 节）。
• 能区分三对最容易混的东西：规划技能 vs 实现技能、任务评审 vs 末端评审、裁定 vs 停机（见 26 节末的对照表）。
• 能预判它什么时候会来问你：动工前一定问，执行中只有四类问，其余不问（23）。
• 能举一个自己的例子：把"改一行配置"和"加一个新功能"分别套进三条路径，说出各自该产出什么——这条只有你能验（99）。

01它说的"工作流程"到底指什么

先破三个错想

错想一：它是一套命令，记住就能用。不是。它是一堆带触发条件的说明文件，官方叫 skill（技能）——每份是一个 SKILL.md，写清"什么情况下该用它、用它时必须做哪几件事"。你不用敲它，代理开工前会自己去查（04 节）。

错想二：它是"帮我把代码写得更好"的工具。不是。官方 README 的定位是"a complete software development methodology"（一套完整的软件开发方法论）——重点在流程。它最值钱的几个环节做的是：向你提问、把答案落成文档、派一个没有你对话历史的代理去独立核对。

错想三：不需要任何前置知识就能看懂。半对。入口很简单（正常提需求就行），但要读懂它给的产物（设计文档、计划、评审报告），你得知道"什么叫一个任务""什么叫测试先写"。所以这篇标 🟡 进阶，不是 🟢 入门。

它是什么：一串带闸门的接力

把官方 README 的七步和技能原文对照着看，它的形状是一条接力：每一棒交出去之前都有一道门，门没过大不了停在原地，但不会"带着没确认的东西往下跑"。四个稳定特征：先问再写（动手前先把"你到底要什么"逼出来）；设计 → 计划 → 派发（设计文档是权威，计划是它对设计的论证，每个任务被抽成一张独立的任务单）；没人独立看过就不算完成（每任务一次窄评审，全部完成后再来一次全分支宽评审）；进度写在磁盘上（都进那个叫账本的文件，见 21 节）。

02官方七步摘要，和技能里真正强制的规则

README 的《The Basic Workflow》列了七步。它好记，但它是摘要，不是规范——真正约束行为的是每个技能自己的 SKILL.md。记住两边的差额，你才知道该盯哪里。

摘要和实现脱节的地方，具体是哪一处

第 6 行那个"归谁管"的问题，有一份设计文档记下了修法：任务级评审的模板与派发方式被上移到 subagent-driven-development 名下，requesting-code-review 保留的是宽评审（全分支）那套模板。README 写的是改之前的分工，照着摘要读会把"谁派任务评审"读错。

还有一层整个没进摘要：账本机制。七步里没有一步叫"记进度"，但它是 SDD 里篇幅最重的一块，且有实测支撑（21）。

结论：把七步当路线图（大概会经过哪几个环节），把 SKILL.md 当规范（它到底会不会做某件事，只信后者）。摘要会漂移，实现不会。

03最小例子：一次小改动走完整条流程

抽象讲三段，不如跟一次真实的小改动。假设你只有一句话的需求："导出页面上当前筛选出来的结果。"

04你没敲命令，它为什么自己启动

启动键不是命令，是一条 1% 规则

负责启动的是 using-superpowers 这个技能，它的原文用全大写写着一条硬规则。中文意思是：只要你认为有哪怕 1% 的可能某个技能和当前任务相关，就必须调用它；技能一旦适用，你没有"选不选"的自由。

# 原文（skills/using-superpowers/SKILL.md，2026-09-13 抓取）
If you think there is even a 1% chance a skill might apply to
what you are doing, you ABSOLUTELY MUST invoke the skill.

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE.

它甚至专门列了一张"自我辩解"清单来堵漏："这只是个简单问题" → 问题是任务，先查技能；"我先看看代码库" → 技能就是告诉你该怎么看的；"我记得这个技能" → 技能会演进，读当前版本。这张表的用途是给代理看的，但对你也有用：当你看到它跳过了某个环节，先问一句"这个技能适不适用"，比教它怎么做更快。

两个都在争着管你的时候，谁优先

技能分两类，冲突时有一条明确规则：

另外，你的指令优先级高于技能（AGENTS.md、CLAUDE.md、你当场说的话）；只有你明确说"跳过这个流程"，才允许跳过。

什么时候这条 1% 规则不生效

技能自己写了一个例外，用的是一对标签：如果一个代理是被派来执行某个具体任务的子代理，它应当忽略这个技能。原因很实际：14 节的派发契约要求子代理"只看得到自己那一个任务"，如果它还跑回去加载一整套启动规则，就会被灌进与任务无关的东西。

<!-- skills/using-superpowers/SKILL.md 开头 -->
<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task, ignore this skill.
</SUBAGENT-STOP>

看到这个标签的意义在于：它是"上下文隔离"的第一道落实，而不只是文档细节。

05第一个决策点：三条路径，选错就白干

它凭什么把流程劈成三条

所有请求——包括你眼里"随口一问"的那种——都要先过一道分类。分类结果只影响一件事：这条路要产出多重的工件（两句话的设计，还是一份设计文档 + 一份实现计划）。

拿不准的时候怎么选

规则很干脆：拿不准选重的一档；分类是棘轮——只能往上加，不能往下减。理由不是保守，而是纠错成本不对称：把 architectural 当成 bounded 做，等发现要改接口时，已经有一批代码建立在这个接口上了；反过来只是多花几分钟写清设计。复核这个决策的最佳时机就是它宣布分类结果的那一刻。

为什么这条把流程劈成三条的规则最容易看漏

因为绝大多数抱怨都来自同一种误读：把七步当成一条铁轨。实际上第一条决策已经把流程劈开了，只是摘要没说。现象是"流程太重"，根因通常是"分类被判重了"——正确的反应是拿一句话去复核分类（"这个改动要不要动接口？"），而不是让它跳过批准。

技能正文专门点了反向的错：随任务简单程度缩水的是工件（设计可以短到两句话），不是批准——沉默不算同意（06 节）。

06硬闸门：批准之前，一行实现代码都不许写

这是整套流程里语气最重的一条，也是原文可引的一段。它把"批不批准"和"任务大小"彻底解耦：

# 原文（skills/brainstorming/SKILL.md，2026-09-13 抓取）
Do NOT invoke any implementation skill, write any code, scaffold any
project, or take any implementation action until you have told your
human partner what you intend and they have approved it. This applies
to EVERY task on EVERY path below — the ceremony scales with the task;
the approval never does.

中文重述：在你告诉人类伙伴你打算做什么、并且对方批准之前，不许调用实现类技能、不许写代码、不许搭脚手架、不许采取任何实现动作。这条对每条路径上的每个任务都成立——仪式随任务缩水，批准永远不缩。

闸门到底长什么样

• 谁来批准：你，不是代理自己——自评自批会让闸门退化成装饰。
• 什么时候：它说清楚打算做什么之后、任何实现动作之前。"先写一点再问"会让批准变成事后通知。
• "行吧""随便"算吗：不算，要一个明确的 yes。"没反对"和"同意"是两件事——这条在收尾菜单（24）还会再出现一次，那里判定更严。
• 小改动能省吗：不能，但可以短到一句话——省的是展示篇幅，不是这一步本身。

你在这里该盯什么

盯两件事：它有没有说清打算做什么（而不是"我准备开始了"），以及它有没有在你回答之前就动起来。后者是真正的故障——闸门的价值全在"顺序"上，晚一秒就没了。

07第二个决策点：隔离工作区，先检测再创建

为什么要有这一步

隔离工作区（官方做法是 git worktree，宿主也可能提供等价机制）就是另开一个目录检出同一份仓库，让这次改动不碰你当前手头的代码，"改坏了"的半径因此限制在这个目录里。它在流程里的位置是场地条件：设计批准后、动工前准备好，之后所有任务都在这里跑。

三个具体动作，每个都有个"别做"

一条与它配套的硬规则

SDD 的 Setup 里有一句几乎是逐字的规定：没有人类伙伴的明确同意，绝不在 main / master 分支上开始实现。注意它和批准闸门不是同一件事——批准的是"做什么"，这一条锁的是"在哪儿做"。两者都要。

# 典型的一组命令（用 git 自己的 worktree 机制）
git worktree add ../feature-export -b feat/export-filtered
cd ../feature-export
npm install          # 跑项目自己的初始化
npm test             # 验证基线：必须全绿再开工

# 收尾阶段清理时只动这一处（第 24 节会讲为什么只清这里）
git worktree list
git worktree remove ../feature-export

08把设计切成 2–5 分钟的步子：计划的写法是被规定死的

写计划时要假设读者是谁

writing-plans 的开篇用一句话定义了"写给谁看"。这句话决定了后面所有规则，所以值得原文引一次：

# 原文（skills/writing-plans/SKILL.md，2026-09-13 抓取）
Write comprehensive implementation plans assuming the engineer has
zero context for our codebase and questionable taste. ...
Assume they are a skilled developer, but know almost nothing about
our toolset or problem domain. Assume they don't know good test
design very well.

中文重述：写计划时要假设执行者对我们的代码库零上下文、品味可疑；假设他是技术不错的开发者，但对我们的工具链和问题域几乎一无所知，而且不太懂好的测试设计。为什么把执行者想得这么差？因为它就是一份派发材料的母本：每个任务会被抽出来单独发给一个全新子代理，那个子代理没有你的对话、没有你的权衡过程、看不到别的任务，手里只有这张任务单。这是为真实的读者写文档，不是谦虚。

任务该切多大：一条可以背下来的判据

技能正文给的定义比"2–5 分钟"更本质——它把任务和步骤分开了：

而任务的内部步骤才是 2–5 分钟粒度，固定五步（写失败测试 → 跑它确认失败 → 写最小实现 → 跑它确认通过 → 提交）。这五步在计划文档里有固定格式，下面两份可以直接照抄、把名字换掉：

# 每任务循环里那固定五步，在计划文档里长这样（照抄改字即可）
- [ ] **Step 1: Write the failing test**

```python
def test_rejects_empty_input():
    assert parse("") == ParseError.EMPTY
```

- [ ] **Step 2: Run test to verify it fails**

Run: `pytest tests/test_parse.py -v`
Expected: FAIL — "ParseError has no EMPTY"

- [ ] **Step 3: Write minimal implementation**

```python
def parse(s):
    if not s: return ParseError.EMPTY
```

- [ ] **Step 4: Run test to verify it passes**

Run: `pytest tests/test_parse.py -v`
Expected: PASS

- [ ] **Step 5: Commit**

```bash
git add tests/test_parse.py src/parse.py
git commit -m "feat: reject empty input"
```

而一个完整的任务，除了这五步还要写清文件清单与接口——文件路径要精确到行号，接口要说清"消费什么、产出什么"，因为执行者只看得见自己这一个任务：

### Task N: 导出当前筛选结果

**Files:**
- Create: `src/export/to-csv.ts`
- Modify: `src/pages/results.tsx:120-140`
- Test: `tests/export/to-csv.test.ts`

**Interfaces:**
- Consumes: `filteredRows(): Row[]`（来自 Task 2，签名见那份任务单）
- Produces: `toCsv(rows: Row[]): string`——后面的任务按这个签名调用

09计划头部五件套：每一件都在防一个具体的失败

技能正文写着"每个计划必须以这个头部开始"（原文用的就是 MUST 级别的措辞）。其中每一件都有功能，不是格式洁癖：

头部在文件里长这样（照抄改字即可）：

# 导出当前筛选结果 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
> (recommended) or superpowers:executing-plans to implement this plan task-by-task.

**Goal:** 结果页能把当前筛选结果导出成 CSV。
**Architecture:** 纯函数负责序列化，页面只负责取数并触发下载。
**Tech Stack:** TypeScript、React、Vitest
**Spec:** docs/superpowers/specs/2026-09-13-export-filtered-design.md

## Global Constraints

- Node >= 20.11（以 package.json 的 engines 为准）
- 不新增运行时依赖；CSV 序列化手写
- 用户可见文案统一走 `t()`，不出现硬编码中文
- 导出文件名格式：`results-YYYYMMDD.csv`

⚠️ Global Constraints 丢了会怎样：一个记录在案的事故

设计文档里记了一次评测中发现的问题：某次运行交付的模块版本下限与设计里写的不一致，而根因不是实现者写错——是没有任何一个评审者见过这条约束：控制者在把需求传给评审者时把全局约束漏掉了。所以技能现在写死了一条：控制者必须把约束逐字抄给评审者，因为它就是评审者的"注意力透镜"。

这条对你有两个用处：① 写设计文档时，把项目级硬要求单独成节，因为下游会逐字搬运它；② 看到代理交付了某个奇怪的版本号或命名，先查这条约束在不在传递链上，而不是先怀疑实现者。

还有一条相关规则：一份设计如果覆盖了多个互相独立的子系统，应当在 brainstorming 阶段就拆成多份；计划阶段发现没拆，就停下来建议拆开——因为跨子系统的任务没办法被单独派出去。

10哪些写法一律算"计划失败"

技能把下面这些称为 plan failures（计划失败）。注意措辞的分量：不是"后面再补"，而是这份计划本身不合格。

同一件事的两种写法，对照着看

- [ ] Step 3: 实现解析器
  加适当的错误处理，并处理边界情况。
  为上面的逻辑写测试。

- [ ] Step 1: Write the failing test
```python
def test_rejects_empty_input():
    assert parse("") == ParseError.EMPTY
```
- [ ] Step 2: Run it, verify it FAILS
  Run: `pytest tests/test_parse.py -v`
  Expected: FAIL — "ParseError has no EMPTY"
- [ ] Step 3: Minimal implementation
```python
def parse(s):
    if not s: return ParseError.EMPTY
```
- [ ] Step 4: Run, verify PASS
- [ ] Step 5: Commit

11写完必须自审：三步固定动作

计划写完后有三个动作，顺序固定，且由写计划的人自己跑——技能明确写了这不是一次子代理派发。三步各有各要抓的东西：

发现问题的处理方式是"就地修掉，不需要再复审一轮"。这条规则在本流程里反复出现，它防的是"用一个流程去审另一个流程"的无限套娃：自审就是自己看，看到就改，改完继续。

计划的终点：把两条执行路径交给你选

计划保存后，技能要求给出两条执行路径让你选，原文给的措辞几乎可以直接用：

Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:

1. **Subagent-Driven (recommended)** - 我每个任务派一个全新子代理，任务之间评审，迭代快
2. **Inline Execution** - 在当前会话里用 executing-plans 分批执行，带检查点

Which approach?

注意这里的分工：它给选项，不给决定。两条路径的性格差别很大（见 05 节的三条路径与 12 节的循环），选错了体验完全不同。

12一个任务走五步：主循环的骨架

执行阶段最厚的一份技能是 subagent-driven-development（下文简称 SDD），单文件 568 行，是改动最频繁的一份。它开篇先解释了"为什么要用子代理"，理由和我们通常想的不一样：

# 原文（skills/subagent-driven-development/SKILL.md，2026-09-13 抓取）
They should never inherit your session's context or history —
you construct exactly what they need. This also preserves your own
context for coordination work.

中文重述：子代理永远不该继承你会话的上下文与历史，你要为它精确构造它需要的东西。这么做的两个收益：它不会被你一路累积的假设带偏；你自己的上下文额度被保住，用于协调工作。第二点常被忽略，但它解释了后面一大批看起来"过于抠门"的规则——为什么派发不许贴历史、为什么 diff 要交给文件。核心原则一句话：每任务一个全新子代理 + 任务评审（规格 + 质量）+ 末端一次宽评审 = 高质量、快迭代。

Setup：开工前要做的四件事

然后进入五步循环

第 5 步的完结记录格式是固定的：

Task <N>: complete (commits <base7>..<head7>, review clean)
# 跳闸过的任务则是：
Task <N>: complete (commits <base7>..<head7>, <K> parked)

13开工前的冲突预扫：产出是一张表，不是一句"没问题"

这一节是全文里最容易被跳过的，但技能写得非常具体：扫描的产出是一张表，不是一句"扫干净了"。原文对敷衍有一句直白的判词："扫干净了"而没有这些行，等于你没扫。

表里必须有的两类行

扫出来之后怎么处理

每一处冲突都要在开工前裁定，裁定写进账本、放在它那一行旁边；干净就直接开始，不必多话。这里有一条边界值得记住：预扫不是为了把实现阶段可能冒出的冲突一次算完——技能正文把后者留给评审循环当兜底。预扫管的是从计划文本本身就能看出来的冲突。

这张表也是你复核"代理是不是真的读了计划"的最便宜凭据——要它把这行表贴出来，只有真扫过才写得出来。

14派发契约：一次派发必须给的五样东西

派发之前先记坐标

技能规定：派发实现者之前先记下 BASE（git rev-parse HEAD），后面的评审包和修复轮 diff 都要用它。而且写死了一句"绝不"：绝不能事后用 HEAD~1 代替——那会静默丢掉多提交任务的除最后一次之外的全部提交：评审者会看到一份不完整的 diff，却不知道它不完整。

# 派发前记下 BASE
git rev-parse HEAD          # 例如 4f2a9c1…，记下来

# 拿这个计划的任务单（技能自带脚本，会打印它写出的唯一文件路径）
scripts/task-brief docs/superpowers/plans/2026-09-13-export-filtered.md 1
# → …/.superpowers/sdd/2026-09-13-export-filtered/task-1-brief.md

# 评审包：把提交列表、统计摘要、带上下文的完整 diff 装进一个文件
scripts/review-package docs/superpowers/plans/2026-09-13-export-filtered.md <BASE> HEAD
# → …/task-1-review-<BASE7>..<HEAD7>.diff   （路径由脚本打印）

# 没有 bash 时的等价写法（原文给出的回退方案）：三条命令重定向进同一个文件
git log --oneline > review.diff
git diff --stat >> review.diff && git diff -U10 >> review.diff

派发内容由五个部分组成

技能正文把这五条列成了一份清单，缺一条就意味着一件事要靠猜：

可以直接抄的派发模板

你负责计划里的 Task 1：导出序列化函数。它是整个功能的第一块——
它产出的 toCsv(rows) 后面会被页面调用。

先读这个文件，它是你的需求，里面的确切值要逐字使用：
  …/.superpowers/sdd/2026-09-13-export-filtered/task-1-brief.md

任务单不知道的接口（来自已完成的调研）：
  filteredRows(): Row[] 已有，返回 { id: number; name: string }[]

我注意到的一处歧义，裁定如下：
  任务单写"空数组返回空字符串"，但 CSV 消费方要求始终有表头；
  裁定：空数组返回 'id,name\n'。理由：与 Task 2 的表头复用逻辑一致。

完成后把完整报告写进：
  …/.superpowers/sdd/2026-09-13-export-filtered/task-1-report.md
回报只要四样：状态、提交号、一行测试结论、你的疑虑。

约定：你不派子代理——不派助手，也不派评审者。评审我来安排。
有不清楚的地方直接问我，别猜。

派发里三条"绝不"

一条很实用的小规矩：批量小活

当计划里连着几个同形状的小改动（同一处一行修复、同一个常量变更、同一个字段添加重复出现在多个文件里），不要一个任务派一个子代理——写一份派发说明列出每个文件和它的改动，整批发给一个子代理，把它的 diff 当一个单位评审。一个任务一次派发，留给那些需要自己判断、自己测试、自己一个评审面的工作。

15四种回报状态：每一种都有对应动作

实现者只被允许报四种状态之一。好处是你不用读长篇解释就知道该怎么办——状态本身就是路由键。

BLOCKED 的四种原因，对应四种改法

① 上下文问题 → 补上下文、同模型重派；② 需要更强的推理 → 换更强模型；③ 任务太大 → 拆成更小的块；④ 计划本身错了 → 裁定修正、记账，并把这条裁定带进重派。

原文对 BLOCKED 有一句硬要求：绝不忽略升级请求，也绝不让同一个模型毫无改变地重试——"如果实现者说它卡住了，那么有些东西必须改变"。

最后一条容易忽略的规定：实现者提问时——不管开工前还是任务中途——都要清楚完整地回答它，需要就补上下文，别催它赶紧开始写。所以当你看到子代理在提问，那不是卡住的信号；真正的故障信号是它不问、直接猜。

16评审契约：两个判定，缺一个都不算完成

评审者拿到的三样东西

评审不是"再看一眼代码"。技能规定：先把 diff 交给文件（上一节的评审包；这个输出从不进入你自己的上下文），再把三个路径给评审者，外加约束这个任务的全局约束：

1. 同一份任务单（它审查的规格）
2. 报告文件（实现者说它做了什么）
3. 评审包（提交列表 + 统计摘要 + 带上下文的完整 diff）
4. 外加 Global Constraints——09 节那条"必须逐字抄给评审者"的约束块

必须拿回两个判定

原文对此的措辞是"绝不要接受缺少任何一个判定的报告"，而且加了一句：实现者的自审永远不能替代任务评审——两者都要。理由很直白：自审用的是同一个脑子、同一批假设，它看不见自己的盲区。

那一类 ⚠️ 是什么意思

评审者可以报一类叫"无法从 diff 验证"的项：那些要求写在没被改动的代码里，或者跨了好几个任务，单看这份 diff 判断不了。它的规则和另外两类都不同：不阻塞评审的其余部分继续；但你必须逐条自己解决，才能把任务标记成完结（只有你手上有计划和跨任务上下文）；如果你确认它确实是真缺口，就按规格评审失败处理，和其他发现一起进循环。

任务评审 vs 全分支评审：别混

技能对"任务评审"的定位说得很清楚：它是窄闸门。宽度的唯一合法出口在最后那次全分支评审。把任务评审做成全分支规模，结果是每个任务又慢又贵（这件事有实测数字，见 25 节）。

17重审为什么必须"范围受限"

先看它修掉的是什么病

修复之后要重审，但"重审"有两种做法，差别是决定性的。这个流程之前的那一版，循环的字面规则就是"Repeat until approved"（重复到被批准为止）：没有轮次上限，而且每一次重审都是对整个 diff 的全新完整评审。结果是"一个非确定性的评审者每轮都能翻出新发现，而不是核实修复"——节奏变成"实现、评审、修、评审、评审、修、评审、修"，没有断路器。

修法是把重审的范围钉死：只看修复范围内的 diff。

范围受限重审的输入与输出，都是写死的

原文的反驳很干脆：有人说"评审者反正还会发现新东西"——回答是"范围受限的重审是在核实修复，它不会漫游；未改动代码上的新发现进账本，不进循环。"

每一轮还要过一道完整性门禁

重审之前有一道检查：修复报告里必须同时有这三样，缺一样就先别派重审——

• 覆盖测试：哪些测试覆盖了被改动的代码（修复消息里要点名测试文件："一行修复不需要整个测试套件"）
• 跑的命令：实际敲的那条
• 输出：运行结果

这一轮的动作是固定的四件：实现者修 → 重跑覆盖被改代码的测试 → 把修复报告追加到同一个报告文件 → 返回短契约。技能还专门加了一条禁令：控制者绝不自己动手修发现——那会污染协调用的上下文，而且绕过评审。

18修复循环：五轮上限、换人不换题、到点跳闸

什么会触发循环

三个触发条件之一成立就进循环：

• 规格评审报了 ❌；
• 出现任何 Critical 或 Important 级发现；
• 有一条你自己确认属实的 ⚠️ 项（上一节那类"无法从 diff 验证"的）。

而在循环开始之前，有两类发现被直接分流出去，不占轮次：

五轮怎么分配：前三次换题不换人，后两次换人又换脑子

第 5 轮之后：跳闸，由你逐条裁决

第 5 轮的重审仍留着开口发现时，停止派发，控制者逐条裁决。三种处置的区别很关键：

两条配套纪律，保证"跳闸"不被用成"提前放弃"

只在到上限时裁决——原文有一句很尖锐的话："提前裁决来结束循环，是换了个名字的预判。"每次裁决都是账本里的一行——静默丢弃是被禁止的。

四种典型借口（都是原文点名过的）

19三条由观测换来的"不许"

评审环节有三条禁令，它们的共同点是：都不是从原则推出来的，而是从真实会话的成本观测里收回来的。

⚠️ 第四条禁令：实现者不许自己派子代理，尤其不许派评审者

派发里带着一条"无子代理契约"，实现者的模板里写着：这件事的活你自己做完。绝不派子代理去实现任务的一部分，尤其绝不派一个评审者来检查你的工作。它还给了一句我认为很有用的解释——如果你心里冒出"多一个独立评审会让我的报告更强"，那个评审已经安排好了，报告即可。

技能把"工人自带的评审者"明确定义为一个应当被标记的缺陷，而不是严谨。理由：每个工人自己生出来的评审者都在重复控制者本来就会派的那个任务评审——等于每个任务白付一个评审座位。

这条对你有直接用处：看到"我自己又派了个代理帮我审了一遍"这种描述时，应该当成流程出错的信号，而不是加分项。

20任务之间不许停下来问：连续性是被写进规则的

SDD 里有一条明确的"不要"，语气很重，中文重述是：不要在任务之间停下来跟人类伙伴确认，把计划里的任务全部执行完再停。唯一的停止理由是那四个具名条件，或者所有任务完成。原文把"要继续吗？"这类提示和进度小结（"目前 2/5"）称为浪费他们的时间——"他们让你执行计划，那就执行"。

为什么这条规则值得单独讲

因为它和多数人对"AI 代理"的期待正相反。多数人觉得"多问我一句更安全"，但这个流程算的是另一笔账：把"人"当默认检查点，等于把最贵的收益（无人值守连续推进）主动放弃，而且把"执行"降级成了"轮流批准"。所以判据是：你停下来要问的这件事，属于那四类之一吗？不属于，就该裁定 + 记账 + 继续。

先分清"动工前"和"执行中"

动工前：批准闸门永远要等一个明确的 yes，任务再小也不省——你在"开始做之前"保留了全部控制权。执行中：四类之外全部自己裁定（格式固定：决定了什么 / 为什么 / 错了的代价），记进账本，继续——你在"已经开始做之后"换来了不被阻塞的推进。两个时刻、两套规则，互不侵蚀。授权大胆的前提是"错误可撤销、且记账后可见"，这个前提在下一节变成了四条边界。

与连续性配套的还有一条等待纪律：绝不用短超时反复轮询，也别一声不吭地无限等。手上有本地活（更新账本、打包下一份评审、读报告）就继续做；真的闲着时按有限时段等（平台允许的话五到十分钟一段），每段之间发一行状态并核对还活着的子代理。如果你看到它每隔几秒看一次子代理状态，那是回归。

21账本：进度为什么必须写在文件里

这是整套流程里最"不优雅"、也最有证据支撑的一节。SDD 的 Setup 段第一句就是这条痛点的记录：

# 原文（skills/subagent-driven-development/SKILL.md，2026-09-13 抓取）
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.

中文重述：对话记忆活不过上下文压缩。在真实会话中，丢失了进度的控制者重新派发了整批已经完成的任务序列——这是被观测到的最昂贵的失败。

它到底有多贵，设计文档里记了三组可核对的数字（前两组来自"没有隔离"时期，第三组来自一次压力测试）：

那次压力测试推翻了一个假设，也校准了一个说法

测试场景是"上下文压缩后恢复"，而且故意把本该失败的条件都摆好：一个陈旧扁平路径的账本（属于另一个计划）、另一个计划自己的已完成目录、而当前计划一份记录都没有。

• 结果：25/25 次控制者都拒绝了把别人的账本当自己的进度用（三个轮次、五个单元格、每格五个全新子代理）。假设中的失败——盲目采信陈旧外部账本——没有复现。
• 但可复现的代价还在：在最接近真实崩溃恢复的那一轮里，每个控制者平均仍要花 9.0 次工具调用（7、13、9、10、6）去先证明这份账本不是自己的，然后才开始干活。

这里要说清一件容易被讲反的事：新的目录结构并没有把这个数字降下来。同一份报告给出的对照是——结构性改造之后，同一场景的原始工具调用数反而变成 9.6 次（9/11/9/7/12），因为新夹具里的陈旧材料更多（多了"自己的空目录""扁平旧账本""另一个计划的已完成目录"三处，而旧夹具只有一处扁平账本）。

账本的格式：几行字符串，每一行都有语义

账本就是一个纯文本文件 progress.md，放在这个计划专属的、被 git 忽略的工作区里。格式看起来简陋，但每一行都是为了让下一个接手的人（或代理）能据此行动：

一份真实形状的账本大概长这样（内容不重要，注意行的种类与顺序）：

# SDD ledger — plan: docs/superpowers/plans/2026-09-13-export-filtered.md

## Preflight rulings
- Task 1 × Task 2 共享 to-csv.ts → 接口以 Task 1 的签名为准
- Task 3："始终有表头"与空数组分支矛盾 → Ruling: 空数组也输出表头

## Progress
Task 1: complete (commits 4f2a9c1..8b3d0e7, review clean)
Task 2: minor (deferred): CSV 转义只覆盖逗号，未覆盖换行
Task 2: fix round 1/5 (2 addressed, 0 open — 魔法数字/进度上报; commits 8b3d0e7..c19f4aa)
Task 2: complete (commits 8b3d0e7..c19f4aa, review clean)
Task 3: parked — 导出文件名时区未处理 — Ruling: 不在本计划 spec 范围内，延后

为什么必须记"提交号"，而不只是"任务 3 已完成"

因为 账本给的是坐标，真相在 git 里。技能原文说得很关键：账本里记下的提交号在 git 里真实存在，即使你的上下文已经想不起来创建过它们。由此推出一条纪律：被压缩之后，信账本和 git log，不要信你自己的回忆。

还有一条警告：这个工作区是草稿区，会被清掉——技能正文直接点出 git clean -fdx 会摧毁它（它是被 git 忽略的临时区）。撞上时的恢复办法不是找回文件，而是从 git log 恢复；这正是"必须记提交号"的另一半理由。

🚨 收尾时最容易漏的一步：裁定必须活着走出去

SDD 收尾有一条特殊要求：删除工作区之前，把账本里每一条含 Ruling: 的行收集进最终消息，标题叫 "Rulings I made"，按做出决定的顺序排列，每条附上"错了的代价"。原文把严重性说透了：

原因很实在：工作区会被 rm -rf 删掉，记录移交给 git 历史——但裁定不会自动进入 git（它只是工作区里的几行文字）。所以这一步漏了，你就再也看不到代理替你做了哪些判断。技能对这份清单的要求是穷尽：账本里有几条裁定，清单里就有几条。

22压缩或换会话之后，怎么接着做

恢复动作被写成三条判断，顺序固定，都能机械执行。这也是你可以亲手复核代理行为的地方——打开工作区里那个 progress.md，看第一行。

这三步能成立，靠的是上一节那条设计：一个计划一个目录 + 第一行写身份。它省下的不是"少犯错"，而是每次都少花一次取证开销——这个思路本身值得学：一个机制的价值不一定要体现在"避免灾难"上，也可以体现在"把每次都要付的税砍掉"。

23只有四件事能停下它，其它一律自己裁定

这是理解整套流程"性格"的关键一节。SDD 用两个小标题定义了自己的行为准则，第一个是 "Rulings, not stalls."（裁定，而不是停摆）：

# 原文（skills/subagent-driven-development/SKILL.md，2026-09-13 抓取）
A running plan does not wait on a human. Conflicts, ambiguities,
plan defects, a cap you would have asked to exceed — decide them.
The spec is the binding authority, the plan is its argument, and
your judgment settles what neither answers. ... A wrong ruling costs
rework your human partner can see and undo; a session parked on a
question costs their whole day and buys nothing.

中文重述：运行中的计划不等人。冲突、歧义、计划缺陷、一个你本来会申请突破的上限——都由你决定。spec 是有约束力的权威，plan 是它对 spec 的论证，两者都没回答的部分由你的判断来定。每条决定都要记成 Ruling: <决定了什么> — <为什么> — <如果错了代价是什么>，然后继续。

最后那句是整段的灵魂：一个错误的裁定，换来的是人类看得见、也能撤销的返工；一个停在问题上的会话，换来的是他一整天的等待，而且什么都没买到。这是一个明确的经济学取舍：用"可撤销的错误"换"不阻塞"。让这个取舍不至于失控的，是下面四条边界。

四件必须停下来的事

注意第四条的门槛被刻意设得很高："每条路都是猜"，而不是"有点不清楚"。它的作用是防止把"裁定"这个工具用来逃避思考——发现计划有缺陷时，默认动作是裁定最小修正并记账，只有连最小修正都无从谈起时才停。

❌ 错误：把"人"当成默认的检查点

"我做完任务 1 和 2 了，要继续吗？"
"任务 3 有个小歧义，等你回复再动手。"
"给你一个进度小结：目前 2/5……"

动工前：批准闸门永远要等一个明确的 yes
执行中：四类之外全部自己裁定
        格式固定（决定了什么 / 为什么 / 错了的代价）
        记进账本，继续

⚠️ 这条授权反过来用，就是整套流程最危险的地方

"我自己裁定"这句话，如果被用在四类停机条件上——比如顺手强推了一个分支、或者用 --force 清了挡路的工作区——那么这套流程用来兜底的那个机制就失效了：裁定之所以可以大胆，是因为错误可撤销、且记账后可见；破坏性与安全敏感动作同时打破了这两条。你读代理输出时最该盯的就是这里：它把哪些动作归类成了"可裁定的"。

反过来的误判：有三类提问是设计如此

不要因为它停下来问你就断定"又卡住了"。有三类提问本来该发生：① 动工前的批准闸门（每条路径、每个任务都要）；② brainstorming 的澄清提问（一次问一个，而且偏好多选题）；③ 上面那四类停机条件。真正的异常是另一种：在"已经批准、正在执行"的阶段，为了一件四类之外的小事来问你。把这两者分开看，你就不会去"修"正确的行为。

24末端评审与收尾：一次宽评审，一个由你选的菜单

末端评审：一次，很宽，最强模型

所有任务走完之后，流程做一次全分支评审（不是每任务那种窄评审），四个特点都有理由：

有发现时：恰好一次修复波

处置方式是硬性的：派一个修复子代理，带上完整的发现清单——不是每条发现一个修复者；然后恰好一次范围受限的重审（同样只看修复范围），残余发现按跳闸那套处理。没有第二轮修复波，剩下的承重发现会在收尾阶段呈现给你。

为什么这么抠？设计文档给的成本结论很具体："一次真实会话的末端评审修复波，花的钱比它所有任务加起来还多。"原因是每条发现一个修复者时，每个修复者都要重建上下文并重跑测试套件——纯粹的重复开销。

收尾：动作顺序是固定的五步

最后一个技能 finishing-a-development-branch 把这个顺序写成了一条链：验证测试 → 探测环境 → 呈现选项 → 执行选择 → 清理。顺序本身是规则，其中两处最容易出错：

"丢弃"是一条隐藏路径

三个选项里没有"丢弃这份工作"。它只在你明确要求扔掉时出现，且出现时必须先把要删的东西摆出来：分支名、全部提交的清单、工作区路径，然后要求你亲手打出 discard 才算确认——随口一句"行，删了吧"不算。

git merge-base main HEAD        # 取 MERGE_BASE，给末端评审的 diff 包用
npm test                        # 全量测试：菜单只在绿色之后出现
git status --porcelain -uall    # 工作区删不掉时，先把风险摆出来
git worktree remove .worktrees/feature-export
git branch -d feat/export-filtered

25代价与模型纪律：为什么"用最便宜的模型"经常更贵

这套流程有一批看起来很"抠"的规则（不许贴历史、diff 交给文件、Minor 不进循环、一次修复波）。它们不是洁癖，而是一组被反复测量的成本结论。最有反直觉价值的一条是：

它还有一条硬要求：每次派发都必须显式写模型。原文解释了原因：省略模型会让子代理继承你会话的模型——那通常是可得的最强也最贵的那个——从而静默地废掉整个模型选择策略。

一次"加固反而变贵"的实测：读数字才看得见的东西

同一份评测场景（一个叫 go-fractals 的图形程序）在不同配置下的公开数字如下。第三列的解读是必要的——只看前两列会得出错误结论：

为什么会"加固反而变贵"？文档给出了逐个子代理的回合剖析，结论按影响排序是：便宜模型在多步工作上回合数翻倍（1197 个子代理回合里有 678 个是最便宜的那一档）、每次派发的固定开销（每个任务起 3 个子代理、每个都要自己重新推导 diff；控制者协调本身占了一半的钱）、以及证据叙述的开销。这就是"回合数比单价重要"这句话的来源。

我自己复核过的两件事

上面这些数字是维护者自己的评测记录，我没有条件复现整套实验——但凡是能用文档里给出的绝对数除出来的比例，我都除了一遍，并把方法写在这里，你可以手工验证：

• 三个百分比：44.4 ÷ 64.9 = 0.684 → −31.6%；13.4 ÷ 21.2 = 0.632 → −36.8%；11.67 ÷ 16.07 = 0.726 → −27.4%。文档写的是 −32% / −37% / −27%，三个都在四舍五入范围内成立。
• "最差一抽也胜过基线"：文档说同设计的 8 次运行分布在 44.4–57.1 分钟 / 13.4–20.0M / $11.67–14.84；拿最差那端与基线比——57.1 < 64.9、20.0 < 21.2、14.84 < 16.07，三个轴全部成立。
• 顺带算出的极差：57.1 ÷ 44.4 = 1.286，即同样 prompts 下最好与最差相差 28.6%。这解释了文档为什么把结论都改写成区间、并声明了 ±6 分钟的噪声地板，也提醒你：任何单次成本数字都该当成区间里的一抽。

另一条被量化过的"评审越界"

任务级评审最初被做成"分支评审规模"，文档记得很具体：一个真实会话里 8 个质量评审者有 7 个跑了全仓库 grep，最贵的跑了 50+ 次 Bash 命令、约 200 秒；同期规格评审者只花 6–16 次工具调用、14–65 秒——质量评审的成本是规格评审的 4–8 倍。修法本身比数字更值得记：不是禁止广度，而是把广度挂在"具名风险"后面——跨模块审计（锁顺序、变更的契约、共享可变状态）有时候正是正确的评审方法，"把广度门禁在一个说出口的具体风险之后，而不是禁止它"。

26常见坑：症状、根因、怎么避免

下面每一条都是"你会看到什么"先行——因为症状是你能观察到的，根因不是。

三对最容易混的东西，一句话分清

四类"看起来像坑、其实是设计"的行为

27术语对照表

这些词在这套流程里都有特指，用日常义去理解会正好理解反。第三列回答"为什么重要、什么时候用、别把它当成什么用"。

28速查表：每一步的起点、产出与硬规则

阶段速查

"什么时候该停下来问你"已经在 23 节的对照里讲过了；这里不再重复一张同样的表。

可以直接抄的东西

五个反直觉点

1. 简单任务也要批准。随简单程度缩水的是工件（两句话的设计），不是批准。沉默不算同意。
2. 便宜的模型常常更贵。回合数比 token 单价重要；最便宜档在多步工作上要多花 2–3 倍回合。而且不显式指定模型 = 继承最贵的那档。
3. 子代理不知道你的历史，是特性。把历史粘进派发（真实案例 42k 字符里 99% 是历史）既是成本，也是污染。一次派发只装一个任务。
4. 循环靠"范围受限"收敛，不靠"更努力"。重审只看修复 diff；上限 5 轮；到点跳闸裁决并记账。没有上限的"再试试"，正是被修掉的病。
5. 官方摘要会跟实现脱节。七步摘要里"任务评审归谁"已经过时，而且整层账本机制没进摘要。判断行为要去读 SKILL.md。

29参考来源与证据边界

本文所有关于"它要求什么"的陈述，都来自下面这份文件清单。抓取时间：2026-09-13。我按"实际读到什么程度"分层列出，并标明每份文件在本文里承担哪一部分——没有读过的文件，本文不引用其内容。

A. 逐行读完的技能原文（本文主要依据）

• skills/subagent-driven-development/SKILL.md（568 行）——第 12–24 节的主要依据：五步循环、四种报告状态、派发五要素、账本与工作区、修复循环与五轮上限、断路器三分类、"裁定不是停摆"与四个停机条件、末端评审、收尾前收集裁定的要求。
• skills/brainstorming/SKILL.md（250 行）——第 05、06 节：三条路径、批准闸门原文、"太简单不需要批准"反模式。
• skills/writing-plans/SKILL.md（171 行）——第 08–11 节：写给谁看、任务切分判据、2–5 分钟步骤、强制头部五件套、禁止写法清单、自审三步、执行交接的两条路径。
• skills/test-driven-development/SKILL.md（320 行）——第 08 节五步骨架与"删除先于测试写下的代码"。
• skills/using-superpowers/SKILL.md（63 行）——第 04 节全部：1% 规则原文、技能优先级、<SUBAGENT-STOP>、用户指令优先级、plan 模式前的 brainstorming 前置。
• skills/using-git-worktrees/SKILL.md（167 行）——第 07 节：先检测再创建、忽略检查、基线测试。
• skills/finishing-a-development-branch/SKILL.md（225 行）——第 24 节：五步链、两种菜单、discard 确认词、清理归属与 --force 禁令。
• skills/executing-plans/SKILL.md（64 行）——第 11 节两条执行路径的对照与"立刻停"四条。
• skills/requesting-code-review/SKILL.md（95 行）——第 02、24 节：宽评审模板的归属与"在何时必须评审"。
• SDD 的三份派发模板：implementer-prompt.md（154 行）、task-reviewer-prompt.md（207 行）、re-review-prompt.md（115 行）——第 14–16 节：无子代理契约、评审者输入清单、重审的三条输出契约。
• SDD 自带的三个脚本名：scripts/sdd-workspace、scripts/task-brief、scripts/review-package——第 12、14 节的命令用法（我核实了这三个路径存在、读到它们在正文里的用法，没有逐行读脚本本体）。

B. 逐行读完的设计文档与仓库元数据

• docs/superpowers/specs/2026-07-15-sdd-fix-loop-redesign-design.md（196 行）——第 17、18 节：修复前的"Repeat until approved"、三条设计决定（resume 原实现者 / 重审范围受限 / 五轮断路器）、"扛过三次 resume"的策略原话。
• docs/superpowers/specs/2026-06-09-sdd-task-scoped-review-dispatch-design.md（160 行）——第 02、14、25 节：模板归属被修掉的记录、质量评审 4–8 倍的数字、成本迭代表与 678/1197 回合剖析。
• docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace-eval-results.md（543 行）——第 21 节整节的数字来源：25/25、9.0 次（7/13/9/10/6）与改造后 9.6 次（9/11/9/7/12）的对照表，以及"原始调用数没有下降、承重结论是误认不再可能"的原话。
• docs/superpowers/specs/2026-07-06-sdd-plan-scoped-workspace.md（196 行）——第 21 节：269 次派发 / 约 22 个任务、68 个文件来自三个计划、身份行与"每个计划一个目录"的设计理由。
• README.md（main 分支）——第 02 节的七步清单、How it works 概述、技能清单。
• .claude-plugin/plugin.json——版本号 6.3.0 与仓库地址。
• GitHub API：仓库元数据（默认分支 main、star 数、最后推送时间）、releases/latest、commits?per_page=10（确认 main 上最后一次提交是 2026-08-12 的发布提交 b36e0829）、contents/docs/superpowers/specs。

C. 只下载/列了清单，未读、因此未引用其内容的文件

skills/receiving-code-review/、skills/verification-before-completion/、skills/systematic-debugging/、skills/dispatching-parallel-agents/ 四份 SKILL.md；docs/superpowers/specs/2026-06-10-strict-cost-sdd-design.md；evals/ 目录（夹具需单独初始化，本次未取）。

99一句话总结