教程概述

系列目录：Superpowers 教程系列索引

brainstorming 是 Superpowers 框架中最重要的技能之一。它的核心理念是：在写任何代码之前，先充分理解问题。

你将学到

• ✅ brainstorming 技能的触发时机
• ✅ 苏格拉底式提问的工作流程
• ✅ 设计文档的结构与保存
• ✅ 实际案例分析
• ✅ 常见问题与应对策略

为什么需要 brainstorming？

传统 AI 开发流程的问题

flowchart LR
    A[用户需求] --> B[AI 直接写代码]
    B --> C[发现理解有误]
    C --> D[返工重写]
    D --> E[多次迭代]
    E --> F[最终完成]
    
    style B fill:#ffcccc
    style C fill:#ffcccc
    style D fill:#ffcccc

Superpowers 的流程

flowchart TD
    A[用户需求] --> B[brainstorming 启动]
    B --> C[苏格拉底式提问]
    C --> D[明确需求细节]
    D --> E[生成分块设计文档]
    E --> F[用户逐块确认]
    F --> G[开始实现]
    
    style B fill:#e1f5ff
    style E fill:#e1f5ff
    style F fill:#e1f5ff

效果对比

brainstorming 技能详解

触发时机

brainstorming 技能会在以下场景自动触发：

1. 创建新功能 - “添加一个用户登录功能”
2. 构建组件 - “创建一个导航栏组件”
3. 修改行为 - “改变文章的排序方式”
4. 添加集成 - “接入 Stripe 支付”

核心工作流程

sequenceDiagram
    participant U as 用户
    participant AI as AI 助手
    participant D as 设计文档
    
    U->>AI: 我想添加评论功能
    AI->>AI: 触发 brainstorming
    AI->>U: 问题 1: 评论需要审核吗？
    U->>AI: 需要，先审后发
    AI->>U: 问题 2: 支持哪些格式？
    U->>AI: Markdown 和代码块
    AI->>U: 问题 3: 用户系统？
    U->>AI: 使用现有的 GitHub OAuth
    AI->>D: 生成分块设计文档
    D->>U: 第 1 块：数据模型设计
    U->>AI: 确认
    D->>U: 第 2 块：API 设计
    U->>AI: 需要修改...
    AI->>D: 更新设计
    D->>U: 第 3 块：前端组件
    U->>AI: 确认全部
    AI->>AI: 设计完成，转入 planning

苏格拉底式提问法

什么是苏格拉底式提问？

苏格拉底式提问是一种通过问题引导思考的方法。在 brainstorming 中，AI 不会直接假设，而是通过一系列问题来：

1. 澄清概念 - “你说的’快速’具体指什么？”
2. 挑战假设 - “为什么选择这个方案？”
3. 探索替代 - “有没有考虑过其他方法？”
4. 验证一致性 - “这和之前的设计是否冲突？”

典型问题类型

1. 需求澄清类

• 这个功能的目标用户是谁？
• 用户最需要解决的核心问题是什么？
• "高性能"的具体指标是什么？（QPS？延迟？）
• 需要支持哪些边界情况？

2. 技术选型类

• 为什么选择 Redis 而不是 Memcached？
• 这个方案的可扩展性如何？
• 有没有更简单的替代方案？
• 技术债务的接受程度如何？

3. 安全与风险类

• 这个接口需要哪些认证机制？
• 如何防止滥用/攻击？
• 数据敏感性如何？需要加密吗？
• 失败场景下的降级策略是什么？

4. 测试与验证类

• 如何验证这个功能是正确的？
• 需要哪些单元测试？
• 集成测试的策略是什么？
• 性能测试的基准是什么？

设计文档结构

brainstorming 完成后，会生成一个结构化的设计文档，通常包含以下部分：

标准模板

# 功能名称

## 1. 概述

### 1.1 目标
[功能要解决的核心问题]

### 1.2 范围
[包含的功能边界]

### 1.3 非目标
[明确不包含的内容]

## 2. 需求

### 2.1 功能需求
- [ ] FR1: ...
- [ ] FR2: ...

### 2.2 非功能需求
- [ ] 性能：...
- [ ] 可用性：...
- [ ] 安全性：...

## 3. 设计方案

### 3.1 架构概述
[系统架构图]

### 3.2 数据模型
[数据库 schema/数据结构]

### 3.3 API 设计
[接口定义]

### 3.4 组件设计
[前端/后端组件划分]

## 4. 实施考虑

### 4.1 技术选型
[关键技术决策及理由]

### 4.2 依赖关系
[外部依赖和内部依赖]

### 4.3 风险与缓解
[潜在风险和应对策略]

## 5. 测试策略

### 5.1 单元测试
[需要覆盖的核心逻辑]

### 5.2 集成测试
[系统间交互测试]

### 5.3 性能测试
[性能基准和测试方法]

## 6. 验收标准

- [ ] 所有功能需求实现
- [ ] 单元测试覆盖率 ≥80%
- [ ] 性能指标达标
- [ ] 代码审查通过

分块确认机制

设计文档不会一次性全部抛出，而是分块呈现：

第 1 块：概述和需求（等待确认）
    ↓
第 2 块：数据模型和 API（等待确认）
    ↓
第 3 块：组件设计和实施（等待确认）
    ↓
第 4 块：测试策略和验收标准（等待确认）

这样做的好处：

• ✅ 用户不会被大量信息淹没
• ✅ 可以及时纠正方向偏差
• ✅ 每部分都能充分讨论

实战案例

案例：为博客添加标签系统

场景设定

用户输入：

我想给我的博客添加标签功能，让文章可以有多个标签，用户可以按标签筛选。

实际对话流程

步骤 1：初始需求澄清

AI: 好的，我来帮你设计标签系统。在开始之前，我想了解一些细节：

1. 标签管理方式：
   - 作者手动添加标签？
   - 允许用户提交标签建议？
   - 需要标签审核机制吗？

2. 标签特性：
   - 标签有层级关系吗（如：技术/AI/机器学习）？
   - 需要标签同义词管理吗（如：AI = 人工智能）？
   - 标签数量有上限吗？

3. 展示需求：
   - 文章列表页需要显示标签吗？
   - 需要标签云组件吗？
   - 标签页需要展示什么信息？

步骤 2：技术选型讨论

用户：标签是扁平的，没有层级。作者手动添加，不需要审核。

AI: 明白了。关于技术实现，有几个问题：

1. 数据存储：
   - 当前博客使用什么数据库？
   - 倾向于关系型（MySQL/PostgreSQL）还是文档型（MongoDB）？

2. 搜索功能：
   - 只需要精确匹配标签？
   - 需要模糊搜索/标签推荐吗？

3. SEO 考虑：
   - 每个标签需要独立的 URL 页面吗？
   - 需要生成标签 sitemap 吗？

步骤 3：设计文档生成

确认所有问题后，AI 开始生成分块设计文档：

【设计文档 - 第 1 块：数据模型】

基于我们的讨论，这是数据模型设计：

## 数据模型

### articles 表（现有）
- id
- title
- content
- created_at

### tags 表（新增）
- id (PK)
- name (UNIQUE)      # 标签名，唯一
- slug (UNIQUE)      # URL 友好的名称
- created_at

### article_tags 表（新增，关联表）
- article_id (FK)
- tag_id (FK)
- PRIMARY KEY (article_id, tag_id)

【确认说明】
- 多对多关系：一篇文章可以有多个标签，一个标签可以关联多篇文章
- 标签名唯一，避免重复
- slug 用于 SEO 友好的 URL

请确认这个设计是否符合你的需求，或需要修改？

步骤 4：迭代修改

用户：标签表还需要一个 description 字段，用于标签说明。

AI: 好的，更新后的 tags 表：

### tags 表（更新后）
- id (PK)
- name (UNIQUE)
- slug (UNIQUE)
- description (TEXT, NULLABLE)  # 新增
- created_at

【继续第 2 块：API 设计】
...

步骤 5：设计完成

所有块确认后，设计文档被保存，准备进入 planning 阶段。

最佳实践

对用户（你）的建议

1. 充分回答问题

✅ 好：详细说明需求和约束
❌ 差："随便"、"都可以"

示例：
✅ "需要支持 1000 QPS，延迟<100ms"
❌ "性能要好"

2. 主动提出约束

- 时间约束："这个功能需要在下周上线"
- 技术约束："只能用现有的 MySQL，不能引入新数据库"
- 资源约束："只有我一个人维护，需要简单"

3. 质疑设计决策

- "为什么选择这个方案？"
- "有没有更简单的做法？"
- "这个设计的扩展性如何？"

对 AI 的建议（通过配置）

1. 设置上下文

brainstorming:
  context:
    project_type: "personal-blog"
    team_size: 1
    tech_stack: ["Hugo", "MySQL"]
    constraints:
      - "不能引入新的数据库"
      - "需要兼容现有主题"

2. 定义问题深度

brainstorming:
  question_depth: "medium"  # shallow/medium/deep
  # shallow: 3-5 个问题
  # medium: 8-12 个问题
  # deep: 15+ 个问题，完整设计审查

3. 配置设计文档详细程度

brainstorming:
  design_doc:
    detail_level: "standard"  # minimal/standard/comprehensive
    include_diagrams: true
    include_api_spec: true

常见问题

Q1: brainstorming 太慢了，能不能跳过？

答：不建议跳过，但可以优化：

# 快速原型模式
brainstorming:
  mode: rapid
  max_questions: 5
  design_doc: minimal

但请记住：前期省下的时间，后期会加倍还回去。

Q2: AI 问的问题太基础怎么办？

答：主动提供上下文：

我想添加标签功能。先说明一下背景：
- Hugo 静态博客
- MySQL 数据库
- 个人使用，QPS<10
- 不需要评论、用户系统

基于这些，我们直接讨论标签设计？

Q3: 设计文档太长，看不完

答：要求 AI 简化：

请简化设计文档，只保留核心部分，细节可以在实现时讨论。

或者配置：

brainstorming:
  design_doc:
    max_length: "2 pages"
    focus_on: ["data_model", "api"]

Q4: brainstorming 后 AI 还是直接写代码

答：检查以下配置：

# 确保 enforce_design_first 启用
superpowers:
  enforce_design_first: true
  require_design_approval: true

设计文档保存位置

brainstorming 完成后，设计文档会保存在：

.project/designs/
└── feature-<name>-<date>.md

例如：

.project/designs/
└── feature-tag-system-2026-02-28.md

可以通过以下命令查看历史设计：

ls .project/designs/
cat .project/designs/feature-tag-system-2026-02-28.md

与其他技能的协作

brainstorming → writing-plans

设计确认后，自动触发 writing-plans 技能：

brainstorming 完成
    ↓
自动触发 writing-plans
    ↓
生成原子化实现任务

brainstorming → using-git-worktrees

开始实现前，自动触发 worktree 创建：

准备开始实现
    ↓
自动触发 using-git-worktrees
    ↓
创建隔离开发环境

小结

brainstorming 技能的核心价值：

1. 强制思考 - 不让 AI 直接跳进代码
2. 需求澄清 - 通过提问挖掘真实需求
3. 设计文档 - 留下可追溯的设计决策
4. 用户确认 - 每步都需要你的批准

关键要点

• ✅ brainstorming 在写代码之前自动触发
• ✅ 苏格拉底式提问是核心方法
• ✅ 设计文档分块确认，避免信息过载
• ✅ 设计文档被保存，可追溯决策历史

系列导航：

• ← 上一篇：教程 1：Superpowers 入门与安装
• → 下一篇：教程 3：writing-plans - 编写可实现的技术方案
• 返回：教程系列索引