brainstorming

将构思转化为设计

通过基于代码库的结构化研究，将初步构思转化为可直接实施的设计。完整流程（并行研究子 Agent + 评估器）针对开放式多组件问题进行了校准。以下的快速退出检查可让简单任务跳过此流程。这是一项包含多个阶段的重要工作——建议通过 Claude Code 内置的 /goal 来运行此流程（见下文）。

推荐：通过 /goal 运行

构思过程包含开放式、多轮研究。请在 Claude Code 内置的 /goal（v2.1.139+）下启动此流程，这样新的评估器就能在多轮对话中推动流程完成，而不是让它中途停止：

/goal "Claude has narrated a successful design commit (with commit hash) and the evaluator's verdict is PASS" /superpowers:brainstorming "<problem>"

/goal 是一个由用户输入的外层包装器（技能无法在运行过程中为自身启用它），其评估器只会评判 Claude 在对话记录中叙述的内容——应根据叙述输出来描述条件（提交哈希、评估器的原样判定行），而不是文件系统状态。完整语义、条件措辞和快速退出的交互方式：../../skills/references/goal-wrapper.md。

关键：快速退出检查（在初始化前运行）

将 $ARGUMENTS 归入以下三个类别之一。不要默认“拿不准时就继续”——这会让 Agent 单方面倾向于过度设计。

类别 A — 明确的简单任务信号（快速退出：不要编写设计文件，也不要启动评估器）：

• 只涉及单个文件或单行更改（“将 X 改为 Y”“将 foo 重命名为 bar”“将日志级别设为 DEBUG”）
• 机械式重构（“提取辅助函数”“重新排列导入”“更新已弃用的 API 调用”）
• 已明确根因的错误（“cookie 域名不对，修复它”）——转交给 /superpowers:systematic-debugging
• 一次性脚本／配置调整／依赖升级
• 用户明确表示“直接修补”／“不需要计划”／“简要修复”

类别 B — 明确的开放式任务信号（继续初始化）：

• 设计涉及多个组件，且明确列出了子系统（例如：“设计一个支持电子邮件 + SMS + 推送的通知系统”）
• 需求不明确，用户期望通过对话进行澄清
• 全新功能，且明确要求“先设计”／“头脑风暴”

类别 C — 不明确（默认归入类别 B，不要暂停询问）：

• $ARGUMENTS 简短，可能属于任一类别（例如，只有一句话，没有范围提示）
• 同时包含简单任务信号和开放式表述
• 只说明目标，没有指定范围（例如：“提升性能”“让它更快”）

对于类别 A，输出下方的快速退出回复并停止。对于类别 B（包括所有类别 C 的情况），继续初始化。保留 --force 标记以向后兼容，但现在它不执行任何操作（快速退出按单次调用判定）；后续的范围转变由第 1 阶段的中途转向处理逻辑接纳。

快速退出回复（类别 A，原样输出，然后直接编辑或移交）：

检测到这是简单任务。跳过头脑风暴流程（该流程针对开放式多组件问题进行了校准）。如需强制运行完整流程，请重新调用 /superpowers:brainstorming --force "<task>"。

初始化

1. 提取问题陈述：将 $ARGUMENTS 精简为一个约 150 个字符以内的陈述句，用来描述要进行头脑风暴的问题，并保留用户自己的表述。不要改述、删去约束条件，也不要引入用户未使用的词汇。如果开头有 --force 标记，则将其去掉（它已由提前退出检查处理）。如果 $ARGUMENTS 为空，则使用用户刚刚在对话中描述的开放问题。
2. 阅读项目上下文：阅读 CLAUDE.md 和 README.md，了解项目约束。然后查阅文档索引——运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind design --status active 和 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --status expired。将任何 expired: 设计的结论视为非权威内容；应新建设计，而非扩展已过期设计。如果已有同一主题的 active 设计，则在 Phase 1 的冲刺约定中提及，并选择扩展它（优先）或在 Phase 3 收尾时取而代之。接着查阅记忆：运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind memory --status active，并在 Phase 1 探索前阅读排名靠前且与主题相关的 3-5 行所指向的文件。
3. 在同一轮中进入 Phase 1。

核心原则

1. 上下文优先：先探索代码库，再提问
2. 严格遵循 YAGNI：只纳入明确需要的内容
3. 测试优先思维：始终包含 BDD 规范——加载 superpowers:behavior-driven-development 技能
4. 增量验证：进入下一阶段前，验证当前阶段的退出条件
5. 按设计重置上下文：研究和 QA 在全新的子 Agent 上下文中进行（Anthropic harness-design 原则 1）——主 Agent 只负责综合。

Phase 1：范围对齐

探索代码库，在当前轮次中明确并锁定方案，然后进入 Phase 2。

操作：

1. 探索代码库：使用 Read/Grep/Glob 查找相关文件、模式、文档和近期提交。在记录约定前先建立上下文。
2. 冲刺约定：在当前轮次输出中记录结构化提案：
   • “这是我对 [问题] 的理解”
   • “我建议采用 [方案]，因为 [理由]”
   • “考虑过的替代方案：[简要列表及权衡]”
   • “已解决的开放问题：[根据代码库证据自行解答的问题；绝不把这些问题留给用户]”
3. 锁定并推进：将冲刺约定视为已锁定的范围，并进入 Phase 2。不要暂停并请求批准——Phase 2 的评估器和用户提交后的审查是质量关卡。如果某个问题确实无法从代码库中找到答案，就选择最稳妥的默认方案，在冲刺约定中记录假设，并将其写入 Phase 2 的设计文件，以便评估器指出。

开放式问题：当问题需要挑战假设时，在冲刺约定中运用第一性原理推理——指出要挑战的假设、替代性表述，以及它为何会改变所选方案。

退出条件：在当前轮次中记录冲刺约定，确定唯一方案，明确需求和约束，并准备好进入 Phase 2。

中途转向（仅当由 /goal 包裹时才可能）：用新的范围重新执行 Phase 1 步骤 1，并从头重新生成冲刺约定；如果是根本性覆盖，或用户要求“abort”/“cancel”，则以一行说明停止，不写入设计文件。完整处理方式见：./references/scope-alignment.md §Mid-Stream Pivots。

探索模式、提问指南和权衡模板见 ./references/scope-alignment.md。

Phase 2：设计、QA 与术语协调

创建包含集成质量保证的设计文档，然后将跨子 Agent 的术语协调为一份规范词汇表，再进行集成。所有研究均在全新的子 Agent 上下文中进行；主 Agent 只负责综合和协调，不撰写内容。

步骤 1：创建设计文档 文件夹：docs/plans/YYYY-MM-DD-<topic>-design/（必须带 -design 后缀）。同一天同一主题的第二份设计文档使用 -design-2/（之后为 -3/）后缀——文档索引根据完整文件夹路径建立索引。完整规则：./references/design-and-qa.md §Folder Naming Rules。

必需文件（4 个）：

• _index.md -- Context、Discovery Results、Requirements、Rationale、Detailed Design、Design Documents（链接到配套文档）
• bdd-specs.md -- 完整的 Gherkin 场景（成功路径、边缘情况、错误条件）
• architecture.md -- 系统概述、组件、数据结构、集成点
• best-practices.md -- 安全性、性能、代码质量、常见陷阱

_index.md 必须按以下顺序使用这些确切的章节标题：Context、Discovery Results、Glossary、Requirements、Rationale、Detailed Design、Design Documents。## Glossary 章节由下文的词汇协调流程填写——即使未发现词汇差异也必须保留，以便记录规范名称，供未来读者参考。

bdd-specs.md：将所有 Gherkin 场景直接写入此文件。不要创建单独的 .feature 文件——这些文件属于实现阶段。

子 Agent 策略（强制）：通过 Agent 工具并行启动至少 3 个子 Agent，每个都使用相互隔离的全新上下文（研究记录不会污染主 Agent）：架构研究（模式、库、惯例；使用 WebSearch 查找最新实践）、最佳实践研究（安全性／性能／测试；加载 superpowers:behavior-driven-development）、上下文与需求综合，以及针对研究密集型方面的其他子 Agent。完整提示词和输出：./references/design-and-qa.md §Sub-Agent Strategy。

词汇协调（强制，必须在整合之前完成）：所有子 Agent 返回结果后、整合其输出之前，执行一轮明确的检查：扫描子 Agent 输出中的领域名词（任何命名概念而非描述概念的词语），建立按子 Agent 划分的概念词汇表，为存在差异的概念选定一个规范名称（优先采用代码库中的惯例；记录被弃用的其他名称），并在生成整合后的四个文件之前改写子 Agent 输出中的不一致名称——切勿先写完再协调。在 _index.md 的 ## Discovery Results 之后直接添加 ## Glossary 章节，记录规范名称。完整流程和 2026-05-09 的起因案例：./references/design-and-qa.md §Vocabulary reconciliation。

验证（整合后）：对四个文件运行 grep -oE "<concept-noun>"，结果必须只包含规范名称，不能出现任何被弃用的其他名称。若仍存在其他名称，说明协调流程漏掉了某个文件——继续检查并修正后再进行下一步。

整合：完成协调后，主 Agent 整合返回的结果，解决剩余冲突时优先采用代码库中的惯例，并编写 4 份设计文件。

步骤 2：整合式 QA

从 docs/retros/checklists/design-v{N}.md 解析最新的检查清单（N 最大者）。使用检查清单路径，以设计模式启动 superpowers:superpowers-evaluator Agent。评估器以文本形式输出报告内容；将其写入设计文件夹，命名为 evaluation-design-round-{N}.md。然后阅读报告结论：

• PASS：直接进入第 3 阶段收尾——不要暂停等待用户确认（PASS 结论和提交后的 git show 差异即为审查依据）。
• REWORK：修复问题；如有需要，重新运行评估器（写入 evaluation-design-round-2.md 等）。
• REWORK 2 轮及以上：考虑返回第 1 阶段，重新调整方案，而不是继续打补丁。 缺失时自动初始化：如果 docs/retros/checklists/design-v{N}.md 不存在，请勿中止。运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/seed-checklists.sh" design docs/retros/checklists/design-v1.md，记录 Auto-seeded design-v1.md，然后继续使用新文件。退出码处理：0 = 已初始化，3 = 已存在（视为成功并继续使用现有文件），1/2 = 真实错误（磁盘／用法错误 → 中止）。

退出条件：已创建包含所有必需文件的设计文件夹，且 QA 已通过。

有关输出结构详情、子 Agent 模式和 QA 流程，请参阅 ./references/design-and-qa.md。 有关评估者检查清单的校准，请参阅 ./references/evaluation-checklist-reference.md。

阶段 3：收尾

提交设计，并转入实现规划。

操作： 0. 至关重要 — 不得延后：将设计更新至文档索引，以便下游编写器技能能够发现它。运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert design docs/plans/YYYY-MM-DD-<topic>-design/ --status active --summary "<one-line summary>"。如果同一主题先前的 active 设计即将被替换，先运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" set-status docs/plans/<prior-design-path>/ "superseded-by:docs/plans/YYYY-MM-DD-<topic>-design/"，将其标记为已取代。先查询、后更新这一配对操作，可确保索引在各阶段都准确无误。 0.5. 至关重要 — 不得延后：有条件的记忆写入步骤，以 REWORK 轮数达到 2 轮或以上为触发条件（阶段 2 的触发条件）——如果此设计经历了 2 轮或以上的 REWORK，记录反复出现的原因：写入 docs/memory/<category>_<slug>.md（范围反转时使用 category: decision，评估者反复发现的错误时使用 category: pitfall），然后运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert memory docs/memory/<category>_<slug>.md --status active --summary "<one-line>" --category <category>。如果 REWORK 少于 2 轮，则无需执行此步骤。

1. 使用一条链式命令暂存并提交整个文件夹——独立的 git add 会被 git 插件的钩子拒绝：git add docs/plans/YYYY-MM-DD-<topic>-design/ && git-agent commit --no-stage --intent "add design for <topic>" --co-author "Claude <Model> <Version> <[email protected]>"
2. 如果遇到身份验证错误，使用 --free 标志重试
3. 回退方案：如果 git-agent 不可用，请通过 Skill 工具调用 /git:commit 技能；完整回退流程见 ../../skills/references/git-commit.md
4. 过渡提示（输出给用户）："设计已完成。要创建详细的实现计划，请使用 /superpowers:writing-plans。"

提交后不要再添加审查／润色迭代。四个设计文件 + 评估者 PASS + 提交，即为完整的退出条件。

详细的提交模式请参阅 ../../skills/references/git-commit.md。

参考资料

• ./references/scope-alignment.md -- 探索模式、冲刺约定模型、提问指南
• ./references/design-and-qa.md -- 输出结构、子 Agent 模式、QA 流程
• ./references/evaluation-checklist-reference.md -- 供评估者使用的设计评估检查清单参考
• ../../skills/references/git-commit.md -- Git 提交模式（共享）
• ../../skills/references/goal-wrapper.md -- /goal 包装器语义与条件措辞（共享）