Agent 方法论框架 superpowers：先问再动手治哪类翻车
本文基于 superpowers 仓库 commit 44c9b2d（2026-07-27）梳理，该项目仍在持续迭代，具体行为以仓库 https://github.com/obra/superpowers 最新代码与文档为准。
编码 Agent 最贵的翻车，不是把代码写错，而是把一个你根本没要的东西写对了。 这类事故的共同特征是：过程看着极其顺畅，Agent 没报错、测试还绿着、提交信息也写得漂亮，你打开一看，它按自己脑补的那个需求做了三百行。superpowers 里的 brainstorming 技能，整套设计就是冲着这一类翻车去的——它不管你代码写得好不好，只管在动键盘之前把「我以为你要的」和「你实际要的」这条缝焊死。
superpowers 是 Jesse Vincent 的开源项目（MIT 许可证，仓库地址 https://github.com/obra/superpowers ），skills/ 目录下放了十几个技能，brainstorming 是其中被标记为「任何创作性工作之前必须用」的那一个。下面按你能跟着走的顺序拆：它挡的是什么、它怎么挡、代价是什么。
一、它挡的是哪一类翻车
打开 skills/brainstorming/SKILL.md，最扎眼的是文件开头那段用尖括号标签框起来的硬门禁：
<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any
implementation action until you have presented a design and the user has approved it.
This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>
注意最后半句：适用于每一个项目，不管它看起来多简单。紧接着的一节标题干脆就叫「反模式：这个太简单了不需要设计」，正文给出的理由是：待办清单、单函数小工具、改个配置，全都要走这套流程，因为「简单」项目恰恰是未经检验的假设造成最多返工的地方。文档同时留了台阶——设计本身可以很短，真正简单的项目写几句话就行，但你必须把它拿出来、必须拿到批准。
这个取舍值得琢磨。大多数团队的规范会写「重要改动需要评审」，然后所有人开始争论什么叫重要。brainstorming 的做法是取消这个判断题：门槛恒定为「全部」，弹性放在产出的长度上。对 Agent 这类会主动为自己找豁免理由的执行体来说，「按复杂度决定要不要走流程」等于给它留了一个每次都能用的后门，而「一律走，但可以很短」堵掉了这个后门。
同一个仓库的 skills/using-superpowers/SKILL.md 里有张「危险信号」表，把 Agent 会给自己找的借口逐条列出来当成停止信号，比如「这只是个简单问题」「我得先了解上下文」「这个技能有点小题大做」，右边一列全是驳回。两个文件放一起看，意图很清楚：设计门禁的人非常清楚被约束的对象会试图讲道理绕过去。
二、它怎么问：一次一个问题
同样是「先澄清需求」，落到实处最容易变形的地方是提问方式。SKILL.md 在「理解想法」一节里给的约束相当具体：
- 先看当前项目状态（文件、文档、最近的提交），不是上来就问；
- 问详细问题之前先评估规模，如果请求里描述了多个互相独立的子系统，立刻指出来，不要在一个本该先拆解的项目上消耗提问次数；
- 项目太大就帮用户拆成子项目，理清哪些是独立的、彼此什么关系、什么顺序建，然后只对第一个子项目走正常设计流程，每个子项目各自走一遍规格到计划到实现；
- 规模合适的项目，一次问一个问题来打磨想法；
- 能用选择题就用选择题，开放式提问也可以；
- 每条消息只放一个问题，一个话题需要展开就拆成多个问题；
- 提问聚焦在三件事：目的、约束、成功标准。
「每条消息只放一个问题」这条看着琐碎，实际是整套流程里最省你时间的一条。你大概经历过这种场面：Agent 一口气抛来七个问题，你挑了两个认真答，剩下五个含糊带过或者干脆没看见，Agent 把沉默当成默认值填进设计里。一次一问把「答案缺失」变成显式状态——问题没答，流程就停在那儿，不会有静默默认值溜进规格。
问完之后是提方案：给出 2 到 3 个不同的方案并附上取舍，用对话的方式呈现，把推荐的那个放在最前面并解释理由。文档在这里还塞了一句相当克制的要求——对每个方案和设计都要「无情地」按 YAGNI 砍掉不必要的功能。这句话的作用是防止 Agent 把「多给几个方案」演成「多给几套镀金方案」。
然后才是呈现设计：按复杂度决定每一节的篇幅，直白的部分几句话，有讲究的部分最多两三百词；每讲完一节就问一句「到这儿看着对吗」；覆盖的范围是架构、组件、数据流、错误处理、测试；发现哪儿说不通就退回去重新澄清。分节确认这一手同样是为了控制返工半径——设计写完两千字再整体挨枪毙，和第一节就被拦下来，重写成本差一个数量级。
站内的 AI 帮你理需求 和 AI 做方案设计 讲的是通用方法论——怎么组织提问、怎么把想法收敛成方案；这篇讲的是一个具体开源项目怎么把同一件事固化成可执行的流程文件：哪一步不许跳、产物写到哪个路径、卡在哪里等人。方法论告诉你该做什么，这套技能告诉你 Agent 每一步允许做什么。
三、设计之后：规格文档、自查、人工闸门
设计被批准不等于结束。SKILL.md 的清单要求 Agent 为九个步骤各建一个任务并按顺序完成，后半段全是文档和审查：
- 探索项目上下文
- 在合适时机按需提供视觉伴侣（不是一上来就提）
- 一次一个问澄清问题
- 提 2 到 3 个方案
- 分节呈现设计，每节拿批准
- 写设计文档，保存到
docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md并提交 - 规格自查
- 用户复核已写好的规格文件
- 转入实现，调用 writing-plans 技能
第 7 步的自查是四项固定检查：占位符扫描（有没有 TBD、TODO、没写完的段落、含糊的需求）、内部一致性（各节是否互相矛盾，架构和功能描述对不对得上）、范围检查（是否聚焦到能用一份实现计划覆盖，还是需要拆解）、歧义检查（有没有需求能被读出两种意思，有就挑一种写明确）。文档特意加了一句：发现问题就地改掉，不用再审一遍，改完往下走。
第 8 步是人工闸门，连话术都写好了：
"Spec written and committed to `<path>`. Please review it and let me know if you want to
make any changes before we start writing out the implementation plan."
然后等用户回应。要求改就改，改完重跑规格审查，只有用户认可才继续。
同目录下还有一份 spec-document-reviewer-prompt.md，是派子代理去审规格文档时用的提示词模板。它的检查项被列成一张表：完整性、一致性、清晰度（需求是否含糊到会让人做错东西）、范围（是否聚焦到一份计划、有没有跨多个独立子系统）、YAGNI（有没有没人要求的功能和过度设计）。这份模板里最值得抄走的其实是「校准」那一段：只报会在实现规划阶段造成真实问题的事——缺一整节、自相矛盾、歧义到能读出两种意思，这些算问题；措辞微调、风格偏好、「某几节写得没别的节详细」不算。除非存在会导致计划出错的严重缺口，否则一律批准。审查者的输出格式也被钉死：状态是「Approved」或「Issues Found」，问题按「哪一节 + 具体问题 + 为什么影响规划」写，建议单列且明确不作为拦截理由。
写过评审规则的人应该能体会这段校准的分量。没有校准的审查者会退化成挑刺机器，把「建议补充更多细节」当成阻塞项，于是流程卡死、人开始绕过审查。给审查者划出「什么不算问题」，比列举「什么算问题」更能让它跑得长久。相关的判断可以对照 AI 评审的介入时机 一起看。
流程的终点被写得毫无余地：终态是调用 writing-plans。SKILL.md 明确写了不要调用 frontend-design、mcp-builder 或任何其他实现类技能，brainstorming 之后唯一能调用的技能就是 writing-plans。这条约束防的是一种很常见的滑坡——Agent 聊到兴头上顺手就开始搭脚手架，而此时规格还没人看过。
四、这套东西由哪几块组成
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| brainstorming 技能正文 | 硬门禁、九步清单、提问与呈现设计的规则、流程图 | skills/brainstorming/SKILL.md | 每次让 Agent 做新功能、改行为时的第一步 |
| 规格审查提示词模板 | 派审查者复核规格文档的检查表、校准原则、输出格式 | skills/brainstorming/spec-document-reviewer-prompt.md | 规格写完、进入计划阶段之前 |
| 视觉伴侣指南 | 什么时候该用浏览器展示、什么时候该留在终端 | skills/brainstorming/visual-companion.md | 遇到布局、线框、架构图这类看比说更清楚的问题 |
| 视觉伴侣的服务脚本 | 起停本地服务、页面框架模板与前端辅助脚本 | skills/brainstorming/scripts/（含 start-server.sh、stop-server.sh、server.cjs、helper.js、frame-template.html） | 你同意开视觉伴侣之后 |
| 下游的计划技能 | 把规格拆成带测试节奏的小步任务，产物写到 docs/superpowers/plans/ | skills/writing-plans/SKILL.md | 规格被你认可之后的唯一下一步 |
| 技能调用总则 | 规定「相关技能必须在任何回应之前调用」，并列出常见的自我开脱说辞 | skills/using-superpowers/SKILL.md | 会话一开始，决定 brainstorming 会不会被触发 |
| 规格产物目录约定 | 设计文档的默认落盘路径与命名 | docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md | 每次流程走到第 6 步 |
视觉伴侣这块单独说一句，因为它的设计取向很典型。SKILL.md 强调它是工具而不是模式：不要一开始就提，等到第一次真的出现「画出来比说出来清楚」的问题时再提，而且这个提议必须单独占一条消息，里面不许夹带别的问题或总结；用户接受之后也要逐个问题判断走浏览器还是走终端。判定标准写得很直白——一个关于 UI 话题的问题不等于视觉问题，「这个语境下所谓个性指什么」是概念问题走终端，「哪种向导布局更合适」是视觉问题走浏览器。展开的 visual-companion.md 里还提到，本地服务返回的 URL 自带会话密钥，缺了密钥的请求会被服务端拒绝，所以要把完整 URL 原样交给用户，不能只给主机和端口。这些细节的共同点是：把「什么时候该用某个能力」写得比「这个能力有什么功能」更详细。
五、边界与代价：它放弃了什么
这套流程有明确的代价，用之前得认。
它让开发变慢，而且是故意的。 九步清单里有两处等人：设计分节确认、规格写完等你看。你不在电脑前，流程就停着。它换来的是返工减少，但对「今晚就要看到东西」的场景，这个交换不划算。
对小改动是过度设计。 文档自己也承认设计可以短到几句话，但流程步数不变——依然要探索上下文、依然要提方案、依然要写文档并提交、依然要等你复核。改个文案、调个超时值、加个日志，走完这一整套的开销远大于收益。仓库把这条定成硬规则是有它的理由（防 Agent 自我豁免），但你作为使用者要清楚，规则的严格程度和你的实际收益不是一回事。
Agent 会变啰嗦。 一次一个问题意味着轮次变多，你要花更多次交互才能到达同一个终点，上下文窗口的消耗也随之上升；SKILL.md 给 Agent 写好的那句提议话术里，自己就带着一句提醒——这东西还很新，而且「可能相当耗 token」。想控制这部分开销可以对照 上下文预算怎么定 的思路。
它明确不管的事。 这套技能不碰代码质量、不做技术选型的对错判断、不验证你的需求在商业上是否成立、也不保证生成的规格是对的——规格自查只查占位符、矛盾、范围和歧义这四类形式问题，一份逻辑自洽但方向错误的规格照样能通过。测试怎么写、代码怎么落地是 writing-plans 和测试驱动开发那几个技能的事。别指望它兜底。
它假设有一个能拍板的人。 两处闸门都在等人类批准。你要是想搭一条全自动流水线，这套流程的形状根本对不上——它的价值恰恰来自「有人会说不」。这类取舍在 人在环中怎么设计 里有更系统的展开。
六、上手与避坑清单
先读三个文件再谈用不用。 会踩的坑是：看到技能名字就以为自己懂了，结果 Agent 跑起来的行为和你预期完全不同。避法是按顺序读 skills/using-superpowers/SKILL.md（决定技能什么时候被触发）、skills/brainstorming/SKILL.md（主流程）、skills/brainstorming/spec-document-reviewer-prompt.md（审查怎么算通过），三个加起来不到三百行，一顿午饭的工夫读得完。
别在急活上开这套流程。 会踩的坑是：线上出问题、你想让 Agent 赶紧改一行，结果它开始问你成功标准。避法是分清场景——这套技能的定位是「创作性工作之前」，救火和排障应该走排障类流程，仓库里也确实有专门的系统化排障技能。
别把一次一问改成一次多问。 会踩的坑是：嫌轮次多，自己动手把提问规则放宽，然后回到「七个问题答两个」的老路。避法是接受轮次，改问题质量不改问题数量——如果觉得问得太浅，问题出在没先探索项目上下文，不在于一次只问一个。
规格写完真的要读。 会踩的坑是：Agent 说「已写入并提交，请复核」，你回一句「好，继续」。这个闸门是整条流程里唯一由人验证方向的地方，跳过它等于把前面所有提问的收益退还回去。避法是把复核当成必做动作：至少确认它对目的和成功标准的理解跟你一致。
注意它会写文件并提交。 会踩的坑是：不知道规格文档会落到 docs/superpowers/specs/ 并进 git，事后发现仓库里多了东西。避法是提前决定这个目录是否纳入版本管理——SKILL.md 里也写了用户对规格存放位置的偏好可以覆盖默认值。视觉伴侣那部分同理，它的会话文件在项目下的 .superpowers/brainstorm/，文档里提醒了把 .superpowers/ 加进 .gitignore。
别指望规格通过就等于设计正确。 会踩的坑是：审查者回了 Approved，你就当设计没问题了。审查的校准原则写得很清楚，它只拦会让计划出错的严重缺口。避法是把审查当成形式体检，方向判断仍然由你负责。
跑之前确认它没有跳到实现。 会踩的坑是：Agent 聊得挺投入，中途顺手建了目录、写了几个文件，等你发现时规格还没影。避法是盯住那条终态规则——brainstorming 之后唯一允许调用的是 writing-plans，出现任何别的实现动作就是流程被跑偏了。
收个尾
把这套东西压成一句可执行的判断：在 Agent 开始写代码之前，你手里应该已经有一份你亲眼读过、并且明确说了「可以」的东西。 那份东西叫设计还是规格、写在文件里还是聊天记录里，都不重要；重要的是它存在，而且被你确认过。
给自己留一份自检：这次任务里，Agent 有没有在你批准之前动手？它一次问了几个问题？你对成功标准的描述，能不能在它的产出里原样找到？如果三个答案分别是「动了」「一次五个」「找不到」，那么就算这次侥幸做对了，下次也会翻车。
想继续往下看，仓库里两个文件最值得读：skills/writing-plans/SKILL.md，看它怎么把规格拆成两到五分钟一步、每步都带测试和提交的任务；skills/using-superpowers/SKILL.md，看它怎么用一张危险信号表堵住 Agent 的自我开脱。这两块和 brainstorming 是同一套思路的三段——先问清楚、再拆明白、然后才允许动手。
本文属于 superpowers 方法论专题（共 30 篇，含三篇与其它开源 Agent 项目的对照）。想看把资产铺满的另一种取向，见 ECC 开源 Agent 套件专题。