Superpowers 到底该怎么用

00先花 3 分钟：什么时候该用它

读完这一篇，你能回答一个很具体的问题：你手上这个任务，该不该让 Superpowers（下面统称 SP）这套流程接管，以及接管到什么程度。先说清两个词：代理就是替你干活的 AI 编程助手（Claude Code、Cursor 这类工具里的那个"它"）；插件是安装形式——把一组规则文件打包装进你已经在用的工具里。SP 不是"装上就更强"的插件，而是一叠会主动拦住代理的规则文件：你会看到它在什么情况下省下返工，也会看到它在什么情况下纯属拖累。

按你现在的处境，直接翻到那一节

一条能立刻执行的最短路径

读完你应该能

01它到底是什么：先把三个错想破掉

如果你只听过名字，最可能把它想成"一套更聪明的提示词"或"某个一键生成代码的命令"。这两种理解都会让你用错它。

一句话：它到底给你装了什么？

SP 是一叠带触发条件的说明书。行业里管这种"代理在特定任务下会自动加载并遵守的说明书"叫技能（skill）：每个技能是一份 Markdown 文本文件（文件名通常是 SKILL.md），开头写着"什么时候该用我"，正文写着"这类活必须怎么干、干到哪一步才算完"。

你在 Claude Code 这类"AI 程序员"工具里装上它之后，代理不是变聪明了，而是多了一套它必须遵守的作业规程。官方的自我描述就是这个意思——"An agentic skills framework & software development methodology that works."（一套能用的智能体技能框架与软件开发方法论）。

这里有个词值得先分清楚：你用的那个 AI 编程工具（Claude Code、Cursor、Codex、Gemini CLI……）叫宿主；SP 是装在宿主里的内容；让内容生效的机制（技能怎么被找到、怎么被加载）由宿主提供。同一套 SP 内容，装在不同宿主里，"外壳命令"不同，但技能写的东西是同一份。

先打个照面：八个后面会反复出现的词

下面这些词现在只需要"见过一面"，看不懂细节完全没关系——每个词在正文里都有专门一节展开。先扫一眼，是为了让你读后面时不会因为一个生词卡住。

它不是"更聪明的提示词"——那它和提示词差在哪？

提示词（包括写在 AGENTS.md 里的背景说明）和技能都是文本，区别不在"写得多好"，而在什么时候被读到、违反了会怎样：

一句话记法：AGENTS.md 回答"我是谁、我们怎么协作"，技能回答"这类活按这几步做、做不到就不算完"。两者不冲突，通常一起用。

它不换模型、不加私有接口，那它凭什么起作用？

四个环节咬在一起：

顺带解释两个你会在截图里看到的词：门禁指一道"不满足条件就走不过去"的关卡（比如"你点头之前不许写代码"）；钩子（hook）指宿主在某些固定时点（例如会话开始）自动执行的一小段逻辑——上面第 2 步的引导词就是靠钩子塞进去的。装完没生效，很多时候就是钩子没跑（需要重载插件或新开会话）。

它凭什么能跨十几个工具用？

因为它不依赖任何一家厂商的私有能力，而是建立在各家都开始提供的通用"技能"约定上。截至 2026-09 校对时，官方 README 列出的支持面包括：Claude Code、Codex（App 与 CLI）、Cursor、Devin CLI、Gemini CLI、GitHub Copilot CLI、OpenCode、Kimi Code、Pi、Hermes Agent、Antigravity、Factory Droid、Grok Build CLI。装到不同工具上，触发的外壳不同，技能内容与纪律是同一套。

它给你省什么、不省什么？

最后一句是这套东西最反直觉的地方：它多数时候不让你更快，而是让你更少返工。如果你当下的任务是"5 分钟试个想法"，它确实会显得啰嗦——这正是 13 节要处理的情况。

02它在堵哪个洞：为什么"纪律"比"聪明"更值钱

你的问题其实不是"AI 不会写"，而是"过程没纪律"

现在的 AI 编程代理，单看"写某段代码"的能力已经很够用。真正出问题的是它做题的顺序：一句话上来就动手、需求没澄清就先写、为了"看起来完成了"跳过测试、写完不做独立检查就宣布成功。SP 的设计假设非常直白：默认代理会走捷径（take shortcuts），所以把流程做成强制，而不是停在"建议你认真点"。

同一个任务，装与不装差在哪？

需求都是"给注册功能加个邮箱校验"：

注意这不是"能力更强"，是把人类团队里那套让人不互相糊弄的机制，搬给了代理：写代码的和挑刺的不是同一个人，挑刺才有效。

它专门堵的四类漏洞

哪些事它管不了？（说清楚这个才不算吹）

它管的是过程，管不了下面这些：

• 需求本身想错了：Brainstorming 只能帮你把话说清楚，不能替你判断"这功能到底该不该做"。
• 领域知识缺失：流程保证"按纪律实现"，不保证模型懂你的业务。
• 一次性的灵感速写：你只想 5 分钟试个想法时，整套流程是负担——这时该显式豁免（走"探针"路径，见 06 节），而不是硬走。
• 人力层面的问题：谁该做决定、团队认不认这套规范——文件管不了人。

能分清"哪些责任交给流程、哪些留给自己"，才算真正用对了它。

03怎么装、怎么确认它真的接管了

安装这一步本身只要一分钟，但"装完没生效"是新手最高频的翻车点，所以本节后半段的验证与排查比安装更重要。装之前请确认：你已经在终端里跑通过你要装的那个宿主，并且登录过。

先选一个宿主，别一次装五个

SP 对每个宿主都要单独装一次（官方 README 原话就是 "Installation differs by harness. If you use more than one, install Superpowers separately for each one."）。第一周只装你每天真的在用的那个：装多个不会冲突，但新手的理解成本会翻倍。

方式 A：从 Anthropic 官方插件市场装（Claude Code，最省心）

在 Claude Code 的对话里直接输入一行：

/plugin install superpowers@claude-plugins-official

这是官方插件市场（一个可以搜索、安装、自动更新的插件目录，英文叫 marketplace）里的分发渠道，能跟着官方版本走。

方式 B：从 SP 自己的市场装

如果你的宿主没接官方市场，或者你想跟 SP 仓库的发版节奏更紧，用它自己的市场：

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

两条命令分别干两件事：把"obra 的插件市场"登记进你的宿主，然后从这个市场里安装 SP。

其他工具分别怎么装？

同一套技能内容，外壳命令不同。挑你手上正在用的那一段，整段复制（每段都能独立粘贴运行）：

# Antigravity —— 从仓库直接装插件；重复执行同一条命令即更新
agy plugin install https://github.com/obra/superpowers

# Codex App —— 在侧边栏 Plugins 的 Coding 分类里找到 Superpowers，点 + 号按提示装
# Codex CLI —— 打开插件搜索界面后搜 superpowers，选 Install Plugin
/plugins
superpowers

# Cursor —— 在 Agent 聊天里装，或在插件市场搜 superpowers
/add-plugin superpowers

# Devin CLI —— 装好之后用第二条命令更新
devin plugins install obra/superpowers
devin plugins update superpowers

# Factory Droid —— 先登记市场，再安装
droid plugin marketplace add https://github.com/obra/superpowers
droid plugin install superpowers@superpowers

# Gemini CLI —— 装扩展；第二条命令更新
gemini extensions install https://github.com/obra/superpowers
gemini extensions update superpowers

# GitHub Copilot CLI —— 先登记市场，再安装
copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace

# Grok Build CLI —— xAI 官方市场；或在 TUI 里用 /marketplace 搜着装
grok plugin install superpowers@xai-official --trust

# Kimi Code —— 插件市场里找 Marketplace > Superpowers；也可从仓库直装
/plugins install https://github.com/obra/superpowers

# Hermes Agent —— 装完要重启正在跑的会话（它没有"上下文压缩后重新注入"的钩子）
hermes plugins install obra/superpowers --enable

# Pi —— 作为 Pi 包安装；本地开发时可用第二条把它当临时包加载
pi install git:github.com/obra/superpowers
pi -e /path/to/superpowers

# OpenCode —— 让代理去读并遵循官方安装说明
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

如果你更想看"哪个工具用哪一行"的速查，这张表跟上面那段是同一份内容：

装完怎么验证它真的生效？

不要凭"装的时候没报错"下结论，跑完这三步：

/reload-plugins

/help

装完没反应？先查这张排查表

权限与遥测要不要动？

04最小例子：让它接住一个 10 行的小改动

先用一个几乎人人见过的场景——"给用户名输入加长度校验"——把"流程接管"变成看得见的东西。注意：下面第 3、4 步那段完整对话是根据技能规则还原的示意走查，不是逐字输出；不同宿主、不同版本措辞不同，但节奏一致。

第一步：同一句话，两种宿主

你：帮我把用户名加个长度校验。
AI：好的，我改一下 register.js：

你：帮我把用户名加个长度校验。
AI：我命中 brainstorming 技能，先澄清两个问题：
    1) 期望的最小/最大长度是多少？
    2) 超界时是报错还是自动裁剪？

第二步：这条命令代表一次完整的最短闭环

把刚才那几步压缩成你实际输入的东西：

你：/brainstorm
    我想给用户名加长度校验，3–20 位，超界返回错误提示，不要自动裁剪。

AI：（澄清后给出简短设计，等你确认）……（进入实现：worktree → TDD → review → 收尾）

你：可以，按这个做。

如果你只想跳过前面的设计讨论（需求已经很清楚了），也可以从计划直接切入：

/write-plan "给用户名加 3–20 位长度校验，TDD 实现"

第三步：把它展开成"你实际会看到"的一段对话

读它的目的不是背流程，而是让"流程接管"变得可见：每一步都是一条能指出出处的技能约束，不是玄学。

你：/brainstorm 给用户名加长度校验：3–20 位，超界报错，别自动裁剪。

AI：我先把这个归到 brainstorming 的 "bounded（有界）" 路径——
    它是对现有注册流程的小改动。按规则，在你批准前我不会写任何代码。
    先确认两点：
    1) 用户名是否允许空格 / 中文？(A 不允许 / B 允许空格 / C 其他)
    2) 超界时报错文案由我拟一个，还是你用固定文案？
你：A。文案你拟。
AI：好。这是拟在对话内的简短设计，请过目：
    · 改 src/register/validate.ts，新增 validateUsername(name: string): boolean
    · 长度 [3, 20] 内返回 true；错误文案 "用户名需 3–20 位"
    · 通过一个导出函数暴露，供表单调用
    这段设计对吗？批准后我会开 worktree 分支并进入 TDD。
你：可以。
AI：（using-git-worktrees）已在 git@feature/user-length 分支开工，主分支不受影响。
    （TDD RED）先写测试——期望它先失败：

第四步：它真的会先写测试吗？

会，而且顺序不能颠倒：先写一条注定失败的测试，跑一遍确认"失败原因是功能不存在"，再写实现。

// validate.test.ts
import { describe, it, expect } from 'vitest'
import { validateUsername } from './validate'

describe('validateUsername', () => {
  it('rejects a name shorter than 3 chars', () => {
    expect(validateUsername('ab')).toBe(false)   // 此刻 validateUsername 还不存在 → 必然失败
  })
})

AI：（跑测试）红灯确认：失败原因是 "validateUsername is not a function"，正是预期的"功能缺失"。
    （TDD GREEN）写最小实现让它变绿：

// validate.ts
export function validateUsername(name: string): boolean {
  return name.length >= 3 && name.length <= 20
}

这里出现两个你会在全篇反复看到的词：RED 指"测试刚写好、还没实现，所以它必然失败"的那一步；GREEN 指"写了最小实现、测试刚通过"的那一步。它们中间还夹着一步强制动作：亲眼确认红灯的失败原因是对的——不是因为文件名打错、不是因为环境没装好。

第五步：收尾时它会问你什么？

AI：（跑全量测试）绿。补一条超界的测试再走一轮 RED→GREEN 后，
    请求独立评审……（requesting-code-review 报告无 Critical）
    （finishing-a-development-branch）测试全绿。接下来？
    1. Merge back to main locally
    2. Push and create a Pull Request
    3. Keep the branch as-is (I'll handle it later)
你：1。
AI：已合并，清理了 worktree。本次改动完成。

怎么判断"装成功了"？

判据只有一个：面对一条会改代码的指令，代理是先问 / 先设计 / 先测，而不是闷头就改。看到它开始"啰嗦"地走流程，就说明它已经装好了。想立刻把它关掉也很简单——从设置里停用该插件即可。

05七步工作流：一次改动是怎么被接力的

SP 把一次开发组织成一条"接力"：前一个技能交出的产物（批准过的设计、干净的分支、任务清单、绿测试）成为下一个技能的输入。下面按顺序讲清楚：每一步由哪个技能负责、交出什么、以及你作为人什么时候被要求介入。

七步分别由谁负责？

三份"接力文件"长什么样？

工作流里最容易被忽略的一点：每一步的成果多数要落成文件，而不是只留在对话里。这样即使换会话、换代理、上下文被压缩，接力也不会断。下面三份是最小形态（字段示意，路径与字段以官方和你所用工具为准）。

① 设计文档（brainstorming 走架构级路径时产出，存进仓库）：

# docs/superpowers/specs/2026-09-07-user-length-design.md
# 用户名长度校验 · 设计

## 目标与范围
给注册表单的用户名加 3–20 位长度校验，超界报错、不自动裁剪。

## 备选方案（带取舍）
- A. 在 validate.ts 加一个纯函数（推荐：无副作用、易测、表单与后端共用）
- B. 只在表单组件内联校验（不推荐：不可复用、难单测）
- C. 后端再做一次（本次不做，另行排期）

## 组件 / 数据流 / 错误处理 / 测试计划
（……每节讲完向人确认一次……）

② 实施计划（writing-plans 产出，给执行代理照做）：

## 任务 1：新增 validateUsername 纯函数（2–3 分钟）
- 文件：src/register/validate.ts
- 代码：导出 (name) => name.length >= 3 && name.length <= 20
- 验证：node 里单测覆盖 2/3/20/21 位四个输入

## 任务 2：接进注册表单（2–3 分钟）
- 文件：src/register/form.tsx
- 代码：调用 validateUsername，失败时展示文案 "用户名需 3–20 位"
- 验证：浏览器输入 "ab" 应看到报错

③ 进度台账（subagent 模式跨任务记账，防止代理"失忆"）。从 v6.2.0 起，台账不再是一份随手放的 plan-ledger.md，而是落在每份计划自己的工作区里：<仓库根>/.superpowers/sdd/<计划文件名>/progress.md（这个目录被 git 忽略，属于过程产物）：

# SDD ledger — plan: docs/superpowers/plans/user-length.md
- [x] 任务1 validate.ts 提交 a1b2c3d | 评审：PASS
- [x] 任务2 form.tsx    提交 e4f5g6h | 评审：1×Important（已修）→ 复评 PASS
- [x] 任务3 收尾测试     提交 i7j8k9l | 评审：PASS
Ruling: 第2轮 Important 级意见"文案应常量外置"裁定为可延后，记 Minor 待最终评审 — 理由：不影响行为 — 裁错的代价：多一次小改动

最后那行 Ruling: 是官方规定的记账格式：Ruling: <你决定了什么> — <为什么> — <裁错了要付什么代价>。它对应一条很硬的设计原则——"定夺，而不是卡住"（原文 "Rulings, not stalls"）。

为什么非要把东西写成文件？

官方在子代理技能里说得直白："Conversation memory does not survive compaction."——会话记忆扛不住上下文压缩。真实会话里出现过最贵的一种失败：控制器忘了自己进行到哪儿，把已经做完的整串任务重新派发了一遍。文件正是为这件事准备的：台账里记下的提交号在 git 里真实存在，哪怕你的上下文已经完全不记得创建过它们。上下文被压缩后，要相信台账和 git log，而不是自己的回忆。

这不是一条你必须从头走到尾的铁轨

七步是"默认的完整形态"，不是每次都全走一遍。常见的几种偏航都是正规用法：

• 改动极小且清楚：Brainstorming 的 bounded 路径（bounded = 有界，指对仓库里已有流程做范围清晰的小改动）会大幅压缩第①步，你可能在第③步之前就进入实现。
• 任务彼此独立、想并行：走 executing-plans 把一批任务交给并行子代理，或用 dispatching-parallel-agents。
• 需求已经很明确：可以直接 /write-plan，甚至直接说"按 TDD 实现 X"，技能会从命中的那一步接管。
• 纯探索 / 求证：走 brainstorming 的 spike（探针）路径——产出是一个结论或建议，不留下需要保留的代码。

"装了它 = 所有任务都被迫走七步"是误解吗？

是误解。它是按需命中：只有命中的技能才会被触发。测试驱动、修 Bug 前先复现、重大改动先设计——这些是"默认值"；而是否开新分支、是否派子代理，由当前改动的形态决定。真正会让你觉得"被流程绑住"的，通常是 Brainstorming 的盘问与独立评审——那正是它"用 token 换正确率"的地方，取舍见 13 节。

06动手之前，它为什么先跟你抬杠？

Brainstorming 是整个框架的"门卫"技能：新手最容易嫌它烦，老手最离不开它。它要解决的是一句很朴素的话——绝大多数"AI 做错了"，不是模型笨，而是它在实现一个没人确认过的假设。

它为什么叫 brainstorming，却不让你发散？

这个名字容易误导。它做的恰恰相反：收敛式地盘问。技能开头直接写死一条硬门禁（原文用 <HARD-GATE> 标签标出）：在你被告知"它打算怎么做"并且你点头之前，它不许调用任何实现类技能、不许写任何代码、不许搭任何脚手架。而且官方补了一句非常关键的话——"这份仪式感随任务缩放，批准门禁永不缩放"（the ceremony scales with the task; the approval gate never does）。

所以它有三个常见误解值得当场破掉：

• 它不是头脑风暴会议：不鼓励天马行空，而是把模糊想法压成一份可执行的设计。
• 它不是"写代码前的客套"：它产出的每一个问题、每一段设计，都在为"能不能少返工"服务。
• 它不是只有大项目才用：官方明确说，哪怕只是两句话的改动，也要先得到你明确的"可以"。

三条路径怎么选？

技能一开始会把你的请求归入三类之一，并且当众说出分类（这样你可以当场纠正）：

这里的 "有界"是按仓库判定的，不是按你的熟悉程度判定的。官方在红旗表里专门堵了这条借口："我熟这类应用，所以算有界"——"Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural."（有界衡量的是仓库，不是你的熟悉度；新项目没有"已存在的流程"，它是架构级。）

拿不准该走哪条路怎么办？

一次只问一个问题，实际对话是什么样？

它的问题节奏是：一次只问一个、能给选项就不开放、问的都是能改变设计的问题（范围、边界、界面取舍）。下面是一段示意盘问：

你：想给博客加一个"按标签筛选文章"的页面。
AI：（先归类）这是对现有页面结构的改动，我先按 architectural 处理还是 bounded？
    先问最影响范围的问题：这个筛选是
    A 只筛选"已发布"文章   B 也要筛草稿/定时文章   C 其他
你：A。
AI：好的。第二个问题——标签来源：A 文章自带标签字段（需要在编辑页维护）
    B 我选几个固定标签写死在配置里   C 其他
你：A。
AI：那第三个问题，UI：A 顶部一排标签点击切换   B 下拉选择   C 其他
你：A。
AI：清楚了。这轮先给方案草稿（约 150 字，覆盖列表页改造、URL 结构、空结果态、
    测试计划），每讲完一节我都会停下来问你"这部分对吗"……

注意这里的顺序很讲究：先归定路径，再问最影响范围的问题。它不是闲聊，是一台把"模糊愿望"压成"精确需求"的机器。另外，架构级路径还有两个细节：设计文档默认写到 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md（可以被你的偏好覆盖），写完它会先做一遍自查（扫占位符、查前后矛盾、查范围、查歧义），再请你评审文件——不是口头评审。

为什么"改一个常量"也要你点头？

因为门禁拦的不是"改动大小"，而是"未经确认的假设"。官方给出的理由值得原样记住："'Simple' tasks are where unexamined assumptions cause the most wasted work."（恰恰是"简单"任务里，没被检查的假设造成最多浪费。）

一个 10 行的校验，藏着的问题可能是："校验"到底是拦截还是提示？超界是报错还是自动裁剪？允不允许中文和空格？这些确认一次，抵得上返工十次。它还顺带解决了另一个问题：把设计拆成小节逐步确认，每段都短到你的注意力跟得上。

新手最容易踩的四个坑

07怎么把设计切成"换个代理也能照做"的小步？

设计批准后的下一棒，是把"要做什么"翻译成"具体怎么一步步做"。这一棒由 writing-plans 负责写计划，executing-plans 负责在别的会话里按批执行。

一份合格的计划里必须有哪四样东西？

官方对计划的定义有一句很妙的标准：计划要清楚到"一个热情但品味差、没判断力、不了解项目、还讨厌写测试的初级工程师"也能照着执行（原文：clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow）。为了达到这个效果，每个任务被刻意切成 2–5 分钟能做完的颗粒，并自带四样东西：

这样一份计划像施工图纸：工人（执行代理）不用再想"怎么设计"，只按图施工并报告每步结果。它同时让"评审"成为可能——人可以在几百行代码写出来之前，先审一份几十行的计划。

计划该写多细？一条能自检的标准

写计划之前先问自己哪三句话？

写计划这件事本身，就是一次"逼你把实现细节想明白"的脑力劳动。它往往比执行更有价值。

executing-plans 和子代理模式怎么选？

值得一提的是 executing-plans 自己的开场提醒：如果你的宿主支持子代理，就该改用 subagent 模式而不是它。所以它更像是"没有子代理能力时的退路"。

08为什么要一个小任务就换一个代理？

这是 SP 里最能体现工程质量观的一环：主代理不再一口气把整个计划写完，而是每个小任务派一个全新的"子代理"（subagent，由主代理派出去、只干一件事的独立代理）去实现，再派另一个子代理去评审。因为它有明确的"为什么"——

让一个代理从头写到尾，会出什么问题？

两个问题，都很硬：

• 上下文污染：官方原话 "Conversation memory does not survive compaction"（会话记忆扛不住上下文压缩）。让同一个代理连续写 20 个任务，它会把早期的决定"忘"掉、带着前面遗留的坏假设影响后面。
• 自评失效："自己写自己评"几乎必然自卖自夸。所以评审必须由另一个代理来做。

对策就是重置上下文：每个任务一个新代理，它眼里只有这份任务简报（brief）和代码库当前状态，不继承你的会话历史。

四步循环长什么样？

主代理 ──派发──> 实现子代理(sub-impl)
  简报：任务2 form.tsx 接入校验 + 报错文案，路径与代码见计划；写报告到 logs/task2.md
  子代理提交 e4f5g6h 后收工（上下文干净，眼里只有任务2）

主代理 ──派发──> 评审子代理(sub-review)   ← 独立于实现者
  输入：任务2简报 + 实现报告 + 待审 diff
  一级(规格)：实现是否符合任务要求？
  二级(质量)：代码质量如何？→ 报 1×Important："文案应抽成常量，便于表单和后端复用"

主代理：记台账 "任务2: 1×Important"。
  ↳ 修复轮1：让原实现子代理修（上下文还在）→ 提交 e9f0g1h → 针对性复评 → PASS
  ↳ 全部任务完成后：派"最强可用模型"做整分支最终评审，清掉台账里的 Minor 悬案

这里出现一个你在团队协作里也见过的词：diff，指"这次改动到底改了哪些行"的那份对照——评审子代理拿到的就是一份待审 diff，而不是整个代码库。

评审到底查什么？

每个任务后做两级评审，顺序不能反：

严重级别的分档是这套体系的通用语言：Critical（致命，阻塞交付，不修不能往前走）、Important（重要，应修，或明确记账延后）、Minor（轻微，风格命名可读性，记下即可，不当阻断）。

评审意见怎么修？

官方流程写得很具体，而且和很多人的直觉不同：

什么情况才允许它停下来问你？

只有四种，官方逐条列出：

• 遇到不可逆 / 破坏性操作（删数据、强制覆盖之类）；
• 遇到安全敏感动作；
• 涉及工作区之外的副作用（合并、推到共享分支、发布）；
• 计划烂到每条路都只能靠猜。

除此之外，冲突由主代理自行裁定并记入台账（原文 "Rulings, not stalls"——定夺而非卡住）。官方给的理由很有人味：一个错误的裁定，代价是你能看见、能撤掉的返工；而一个卡在问题上的会话，代价是你的一整天。真实案例里，有一次捐赠的会话在一个"控制器本可以自己决定"的问题上卡了将近九个小时。

进度记在哪个文件里？

记在该计划专属的工作区里。从 v6.2.0 起，每个计划有自己的目录，避免"上一份计划的台账被当成这一份的进度"（这种污染在真实使用里出现过）：

# 技能自带的脚本会打印这份计划的工作区路径
scripts/sdd-workspace docs/superpowers/plans/feature-plan.md
# → <仓库根>/.superpowers/sdd/feature-plan/   （被 git 忽略，存放台账、简报、报告、评审包）

# 台账第一行必须写清自己属于哪份计划
# SDD ledger — plan: docs/superpowers/plans/feature-plan.md

恢复规则也很明确：如果台账第一行写的是别的计划文件，那它是别人的进度，别动它，自己新建一份；如果同一份计划里已经有 Task <N>: complete 这一行，那这个任务已经做完了，不要重新派发。

什么任务可以打包给同一个子代理？

从 v6.3.0 起有一条明确的省钱的规则：小而同形的任务要打包。当计划里的一串任务都是"同一种小改动重复在不同文件"（同一处一行修复、同一个常量修改、同一个字段增补），不要一个任务派一个子代理——把每个文件和它的改动写进一份简报，交给一个子代理，把它的 diff 当一整块评审。反过来，"需要自己的判断、自己的测试、自己的评审面"的活，才保持一任务一派发。

三条反直觉但关键的约束

09TDD：唯一一条几乎不许讨价还价的规则

先解释这个词：TDD 是"测试驱动开发"（Test-Driven Development）的缩写。这里的"测试"指一段自动跑的检查代码——你给它输入，它替你判断结果对不对；"驱动"的意思是先写检查、再写实现，顺序不能反。在整个框架里，这是唯一一条几乎不允许松动的规则。

铁律原文是什么？

配套的另一句被反复引用："If you didn't watch the test fail, you don't know if it tests the right thing."（你没亲眼看着测试失败，就不知道它测的是不是对的东西。）另外还有一句总纲式的提醒："违反规则的字面，就是在违反规则的精神。"——这句话专门用来堵"我知道精神，但这个情况特殊"。

为什么"事后补测试"等于没测？

很多人以为 TDD = 写完代码再补个测试。恰恰相反，在那套规则眼里那是自欺欺人：代码已经写好，测试写出来必然秒过，一个没有失败过的测试什么都证明不了——你不知道它测的是你刚写的行为，还是它本来就通过的旧行为。真正的顺序是"用测试倒逼设计"：先写断言，接口的形状就被逼出来了。

红-绿-重构的每一步，具体要做什么？

一个完整的最小例子：从一条断言里"长"出实现

假设要"把字符串里的空白字符全删掉"。TDD 的走法是先只写断言，让接口形状先立起来：

// collapse.test.ts —— RED：此刻 collapseWhitespace 还不存在
import { it, expect } from 'vitest'
import { collapseWhitespace } from './collapse'

it('removes all whitespace', () => {
  expect(collapseWhitespace('a  b \t c')).toBe('abc')
})

跑一遍，确认它是因为"功能缺失"而红：

$ npm test
FAIL  collapse.test.ts
Error: Cannot find module './collapse'   ← 失败原因是"功能缺失"，正是想要的 RED

确认红灯原因正确后，写最小实现让它变绿——不要顺手加什么 trim、换行处理：

// collapse.ts —— GREEN：只做"能过这个测试"的事
export function collapseWhitespace(s: string): string {
  return s.replace(/\s/g, '')
}

$ npm test
PASS  collapse.test.ts   ← 绿。再加一条会失败的边界测试（如把换行也算空白），继续循环

然后才是 REFACTOR：绿着的时候改名、抽函数、去重。全程有一条红线：重构不许让测试变红，更不许在重构时夹带新功能。想加功能？回到 RED 再开一轮。

"写完代码才发现没写测试"怎么处理？

常见的五个借口，官方怎么回？

什么时候可以豁免？

10另外两条铁律：出 Bug 时怎么修，完工时怎么自证

TDD 不是唯一一条铁律。框架里还有两条，同样带"Iron Law"字样——它们分别管"修东西"和"宣布完成"两个最容易糊弄人的时刻。

为什么"改一行碰运气"是最贵的做法？

很多代理遇到 Bug 的行为是：猜一个原因 → 改一行 → 跑一下 → 没好再猜。SP 用 systematic-debugging（系统性调试）把这个过程格式化了。它要消灭的不是"直觉"，而是没有记号的瞎试：每次尝试都应该有一个可检验的假设、一条能复现的路径、一个明确的验证方法。

四阶段根因流程

同一个 Bug 修 3 次还不好，就该停手

两种修法对照

怎么逼代理在说"做完了"之前交出证据？

这条铁律来自 verification-before-completion（完工前验证）：

# 官方给的"门函数"（The Gate Function）：宣布任何状态之前先走完这五步
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

1. IDENTIFY: 哪条命令能证明这个说法？
2. RUN:      完整跑一遍（新跑的、完整的）
3. READ:     读全输出，看退出码，数失败数
4. VERIFY:   输出真的支持这个说法吗？
             - 不支持 → 只陈述实际状态 + 证据
             - 支持   → 连证据一起说
5. ONLY THEN: 才可以下结论

跳过任何一步 = 在撒谎，不是在验证

它有一句极为锋利的补充："如果你没有在这条消息里跑过验证命令，你就不能声称它通过了。"换句话说，"它应该没问题"不算数。你在评审代理交付时最有用的那句话就是："你凭什么说它好了？给我看证据。"

三条铁律的原文并列

# 1. 测试驱动（skills/test-driven-development/SKILL.md）
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

# 2. 系统性调试（skills/systematic-debugging/SKILL.md）
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

# 3. 完工前验证（skills/verification-before-completion/SKILL.md）
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

三条放一起看，你会发现它们其实是同一句话的三个时刻：开工前要确认（三条都要求"先有依据"）、动手时要有证据（测试/复现）、收工时要有证据（刚跑过的验证）。这就是"纪律而不是智力"的具体含义。

11隔离与收尾：为什么要给每个任务一间独立施工房？

两个技能配成一对：using-git-worktrees 负责在工作流早期建隔离工作区，finishing-a-development-branch 负责收尾。它们合起来保证一件事：主分支永远干净，乱糟糟的中间过程都发生在分支里。

worktree 到底是什么？

你平时用的 git branch 是在同一个目录里切换指针，切来切去目录里的文件跟着变。而 worktree（工作树）允许你把同一个仓库的不同分支同时检出到不同目录，互不干扰。通俗说就是：同一个项目，在两个文件夹里各摆一份，各自停在自己的分支上。

它和普通 git branch 差在哪？

技能本身还带着一套"先检测、别重复建"的步骤——它会先判断你是不是已经在一个隔离空间里，是的话就不该再建一层：

# 第一步：先检测当前是否已经在隔离工作区里
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)

# 子模块保护：GIT_DIR != GIT_COMMON 在 git 子模块里也成立，要先排掉
git rev-parse --show-superproject-working-tree 2>/dev/null

# 若 GIT_DIR != GIT_COMMON 且不是子模块 → 你已经在某个 worktree 里，跳过创建，直接做项目初始化

它的核心原则写得很克制：先检测现有隔离，再用宿主原生的 worktree 工具，最后才回退到手工 git 命令——不要跟宿主较劲。

收尾时它会给你哪几个选项？

任务全部完成、测试通过后，finishing-a-development-branch 会把选择摆到你面前。当前版本给的是三个选项：

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)

Which option?

如果你处在一个"分离头指针"（detached HEAD，指当前不在任何分支上、由外部工具托管的临时状态）的工作区里，选项减为两个——PR 或保留，因为这里没有"合并回哪条分支"可言。

选合并时，它的动作顺序也值得抄下来：先切回基础分支 → 拉取最新 → 合并 → 在合并结果上再跑一遍测试 → 绿了才清理 worktree、删掉功能分支。如果合并后的测试红了，就停下、把 worktree 和分支原地保留——因为还没推送，这次合并是本地的、可恢复的。

为什么"丢弃分支"被从菜单里拿掉了？

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

收尾会顺手删掉你没提交的文件吗？

v6.3.0 修掉了一个真实存在的坏行为：当 git worktree remove 因为"工作区里还有没提交的东西"而拒绝执行时，旧流程会伸手去拿 --force（强制删除）。现在它改成停下、把那些文件名字列出来、问你怎么办。这条修复值得单独讲，因为它是"纪律型工具也会犯错、而且错误会被写进发布说明"的一个例子——你在 18 节可以顺着官方 Release Notes 复核。

1214 个技能地图：谁在什么时候自动出手？

前面已经深入讲了几个重头技能。这一节给两张地图：一张是14 个技能分别管什么，一张是什么场景会自动触发哪个技能、你想绕开时能怎么办。最后一小段是可以直接抄的开场模板。

14 个技能分别管什么？

顺带说清两个相关的概念，你会在官方文档里反复看到：自动触发（官方叫 model-invoked）指代理面对某类任务时自己发现"有条规矩要遵守"并加载执行，不需要你敲命令；手动调用（user-invoked）指你用斜杠命令显式发起某个流程。设计意图是：高频的纪律（TDD、复现、评审）尽量自动，低频的、需要你拍板的阶段（澄清、计划）放在命令里，让你保有控制感。

自动触发和手动调用，怎么一眼分清？

什么场景会自动触发哪个技能？

最高频的命令有哪几条？

碰到"它没按流程走"，按这三步排查

可以直接抄的三段开场模板

不确定怎么开口？按你现在的处境挑一段，把方括号里的内容换成你的需求：

# 场景一：需求还模糊 → 让 brainstorming 来澄清
/brainstorm 我想做一个「你的功能一句话」，约束大致是……（欢迎先问我问题）

# 场景二：需求已清楚 → 直接要计划
/write-plan 实现「具体改动」。要求：先按 TDD 走，任务拆小、每步给验证方法。

# 场景三：已有一份计划要跑 → 交给子代理并要证据
请按 superpowers 流程执行这份计划；每个任务完成后独立评审，
并按 severity 汇报；不要自己给自己评审，完工前给出测试通过的证据。

这三段的作用是把"你想走哪条流程"说清楚，剩下的纪律交给技能执行。注意第三段里那句"不要自己给自己评审"——它是整套体系里最值钱的一句约束，见 08 节。另外那句 severity 就是"严重级别"的英文，也就是 08 节讲的那套 Critical / Important / Minor 分档。

13什么时候不该用这一套

这一节是整篇里最该细读的部分。SP 的默认值偏向"多走流程"，所以真正会让人吃亏的，不是"用得不够"，而是用得太重、用在不该用的地方。

哪三类任务不该上流程？

一句话总结判据：流程的价值随"改动规模 × 不可逆程度"上升。改动越小、越可逆，"先确认"这一步就越短——但它不归零。

什么信号说明"你过度用流程了"？

• 你发现自己为了避免它盘问，开始故意把需求写得含糊——那说明你在用它不擅长的方式跟它配合。正确做法是一次把目的、边界、验收标准喂足。
• 你被"每步点一次允许"打断到无法工作——那是权限没配好，见 03 节，不是流程本身的问题。
• 你在为一个"半年才用一次"的规矩写自动技能——见下面的"技能通货膨胀"。

什么时候不该写自己的技能？

写自定义技能是 SP 最有杠杆的一点（它教你用 TDD 的方式打磨技能本身），但技能写多了也是负担：每个自动触发的技能都在消耗上下文与判断力。出现下面这些信号时，先别写：

写一个团队技能长什么样？

如果一个技能确实值得写（高频、肉痛、能用一句话说清触发时机），它的形态极小——一个目录加一份 SKILL.md：

skill-name/
└── SKILL.md

# SKILL.md（示意，字段以你所用的宿主约定为准）
---
name: no-debug-prints
description: 在提交前，禁止把 console.log / print 调试输出留进代码。
  （代理准备提交代码时自动触发）
---

## 规则
- 扫描本批改动；发现遗留调试输出 → 删除后再提交。
- 若删除会影响功能（本意就是保留的日志），停下来问人类。
- 提交流水：清理 → 确认无残留 → 才允许 commit。

开头两行 --- 包起来的那段叫 frontmatter（文件头部的元信息），其中 description 就是"何时该用我"的触发描述——代理面对提交任务时会读到它、意识到"有条规矩要遵守"，于是照章办事。你的工程文化（不许提交调试输出、接口必须用某种命名、报错必须带错误码）都可以这样一条条变成技能。

还有一个反直觉但重要的判据：一个好的技能，标准是"换一个不知情的代理照着做，不会跑偏"。所以 writing-skills 主张用真实小任务去演练你的技能，观察它是否真的被触发、措辞是否有歧义——技能本身也要"测试"。它给的核心原则是："如果你没亲眼看着一个没有该技能的代理失败过，你就不知道这个技能教的是不是对的东西。"

14常见坑：八个真实症状

15常见问题

16术语速查表

这套体系里有不少英文黑话。第三列不是翻译，而是"它为什么重要 / 什么时候用 · 别当什么用"——目标是让你能把这些词放进自己的提示词和对话里。

17五天练习路线：从"装上"到"用得顺手"

别试图一次学会 14 个技能。给一条按天推进的路线，每一步都有明确的"做完算什么过关"。

如果你想把这套东西带给团队

个人的顺手，不等于团队的共识。要向别人推这套东西，最有效的不是发文档，而是先解决他自己最痛的那一次返工：找一条他刚被坑过的流程（"上次改完没测试就上线结果崩了"），演示"如果当时有这条纪律会怎样"。从单点痛点切入，比从"我们该用 SP"的全景提案容易落地得多。

团队层面再往前一步，就是把沉淀的技能文件纳入仓库、走代码评审——技能是文本，天然可 diff、可回滚、可署名。哪天你想改规矩，改的是能追溯到人的一次提交，而不是某个人脑子里的记忆。

18参考来源与证据边界

本文核对过的来源

• github.com/obra/superpowers —— 官方仓库 README：自我定位原话、各宿主安装命令、七步工作流、14 个技能清单、四条哲学、遥测说明、更新策略。
• skills/brainstorming/SKILL.md —— 三条路径（Spike / Bounded / Architectural）、批准硬门禁原文、"拿不准选更重那条"的棘轮规则、红旗表。
• skills/test-driven-development/SKILL.md —— 第一条铁律原文、"删掉重来"的零容忍条款、三类豁免、红绿重构细则。
• skills/systematic-debugging/SKILL.md —— 第二条铁律原文、四阶段根因流程、"修 3 次失败即质疑架构"的升级条款。
• skills/verification-before-completion/SKILL.md —— 第三条铁律原文与"门函数"五步。
• skills/subagent-driven-development/SKILL.md —— 每任务一个全新子代理、两级评审、修复轮 1–3 续用原代理 / 4–5 换更强模型、五轮熔断、"定夺而非卡住"与四种停止条件、台账工作区路径与恢复规则、小任务打包派发、禁止嵌套派生子代理。
• skills/finishing-a-development-branch/SKILL.md —— 三步选项菜单原文、合并后先跑测试再清理的顺序、丢弃只在你明确要求时出现。
• skills/using-git-worktrees/SKILL.md —— 先检测既有隔离、子模块保护、"不跟宿主较劲"原则。
• RELEASE-NOTES.md —— v6.2.0（2026-07-23）与 v6.3.0（2026-08-12）的变更：计划作用域工作区、五轮熔断、菜单里删掉"丢弃"、worktree 强制删除的修复、小任务打包、禁止嵌套派生。
• GitHub 仓库 API —— 版本与热度数字的抓取口径（见下）。

哪些数字是我实际抓到的

抓取方式是 GitHub 公开 API 的两个端点：api.github.com/repos/obra/superpowers（仓库元信息与 star 数）和 api.github.com/repos/obra/superpowers/releases（版本与发布日期）。你可以自己再跑一遍对照——这也是"热度数字只能当量级参考"的原因：它会持续变化。

证据边界与时效

99一句话总结