古法编程

brainstorming 技能是 SuperPowers 中一道不可绕过的硬门禁，它强制 AI 编码代理在写任何代码前必须完成一个包含九个步骤的对话流程。核心目标是澄清需求、提出多个设计方案、输出设计文档并获得用户批准，其唯一的终点是调用 writing-plans 技能生成实施计划，从而杜绝因需求模糊导致的无效编码。

SuperPowers brainstorming 技能详解：从想法到设计文档的硬门禁流程

为什么需要这个技能

当你向 AI 编码代理提出一个需求时，最常见的失败模式是什么？不是它写不出代码，而是它在没有完全理解你意图的情况下就写了大量代码。结果要么方向完全错误，要么细节与预期不符，导致大量返工。SuperPowers 的 brainstorming 技能正是为了解决这个问题而设计的。它不是一个可选的建议，而是一个在任何创造性工作（开发新功能、构建组件、修改现有行为）之前都必须触发的强制性流程。它的核心价值在于，将“先想清楚再动手”从一个习惯，固化为一个 AI 必须遵守的工作协议。

核心机制：不可绕过的硬门禁 (HARD-GATE)

brainstorming 技能的根本约束体现在其 SKILL.md 文件的 <HARD-GATE> 部分：

在你展示设计并得到用户批准之前，不得调用任何实现 skill、不得写任何代码、不得搭建任何项目脚手架。这适用于每个项目，无论其看起来多么简单。

这条规则没有例外。即使你认为一个需求“太简单了”，代理也必须走完完整的对话和设计流程。源文件明确指出，认为“这个需求太简单了，跳过设计吧”本身就是一个反模式（Anti-Pattern）。因为简单项目往往是那些未经审视的假设最容易造成工作浪费的地方。设计文档可以很短，但必须存在并获得批准。

九步流程：从想法到设计文档

整个流程被分解为九个严格顺序的步骤，形成一个完整的闭环：

  1. 探索项目上下文：代理首先检查现有文件、文档和近期提交记录，了解当前代码库状态，而不是在真空中设计。
  2. 评估是否需要视觉辅助：如果后续问题涉及界面布局或视觉内容，代理会单独发出一条消息，询问是否启用浏览器可视化伴侣工具。这条消息不能与其他问题合并。
  3. 逐条提问澄清需求：代理一次只问一个问题，聚焦于理解目的、约束和成功标准。它优先使用多选题，等待你的回答后再问下一个。
  4. 提出 2-3 个方案：基于收集的信息，代理会提出几个不同的技术方向，说明各自的权衡（trade-offs），并明确推荐其中一个及理由。
  5. 分段展示设计：代理按设计的复杂度分段展示，每部分从几句话到两三百字不等，并在每部分后询问你的认可，再继续下一部分。
  6. 撰写并保存设计文档：将最终确认的设计写入 docs/superpowers/specs/YYYY-MM-DD-<主题>-design.md 文件，并将其提交到 Git 仓库。这个路径是项目的默认规范。
  7. 设计文档自查 (Spec Self-Review)：代理用新的眼光审查文档，检查是否存在“TBD”、前后矛盾、需求模糊或范围过大的问题，并直接在文档内修正。
  8. 用户审阅门禁 (User Review Gate)：自查通过后，代理会明确告知你文档路径，请求你审阅。只有在你确认没有问题后，流程才能继续。
  9. 转入实施阶段：最后一步，也是唯一的下一步，是调用 writing-plans 技能来生成详细的实施计划。绝不会直接开始写代码或调用其他实现技能。
digraph brainstorming_flow {
    rankdir=TB;
    node [shape=box];
    A [label="1. 探索项目上下文"];
    B [label="2. 评估视觉辅助需求"];
    C [label="3. 逐条提问澄清需求"];
    D [label="4. 提出 2-3 个方案"];
    E [label="5. 分段展示设计"];
    F [label="6. 撰写设计文档"];
    G [label="7. 设计文档自查"];
    H [label="8. 用户审阅门禁"];
    I [label="9. 调用 writing-plans", shape=doublecircle];

    A -> B;
    B -> C;
    C -> D;
    D -> E;
    E -> F;
    F -> G;
    G -> H;
    H -> I;
}

这个流程的终点是明确而单一的：调用 writing-plans 技能。关于如何从这一步开始制定可执行的计划，可以参考《writing-plans 技能如何写出可执行的 AI 实施计划》。

设计文档的保存与审查历史

设计文档的默认保存路径 docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md 不仅是一个约定，它也是项目可追溯性的基础。这份文档会覆盖架构、组件、数据流、错误处理和测试策略等关键设计决策。

在项目的演进过程中，对设计文档的审查机制也得到了强化。历史上的 spec-document-reviewer-prompt.md 文件定义了一个用于分派规格文档审查子代理的模板。该模板明确列出了审查者需要检查的类别：

  • 完整性：是否存在 TODO、占位符、未完成章节。
  • 一致性：内部是否存在矛盾。
  • 清晰度：需求是否模糊到足以让实现者误解。
  • 范围：是否专注于单个实施计划。
  • YAGNI：是否存在未请求的特性和过度设计。

随后，document-review-system 的设计文档进一步将这种审查流程规范化，明确在 brainstorming 之后、writing-plans 之前，增加了一个规格文档审查循环 (Spec Document Review Loop)。这意味着在完成第7步自查和第8步用户审阅后，代理可以分派一个审查子代理进行结构化验证。如果发现问题，代理会修复文档并重新审查，直到通过。这一机制进一步确保了进入编写计划阶段的设计文档是经过双重检验的、高质量的。

验证与错误处理

如何验证代理是否正确遵循了流程？你可以观察以下几点：

  1. 输入：你的任何编码请求。
  2. 预期输出：代理没有立即生成代码文件，而是开始提问或阅读项目文件。
  3. 错误表现：如果代理直接开始编写生产代码或调用实现技能，说明它没有正确触发或遵守 brainstorming 的硬门禁规则。此时应中断并提醒它遵循流程。
  4. 验证方法：最终，在 docs/superpowers/specs/ 目录下应找到一份带有当前日期的 .md 设计文档，且该文档已提交到 Git 历史。

与其他技能的衔接

brainstorming 技能是 SuperPowers 工作流的起点和强制门禁。它产出的设计文档是后续所有工作的基石。了解整个工作流如何闭环，可以参考 《using-superpowers 工作机制：为什么代理必须先加载相关技能》，它解释了技能发现机制如何确保 brainstorming 等前置技能被正确加载。

FAQ

Q: 如果我的需求非常明确，连几句话的设计都嫌多余，怎么办？ A: 不能跳过。brainstorming 技能是强制流程。但对于清晰的需求，对话会非常简短：代理可能只问一两个问题确认细节，然后快速提出方案并生成一个简短的设计文档。整个过程可能只需要几分钟，但必须完成。

Q: 设计文档保存后，用户审阅环节可以自动化或跳过吗？ A: 不可以。用户审阅门禁（第8步）是流程中的关键一环。代理必须明确请求你查看文档并等待你的批准。这是确保设计符合你最终意图的最后一道人工检查。

Q: 如果我想修改已经确认的设计，该怎么办？ A: 随时可以提出修改。brainstorming 的流程设计本身支持回溯。代理会根据新的信息调整方案，必要时可以回到前面的步骤重新讨论，而不是强迫你走完旧的设计路径。

Q: 这个技能对超大型需求（如“构建一个完整电商平台”）适用吗？ A: 适用，但代理会首先帮助你分解。如果需求描述了多个独立子系统，代理会立即指出并协助你将大需求拆解为若干子项目。然后，对第一个子项目执行完整的 brainstorming 流程，后续子项目再依次进行。