写设计文档最惨的瞬间，是需求评审结束，架构师突然举手：“咦，我们刚才是按单用户还是多用户设计的？”
全场沉默，工时翻倍。
为了杜绝这种尴尬，我把一份AI工作流模板塞进自家项目，规定：
任何新功能，先让AI问三轮，再生成设计文档。
两周下来，返工率从30%降到5%，评审时长砍半。模板只有一页，却救了整组人的周末。

01 先复述，再追问，最多一句

用户说：“我要一个浏览器里做Markdown幻灯片。”
AI先复述：“目标是把Markdown实时渲染成幻灯片，对吗？”
用户点头。
AI只追问一句：“需要多人同时改同一页吗？”
如果答案是否，实时协同、OT算法、WebSocket、Redis整条支线当场砍掉，省掉三天调研。
一句问题，锁定架构主航道。

02 每轮只问三个“会推翻方案”的问题

接下来AI像老练的架构师，心中维护“设计假设状态”，每轮只抛三个能直接影响技术选型的问题：

  • 导出格式只要HTML？→PDF、PPT两条线直接砍。
  • 主题数量≤10？→CSS变量搞定，不必上PostCSS。
  • 幻灯片比例固定16:9？→Renderer不用做响应式断点。

问完立即更新假设，避免重复。
三轮结束，技术栈从“无限可能”缩到“单页WebComponents+Markdown-it”，工程师拿到手就能估排期。

03 用户点头那一刻，才一次性出文档

很多AI工具边聊边写，结果文档里全是“如果、可能、待定”。
我们反着来：AI先汇总所有假设，一次性问用户：
“单用户、无后端、导出HTML、主题≤10套，这些前提能接受吗？”
用户说“可以”，AI才瞬间生成/specs/xxx.md，包含：

  • 一张Mermaid架构图
  • 各组件接口签名
  • 错误降级路径
  • 被砍掉的方案及原因

评审会上，工程师只挑细节，不再质疑“为啥用Redis”这种基础问题，会议时间从55分钟缩到25分钟。

04 三不原则，防止AI“手痒”写代码

  1. 不写requirements.md——需求归产品经理，AI只管设计。
  2. 不写tasks.md——排期归项目经理，AI不抢活。
  3. 不给代码片段——防止把评审拖进Tab还是Space的无聊争论。

设计阶段只谈设计，代码留给键盘。

05 两周实战数据

功能点：Markdown幻灯片编辑器

指标 旧流程 新流程 降幅
返工率 30% 5% 83%
评审时长 55分钟 25分钟 54%
文档页数 18页（大量待定） 6页（全部可执行） 66%

最开心的声音来自测试同学：“终于不用在提测当天才知道‘原来还有协同冲突’。”

06 把模板搬进你的仓库，只需三步

  1. 建文件夹specs/
  2. 在 AI 对话时引用文件，再问问题
  3. Code Review时，先看spec.md是否更新，再读代码

规则一旦透明，AI就成了最守纪律的架构师。

07 小结：问得少，才能做得对

人类架构师的价值，不是画大图，而是先问清关键假设。
让AI学会这个习惯，工程师就能少加无意义的班。
下次需求来了，记得先让AI问三句，再写设计文档——
问得少，返工少，下班早。

08 附件：完整模板下载

# 设计文档生成工作流（逐步询问版）

目标：
通过“最少但必要的逐步提问”，澄清关键设计不确定性，
最终生成一份完整、工程可执行参考价值的设计文档。

本工作流仅生成设计文档，不涉及需求文档、实施计划或代码实现。

---

## 核心约束

- 模型必须创建以下文件（若不存在）：
  'specs/{feature_name}.md`

- 模型不得生成 requirements.md 或 tasks.md
- 模型不得编写任何实现代码
- 模型必须先完成**设计澄清阶段**，再生成设计文档
- 不允许一次性抛出大量问题

---

## 工作流阶段划分

### 阶段 1：初步理解（不提问或最多 1 个问题）

- 模型首先基于用户输入：
  - 复述功能目标
  - 提出一个**初步设计方向概要**
- 若功能目标明显不完整，可提出 **最多 1 个关键问题**
- 不生成 设计文档

---

### 阶段 2：逐步设计澄清（多轮）

- 模型必须：
  - 每一轮 **只询问 1–3 个高价值问题**
  - 问题必须直接影响架构、边界或技术选型
- 禁止询问：
  - UI 细节
  - 实现层代码风格
  - 非设计层的业务流程
- 若用户不确定：
  - 提供 2–3 个可选方案供选择
- 模型需在心中维护“设计假设状态”，避免重复提问

示例问题类型：
- 使用场景是否偏向单用户还是多用户？
- 是否需要持久化存储？规模预期？
- 运行环境约束（本地 / 服务端 / 浏览器）？

---

### 阶段 3：设计收敛确认

- 当模型判断：
  - 核心架构不确定性已消除
- 模型必须明确询问用户一次：

  “这些设计前提是否可以接受？如果可以，我将生成完整设计文档。”

- 仅在用户明确同意后，进入下一阶段

---

### 阶段 4：设计文档生成

- 模型创建并填充：
  `specs/{feature_name}.md`

---

## 设计文档内容要求（design.md）

设计文档必须至少包含以下章节：

### 1. 概述（Overview）
- 功能目标
- 设计范围（包含 / 不包含）
- 关键假设

### 2. 架构设计（Architecture）
- 整体结构
- 核心模块划分
- 技术或模式选型理由
- 可选：Mermaid 架构图

### 3. 组件与接口（Components & Interfaces）
- 各组件职责
- 组件交互关系
- 对外 / 对内接口定义（概念级）

### 4. 数据模型（Data Model）
- 核心数据结构
- 状态与生命周期
- 数据流向

### 5. 错误处理与边界情况
- 主要异常路径
- 失败与降级策略

### 6. 测试与验证策略
- 设计层面的可测试性
- 建议的测试类型与重点

### 7. 设计决策与权衡
- 关键选择
- 被放弃的方案及原因
- 已知限制

### 8. 未决问题（如有）
- 不影响当前设计生成，但需后续确认的问题

---

## 行为准则

- 优先通过提问减少假设，而不是在文档中堆“可能”
- 提问数量应随不确定性递减
- 当不确定性不足以阻塞架构时，应果断进入设计生成
- 设计文档应“可直接交给工程师评审”

---

## 完成条件

- 设计文档 已生成
- 在对话中明确提示用户：
  “设计文档已生成，如需调整请指出。”

拿去改，拿去用，让下一篇设计文档少写“待定”。