brainstorming Agent Skill 实战教程：安装配置与 9 个核心用法
brainstorming Agent Skill 实战教程：安装配置与 9 个核心用法
"You MUST use this before any creative work"——这不是哪位工程师的口头禅，是 obra/superpowers 仓库里 brainstorming 技能写在 SKILL.md 第一行的触发条件。装了这套技能库的编码代理，接到"帮我加个功能"这类请求时不会直接开写，而是先退一步问清楚：给谁用、做成什么样算成功、有什么约束。想法磨成一份双方点头的设计之后，代码才准动。下面从安装讲到 SKILL.md 的九块核心内容：共享理解、三条路径、硬闸、反模式、红旗信号、路径清单、流程图、过程细节、设计之后的交接，最后是可视化伴侣的用法与几个官方文档里白纸黑字写着的坑。步骤与配图依据官方 README 和 SKILL.md 整理。
相关背景可参考 AI 编程总纲，工具档案见 Superpowers 产品页。
动手前需要知道的三件事
Superpowers 是 MIT 许可的开源项目，作者 Jesse Vincent（GitHub ID：obra），仓库地址 github.com/obra/superpowers，star 数已接近 30 万（易变数字，以 GitHub 页面为准），没有付费门槛。它不是一款独立软件，而是一套挂载到编码代理上的技能库——官方 README 列了 17 个支持的 harness：Claude Code、Cursor、Codex CLI、Gemini CLI、Qwen Code、Hermes Agent、Kimi Code、Grok Build CLI、Antigravity、Devin、Factory Droid、Copilot CLI、Pi、Muse 等。README 明确说：用几个 harness 就分别装几次，互不共享。
另一点与常见插件不同：技能是自动触发的，不用手动调用。README 原话是 The agent checks for relevant skills before any task. Mandatory workflows, not suggestions.——强制工作流，不是建议。
安装：一条命令的事，按代理各装各的
Superpowers 在 17 个编码代理上的官方安装命令（依据 README Installation 一节绘制）
以几个主流代理为例。Claude Code 从 Anthropic 官方插件市场装：
/plugin install superpowers@claude-plugins-official
Cursor 在 Agent 对话里输入 /add-plugin superpowers；Gemini CLI 走 gemini extensions install https://github.com/obra/superpowers；Qwen Code 是 qwen extensions install obra/superpowers；Hermes Agent 用 hermes plugins install obra/superpowers --enable，装完重启活动会话。其余代理的命令在 README 的 Installation 一节逐个列出。
装没装对，README 给了验证办法（Muse 小节原文）：
start a fresh session and sendLet's make a react todo list— a working install auto-triggersbrainstormingbefore any code is written.
也就是开个新会话发一句"我们做个 React 待办清单"：正常的安装会让代理在写任何代码之前先触发 brainstorming 来问你需求，而不是直接吐代码。
它在流水线上的位置
brainstorming 是七技能接力链的第一棒：设计未获批，后面的技能都不会启动（依据 README The Basic Workflow 一节绘制）
设计获批后 using-git-worktrees 建隔离工作区并确认测试基线干净；writing-plans 把活拆成 2–5 分钟的小任务，每个任务带确切文件路径与验证步骤；subagent-driven-development（每任务派新子代理逐一审查，最彻底）或 executing-plans（当前会话内联执行、最后整分支一次审查，最省）负责执行；test-driven-development 盯着红绿重构；requesting-code-review 在任务之间按严重度审查；finishing-a-development-branch 收尾给出合并或 PR 的选项。第一棒没跑完，后面一个都不会动——这就是 brainstorming 在这套方法论里的分量。
用法一：共享理解，产物是"对方能纠正的理解"
SKILL.md 对这一步成果的定义不是文档，而是 "an understanding your human partner can recognize and correct, grounded in what they want to accomplish"——一份你的协作对象能认出来、能纠正的理解。拆成三个动作：发现意图、把理解写回去、把意图带进设计。第一步的原文值得整段读：
Discover intent. Use the request and available context to identify the intended outcome, who it is for, and what success looks like. When that information is missing, ask one focused question about purpose or intended use before proposing features or an approach. Knowing the app genre does not tell you why your partner wants it.
末句是精髓：知道对方要做的是个什么类型的 App，并不等于知道他为什么要做它。信息缺了就只问一个聚焦的问题，别趁机让他把任务重新授权一遍。第二步"写回去"要求把预期结果、相关约束、成功标准写成一小段对方能评估的话，把他说的和代理假设的分开，请他纠正之后再当作设计简报。SKILL.md 同时也交代了反面：请求里已经写明目的和约束时，把这些复述出来就行，不要把同样的问题再问一遍。
用法二：三条路径，先分类、说出口
三条路径的判定标准与各自产出；拿不准时选更重的那条，且中途只升不降（依据 SKILL.md Three Paths 一节绘制）
第一个问题问出口之前，技能要先给请求分类，并把分类大声说出来——原话示例：this looks bounded, so I'll present a short design here rather than write a spec（这看着是个有界改动，我就在聊天里给个短设计，不写 spec 了）——说出口是为了让你能当场纠正它。三条路径各补一句判定要点：
Spike（探针）对应可行性问题，产出是一个答案而不是要保留的代码：2–3 句话讲清要试什么，点头就开跑，跑通的东西一律标注 throwaway。Bounded（有界改动）量的是仓库而不是你的熟悉程度——被改的那个流程必须已经存在于仓库里，不存在就归入架构级；有界改动在聊天里给短设计，拿到明确的 yes 才动工，同样没有 spec 文件。Architectural（架构级）覆盖新项目、新子系统和改动他人依赖的接口，走全套：澄清问题、2–3 个方案、分节设计、书面 spec、交接到 writing-plans。
两条路径拿不准时选重的那条。原文把这条规则叫 ratchet（棘轮）：任务中途发现隐藏复杂度，只能停下来、说明、升档，没有中途降级这回事。
用法三：硬闸，批准的是"当前呈现的阶段"
Before taking any implementation action, including invoking an implementation skill, writing product code, scaffolding, installing product dependencies, or creating an external project, complete the selected path's prerequisites.
SKILL.md 用 <HARD-GATE> 标签框死了实现动作的入口：探针路径要对方批准问题与探针计划；有界改动要对方批准聊天里的短设计；架构级要对方先审书面 spec、再审实现计划并选定执行方式。最容易踩的是紧接着的一句——A reply approves the stage actually presented. 回复只批准当前呈现的那个阶段：同意了想法不等于同意了还不存在的产物；聊天里聊定的设计只许可写 spec，spec 批了才许可进入计划环节。闸门没过之前，只读的项目探索是允许的。
用法四：反模式——"太简单不需要走流程"
SKILL.md 专门起了一节对付这句话，标题就叫 Anti-Pattern: "Too Simple To Need Approval"。回应很干脆：每条路径都以"对方批准了对应的设计"收尾，有界改动的审批门槛和架构级一样硬，差别只在产物的尺寸——两句话的设计也是设计，Scale the artifact to the selected path。至于伸手贴标签想跳过工作的，原文判词是 Reaching for a label to skip work IS the doubt：靠贴标签省事这个动作本身就是疑点，说明该走更重的路径。
用法五：红旗信号，一张"念头对现实"的对照表
Red Flags 一节是七个念头的自查表，中译如下（个别措辞意译）：
| 冒出来的念头 | 现实 |
|---|---|
| "这太简单了，不需要设计" | 按选定路径走：有界改动得到聊天里的短设计，架构级得到书面 spec 与计划交接 |
| "我把它叫成有界改动就能跳过 spec" | 伸手够标签来跳过工作，这个动作本身就是疑点——走更重的路径 |
| "是有界改动而且设计显而易见，趁他们看着的时候我先开工" | 闸门是批准，不是设计的长度。先呈现，然后停下等答复 |
| "我熟悉这类 App，所以是有界改动" | 有界无界量的是仓库，不是你的熟悉度。新项目没有已存在的流程——它是架构级 |
| "探针跑通了，代码就留下来吧" | 探针的产出是一个答案。保留代码是新请求——重新分类 |
| "事情变大了，但我快做完了，不用重新分类" | 中途冒出的隐藏复杂度会升级路径。停下来，说出来 |
| "探针批了，后续改动也就批了" | 每个任务有自己的分类和自己的批准 |
人读这张表的价值有两个：知道代理在哪些念头上会自我纠正；以及当你观察到某个念头成真时，知道该在哪个节点介入。
用法六：路径清单，五步、五步、九步
SKILL.md 给三条路径各配了一份任务清单，照抄如下（中译）：
Spike：① 探索项目上下文，够框出探针即可；② 呈现问题与探针计划，2–3 句话；③ 拿批准，点个头就够；④ 调查，在正确性允许的范围内越便宜越好；⑤ 汇报发现——给一条建议，顺手建了的东西全标注 throwaway。
Bounded：① 探索项目上下文（文件、文档、近期提交）；② 问澄清问题，一次一个，只问要紧的；③ 在聊天里呈现短设计——方案、动哪些文件、怎么测；④ 拿批准——原文用了大写 STOP：呈现设计和动手开工不能同一口气，那等于跳闸；⑤ 实现，走正常开发流程（TDD 适用），无计划文档。
Architectural：① 探索项目上下文；② 在「画出来比说清楚更容易」的时刻才征询可视化伴侣（用法九详述）；③ 澄清问题，一次一个，弄清目的、约束、成功标准；④ 提 2–3 个方案，带取舍与推荐；⑤ 分节呈现设计，复杂度决定每节篇幅，每节征求确认；⑥ 写设计文档，存到 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 并提交 git；⑦ spec 自查（用法八）；⑧ 请用户审阅书面 spec；⑨ 交接到 writing-plans 技能写实现计划。
用法七：流程图与终态
SKILL.md 附了一张 dot 语法的流程图，把三条路径从分类节点到各自终态的每一步、每个回环（设计被打回修改、spec 被要求改动）都画了出来，图的收尾强调 Hidden complexity? Upgrade path——复杂度冒头就回到分类节点升档。终态规则只有三句，原文措辞是 terminal states are path-bound：架构级路径在 brainstorming 之后唯一允许调用的技能是 writing-plans，"never frontend-design, mcp-builder, or any other implementation skill"；有界路径获批后直接走正常开发流程，没有计划文档；探针的终态是一份汇报出来的推荐意见。
用法八：过程细节，怎么问、怎么提方案、怎么呈现
The Process 一节为架构级路径补了不少硬性口径。提问：一条消息只问一个问题，话题要展开就拆成多问；能出选择题就出选择题；聚焦三样东西——目的、约束、成功标准。请求一上来就描述了多个独立子系统（原文例句是"做个带聊天、文件存储、计费、分析的平台"）时，先别急着问细节，立刻指出来，帮用户把项目拆成子项目，再对第一个子项目走设计流程——每个子项目有自己的 spec、计划与实现循环。提方案：给 2–3 个带取舍的选项，先说推荐项与理由，并且 YAGNI ruthlessly，把每个方案里用不上的功能无情砍掉。呈现设计：每节按复杂度伸缩，简单就几句话，再复杂也不超过 200–300 词，每节问一次到这里对不对；覆盖架构、组件、数据流、错误处理、测试五个面。
在既有代码库里工作另有三条：先看现有结构、跟随现有模式；影响本次工作的既有问题（比如文件过大、边界不清）作为针对性改进纳入设计，就像一个顺手的好开发者会做的那样；不做与目标无关的重构。
用法九：设计之后的交接
架构级设计定稿后写进 docs/superpowers/specs/ 下的设计文档并提交 git（用户对存放位置有偏好时从其偏好）。写完先过四项自查：扫占位符（TBD、TODO、没写完的小节、含糊的需求）；查内部矛盾（各节是否打架、架构与功能描述是否对得上）；查范围（还装不装得进单个实现计划）；查歧义（一条需求能否有两种读法，能就选定一种写明白）。修完不再审，直接往下走。然后把这句原文发给用户，停下来等回复：
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.
用户要改就改完重跑自查，批准后调用 writing-plans 写实现计划。SKILL.md 的措辞是不留余地的：Do NOT invoke any other skill.
可视化伴侣：按需才提、按题才用
brainstorming 带一个浏览器端的可视化伴侣，能展示 mockup、线框图、架构图和并排对比。规则写得很死：不许开局推销。等第一次遇到"画出来比说清楚更容易"的问题时，单独发一条消息征询（这条征询必须是独立消息，不能捎带任何澄清问题或总结），征询语原文如下：
This next part might be easier if I show you — I can put together mockups, diagrams, and comparisons in a browser tab as we go. It's still new and can be token-intensive. Want me to? I'll open it for you.
对方接受后也不等于所有问题都进浏览器：每个问题单独判断，判据一句话，would the user understand this better by seeing it than reading it? 看着明白还是读着明白。原文给的例子很清楚："个性在这个语境里指什么"是概念问题，走终端；"哪种向导式布局更好"是视觉问题，走浏览器。对方婉拒就继续纯文字，除非他主动再提，不再追问。
官方文档里写明白的几个坑
① 装多个代理要分别装。README 原话 Installation differs by harness，在 Claude Code 装过不代表 Cursor 里有。
② Hermes Agent 上的长会话会丢启动引导。README 明确：Hermes has no post-compaction hook, so a very long session that compacts over its first turn loses the bootstrap — start a fresh session if skills stop triggering. 技能突然不触发时，先重开会话再排查。
③ 批准不跨阶段。聊天里同意了方向，只算批准了写 spec 这一步；探针批了更不等于后续改动获批——红旗表最后一行专门写了这条。
④ 可视化伴侣费 token，且默认带遥测。征询语里官方自己承认 It's still new and can be token-intensive；遥测的实现是 brainstorming 可视化伴侣里的 Prime Radiant logo 从其官网加载、携带 Superpowers 版本号，官方声明不含项目、提示词、代理细节，也看不到点击。介意的话设环境变量 SUPERPOWERS_DISABLE_TELEMETRY 为任意真值即可关闭，Claude Code 的 DISABLE_TELEMETRY 与 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 也被尊重。
⑤ spec 存放位置可被覆盖。默认路径是 docs/superpowers/specs/，但括号里写着用户偏好优先——团队有自己的文档目录时提前说一句，免得代理写完才发现位置不对。
本文步骤与配图依据 obra/superpowers 官方 README 与 skills/brainstorming/SKILL.md 整理（配图为依据官方文档绘制的讲解图），版权归原作者所有。
