概览
brainstorming 技能能做什么
brainstorming 技能坚持一条清晰的规则：先设计和规格说明，再实现和编码。启用后，brainstorming 会引导你在编写代码、脚手架项目或调用任何实现类技能之前，先梳理用户意图、需求和高层设计。
它的核心是协作式对话。你从一个粗糙的想法出发，通过有针对性的问题不断补充背景和约束条件，最后收敛成一份用户可以审阅和批准的明确设计与 spec。只有跨过这个“硬审批闸门”之后，才适合进入构建或重构阶段。
适合哪些人使用 brainstorming
在以下情况下，可以考虑使用 brainstorming 技能：
- 你与 Claude 或类似智能体一起讨论产品功能、组件、UI 流程或架构改动
- 你想避免“这个太简单，不用设计”的反模式
- 你需要在代码变更前，建立可复用、可审计的设计讨论流程
- 你经常在做或调整前端、UI/UX 或流程较重的系统
它适合个人开发者、产品工程师、设计师，以及希望用轻量方式坚持“先设计再实现”流程的团队。
这个技能要解决的问题
brainstorming 技能主要用来避免：
- 在没有澄清目标的前提下直接上手写代码
- 隐含假设直到实现后期才暴露
- UI/UX 改动没有清晰的用户路径或视觉方向
- 规格说明过于模糊，无法支撑可靠的计划或任务拆分
通过强制设计检查点，brainstorming 能减少返工、实现偏差和设计债务。
什么时候适合（或不适合）用 brainstorming
很适合的场景：
- 规划新功能、修改行为，或设计 UI/UX 流程
- 希望有结构化的“发散 → 聚焦”的模板，用于创意、收集上下文和设计审批
- 在权衡方案时，会从视觉草图或示意图中受益
不太适合的场景：
- 只是机械性的小改动（改错别字、重命名变量、更新不会引起行为变化的常量）
- 已经有详细且通过审批的 spec，只需要执行实现（这种情况下更适合直接使用实现类技能）
即使看起来微不足道的任务，比如一个小的 config 修改或单函数工具，也可能埋着假设。你仍然可以用一次非常简短的设计过程来梳理，但依然遵循 brainstorming 的流程会有帮助。
使用方法
安装与基础配置
1. 安装 brainstorming 技能
使用 skills CLI 从 obra/superpowers 仓库添加 brainstorming 技能：
npx skills add https://github.com/obra/superpowers --skill brainstorming
这会拉取技能定义，以及配套的提示词和可选的辅助脚本，放在 skills/brainstorming 目录下。
2. 了解关键文件
安装完成后，建议先浏览这些文件，了解整体流程和可用辅助工具：
SKILL.md– 对 brainstorming 流程的核心说明，包括“先设计后写代码”的硬性闸门和必做步骤清单。spec-document-reviewer-prompt.md– 用于 spec 审查子 agent 的模板提示词，用来检查规格说明的完整性、一致性和清晰度。visual-companion.md– 说明如何使用基于浏览器的可视化 companion，用于展示草图、流程图和视觉方案。scripts/frame-template.html– visual companion 使用的 HTML frame 模板，提供统一、偏重 UI 的布局。scripts/helper.js– 在 visual companion 中处理选中事件和自动刷新（live reload）的前端辅助脚本。scripts/server.cjs,scripts/start-server.sh,scripts/stop-server.sh– 用于启动和管理 visual companion server 的脚本。
开始使用 brainstorming 流程时，不需要修改这些文件。但提前了解它们有助于你把该技能融合进自己的环境和工具链中。
核心 brainstorming 流程
1. 从项目上下文开始
每次使用 brainstorming 前，都应先围绕当前项目建立共同上下文。SKILL.md 中的检查清单强调：
- 查看相关代码文件和文档
- 快速浏览最近的 commits 获取背景
- 明确这次改动会影响系统的哪些部分
在使用 Claude 或其他 agent 时，先提示它探索项目上下文，而不是一上来就要求修改代码。
2. 针对视觉相关问题，提供 visual companion
如果任务涉及 UI/UX 或其他强视觉属性的话题，可以单独提出使用 visual companion。visual-companion.md 中的规则是：
逐个问题判断，而不是按整场会话判断。问自己：这件事，如果“看”比“读”更容易理解吗？
浏览器端的 companion 适合用于：
- UI 草图和布局方案
- 架构和流程图
- 不同设计方向的并排对比
- 讨论间距、层级和视觉细节
而仅用终端（纯文本）更适合：
- 讨论范围、需求和术语定义
- 设计权衡、API/数据建模的逻辑选择
- 各种回答“只需要文字、不需要图”的澄清问题
3. 一次只问一个澄清问题
brainstorming 技能假定的是一场有节奏的对话，而不是一条“超级长提示词”。请使用一系列聚焦的问题，例如：
- "Who are the primary users of this feature?"
- "What constraints do we have on performance or deployment?"
- "Which platforms and screen sizes matter most?"
一次只问一个问题，等待回答后再提出下一个，用迭代方式逐步完善理解。
4. 产出可落地的设计与规格说明
当上下文足够清晰时，把已有信息综合成一份用户真正可以“批准”的设计。根据任务不同，这份设计可能包括：
- 高层目标和成功度量标准
- 用户故事或示例使用流程
- UI 布局描述和视觉方向（可以选择用 visual companion 辅助）
- 数据结构、接口或集成点
- 会影响实现方式的非功能性需求
把这些写成结构化的 spec 文档，存放在你习惯的位置（例如，如果遵循仓库约定，可以放在 docs/superpowers/specs/ 下）。
5. 严格执行“设计闸门”
SKILL.md 中的一条关键规则就是这个硬闸门：
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.
即便看上去只是一个很简单的需求，也适用这条规则。对非常小的改动，设计可能只是几句话的说明，但它必须存在，而且要得到明确确认之后才能继续。
使用 spec 文档审查模板
1. 起草你的 spec
完成 brainstorming 后，根据项目习惯写出 spec，结构可以自由选择。保存到一个方便引用的路径，例如：
docs/superpowers/specs/my-feature-spec.md
2. 启动 spec 审查子 agent
当 spec 准备好需要验证时，使用 spec-document-reviewer-prompt.md 作为模板，创建一个专门审查 spec 的子 agent。将提示词中的 [SPEC_FILE_PATH] 替换为你的 spec 文件路径。
这个审查者会：
- 检查是否有缺失的章节、TODO 或 “TBD” 之类的占位符
- 查找自相矛盾或不一致的需求
- 标记那些可能导致误实现的模糊描述
- 确认范围是否足够收敛，便于制定一份统一的实现计划
审查结果会给出一个 Approved | Issues Found 状态，并附带问题列表，每条问题都会说明为什么它会影响实现规划。
3. 迭代直到通过审批
如果审查结果指出了问题，就更新 spec 并重新运行审查。spec 通过后，你就有了一份可靠的基础，可以交给实现类技能或规划工具继续推进。
使用可视化 brainstorming companion
1. 启动 visual companion server
在 scripts 目录下，可以用以下命令启动 brainstorm server：
./start-server.sh --project-dir /path/to/your/project
常用选项包括：
--project-dir <path>– 将会话文件保存在<path>/.superpowers/brainstorm/下，而不是/tmp，便于持久化。--host <bind-host>– 绑定到特定网卡（例如在容器或远程环境中使用0.0.0.0）。--url-host <display-host>– 控制返回 JSON 中 URL 显示的 hostname。--foreground或--background– 选择在当前终端前台运行还是后台运行。
启动后，脚本会输出包含会话 URL 的 JSON。用浏览器打开该 URL 即可进入 visual brainstorming 界面。
2. 渲染视觉方案
server 会监听一个目录中的 HTML 文件，并总是提供最新的那个。典型用法是：
- Claude（或你的 agent）使用
frame-template.html作为基础，在配置好的screen_dir中写入一个 HTML 文件。 - 当有新文件创建时，浏览器端会通过
helper.js自动刷新加载。 - 用户可以在界面中点击选项或卡片，这些事件会通过 WebSocket 回传给 agent 处理。
这样就可以轻松展示：
- 多个布局方案，以可点击卡片形式呈现
- 流程图和状态机
- 颜色、间距或组件变体的视觉对比
3. 结束后关闭 server
会话结束时，用以下命令干净地停止 brainstorm server：
./stop-server.sh <session_dir>
如果会话目录在 /tmp 下，这一步也会清理生成的临时文件。对于 .superpowers/ 下的持久化目录，则会保留，以便你之后回看草图和图表。
将 brainstorming 融入你的工作流
- 作为标准的 pre-commit 步骤： 在合并 feature 分支前，要求先完成 brainstorming，并通过 spec 审查。
- 与其他技能配合： 先跑 brainstorming，产出并冻结 spec，然后再交给实现、重构或测试类技能。
- 针对 UI/UX 工作： 将对话式 brainstorming 与 visual companion 结合，在写任何 CSS 或组件代码之前，就验证布局和交互思路。
你可以自由调整目录结构、命名和 spec 格式，让它与现有仓库保持一致；但建议保持这一核心模式：context → questions → design/spec → review → implementation。
常见问题（FAQ）
brainstorming 技能只适用于大型复杂项目吗？
不是。brainstorming 技能就是为了避免“这个太简单，不用设计”这种反模式而设计的。即便只是一次小的 config 修改或临时工具函数，也可能隐藏关键假设。对非常小的任务，设计可以是一段简洁描述，但在实现前，最好仍然把它说清并确认。
如果我已经有 spec 了，还需要 brainstorming 吗？
如果你已经有一份全面、最新且通过审批的 spec，可以不必再完整跑一轮 brainstorming。不过，你仍然可以用 spec-document-reviewer-prompt.md 中的模板，先对现有 spec 做一次验证。如果审查发现有缺口或模糊点，再用一轮精简版 brainstorming 来补齐。
brainstorming 与实现类技能如何配合？
brainstorming 技能的定位是在任何实现类技能之前运行。它的输出包括：
- 一份清晰的、已通过用户审批的设计
- 一份可以继续审查和迭代的 spec 文档
只有在通过这个“设计审批闸门”之后，才应该调用编码或重构类技能。这种分层方式能让设计意图更加明确，减少实现阶段的反复沟通。
不用 visual companion 也能从 brainstorming 中获益吗？
可以。visual companion 是可选的。
- 如果你的工作多是后端逻辑、API 或基础设施，可以把 brainstorming 完全当成文本向导流程来用。
- 如果你做 UI/UX、产品设计或前端，配合
visual-companion.md和scripts/目录下的工具，用 visual companion 会更方便对比方案、收集反馈。
判断标准很简单：看视觉呈现是否真的能让这次讨论更清晰。
如果无视“硬闸门”，直接开始写代码会怎样？
跳过“硬设计闸门”相当于放弃了 brainstorming 的最大价值——在早期发现偏差。可能导致：
- 功能最终效果与用户期望不符
- UI 做完后因为反馈而需要大改甚至重做
- spec 落后于代码，变成难以维护的“文档债务”
建议把闸门当作一条流程纪律：在设计写清、评审并明确通过之前，不写也不请求任何代码。
我可以自定义 spec 审查标准吗？
可以。spec-document-reviewer-prompt.md 中定义了 completeness、consistency、clarity、scope 和 YAGNI 等类别。你可以在保留整体审查流程的前提下，根据自己的领域添加安全性（security）、性能（performance）、合规（compliance）等检查项。
brainstorming 是否绑定某个特定框架或技术栈？
不会。brainstorming 技能与技术栈无关，它关注的是上下文收集、需求澄清、设计表达和视觉探索，而不是某个框架的实现细节。无论是前端应用、后端服务、系统集成，还是混合型系统都可以使用。
如何卸载或停用 brainstorming 技能？
该技能只是 obra/superpowers 技能集中的一部分。要停用它，你可以：
- 在 agent 或 skills loader 配置中移除或注释掉相关配置
- 在工作流和流水线中不再调用它
brainstorming 技能本身不会对系统做任何全局修改，所以停用只涉及配置和使用习惯的调整。