Superpowers 实战指南 | 第2期 - 头脑风暴：在写代码前先把设计想明白

🧠 "你确定要这么做吗？" —— 每个优秀的技术合伙人在你冲动写代码前都会问的第一句话。Superpowers 的 brainstorming 技能就是那个帮你踩刹车、理思路、出方案的智慧伙伴。

---

为什么"想清楚再写"如此重要？

一个典型的悲剧

你：帮我做一个实时聊天系统。
AI：好的，我这就开始实现...（哗哗写了 800 行代码）
你：（三小时后）等等，我要的是类似 Slack 的频道模式，不是一对一私聊……
AI：好的，让我重构……（又哗哗写了 600 行）
你：（又过两小时）这个 WebSocket 怎么老断线？重连逻辑呢？
AI：呃，当时没考虑到这个需求……

结果：5 个小时的工作，70% 需要推倒重来。

Superpowers 的做法

Superpowers 有一条硬性门槛（Hard Gate）：

在设计被用户批准之前，
不允许写任何代码、创建任何文件、执行任何实现动作。
无论项目看起来多简单。没有例外。

这不是建议，是铁律。

---

brainstorming 的完整流程

当你说出"我想做一个 XXX 功能"时，brainstorming 技能自动激活，开始以下流程：

┌───────────────────────────────────────┐
│ Step 1: 探索项目上下文                 │
│ 读取文件结构、文档、最近的 Git 提交     │
└──────────────┬────────────────────────┘
               ↓
┌───────────────────────────────────────┐
│ Step 2: 评估是否需要可视化伴侣         │
│ 如果涉及 UI 设计，提供浏览器可视化     │
└──────────────┬────────────────────────┘
               ↓
┌───────────────────────────────────────┐
│ Step 3: 逐个提问澄清需求               │
│ 每次只问一个问题，优先选择题           │
└──────────────┬────────────────────────┘
               ↓
┌───────────────────────────────────────┐
│ Step 4: 提出 2-3 种方案及权衡分析       │
│ 带推荐理由，让你做选择                 │
└──────────────┬────────────────────────┘
               ↓
┌───────────────────────────────────────┐
│ Step 5: 分段展示设计方案                │
│ 每段确认一次，确保你真正理解了          │
└──────────────┬────────────────────────┘
               ↓
┌───────────────────────────────────────┐
│ Step 6: 编写设计文档并提交到 Git        │
│ 保存到 docs/superpowers/specs/         │
└──────────────┬────────────────────────┘
               ↓
┌───────────────────────────────────────┐
│ Step 7: 设计文档自审查                  │
│ 扫描占位符、矛盾、模糊需求             │
└──────────────┬────────────────────────┘
               ↓
┌───────────────────────────────────────┐
│ Step 8: 用户审阅设计文档                │
│ 修改 → 重新审查 → 直到用户满意         │
└──────────────┬────────────────────────┘
               ↓
┌───────────────────────────────────────┐
│ Step 9: 交接到 writing-plans            │
│ 进入下一阶段：编写实施计划             │
└───────────────────────────────────────┘

---

实战演示：从模糊想法到清晰设计

场景：为博客添加搜索功能

你说：

我想给我的博客加一个搜索功能。

Round 1：探索上下文

AI 首先会悄悄看一下你的项目：

🧠 [Brainstorming] 探索项目上下文...
- 技术栈：Next.js 14 + Tailwind CSS + Supabase
- 文章数量：articles 表约 150 条记录
- 现有导航：Header 包含 Logo、首页、关于 三个链接
- 最近提交：3 天前添加了文章分类功能

Round 2：逐个提问

AI 不会一次性抛出 5 个问题，而是一个一个来：

AI 第一个问题：

搜索功能有几种常见模式，你倾向于哪种？

A) 📍 即时搜索 —— 在导航栏嵌入搜索框，输入即搜索，类似 Notion
B) 📍 搜索页面 —— 单独的 /search 页面，有筛选和排序功能
C) 📍 命令面板 —— Cmd+K 呼出搜索面板，类似 VS Code / Linear

我推荐选 C（命令面板），理由是：
- 你的文章量 150 篇，不需要复杂筛选
- 用户体验最优雅，不占据导航栏空间
- 实现成本适中，Next.js 有很多成熟方案

你回答： C，同意。

AI 第二个问题：

搜索范围包括哪些内容？

A) 只搜标题
B) 搜标题 + 正文内容
C) 搜标题 + 正文 + 标签/分类

建议选 B 起步。理由是搜正文能发现用户真正想找的内容，
而标签搜索可以后续通过分类导航来替代。

你回答： B，同意。

AI 第三个问题：

搜索引擎选什么？你的 150 篇文章有以下方案可选：

A) Supabase 全文搜索（PostgreSQL tsvector）
   - 优点：零额外依赖，你已经用了 Supabase
   - 缺点：中文分词需要额外配置
   
B) 前端静态搜索（FlexSearch / Fuse.js）
   - 优点：零服务端成本，离线可用
   - 缺点：文章多了性能下降，需构建时生成索引
   
C) Algolia / Meilisearch
   - 优点：搜索体验极佳，支持模糊匹配
   - 缺点：引入第三方依赖，有成本

我推荐选 A（Supabase 全文搜索），理由是：
- 你已经在用 Supabase，零额外依赖
- 150 篇文章完全在 PostgreSQL 能力范围内
- 后续可以平滑迁移到更强的方案

你回答： A，同意。

Round 3：展示设计方案

经过 3 轮提问（实际可能更多），AI 已经收集到足够信息，开始分段展示设计：

设计 - Part 1：架构概览

## 搜索功能架构

### 组件结构
App
├── SearchDialog          ← 新增：Cmd+K 搜索面板
│   ├── SearchInput       ← 搜索输入框（自动聚焦）
│   └── SearchResults     ← 搜索结果列表（虚拟滚动）
└── Header
    └── SearchTrigger     ← 新增：导航栏搜索图标

### 数据流
用户按 Cmd+K → 打开 SearchDialog → 输入关键词 
→ 防抖 300ms → 调用 /api/search → 
Supabase 全文搜索 → 返回结果 → 渲染列表

这部分看起来 OK 吗？

你回答： OK。

设计 - Part 2：数据库变更

### 数据库变更

-- 添加全文搜索向量列
ALTER TABLE articles 
ADD COLUMN search_vector tsvector 
GENERATED ALWAYS AS (
  to_tsvector('english', coalesce(title, '') || ' ' || coalesce(content, ''))
) STORED;

-- 创建 GIN 索引加速搜索
CREATE INDEX idx_articles_search ON articles USING GIN(search_vector);

⚠️ 注意：当前使用 'english' 字典。如果需要支持中文搜索，
后续需要安装 zhparser 扩展。MVP 阶段先支持英文搜索。

这部分看起来 OK 吗？

你回答： OK，MVP 先英文没问题。

Round 4：写入设计文档

确认完毕后，AI 将完整设计写入文件并提交：

🧠 [Brainstorming] 设计文档已保存到：
   docs/superpowers/specs/2025-04-21-blog-search-design.md

🧠 [Brainstorming] 自审查中...
   ✅ 无占位符（TBD/TODO）
   ✅ 各章节无矛盾
   ✅ 范围适合单个实施计划
   ✅ 无歧义需求

🧠 [Brainstorming] 已提交到 Git。
   请审阅设计文档，确认无误后我将开始编写实施计划。

---

可视化伴侣：让设计讨论"看得见"

当 brainstorming 涉及 UI 设计问题时，AI 会主动提供可视化伴侣：

AI: 我们接下来的讨论会涉及一些需要"看"才好判断的东西。
    我可以在浏览器中展示线框图、布局方案和 UI 对比。
    这个功能还在实验阶段，会消耗一些额外 token。
    要试试吗？（需要打开一个本地 URL）

如果你同意，AI 会在浏览器中直接渲染：

• 线框图 / Wireframe
• 布局方案对比（A/B/C 方案并排展示）
• 架构图（Mermaid 图表）
• 组件层级关系图

💡 智能判断：不是所有问题都会用浏览器。"搜索引擎选哪个"这种概念性问题用文字就够了。只有"搜索面板的布局用全屏还是居中弹窗"这类视觉问题，才会调用浏览器。

---

关键设计原则

brainstorming 背后贯彻了几条重要的工程理念：

1. YAGNI（You Aren't Gonna Need It）

❌ "再加个搜索历史记录功能吧"
→ Brainstorming 会说：150 篇文章需要搜索历史？先上线再看数据。

❌ "支持中文和英文双语搜索"
→ Brainstorming 会说：MVP 先支持一种语言。你的用户主要说什么语？

2. 设计为隔离性服务

✅ 好的设计：每个单元有一个清晰的职责、可以被独立理解和测试
❌ 差的设计：所有逻辑都塞在一个 500 行的文件里

3. 一次只问一个问题

❌ "你想用什么技术栈？数据库用什么？要不要响应式？支持多语言吗？"
→ 用户被 4 个问题淹没，回答质量下降

✅ "你倾向于 A/B/C 哪种搜索模式？"
→ 一个问题，集中选择，然后继续下一个

4. 大项目必须拆解

如果你的需求是"做一个 SaaS 平台，带用户系统、计费、分析和聊天"，Brainstorming 不会帮你设计一个巨型方案。它会：

AI: 这个项目包含 4 个独立子系统。我建议先拆解：
    1. 用户系统（核心基础设施）
    2. 聊天功能（核心业务）
    3. 计费系统（变现能力）
    4. 数据分析（增长引擎）

    先从"用户系统"开始 brainstorming，
    后面每个子系统走一轮独立的 设计 → 计划 → 实现 循环。
    先做哪个？

---

与 GStack /plan-ceo-review 的对比

维度	GStack /plan-ceo-review	Superpowers brainstorming
角色定位	CEO——砍需求	技术合伙人——探索需求
对话模式	你给清单，CEO 直接批复	逐个问答，一起共创
输出物	评审报告	完整设计文档，包含架构、组件、数据流
是否有可视化	❌	✅ 可视化伴侣
交互深度	单轮评审	多轮，每段设计都要确认
后续衔接	需要手动调用 eng-review	自动 衔接到 writing-plans

---

实战技巧

技巧一：拥抱"一次只问一个"

不要着急。Brainstorming 问的每个问题都是在帮你避免后面的返工。耐心回答，比匆忙开始写代码要快得多。

技巧二：主动提出约束条件

我想做一个搜索功能。
约束条件：
- 不能引入新的外部依赖
- 必须在 2 天内完成
- 不需要支持模糊搜索

约束越明确，AI 的方案越精准。

技巧三：对设计文档较真

当 AI 写出设计文档后，仔细看。发现模糊的地方立刻提出来。现在改设计文档的成本，只有改代码成本的 1/10。

---

小结

▪️ brainstorming 是 Superpowers 全流程的起点——没有通过的设计，就不允许写代码 ▪️ 逐个问答的对话模式，确保每个设计决策你都真正理解了 ▪️ 自动生成并提交设计文档，配有自审查机制（扫描占位符、矛盾、歧义） ▪️ 可视化伴侣让 UI 设计讨论"看得见" ▪️ 大项目自动拆解为子系统，每个子系统独立走完整流程

在下一篇文章中，我们将进入写完设计后的关键一步：writing-plans 编写实施计划——如何把一个设计拆成傻瓜都能执行的原子任务。

---

好了，本期的内容到这里就结束了，如果你觉得对你有帮助的话，欢迎点赞、在看、转发，我们下期见！Bye~

---

📝 作者：NIHoa ｜ 系列：Superpowers实战指南系列 ｜ 更新日期：2025-04-21