Agent 方法论框架 superpowers 的七步工作流拆解
本文基于 superpowers 仓库 commit 44c9b2d（2026-07-27）梳理，该项目仍在持续迭代，具体行为以仓库 https://github.com/obra/superpowers 最新代码与文档为准。
superpowers 的七步不是七条建议，而是一条产物链：每一步的交付物就是下一步唯一的输入。 头脑风暴交出一份提交进 git 的设计文档，计划这一步只读设计文档；计划交出一份带精确文件路径和完整代码的任务清单，执行这一步只读任务清单里被切出来的那一段。你跳过中间某一步，下一步不是”少一道手续”，而是没有可读的文件——它只能靠猜，而猜出来的东西没人复审。理解这条链，比记住七个技能名字有用得多。
这篇讲的是一个具体项目怎么把方法论落成可执行的文件和脚本。站内的 规格驱动开发（SDD）是什么 讲的是”先写规格再写代码”这套通用范式，从 vibe coding 到工程化 讲的是随手让 AI 写代码为什么撑不住工程规模——那两篇给的是判断框架，本篇给的是一个能当场打开对照的实现样本：文件在哪、脚本叫什么、哪一步卡住会退回哪一步。
一、先看清这条链的形状
superpowers 自己在 README 的「The Basic Workflow」里把流程列成七项：brainstorming、using-git-worktrees、writing-plans、subagent-driven-development 或 executing-plans、test-driven-development、requesting-code-review、finishing-a-development-branch。仓库的 skills/ 目录下一共有 14 个技能目录，除了这七步涉及的，还有 systematic-debugging、verification-before-completion、dispatching-parallel-agents、receiving-code-review、writing-skills、using-superpowers。
这里有个容易看漏的点：这七项不是并列的功能菜单，而是有明确交接协议的流水线。brainstorming 的 SKILL.md 里写死了终点——“The terminal state is invoking writing-plans”，并且明确禁止在头脑风暴之后去调 frontend-design、mcp-builder 或任何其他实现类技能。也就是说，这一步的出口只有一个。同样，writing-plans 的末尾是一个二选一的交接：走 subagent-driven-development，还是走 executing-plans。executing-plans 的最后一步则强制交给 finishing-a-development-branch。
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| brainstorming | 把模糊想法问成设计文档，分段拿到你的确认 | skills/brainstorming/SKILL.md | 你刚说完”我想做个 X” |
| 可视化伴侣 | 需要看图才说得清时才临时提供的浏览器界面 | skills/brainstorming/visual-companion.md | Agent 单独发一条消息问你要不要开 |
| using-git-worktrees | 确认或创建隔离工作区，跑安装、验基线测试 | skills/using-git-worktrees/SKILL.md | 设计通过之后、动代码之前 |
| writing-plans | 把设计拆成 2-5 分钟一步的任务，带完整代码 | skills/writing-plans/SKILL.md | 你说”计划写一下” |
| subagent-driven-development | 每个任务派一个新 Agent 实现，逐任务复审 | skills/subagent-driven-development/SKILL.md | 你选了推荐的那条执行路线 |
| 三个执行脚本 | 定工作区目录、切任务简报、生成复审包 | skills/subagent-driven-development/scripts/ | 执行阶段每个任务都要跑 |
| executing-plans | 不派 Agent，在当前会话里按批执行、人来卡点 | skills/executing-plans/SKILL.md | 你的工具链没有子 Agent 能力 |
| test-driven-development | 红绿重构，测试没先失败过就删代码重来 | skills/test-driven-development/SKILL.md | 实现阶段每写一行生产代码 |
| finishing-a-development-branch | 验全量测试，然后给出合并/PR/保留三选一 | skills/finishing-a-development-branch/SKILL.md | 所有任务做完之后 |
表里这些路径都是真实存在的，你 clone 下来就能一个个打开对照着读。下面按顺序拆。
二、前两关：设计闸门和工作区隔离
这两关解决的问题是同一个：防止不可逆的动作发生在没人点头之前。
brainstorming 的 SKILL.md 里有一段用 <HARD-GATE> 标签框起来的硬约束，意思是在把设计呈现给你、并且你批准之前，不许调用任何实现类技能、不许写代码、不许搭项目脚手架，而且这条对每个项目生效，不管它看上去多简单。紧跟着有一节专门叫「Anti-Pattern: This Is Too Simple To Need A Design」，把”这个太简单了不用设计”点名为反模式——理由是简单项目恰恰是未经检验的假设最容易造成返工的地方。设计可以很短（真正简单的项目几句话就行），但必须呈现、必须拿到确认。
这一步的具体做法是九项检查清单：先探项目现状（看文件、看文档、看最近的提交），然后一次只问一个问题（文档强调 one question per message），接着提 2-3 个方案带取舍和推荐，再把设计按复杂度分段呈现——简单的几句话，复杂的最多 200-300 字，每段问一次”这样对吗”。确认之后写设计文档到 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 并提交进 git，然后做一遍自查（扫占位符、查前后矛盾、查范围是否需要拆分、查有没有能被两种理解的需求），最后再请你复审这个文件。
这里有个细节值得单独说：设计文档是被 commit 进 git 的，不是留在对话里的。这是整条链能扛住上下文丢失的地基——对话会被压缩，文件不会。
第二关是工作区。using-git-worktrees 的第 0 步不是创建，而是检测：比对 git rev-parse --git-dir 和 git rev-parse --git-common-dir，两者不同说明已经在一个链接工作树里，直接跳到项目安装那步，不要再套一层。文档还加了个子模块守卫——在 git submodule 里这两个值同样会不相等，所以要用 git rev-parse --show-superproject-working-tree 排除掉。创建时优先用你的工具链自带的工作树能力（文档举的例子就是 EnterWorktree 这类工具），没有才退回 git worktree add；用 git 手搓时必须先跑 git check-ignore 确认目录被忽略，没被忽略就先加进 .gitignore 并提交。默认目录是项目根下的 .worktrees/。这一关的最后一步是跑一遍测试确认基线是干净的——基线脏了，后面每一次失败都说不清是谁造成的。
对你意味着什么：如果你习惯直接在 master 上让 Agent 改，这两关会显得很烦。但它们换来的是——任何一次”这个方向不对”，你损失的只是一个分支和几段对话，不是主干。
三、计划这一步为什么写得像给新人的操作手册
writing-plans 开篇给了一个很直白的读者假设：假设执行这份计划的工程师对代码库零上下文、品味存疑；他是熟练开发者，但几乎不了解你的工具链和问题域，也不太懂怎么设计测试。README 里那句更狠——计划要清楚到”一个热情但品味差、没判断力、没项目上下文、还讨厌写测试的初级工程师”也能照着做。
这个假设直接决定了计划的写法。任务粒度定在 2-5 分钟一步：“写失败的测试”是一步，“跑一下确认它失败”是一步，“写最小实现”是一步，“跑测试确认通过”是一步，“提交”是一步。每个任务开头要列出 Files（Create / Modify / Test，路径精确到行号范围）和 Interfaces（Consumes 写从前面任务拿什么，Produces 写后面任务依赖什么，都要写精确签名）——文档解释了 Interfaces 存在的原因：任务的实现者只看得到自己那一个任务，这个块是他了解相邻任务用了什么名字和类型的唯一途径。
然后是一节叫「No Placeholders」的禁令清单，里面列的东西被直接定性为”计划失败”：TBD、TODO、“稍后实现”；“加上适当的错误处理”、“加上校验”、“处理边界情况”；“给上面写测试”（没有实际测试代码）；“和任务 N 类似”（要求把代码重复写一遍，因为工程师可能乱序读）；只说做什么不说怎么做的步骤；引用了任何任务都没定义过的类型或函数。
计划写完还有一遍自查，三项：逐条对照规格看有没有需求没落到任务上；扫一遍上面那些占位符红旗；查类型一致性——文档给的例子是任务 3 里叫 clearLayers()、任务 7 里写成 clearFullLayers()，这就是个 bug。
计划文档的头部是强制格式，必须有 Goal、Architecture、Tech Stack，还有一节 Global Constraints，要求把规格里的项目级约束（版本下限、依赖限制、命名和文案规则、平台要求）一行一条、原值照抄地列进去，每个任务的要求都隐含包含这一节。
对你意味着什么：这一步是整条链里最费 token 也最容易被你嫌啰嗦的一步。但它是执行阶段能”每个任务派一个空白 Agent”的前提——空白 Agent 之所以能干活，全靠计划里那些完整代码和精确签名。计划写虚了，执行阶段就会退化成一堆各自猜测的并行会话。
四、执行与收尾：四种状态、五轮上限、三个选项
执行有两条路。executing-plans 是简单那条：读计划、批判性地过一遍、有疑虑先提出来、然后按步骤执行、跑验证。它的 SKILL.md 里有一句挺诚实的提示——建议你告诉人类伙伴，superpowers 在有子 Agent 能力的环境里效果好得多，如果有，就改用 subagent-driven-development。它还写明了什么时候必须停：撞到阻塞、计划有致命缺口、看不懂某条指令、验证反复失败——问，别猜。
subagent-driven-development 是复杂那条，也是文档推荐的默认路线。核心是每个任务派一个全新的实现 Agent，做完立刻派一个复审 Agent 过两个维度（规格符合性 + 代码质量），最后再对整个分支做一次广度复审。关于这种派发模式本身，站内 Claude Code 的 subagent 怎么用 有更基础的铺垫。
这一步里有几个设计得很具体的机制：
台账。 文档明说会话记忆扛不过压缩，并且记了一个真实教训：丢了位置的控制方会把已经完成的整段任务序列重新派发一遍，这是观察到的最贵的失败。所以进度记在文件里，不只记在待办里。每份计划有自己的工作区目录 <repo-root>/.superpowers/sdd/<plan-basename>/，由 scripts/sdd-workspace 脚本打印路径；台账在 <workspace>/progress.md，第一行必须写自己的身份 # SDD ledger — plan: <plan file path>。别的计划的目录不归你读写。文档还提醒 git clean -fdx 会把这个目录清掉（它是被 git 忽略的临时空间），真清了就靠 git log 恢复。
交接靠文件，不靠粘贴。 派发实现 Agent 之前跑 scripts/task-brief PLAN_FILE N 把那一个任务的完整文本切成一个独立文件，派发提示词里给的是这个文件的路径，而不是整份计划——文档明确写着”Never make a subagent read the whole plan file”。复审同理：跑 scripts/review-package PLAN_FILE BASE HEAD 生成一个包含提交列表、diff 统计和带上下文 diff 的文件，把路径给复审 Agent。理由写得很直白：你粘进派发提示词的东西、和子 Agent 打印回来的东西，都会常驻你自己的上下文并在之后每一轮被重读。文档举了个真实的反面例子——某次派发提示词到了 42k 字符，其中 99% 是粘贴进去的历史。这类中间产物怎么落盘，站内 Agent 中间产物落盘 单独讲过。
四种回报状态。 实现 Agent 只能回四种之一：DONE（生成复审包，派复审）、DONE_WITH_CONCERNS（完成但有疑虑，先读疑虑，涉及正确性或范围的先处理再复审）、NEEDS_CONTEXT（缺信息，补上下文重派）、BLOCKED（做不下去，分四种情况处置：上下文问题就补上下文同模型重派、需要更强推理就换更强模型、任务太大就拆、计划本身错了就上报人类）。文档特别写了一句：绝不忽略上报，也绝不让同一个模型原样重试。
五轮上限的修复循环。 复审报了规格不符、或者任何 Critical / Important 级别的发现，就进循环。一轮 = 一次修复派发 + 一次限定范围的重审，每个任务最多五轮。1-3 轮唤回原来那个实现 Agent（它的上下文还在，知道自己当初为什么那么写）；4-5 轮换一个全新的实现 Agent、并且用比卡住那个高至少一档的模型，还要告诉它”前面有人试过 N 次，现在归你，报告文件里有试过什么”。文档给的判断是：连着三次唤回都没收敛，通常说明这个 Agent 看不见自己的问题，换人加换档一起做。Minor 级别的发现不进循环，记进台账留给最终复审去分诊——文档管”没人读的汇总”叫静默丢弃。计划本身规定的东西被复审判为缺陷时，不是 Agent 拍板，要把发现和计划原文一起摆给人来定谁说了算，这类人机交接可参考 Agent 流程里的 human-in-the-loop。跑满五轮还有未决发现就触发断路器：要么带裁决意见记进台账留档，要么——如果这个问题是承重的（后面任务要建在它上面，或者它暴露了计划缺陷）——直接停下来上报 BLOCKED。
模型选择是显式的。 文档要求派发时必须写明模型，因为省略会继承会话模型（通常是最贵那个），等于把这一节架空。同时给了个反直觉的判断：轮次数比 token 单价更决定成本，最便宜的模型在多步任务上常花 2-3 倍轮次，反而更贵，所以复审和”从散文描述干活”的实现者用中档打底；只有当任务文本里已经写好了完整代码、实现等于誊抄加跑测试时，才用最便宜那档。
收尾。 finishing-a-development-branch 先跑一遍项目全量测试，失败就报出来停住——菜单只在测试全绿之后出现。然后检测环境：普通仓库和具名分支的工作树给三个选项（本地合并回基线分支 / 推送并建 PR / 保持现状），detached HEAD 状态只给两个（没有本地合并）。文档要求菜单原样呈现，选哪个是人类的决定。丢弃工作这条路只在你明确要求时才存在，而且要你手打 discard 这个词才算确认。这条链上贯穿始终的一句话是：合并进错的基线分支，撤销代价很大，所以分叉点不确定就问。
五、边界与代价
这套东西不是没有成本的，仓库自己也没打算藏。
它会让开发变慢，而且是设计如此。 一个”给按钮换个颜色”的改动，按这条链走要经历设计呈现、你点头、写设计文档并提交、你复审文件、建工作区、跑基线测试、写计划、计划自查、派实现、派复审、跑收尾菜单。brainstorming 里那条反模式条款堵死了”这个太简单了”这个出口。所以对真正的小改动，这是过度设计——你得自己判断什么时候整套走、什么时候只借用其中一两个技能。
它会让 Agent 变啰嗦。 每个技能开头都要求”宣告”自己正在用哪个技能，计划要求把代码完整写两遍而不是写”同任务 N”，派发前后要生成简报文件和复审包文件。这些都是可读性和可恢复性的代价，不是白拿的。
它换取可恢复性的方式是产生大量中间文件。 设计文档、计划文档进 git；简报、报告、复审包、台账落在被忽略的 .superpowers/sdd/<plan-basename>/ 目录里。最终复审干净之后这个目录会被删掉，理由是 git 历史已经是记录了。但过程中它是实打实占磁盘和占注意力的。
它明确不管的事。 这套流程不替你做技术选型的对错判断——2-3 个方案的取舍是摆给你选的。它不保证生成的代码正确，只保证每段代码都过了一次独立复审和一次红绿测试。它也不管部署、不管发布、不管线上运维：链条终点是合并或者建 PR，之后的事不在里面。跨仓库、跨服务的协调也不在范围内——brainstorming 遇到”一个平台带聊天、存储、计费、分析”这种请求时，做法是先拆成子项目，每个子项目各走一遍完整的规格到计划到实现，而不是一份规格吃下全部。
依赖前提。 推荐路线要求你的工具链有子 Agent 能力；没有的话只能走 executing-plans，收益按文档自己的说法会明显下降。TDD 那条铁律（生产代码之前必须有一个失败过的测试）在没有可运行测试框架的项目里也很难落地。
另外一个和技术无关但该知道的事实：README 写明 brainstorming 的可选可视化伴侣功能默认会从项目方网站加载一个 logo，其中带上所用的 superpowers 版本，用来粗略估计使用量；设置环境变量 SUPERPOWERS_DISABLE_TELEMETRY 为任意真值可以关掉，它也遵从 DISABLE_TELEMETRY 和 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 这两个开关。项目采用 MIT 许可证。
六、上手与避坑清单
别把七步当七个可选功能挑着用。 会踩是因为技能名字看起来像独立工具，你很自然会想”我只要 writing-plans”。但计划的质量取决于设计文档的质量，而设计文档是 brainstorming 那九步问出来的。避法：要么整条走，要么明确知道自己在手工补齐上游产物——比如你自己写好规格文件，再从 writing-plans 接入。
别在 master 上直接开跑。 会踩是因为工作树那一步看着像”环境准备”，容易顺手跳过。executing-plans 和 subagent-driven-development 两处都写了同一句：未经人类明确同意，绝不在 main/master 上开始实现。避法：把第 0 步的两条 git rev-parse 检测当成必跑项，确认自己到底在不在隔离工作区里。
别用 HEAD~1 当复审的起点。 会踩是因为”复审上一个提交”听起来天经地义。但一个任务可能产生多个提交，用 HEAD~1 会静默地只看到最后一个，前面的改动没人审过就过关了。避法：派实现 Agent 之前先跑 git rev-parse HEAD 记下 BASE，复审包用这个 BASE。
别在派发提示词里预先给复审定调。 会踩是因为你觉得某个发现肯定是误报，想省一轮循环。文档把这条单列出来，还给了自查信号：如果你正在写的提示词里出现了”不要标记这个”、“别把 X 当缺陷”、“最多算 Minor”、“计划就是这么定的”，就停——你在预判，而且通常是为了给自己省一轮。避法：让复审照常提，你在循环里裁决，裁决要写进台账。
别自己动手改复审提出的问题。 会踩是因为”就一行，我顺手改了比派发快”。但控制方自己改有两个后果：污染你的协调上下文，以及这个修改没经过复审。避法：唤回原实现 Agent，把发现原样发过去。
别把累积的历史粘进后续派发。 会踩是因为你担心新 Agent 不知道前面发生了什么。文档的判断是：一个新 Agent 需要的只有它自己的任务、它碰到的接口、以及全局约束，别的都不要。避法：用 scripts/task-brief 切简报，派发提示词里只写五样东西——这个任务在项目里的位置一句话、简报路径、前置任务定下的接口和决策、你对简报里歧义的裁定、报告文件路径和回报格式。
别让”任务完成”这句话没有台账支撑。 会踩是因为长会话被压缩后，你的记忆和实际提交对不上。避法：每个任务完成时按格式往台账追加一行（完成的提交范围、复审是否干净、有几条被留档），压缩之后信台账和 git log，不信自己的印象。
装的时候按工具链分别装。 README 写明安装方式因宿主而异，同时用多个宿主就要各装一遍——这一条纯属机械操作，但漏了会出现”我明明装过了”的困惑。
收束
真要用这套东西，先按这个顺序读四个文件：README.md 看整条链的形状，skills/brainstorming/SKILL.md 看第一道闸门怎么卡的，skills/writing-plans/SKILL.md 看它对”一份能被陌生人执行的计划”的定义，skills/subagent-driven-development/SKILL.md 看台账、五轮上限和断路器这三样机制——最后这个文件是整个仓库里工程密度最高的一份，它的「Common Rationalizations」表格逐条列了执行时最容易给自己找的借口和对应的反驳，值得单独读一遍。
自检三问：我这次的改动，值得走完整条链吗？如果不值得，我准备手工补上哪些上游产物？如果值得，我的项目有没有一个能跑起来、且当前是全绿的测试套件——没有的话，链条中间那几道靠测试撑着的关卡是虚的，走完也只是走了个形式。
本文属于 superpowers 方法论专题（共 30 篇，含三篇与其它开源 Agent 项目的对照）。想看把资产铺满的另一种取向，见 ECC 开源 Agent 套件专题。