brainstorming

将构想转化为设计

概述

通过自然、协作式的对话，帮助将构想转化为完善的设计和规格说明。

首先了解当前项目的上下文，然后一次提出一个问题，逐步完善构想。了解要构建的内容后，呈现设计并征求用户批准。

为什么要先设计？

在实施前呈现设计，可以避免几种代价高昂的问题：

• 假设不一致 — 朝错误目标编写代码，之后纠正的成本很高
• 范围蔓延 — 设计能明确边界；没有设计就开始实施，容易导致功能膨胀
• 架构返工 — 早期代码往往会造成结构性债务，并不断累积
• 专业技能浪费 — 实施技能虽然强大，但没有明确方向时也会造成浪费

这适用于所有项目，包括简单项目。待办事项列表、单功能实用工具或配置变更，都可能最终交付错误的成果。简单项目的设计可以简洁一些（几句话即可），但必须在开始实施前完成并获得批准。

反模式：“这太简单了，不需要设计”

详细的问题模式和预防步骤，请参阅下文的常见陷阱 1。

工作流

按以下阶段系统地推进。每一步都建立在前一步的基础上：

1. 了解项目上下文 — 检查文件、文档和近期提交，确保对话基于实际情况
2. 提出澄清问题 — 一次一个，了解目的、约束和成功标准
3. 提出 2-3 种方案 — 说明权衡，并给出你的建议，以表明你考虑过其他方案
4. 呈现设计 — 根据复杂程度分节呈现，并在每节之后征求用户批准
5. 撰写设计文档 — 保存到 docs/plans/YYYY-MM-DD-<topic>-design.md，并提交以保留决策记录
6. 过渡到实施 — 调用 writing-plans 技能，制定详细的实施计划

流程图

digraph brainstorming {
    "Explore project context" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "Present design sections" [shape=box];
    "User approves design?" [shape=diamond];
    "Write design doc" [shape=box];
    "Invoke writing-plans skill" [shape=doublecircle];

    "Explore project context" -> "Ask clarifying questions";
    "Ask clarifying questions" -> "Propose 2-3 approaches";
    "Propose 2-3 approaches" -> "Present design sections";
    "Present design sections" -> "User approves design?";
    "User approves design?" -> "Present design sections" [label="no, revise"];
    "User approves design?" -> "Write design doc" [label="yes"];
    "Write design doc" -> "Invoke writing-plans skill";
}

下一步是调用 writing-plans，从设计阶段进入详细规划。其他实施技能（frontend-design、mcp-builder 等）应在计划编写完成后再使用。按此顺序推进，可确保实施计划本身已通过验证，能够有效指导工作。

流程

理解构想：

• 首先检查当前项目状态（文件、文档和近期提交）
• 一次提出一个问题，逐步完善构想
• 尽可能优先使用选择题，但也可以提出开放式问题
• 每条消息只问一个问题——如果某个主题需要进一步探讨，就拆分成多个问题
• 重点了解目的、约束和成功标准

探索方案：

• 提出 2-3 种不同方案，并说明各自的权衡
• 以自然对话的方式呈现选项，并给出你的建议和理由
• 先介绍你推荐的方案，再解释原因

呈现设计：

• 确认已了解要构建的内容后，呈现设计
• 根据每部分的复杂程度调整篇幅：简单内容用几句话，复杂内容可写 200-300 词
• 每完成一部分，都询问目前看来是否合适
• 涵盖架构、组件、数据流、错误处理和测试
• 如果有不清楚的地方，准备好回头澄清

设计完成后

文档：

• 将经过验证的设计写入 docs/plans/YYYY-MM-DD-<topic>-design.md （如果 docs/plans/ 目录不存在，则创建该目录：mkdir -p docs/plans）
• 将设计文档提交到 git

实施：

• 调用 writing-plans 技能，制定详细的实施计划
• 不要调用任何其他技能。下一步必须是 writing-plans。

核心原则

• 一次只问一个问题 - 不要用多个问题让对方应接不暇
• 优先选择题 - 条件允许时，选择题比开放式问题更容易回答
• 严格遵循 YAGNI 原则 - 从所有设计中移除不必要的功能
• 探索替代方案 - 确定方案前，始终提出 2-3 种做法
• 增量验证 - 展示设计，并在继续前获得批准
• 保持灵活 - 遇到不合理之处时，回头进行澄清

示例

示例 1：新增功能请求

用户：“我们来给应用添加深色模式吧”

头脑风暴工作流：

1. 检查当前主题实现
2. 询问：“深色模式应该自动启用（跟随系统偏好）、手动切换，还是两者兼有？”
3. 提出 3 种做法：CSS 变量、Tailwind dark: 类，或主题提供程序
4. 展示设计分项：调色板、组件更新、存储策略
5. 逐项获得批准
6. 将设计文档写入 docs/plans/YYYY-MM-DD-dark-mode-design.md
7. 调用 writing-plans 技能

**预期输出：**经过验证的设计文档 + 转入规划阶段

示例 2：实用函数

用户：“我需要一个格式化电话号码的函数”

头脑风暴工作流：

1. 询问：“需要支持哪些格式？（仅美国、国际格式等）”
2. 询问：“它应该验证号码，还是只负责格式化？”
3. 提出几种做法：基于正则表达式、使用库（libphonenumber），或简单的格式化器
4. 展示设计：函数签名、边界情况、错误处理
5. 获得批准
6. 编写简要设计文档
7. 调用 writing-plans

**预期输出：**即便是“简单”的实用工具，也应先进行设计

示例 3：架构变更

用户：“我们应该从 REST 迁移到 GraphQL”

头脑风暴工作流：

1. 检查当前 API 结构和客户端用法
2. 询问：“是什么促使你们这样做？性能、开发体验，还是特定功能？”
3. 询问：“这是渐进式迁移，还是一次性整体迁移？”
4. 提出 3 种做法：并行 API、基于 REST 的 GraphQL 封装，或全面重写
5. 展示设计：架构设计、迁移策略、向后兼容性
6. 逐步展示各个部分，并获得批准
7. 编写全面的设计文档
8. 调用 writing-plans

**预期输出：**包含迁移策略的多阶段设计

故障排除

问题：用户不断要求“直接动手做”

**症状：**用户想跳过头脑风暴，直接开始写代码

**原因：**认为设计阶段会给“简单”任务增加额外负担

解决方案：

1. 表示理解对方的紧迫性：“我理解你想快速推进”
2. 说明风险：“没有设计，我们可能会做出错误的东西”
3. 提议限时设计：“让我快速问 2 个问题，确认一下方案”
4. 如果用户仍然坚持，就给出最精简的设计：“这是我计划构建的内容……”
5. 继续之前，获得明确批准

问题：设计变成了实现计划

**症状：**设计文档中包含代码片段、文件结构或分步说明

**原因：**混淆了设计（做什么/为什么）和规划（如何做/何时做）

解决方案：

1. 让设计聚焦于：架构、组件、数据流、权衡
2. 将实现细节留到 writing-plans 技能中处理
3. 如果发现自己写下了“第 1 步：创建文件 X”，就停下来，转入规划阶段

问题：用户在实现过程中改变主意

**症状：**开始工作后，用户要求采用不同的行为或方案

**原因：**设计不够具体，或假设未经验证

解决方案：

1. 立即停止实现
2. 回到头脑风暴模式
3. 就新需求提出澄清问题
4. 展示修订后的设计
5. 恢复实现之前，获得明确批准
6. 根据新的决定更新设计文档

问题：陷入无休止的设计迭代

症状： 用户不断要求提供更多选项，或对所有设计都不满意。

原因： 成功标准不明确，或用户不确定自己想要什么。

解决方案：

1. 暂停一下并询问：“理想的结果应该是什么样的？”
2. 提出一个最小可行版本：“我们能构建的最小实用版本是什么？”
3. 建议制作原型：“要不要快速构建一个原型来探索这个方向？”
4. 如果仍然没有进展，建议设定时间限制：“我们先选方案 A，如果效果不佳再重新评估。”

常见陷阱

1. 因为任务“简单”而跳过头脑风暴

会发生什么： 你认为任务很直接（单个组件、小型实用工具、配置更改），于是直接开始实现，并打算在编码过程中再解决细节问题。

为何适得其反： “简单”任务中的假设最危险，因为它们看起来显而易见。你编写了一种行为，而用户期待的是另一种；等你发现时，脚手架已经搭好，需要返工。

如何避免： 把任务简单视为加快头脑风暴的理由，而不是跳过它的理由。花 30 秒交流（“这是一个只包含单个文件、用于执行 X 的实用工具，对吗？”），就能避免花 30 分钟重构。即使只是明确确认看似显而易见的内容，也很有价值。

2. 未经用户明确批准就开始编写代码

会发生什么： 你提出一个设计，用户提出澄清问题，你却把这理解为稍有兴趣，并开始编写代码，同时“思考他们的反馈”。

为何适得其反： 用户仍在评估。未经批准就编写的代码往往需要重写。设计尚未敲定，你却已经表示要继续推进。

如何避免： 等待用户明确表示批准（“看起来不错”“就按这个来”“可以发布”）后，再调用 writing-plans。只要用户提出了澄清问题，就说明设计尚未定稿——请修改后重新展示。

3. 直接调用实现技能，而不先编写计划

会发生什么： 设计获批后，你很想直接调用 frontend-design、mcp-builder 或其他实现技能，而不是先调用 writing-plans。

为何适得其反： 实现技能功能强大，但缺乏结构。提供一份明确范围、验收标准和技术决策的详细计划时，它们才能发挥最佳效果。跳过计划意味着技能必须重新制定计划，导致工作效率低下，并可能造成范围蔓延。

如何避免： 始终调用 writing-plans，作为头脑风暴与实现之间的桥梁。让它把头脑风暴中的决策整理成具体计划，供实现技能遵循。

4. 设计过于抽象，难以实现

会发生什么： 你提出的设计理念上合理，却缺少具体细节——比如只说“我们会用响应式网格展示项目”，却没有说明列数、断点或筛选方式。

为何适得其反： 由于设计没有给出答案，实现一开始就会遇到问题。最终，执行者只能猜测细节、错误实现，而你不得不再进行修改。

如何避免： 设计应足够具体，让执行者无需打开设计文档提问就能开始工作。请包含示例、具体数字、边缘情况和权衡决策。如果某个细节对你来说都不明确，那么在实现时也会同样不明确。