头脑风暴：从想法到设计

通过自然的协作对话，帮助用户将想法转化为完整的设计和规格文档。

先了解当前项目上下文，然后逐个提问来细化想法。一旦理解了要构建的内容，呈现设计方案并获得用户认可。

<HARD-GATE> 在呈现设计方案并获得用户认可之前，不要编写任何代码、搭建任何项目脚手架，或执行任何实现操作。无论项目看起来多简单，这一规则都适用。 </HARD-GATE>

反模式："这个太简单了不需要设计"

一旦触发了这个 skill，即使项目看起来很简单（一个 todo list、一个单函数工具），也要走设计流程。"简单"项目恰恰最容易因为未检验的假设而浪费工作量。设计可以很短（对于真正简单的项目只需几句话），但必须呈现并获得认可。

检查清单

必须为以下每一项创建任务，并按顺序完成：

1. 探索项目上下文 — 检查文件、文档、最近的提交
2. 适时提供可视化伴侣 — 不要一开始就提供。当某个问题用"看"比"说"更清楚时，在那个时刻提出（单独一条消息）；用户同意后为他们打开浏览器标签页。如果整个过程不需要可视化，就不要提。详见下方"可视化伴侣"章节。
3. 提出澄清问题 — 每次只问一个，理解目的/约束/成功标准
4. 提出 2-3 个方案 — 附带权衡分析和你的推荐
5. 呈现设计 — 按复杂度分节展示，每节之后获得用户认可
6. 编写设计文档 — 保存到 docs/specs/YYYY-MM-DD-<主题>-design.md 并提交
7. 规格自审 — 快速检查占位符、矛盾、歧义、范围（见下方）
8. 用户审阅规格 — 请用户审阅规格文件后再继续
9. 过渡到实现 — 创建实施计划并开始工作

流程图

探索项目上下文 → 提出澄清问题 → 提出 2-3 个方案 → 分节呈现设计
    ↓
用户认可设计？ —[否，修改]→ 返回呈现设计
    ↓ 是
编写设计文档 → 规格自审（就地修复） → 用户审阅规格？
    ↓                                      ↓ 需要修改 → 返回编写设计文档
    ↓                                      ↓ 通过
    └──────────────────────────────────── 开始实现

终态是开始实现。 用户批准规格后，创建分步实施计划并开始编码。

流程详解

理解想法：

• 先了解当前项目状态（文件、文档、最近提交）
• 在深入提问之前先评估范围：如果需求描述了多个独立子系统（例如"构建一个有聊天、文件存储、计费和分析的平台"），立即指出这一点。不要花时间细化一个需要先拆分的项目
• 如果项目对一份规格来说太大，帮助用户分解为子项目：独立的部分有哪些，它们如何关联，应该按什么顺序构建？然后对第一个子项目走正常设计流程。每个子项目有自己的 规格 → 计划 → 实现 循环
• 对范围合适的项目，逐个提问来细化想法
• 尽量使用选择题，开放式也可以
• 每条消息只问一个问题——如果某个话题需要更多探讨，拆成多个问题
• 关注：目的、约束、成功标准

探索方案：

• 提出 2-3 个不同方案及其权衡
• 以对话方式呈现选项，附带你的推荐和理由
• 先说你推荐的方案并解释为什么

呈现设计：

• 一旦你认为理解了要构建的内容，呈现设计
• 每节的详细程度与其复杂度匹配：简单的几句话，复杂的可到 200-300 字
• 每节之后询问用户是否正确
• 覆盖：架构、组件、数据流、错误处理、测试
• 准备好在某处不清楚时回头澄清

为隔离和清晰而设计：

• 将系统拆分为更小的单元，每个单元有一个清晰的职责，通过定义良好的接口通信，可以独立理解和测试
• 对每个单元，你应该能回答：它做什么，怎么使用它，它依赖什么？
• 别人能不看内部实现就理解一个单元的功能吗？能修改内部实现而不破坏使用者吗？如果不能，说明边界需要重新划分
• 更小、边界清晰的单元也更容易处理——对能在上下文中完整容纳的代码，推理更准确，编辑更可靠。当文件变得很大时，通常意味着它做了太多事

在已有代码库中工作：

• 在提出变更之前先了解现有结构。遵循现有模式
• 如果现有代码的问题影响到当前工作（例如文件过大、边界不清、职责纠缠），将针对性改进纳入设计——就像一个好开发者在工作时顺手改善接触到的代码
• 不要提出无关的重构。专注于当前目标

设计之后

文档：

• 将验证过的设计（规格）写入 docs/specs/YYYY-MM-DD-<主题>-design.md
• （用户对规格存放位置的偏好优先于此默认路径）
• 写作要清晰简洁——短句、主动语态、具体细节优于模糊概括
• 将设计文档提交到 git

规格自审： 写完规格文档后，以全新的视角审视它：

1. 占位符扫描： 有"TBD"、"TODO"、未完成的章节或模糊的需求吗？修复它们。
2. 内部一致性： 各章节之间有矛盾吗？架构与功能描述匹配吗？
3. 范围检查： 这是否聚焦到足以支撑一份实施计划？还是需要拆分？
4. 歧义检查： 有没有哪个需求可能被理解为两种意思？如果有，选定一种并明确写出。

发现问题就地修复。不需要重新审阅——修完继续。对于复杂规格，可以参考 spec-document-reviewer-prompt.md（在本 skill 目录中）派遣 subagent 进行独立审阅。

用户审阅关卡： 规格自审通过后，请用户审阅：

> "规格已编写并提交到 <路径>。请审阅，如有修改意见告诉我，没问题的话我们开始实现。"

等待用户回复。如果要求修改，修改后重新自审。只有用户认可后才继续。

实现：

• 认可后，创建详细的分步实施计划
• 将工作拆分为小的、可验证的增量
• 按计划开始实现

核心原则

• 每次只问一个问题 — 不要用多个问题轰炸用户
• 优先选择题 — 比开放式问题更容易回答
• 严格 YAGNI — 从设计中移除不必要的功能
• 探索替代方案 — 总是在确定之前提出 2-3 个方案
• 渐进验证 — 呈现设计，获得认可后再继续
• 保持灵活 — 发现不对时回头澄清

可视化伴侣

基于浏览器的伴侣工具，用于在头脑风暴中展示 mockup、图表和可视化选项。它是一个工具而非模式。接受伴侣意味着它可用于需要可视化处理的问题，并不意味着每个问题都通过浏览器。

适时提供（just-in-time）： 不要一开始就提供。等到某个问题用"看"确实比"说"更清楚——一个真正的 mockup/布局/图表问题，而不仅仅是一个涉及 UI 的话题。第一次出现这种情况时，单独发一条消息提出： > "接下来这个部分可能用看的比说的更清楚——我可以在浏览器标签页中为你展示 mockup、图表和对比。这个功能比较新，会消耗较多 token。要我开吗？"

这个提议必须是独立的一条消息。 不附带任何澄清问题、总结或其他内容。等待用户回复。如果接受，用 --open 启动服务器让浏览器自动打开。如果拒绝，继续纯文本模式，不再主动提供（除非用户主动提起）。

逐问题决策： 即使用户接受了伴侣，也要对每个问题决定是用浏览器还是终端。判断标准：用户看到它会不会比读到它理解得更好？

• 用浏览器 展示本质是视觉的内容 — mockup、线框图、布局对比、架构图、并排的视觉设计
• 用终端 展示本质是文字的内容 — 需求问题、概念选择、权衡列表、A/B/C/D 文字选项、范围决策

关于 UI 话题的问题不自动等于视觉问题。"这个上下文中'个性化'是什么意思？"是概念问题——用终端。"这两种向导布局哪个更好？"是视觉问题——用浏览器。

如果用户同意使用伴侣，在继续之前阅读详细指南： visual-companion.md（在本 skill 目录中）