SDD Brainstorming

在实现任何新功能、构建组件、添加功能或修改行为之前必须使用。用于在实现前探索用户意图、需求和设计。

Install

openclaw skills install @mahingbun-dev/sdd-brainstorming

SDD Brainstorming — 头脑风暴与设计

Overview

通过协作对话使用 AskUserQuestionTool 将想法转化为完整的设计和规格说明。

首先检查模型，然后确定意图（新建或更新），了解当前项目背景，提出问题（每次最多 2 个相关问题）以完善想法。理解要构建的内容后，展示设计并获取用户批准，然后撰写设计文档。

关键概念

工作区 (Workspace)： 通过 .sdd-workspace 配置文件中 workspace_path 指定的根目录
Spec 目录： 所有 SDD 文档存储在 {workspace}/spec/ 下

Step 0: 读取工作区配置

在任何操作之前，必须读取工作区配置：

检查当前 OpenClaw workspace 中是否存在 .sdd-workspace
如果存在，读取 workspace_path 作为工作区根目录 {workspace}
如果不存在，显示错误："请先运行 /sdd-global-init 初始化工作区。" 并停止

验证工作区目录存在，如果不存在提示用户重新初始化。

在展示设计并获得用户批准之前，**不要**调用任何实现技能、编写任何代码、搭建任何项目或采取任何实现行动。这适用于每个项目，无论看似多么简单。

反模式: "这太简单不需要设计"

每个项目都要经过这个过程。待办事项列表、单功能工具、配置更改——都是如此。"简单"项目是未经审视的假设造成最多浪费工作的地方。设计可以很短（对于真正简单的项目只需几句话），但你必须展示并获得批准。

清单

你必须为每个项目创建任务并按顺序完成：

模型检查 — 检测当前模型是否为 Opus（检查 system prompt 中的模型信息）；如果不是 Opus，输出纯文本建议（非阻塞：无论如何都继续）
确定意图 — 使用 AskUserQuestionTool 询问："新建需求" 或 "更新已有需求"
- 新建需求: 扫描 {workspace}/spec/ 中与今天日期匹配的现有 feature_YYYYMMDD_* 文件夹，找到最大序列号，自动生成下一个 YYYYMMDD_F{NNN}，然后 AI 生成 kebab-case 主题（最多 5 个词）并通过 AskUserQuestionTool 让用户确认/修改
- 更新已有需求: 扫描 {workspace}/spec/ 中所有 feature_* 文件夹；如果 ≤4 个，作为 AskUserQuestionTool 选项列出；如果 >4 个，显示最近的 3-4 个作为选项（用户可通过 "Other" 输入）
检查现有文档 — 检查 {workspace}/spec/feature_YYYYMMDD_FNNN_topic/spec-design.md 是否存在；如果存在，读取它
探索项目背景 — 检查文件、文档、最近的提交
- 如果 {workspace}/spec/global/ 存在: a. 读取 {workspace}/spec/global/constraints.md 了解架构约束（新功能必须遵守） b. 读取 {workspace}/spec/global/index.md 了解已完成功能的全貌 c. 读取相关的 {workspace}/spec/global/domains/*.md 了解该领域的现有决策
- 将约束信息作为新功能设计的先决条件
提出澄清问题 — 每次最多 2 个相关问题，通过 AskUserQuestionTool，了解目的/约束/成功标准
提出 2-3 种方案 — 包含权衡和你的推荐
展示设计 — 分部分展示，通过 AskUserQuestionTool 获取每个部分的批准
撰写设计文档 — 保存到 {workspace}/spec/feature_YYYYMMDD_FNNN_topic/spec-design.md
- 新文档：直接写入
- 现有文档：显示变更摘要，通过 AskUserQuestionTool 确认，然后覆盖
生成设计配图 — 撰写文档时，收集需要视觉说明的部分的配图规格（使用下面的两层触发规则）；写完后，启动一个后台子代理批量生成所有配图 via /gen-image；保存到 {workspace}/spec/feature_YYYYMMDD_FNNN_topic/images/，在 spec-design.md 中用 ![alt](./images/NN-type.png) 引用

流程图

dot

digraph brainstorming {
    "Model check" [shape=box];
    "Determine intent\n(new/update)" [shape=diamond];
    "Auto-generate ID + confirm topic" [shape=box];
    "Select existing feature" [shape=box];
    "Check existing doc" [shape=box];
    "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];
    "Generate design images" [shape=doublecircle];

    "Model check" -> "Determine intent\n(new/update)";
    "Determine intent\n(new/update)" -> "Auto-generate ID + confirm topic" [label="new"];
    "Determine intent\n(new/update)" -> "Select existing feature" [label="update"];
    "Auto-generate ID + confirm topic" -> "Check existing doc";
    "Select existing feature" -> "Check existing doc";
    "Check existing doc" -> "Explore project context";
    "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" -> "Collect image specs";
    "Collect image specs" -> "Launch subagent\n(batch gen images)" [label="background"];
    "Launch subagent\n(batch gen images)" [shape=doublecircle];
}

终止状态是在写完设计文档后启动后台子代理生成配图。 主流程不等待子代理完成。立即向用户输出纯文本消息（中文），建议下一步：/sdd-writing-plans。不要自动 git commit。

过程详解

模型检查:

检查 system prompt 中的模型信息（例如 "powered by the model named Opus" 或包含 "opus" 的模型 ID）

如果不是 Opus：输出以下纯文本消息并立即继续（非阻塞）：

text

⚠️ 当前模型不是 Opus，建议切换到 Opus 以获得最佳头脑风暴质量。输入 /model 切换模型。

确定意图并生成 feature ID:

使用 AskUserQuestionTool 询问：新建需求 or 更新已有需求
新建需求流程:
1. 获取今天的日期，格式为 YYYYMMDD
2. 扫描 spec/ 目录中匹配 feature_YYYYMMDD_F*（相同日期）的文件夹
3. 找到最高的序列号，加 1（如果没有则从 F001 开始）
4. AI 根据用户描述生成 kebab-case 英文主题标签（最多 5 个词）
5. 使用 AskUserQuestionTool 展示生成的 ID 和主题让用户确认（例如 "feature_20260302_F001_auth-system"）
更新已有需求流程:
1. 扫描 spec/ 中所有 feature_* 目录
2. 如果 ≤4 个 feature：作为 AskUserQuestionTool 选项列出全部
3. 如果 >4 个 feature：显示最近的 3-4 个作为选项；用户可通过 "Other" 输入完整名称
4. 对于更新，保留文件夹名称中的原始 YYYYMMDD 日期
确定 feature 文件夹后，检查 {workspace}/spec/feature_YYYYMMDD_FNNN_topic/spec-design.md 是否已存在
如果存在，读取现有文档——稍后你将与新的头脑风暴结果进行智能合并

理解想法:

首先查看当前项目状态（文件、文档、最近提交）
如果 {workspace}/spec/global/ 存在，读取 {workspace}/spec/global/constraints.md、{workspace}/spec/global/index.md 和相关的 {workspace}/spec/global/domains/*.md 了解现有架构约束和已完成功能——新设计必须与这些约束保持一致；如果需要新的/更改的约束，在设计文档中明确标注
通过 AskUserQuestionTool 提问以完善想法
每次最多 2 个相关问题——将密切相关的问题分组
尽量使用多项选择问题，但也接受开放式问题
聚焦于理解：目的、约束、成功标准

探索方案:

提出 2-3 个不同的方案，包含权衡
对话式展示选项，包含你的推荐和理由
先说出你的推荐选项并解释原因

展示设计:

一旦你认为理解了要构建的内容，就展示设计
每个部分的内容量根据复杂程度调整：如果直接则几句话，如果细微则多达 200-300 词
每个部分后使用 AskUserQuestionTool 询问是否看起来正确
如果有不清楚的地方，准备好回去澄清

写文档:

用中文写设计文档到 {workspace}/spec/feature_YYYYMMDD_FNNN_topic/spec-design.md
使用下面的设计文档模板
如果更新现有文档：首先向用户展示变更摘要，使用 AskUserQuestionTool 获得确认，然后用智能合并的内容覆盖文件
如果创建新文档：直接写入
不要 git commit。

生成设计配图:

两层触发系统——AI 决定哪些部分需要配图，不需要用户确认，配图数量无上限：

强制（必须生成）:

UI/UX 内容：页面布局、交互流程、线框图
数据流：多系统或多模块数据流图
状态机：状态转换图
系统架构：组件/服务架构图

建议（AI 根据信息密度判断）:

3 个以上实体交互，或存在条件分支/状态转换
8-10 行以上纯文本描述的概念，无视觉辅助
嵌套列表、多层表格或其他复杂结构化数据

配图类型 style mapping：

配图类型	Style prefix	宽高比
UI 交互流	Clean flat flowchart, minimal	`16:9`
页面布局/线框图	Figma-style wireframe	`3:4` 或 `9:16`（竖屏）/ `16:9`（横屏）
架构/数据流	Technical diagram, vector style	`16:9`
概念图示	Flat design, soft pastel	`1:1` 或 `16:9`
状态机/状态转换	Clean flat state diagram, rounded nodes with arrows, minimal	`16:9`
实体关系图	Technical ER diagram, vector style, standard entity notation	`16:9`

配图生成工作流：

撰写 spec-design.md 时，在需要配图的位置（根据上述触发规则）插入 ![描述](./images/NN-type.png) 占位符引用
收集配图规格 —— 撰写时为每个占位符记录：描述、配图类型、style prefix、宽高比
写完文档后，启动一个单独的后台子代理（使用 Agent tool，run_in_background: true），通过为每个规格调用 /gen-image 批量生成所有配图
不要等待子代理完成——立即继续到完成消息

子代理 prompt 模板：

Generate the following design images for {workspace}/spec/feature_YYYYMMDD_FNNN_topic/images/. For each image, call /gen-image with the specified parameters. Images: [list of {filename, description, style_prefix, aspect_ratio}]

通用配图参数：

配图中的文字：添加约束 Text labels in Simplified Chinese unless technical English terms
分辨率：1K（草稿质量）
宽高比：AI 根据上表根据内容类型选择
命名：NN-type.png（例如 01-flow.png, 02-wireframe.png, 03-state.png, 04-er.png）
输出路径：{workspace}/spec/feature_YYYYMMDD_FNNN_topic/images/NN-type.png

启动子代理后，向用户输出（中文）："✅ 设计文档已写入 {workspace}/spec/feature_YYYYMMDD_FNNN_topic/spec-design.md，配图正在后台生成中（完成后会通知）。\n\n建议下一步：运行 /sdd-writing-plans 生成执行计划。"

设计文档模板

设计文档用中文撰写。"方案设计" 部分没有固定的子部分——根据功能需要动态组织（例如架构、API 设计、数据模型、用户场景、交互流程等）。

markdown

# Feature: YYYYMMDD_FNNN - topic

## 需求背景
描述当前的问题或动机，为什么需要这个 feature。

## 目标
- 核心目标 1
- 核心目标 2

## 方案设计
（根据需求项目情况，动态增加子章节，如架构设计、接口设计、数据模型、用户场景与交互流程等）

> 在适合的章节中插入设计配图：`![描述](./images/NN-type.png)`

## 实现要点
关键技术决策、难点、依赖。

## 约束一致性
说明本方案与 `{workspace}/spec/global/constraints.md` 中架构约束的一致性。如有新增或变更约束，在此标注。
（如 `{workspace}/spec/global/` 不存在则省略此章节）

## 验收标准
- [ ] 标准 1
- [ ] 标准 2

关键原则

开始时检测模型 - 检查模型，如果不是 Opus，输出纯文本建议；非阻塞，始终继续
所有交互使用 AskUserQuestionTool - 永远不要用纯文本提问；始终使用结构化工具
自动生成 feature ID - 日期 + 零填充序列号 + AI 生成的主题；用户通过 AskUserQuestionTool 确认
每次最多 2 个相关问题 - 将密切相关的问题分组，但不要让人应接不暇
尽量使用多项选择 - 比开放式问题更容易回答
设计文档用中文 - 设计文档始终用中文撰写
现有文档智能合并 - 读取旧文档，将新头脑风暴内容合并，用合并内容重写整个文档
两层配图触发规则 + 后台生成 — 强制配图针对 UI/UX、数据流、状态机、架构；建议配图当信息密度高时（3 个以上实体交互、8 行以上文本、复杂结构）；撰写时收集规格，然后启动单个后台子代理通过 /gen-image 批量生成所有配图，不阻塞主流程
彻底 YAGNI - 从所有设计中删除不必要的功能
探索替代方案 - 在确定之前总是提出 2-3 个方案
增量验证 - 分部分展示设计，获得批准后再继续
保持灵活 - 有不清楚的地方回去澄清