Design Craft

---
name: design-craft
description: 将需求描述转化为面向技术评审的设计文档，默认拆分为父文档+子需求文档的多文档结构。适用于"写设计文档"、"生成设计方案"、"出设计"、"帮我设计"、"design doc"、"dd"、"td"等场景。仅在用户已能给出基本可读的需求描述时使用，不替代需求分析或产品设计。
---

# 设计文档生成器

## 概述

将一段较完整的需求描述转化为面向技术评审的设计文档。默认拆分为父文档+子需求文档的多文档结构（子需求为组织主轴），简单需求可走单文档快速通道。覆盖需求确认→语义分析→交互建模→拆分→大纲→填充→归档的完整流程，每个关键阶段需用户确认。

## 何时使用

仅在以下情况使用本 skill：

- 用户已经能给出**一段较完整的需求描述**（不是一句话标题）
- 用户的目标是产出一份**给小团队评审用的轻量级设计文档**
- 用户希望**结构完整但不啰嗦**

若只是粗略想法、一句话标题、或仅需问答澄清需求，**不要使用本 skill**，先帮用户把需求说清楚。

### 单文档快速通道

若需求简单判定可走单文档模式，加载 [SINGLE_DOC.md](SINGLE_DOC.md) 获取完整规范。核心规则：同时满足 4 项条件 → 跳过阶段 2.5/3 → 14 章骨架填充。

## 核心原则

1. **默认多文档**：除非同时满足全部简单条件，否则强制拆分为父文档+子需求文档。单文档可能掩藏复杂度
2. **子需求为轴**：术语、决策、接口均归属到对应子需求，不设全局汇总章混淆归属
3. **前置成熟度判定**：上下文已有充分讨论时，跳过阶段 1/2，减少已有内容的复述
4. **交互先于设计**：在拆分需求和设计之前，必须先明确对象/模块/用户间的调用关系（阶段 2.3），建立协作地图作为后续设计的输入约束
5. **一览图必须**：拆分后必须输出关键环节一览图，将子需求作为节点展示全局流程
6. **分阶段确认**：每个关键阶段必须等用户确认才能继续
7. **不脑补需求**：发现需求模糊或场景不成立时，停下来，而非自行补全
8. **专家资产优先**：设计前主动查询专家团，复用架构设计、已知坑、接口契约等资产，避免重复设计已解决的问题

## 工作流总览

```
前置：信息收集             → req 查需求文档 + 检查依赖文档 + 专家团查询 + 代码现状调研
阶段 0：需求成熟度判定       → 判定上下文是否存在充分讨论
阶段 1：需求摘要确认         → 输出"我理解的需求"，等用户确认
阶段 2：语义分析与场景对齐   → 拆解语义、匹配场景、判定价值
阶段 2.3：交互对象总览       → 明确对象/模块/用户间的调用关系，建立协作地图
阶段 2.5：需求拆分（默认触发）→ 拆分子需求 + 依赖 DAG + 关键环节一览图
阶段 3：大纲与边界输出       → 父文档 4 全局章 + 子需求按需章
阶段 4：分章节填充           → 按依赖拓扑序填充各文档
阶段 5：落盘归档             → 写入 + 质量自检 + 一致性校验
```

**未得到用户对当前阶段的确认前，不进入下一阶段。**

### 前置信息收集（阶段 0 之前执行）

在进行设计之前，先收集已有的输入信息，避免凭空设计。

#### 1. 检查需求管理配置

检查项目根目录是否存在 `.requirements/config`：

- **已配置**：存在合法的 `storage_path`，可读取已有需求文档
- **未配置**：跳过需求文档读取，后续阶段 1 基于用户口头描述进行

#### 2. 读取需求文档

若已配置需求管理，使用 `req` 命令获取需求信息：

```bash
# 查看当前所有需求
req list

# 若用户提供了 REQ-ID，读取具体需求
req list --id {REQ-NNN}
```

读取需求目录下的 `requirement.md`，提取作为设计输入：
- 功能描述与目标
- 验收标准
- 非功能性约束
- 涉及的用户角色

> **重要**：需求文档内容必须在阶段 1（需求摘要确认）中引用确认，不能跳过需求确认阶段。

#### 3. 检查第三方依赖文档

检查需求目录下是否存在 `dependencies/` 目录：

- **存在**：列出所有依赖文档，读取并作为设计输入
- **不存在**：在阶段 2.3（交互对象总览）时识别到外部系统后，建议用户使用 `dependency-docs` skill 整理

> 依赖文档存放位置：`dependencies/` 目录（单文件或多文件模式）

#### 4. 专家团查询

调用 use_skill("expert-solution-workflow") 查询当前需求涉及的模块的相关经验、解决方案或记忆（如该模块的业务专家资产包；查询失败或不可用，忽略此步骤继续正常流程）：

- **找到专家**：加载专家资产（架构设计、实现导航、接口契约、已知坑等），作为设计输入的重要参考。专家的架构设计可直接用于阶段 2.3 的协作地图构建，已知坑可帮助设计时规避历史问题
- **未找到专家**：继续正常流程

#### 5. 代码现状调研

根据当前需求，有选择地调研代码库中相关信息，确保设计与现有代码风格、架构保持一致。详细规范加载 `code-survey` skill。

核心规则：
- **按需调研**：只调研与当前需求相关的维度，不相关的跳过
- **信息复用优先**：记忆系统/知识库 → 已有文档 → 代码库搜索
- **可跳过**：满足快速跳过条件时（成熟度高、用户已熟悉、知识库充分）可极简化或跳过

#### 6. 汇总输入信息

收集完成后，向用户摘要已有的输入信息（需求文档、依赖文档、专家资产、代码调研），确认后进入阶段 0。

---

## 阶段 0：需求成熟度判定

在阶段 1 之前，先判定上下文中是否已存在对需求的充分讨论。

**判定条件**（满足 1 项即为成熟度高）：

- 用户已给出多轮（3+ 条消息）分析讨论，含具体技术方案比较
- 用户已明确关键决策点或给出 AS-IS / TO-BE 对比
- 上下文已包含需求挖掘（requirement-mining）的完整输出

**判定结果**：

| 成熟度 | 处理方式 |
|--------|---------|
| 高 | 输出「已有理解摘要」一次性确认，跳过阶段 1 和阶段 2，直接进入阶段 2.3 |
| 中 | 走阶段 1 → 2 但精简输出（省略价值判定等已讨论内容） |
| 低 | 走完整标准流程 |

**成熟度高时的输出格式**：

```text
⚡ 已有理解摘要（基于上下文讨论）
━━━━━━━━━━━━━━━━
核心诉求：<基于已有讨论提炼>
关键决策点：<已确认的技术决策>
涉及模块：<涉及的文件/模块>

以上理解均来自上下文讨论，确认后直接进入交互对象总览（阶段 2.3）。
如有偏差请纠正，我将回退到阶段 1 重新对齐。
```

---

## 阶段 1：需求摘要确认

将用户需求复述为结构化摘要，逼出隐含假设。

输出格式：

```text
📌 需求摘要
━━━━━━━━━━━━━━━━
原始描述：<原文回放>
核心诉求：<本质诉求，一句话>
变更类型：新增 / 修改 / 重构 / 删除
触发主体：<谁会用 / 谁会触发>
预期产物：<最终产物形态>

请确认以上理解是否正确。
```

---

## 阶段 2：语义分析与场景对齐

**这是本 skill 最重要的步骤，不可跳过、不可合并到其他阶段。**

### 核心问题

> 同一句需求描述，不同人理解不同 → 设计方向跑偏 → 文档作废。

### 三个动作

**① 语义拆解**：把需求逐条提取，用更明确的术语替换歧义词。

常见歧义词：幂等（接口/任务/消息）、缓存（进程内/分布式/CDN）、异步（线程/协程/消息队列）、限流（单机/全局/用户/接口）、通知（推送/邮件/站内信/Webhook）

**② 场景匹配**：每条款项明确触发场景、使用主体、解决痛点。

**③ 价值判定**：每条三选一：

| 标记 | 含义 | 处理 |
| --- | --- | --- |
| ✅ 匹配 | 场景真实、价值成立 | 进入设计 |
| ⚠️ 存疑 | 场景模糊或价值不明 | 提出具体反问 |
| ❌ 不匹配 | 场景不成立 | 劝退或推荐替代方案 |

**④ 非功能性需求确认**：每条需求额外确认以下关键维度（若用户未主动提及，按默认假设处理并注明）：

| 维度 | 默认假设 | 需追问的信号 |
|------|---------|-------------|
| 数据量级/并发 | 单机低量级、单用户低频 | 涉及批量/流式/大文件、多用户/高并发 |
| 可用性/一致性 | 允许单点故障、最终一致 | 涉及线上服务/关键路径、资金/状态关键操作 |
| 延迟容忍 | 秒级 | 涉及实时/交互式场景 |

> 默认假设必须在方案章显式标注，如"本方案默认单机低量级，若需扩展请在阶段 3 前确认"。

### 关键约束

- 出现 ❌ 时不能硬写设计
- 出现 ⚠️ 时反问必须具体到二选一
- 多维度歧义时逐维度追问，不一次性列出所有组合
- 详见 [reference.md](reference.md) 中的语义分析示例

---

## 阶段 2.3：交互对象总览

### 目的

在拆分需求和设计之前，先明确参与交互的**核心对象/模块及其调用关系**，建立全局"协作地图"。让用户对"谁跟谁交互"有一个地图级认知，作为后续需求拆分和设计的输入约束。

### 触发条件

阶段 2 确认后**自动触发，不可跳过**。

### 输入

阶段 2 确认的场景、角色、功能本质。

### 输出

#### 1. 交互对象清单

列出所有参与交互的核心对象/模块，含用户角色。每个对象标注职责（一句话）。

| 对象/模块 | 类型 | 职责 |
|-----------|------|------|
| [用户角色名] | 用户 | [一句话职责] |
| [模块名] | 内部模块 | [一句话职责] |
| [外部系统名] | 外部系统 | [一句话职责] |

**协作地图辅助——强关联关系查询**：建立交互对象清单时，可调用 `use_skill("ki-memory-lookup")` 检索涉及模块的强关联关系（跨模块契约/业务耦合），作为协作地图中"模块间牵动关系"的补充依据，避免设计时遗漏已有代码的强耦合（查询失败或无可用记录，忽略继续）。

**方案前置核对——决策记忆查询**：进入具体方案设计前，可调用 `use_skill("ki-memory-lookup")` 的决策记忆策略，检索该模块是否已有历史决策记录——若命中的「被否决方案」正是当前要论证的方案，先核对原否决理由是否仍成立再继续，避免重复论证同一个已否决方案（查询失败或无可用记录，忽略继续）。

**类型说明**：
- **用户**：参与交互的人类角色（如 普通用户、管理员、运营人员）
- **内部模块**：系统内部的功能模块（如 用户模块、订单模块、支付模块）
- **外部系统**：第三方服务、外部 API、消息队列、数据源等

#### 2. 调用关系图（mermaid）

```mermaid
flowchart LR
    User["👤 用户"]
    ModuleA["📦 模块A"]
    ModuleB["📦 模块B"]
    ExtSys["🌐 外部系统"]

    User -->|"触发操作"| ModuleA
    ModuleA -->|"调用"| ModuleB
    ModuleA -->|"请求"| ExtSys
    ModuleB -->|"返回结果"| ModuleA
    ModuleA -->|"展示结果"| User
```

**制图规则**：
- 节点 = 对象/模块/用户/外部系统
- 连线 = 调用方向 + 触发条件（箭头旁标注）
- 不确定的调用关系标注 `[待确认]`，连线用虚线样式
- 外部系统用不同颜色或边框区分（如虚线边框）

#### 3. 关键交互说明

每条调用关系补充：

| 调用方 | 被调用方 | 触发条件 | 数据/控制流向 | 备注 |
|--------|----------|----------|---------------|------|
| 用户 | 模块A | 用户执行 [操作] | 控制流：触发 [行为] | — |
| 模块A | 模块B | 模块A 需要 [数据/能力] | 数据流：[什么数据] | — |
| 模块A | 外部系统 | 需要 [外部能力] | 数据流：[请求/响应] | [待确认] |

### 约束

- **粒度**：模块/对象级，不深入到具体类/函数/方法
- **外部系统**：第三方 API、消息队列、数据库中间件等均作为独立节点纳入
- **不确定关系**：标注 `[待确认]`，直接询问用户，不自行假设
- **不替代后续设计**：此图是"协作拓扑"，不是详细时序图或流程图

### 输出格式

```text
🗺️ 交互对象总览
━━━━━━━━━━━━━━━━

【交互对象清单】（表格：对象/模块、类型、职责）

【调用关系图】（mermaid 图）

【关键交互说明】（表格：调用方、被调用方、触发条件、数据/控制流向、备注）

请确认对象完整性、调用关系准确性、待确认关系。
```

---

## 阶段 2.5：需求拆分

### 触发条件（默认触发）

**默认拆分。仅当同时满足以下全部条件时，才合并为单文档：**

1. 简单需求：无流程变化、涉及文件 ≤ 3 个或变更行数 ≤ 100 行、无跨模块交互
2. 用户确认"不需要拆分"

**上游已拆分则复用不重拆**：若需求目录下存在 `sub-requirements/` 子目录（requirement-mining「子需求拆分」的产物），则跳过本阶段的拆分动作，**直接复用上游的子需求划分**，将需求子项转译为设计子需求（补接口契约 / 数据模型 / 时序）。上游子需求边界标 ⚠️ 存疑的，在阶段 2.3 交互对象总览时重点核对边界。

### 拆分动作

1. **识别子需求**：将需求拆为 N 个边界清晰的子需求，每个子需求需满足：
   - 有独立的触发场景和使用主体
   - 可独立定义接口契约
   - 可独立验证

2. **构建依赖 DAG**：识别子需求间的依赖关系

3. **输出关键环节一览图**：用 mermaid 将子需求作为节点，展示在全局流程中的位置

4. **分期推荐**：子需求 ≥ 4 个或存在依赖层级时推荐分期

### 输出格式

```text
🔀 需求拆分
━━━━━━━━━━━━━━━━

【复杂度判定】
- 结论：默认拆分 → 生成 N 个子需求

【子需求清单】（表格：编号、子需求、触发场景、独立验证方式）

【关键环节一览图】（mermaid 图，标注每个子需求在全局流程中的位置）

【依赖关系】（mermaid 图 + 依赖说明）

【分期推荐】（子需求 ≥ 4 个或存在明显依赖层级时输出）

【文档规划】
- 父文档：<feature>_DESIGN.md（全局架构 + 一览图 + 全局风险）
- 子文档：S-01 → <feature>_S01_<名称>_DESIGN.md

请确认子需求划分、一览图准确性、分期方案合理性。
```

### 关键约束

- 拆分后必须输出关键环节一览图
- 一览图中的节点是子需求编号+名称，连线是数据/控制依赖
- 用户可调整子需求粒度、依赖关系、分期方案

---

## 阶段 3：大纲与边界输出

### 多文档结构（默认）

**父文档**仅含 4 个全局章节：

1. 需求背景 & 目标 — 全局背景 + 整体目标 + 不在范围内
2. 关键环节一览图 — 阶段 2.5 确认后的一览图（可微调）
3. 总体方案设计 — 以子需求节点图替代文字描述，标注跨子需求共享术语
4. 全局风险 & 跨子需求依赖 — 跨子需求风险 + 接口契约变化风险 + 共享术语速查

**共享术语**不单独成章。每个子需求定义自己的术语，跨子需求共享术语在父文档第 4 章"共享术语速查"中携带引用（不重复定义）。

**子需求文档**各自按需取用章节，最少 4 章：

| 子需求特征 | 必含章节 | 可追加章节 |
|-----------|---------|-----------|
| 纯数据模型变更 | 术语、现状(AS-IS)、方案(TO-BE)、数据模型 | — |
| 纯函数/接口新增 | 术语、现状(AS-IS)、方案(TO-BE)、接口设计 | — |
| 含复杂时序流程 | +时序图 | — |
| 含性能敏感路径 | +性能安全 | — |
| 含异常路径 | +异常处理 | — |
| 含重构场景 | +迁移策略 | — |
| 涉及 ≥2 个文件改动 | +影响范围 | — |
| 存在未决事项 | +待定问题（自动追踪） | — |

章节模板详见 [SUB_TEMPLATE.md](SUB_TEMPLATE.md)。

> **重构场景增强**：当子需求含"重构/合并/统一/简化/替换"等关键词时，现状章和方案章自动包含 AS-IS 流程图 + TO-BE 流程图 + 迁移策略小节。

输出格式：

```text
📋 设计文档大纲

【父文档】<feature>_DESIGN.md（4 章）
1. 需求背景 & 目标
2. 关键环节一览图
3. 总体方案设计（子需求节点图 + 共享术语速查）
4. 全局风险 & 跨子需求依赖

⛔ 不在范围内：<...>

【子文档 S-01】<feature>_S01_<名称>_DESIGN.md
- 必含：术语 / 现状(AS-IS) / 方案(TO-BE) / 数据模型
- 追加：时序图（含关键时序）

⛔ 本子需求不在范围内：<...>

【子文档 S-02】<feature>_S02_<名称>_DESIGN.md
- 必含：术语 / 现状(AS-IS) / 方案(TO-BE) / 接口设计
（无追加章节）

⛔ 本子需求不在范围内：<...>

请确认大纲与边界。
```

### 单文档（快速通道）

走快速通道时，按 SINGLE_DOC.md 的 14 章骨架列出大纲，章节可省略规则见该文档。

---

## 阶段 4：分章节填充

### 填充策略：逐子文档确认

为避免全部确认后上下文爆炸，采用**先总体确认大纲，再逐个子文档确认填充**的策略：

1. **第一轮：填充父文档** → 确认父文档 → 进入第二轮
2. **第二轮：逐子文档填充** → 按依赖拓扑序，每完成一个子文档即让用户确认，确认后继续下一个
3. 有依赖的子需求必须等待所依赖的子文档完成并确认后再填充

### 代码路径与目录结构要求

设计涉及的每个文件/模块，必须明确写出**文件路径**。如果是新增文件，必须给出**完整的目录结构**，标明新文件位置：

```
project/
├── src/
│   ├── api/
│   │   ├── user.py          # [修改] 新增 /users/verify 端点
│   │   └── middleware.py     # [修改] 添加认证中间件
│   ├── models/
│   │   └── user.py          # [修改] 新增 verified 字段
│   └── services/
│       └── auth_service.py  # [新增] JWT 认证服务
```

### API 接口设计规则

涉及**新增或修改 API 接口**时，必须遵循以下顺序：

1. **先确定接口契约**：完整签名（方法、路径、参数类型、返回值、异常）
2. **再编写具体实现**：基于已确认的契约编写代码设计
3. **必须附带 Demo 返回示例**：JSON 格式的响应示例，非最终数据格式，仅用于直观理解接口行为

```json
// Demo 返回示例（仅示意格式，非最终数据）
{
  "code": 200,
  "data": {
    "id": "usr_abc123",
    "name": "张三",
    "verified": true
  },
  "message": "success"
}
```

### 多文档填充

**第一轮：填充父文档。** 父文档 4 章，每章 ≤ 200 字。第 3 章总体方案设计以 mermaid 子需求节点图为主。填充完后等用户确认。

**第二轮：按依赖拓扑序逐个填充子文档。** 子文档按 SUB_TEMPLATE.md 模板填充，字数不限但要精炼。每完成一个子文档，**停下来让用户确认**，确认通过后再继续下一个。

风格约束：
- 不写"众所周知"、"显而易见"等空话
- 列表项 ≤ 5 条
- 每章可有 0~1 张 mermaid 图
- 子文档引用的接口签名、术语必须与父文档第 4 章一致
- 每个涉及的文件必须写明路径，新增文件必须给出目录结构

### 章节内容质量标准

每个章节必须满足最低信息密度要求，不满足的章节视为不合格，需补充后才能进入阶段 5：

| 章节 | 最低信息密度要求 | 不合格示例 |
|------|-----------------|-----------|
| 现状(AS-IS) | 必须给出具体文件路径或代码行号 | "当前代码结构不够清晰" |
| 方案(TO-BE) | 每个变更点必须说明改什么、改成什么、为什么，注明文件路径 | "采用更合理的设计" |
| 关键决策点 | 每个决策点至少 1 个被否决方案 + 否决理由；"重新评估触发条件"必须是可观测判据（阈值/依赖变化/技术栈支持），否则填"无"；本表不写 ki（设计阶段决策易变，仅作为决策记忆数据源，落地后由 expert-team 收割） | 只列一个方案无对比；"触发条件"写"性能不足时"这类不可判定的空话 |
| 接口设计 | 必须给出完整签名（方法、路径、参数类型、返回值、异常）+ Demo 返回示例 | 只写函数名无签名 |
| 数据模型 | 必须给出完整字段定义 + 含义注释 | 只写"增加若干字段" |
| 异常处理 | 每行必须包含：场景→行为→是否对外暴露 | "出错时抛异常" |
| 时序图 | 必须标注消息名称和方向，不能只有箭头无文字 | 只有参与者无消息 |

### 单文档填充

按 SINGLE_DOC.md 的填充策略执行：14 章填充顺序（现状后置）、每章 ≤ 200 字、代码路径与 API 接口设计规则、风格约束。

---

## 阶段 5：落盘归档 + 自动评审

### 存储位置

检查项目中是否已配置存储位置（`.requirements/config`）：

- **已配置**：读取 `storage_path`，设计文档存放在 `{storage_path}/{YYYY-MM-DD}-{功能名称}/design/`
- **未配置**：询问用户，给出默认建议 `.requirements/`

配置后自动创建目录结构，后续设计文档统一存放。

**存储规范**：加载 `requirement-doc-store` skill 获取完整目录结构和文件命名规范。

### 多文档场景

先落盘父文档，再按依赖拓扑序依次落盘子文档。父文档存入 `design/DESIGN.md`，子文档存入 `design/` 目录。

```text
✅ 设计文档已生成

父文档：<路径>（4 章）
子文档：
  - <路径>（N 章）
  ...

🔍 质量自检清单
━━━━━━━━━━━━━━━━

【可自动校验】
☐ 父文档第 2 章包含 mermaid 代码块（一览图）
☐ 每个子文档文件名匹配 S-XX 编号
☐ 子文档中引用的接口签名在父文档第 4 章存在
☐ 父文档第 4 章声明的接口均有子文档正确引用
☐ 一览图中的每个子需求节点都有对应的子文档文件
☐ 子文档间的交叉引用在文档内有对应链接
☐ 共享术语在父文档第 4 章有速查条目
☐ 无"众所周知"/"显而易见"/"业界通用做法"等空话
☐ 每个决策点至少 1 个被否决方案
☐ 章节内容质量标准全部达标（见阶段 4）

【需人工判断】
☐ 一览图准确反映全局流程（子需求编号 + 位置正确）
☐ 子文档"不在范围内"未超出父文档边界
☐ 异常处理表覆盖主要失败路径
☐ 非功能性需求假设已显式标注
☐ 待定问题表覆盖所有未决事项
```

### 自动评审循环

设计文档落盘后，**自动调用 `design-review` skill 进行评审**，进入评审-修复循环：

```
落盘完成 → 调用 design-review → 有阻断/警告？
    ├── 无问题 → ✅ 评审通过，输出评审报告
    └── 有问题 → 自动修改文档 → 再次调用 design-review
                    ↑                           │
                    └── 最多重复 3 次 ──────────┘
                    超过 3 次 → 输出剩余问题，交由人工处理
```

### challenger 二次质疑（design-review 通过后执行）

design-review 评审通过后，**自动调用 `challenger` skill 进行深度二次审查**。详细流程见 [CHALLENGER_REPORT.md](CHALLENGER_REPORT.md)。

核心规则：
- 根据需求类型自动匹配质疑策略（feature / bug-fix / optimization）
- 质疑报告输出后**不自动修复**，向用户提供 3 个选项：🔧 自动修复 / 📁 报告落盘 / ⏭️ 跳过
- 选修复：按行动建议修改 → design-review 验证 1 轮 → 仍有问题人工判断
- 选落盘：写入 `review/challenge-report.md` + `req update` 注册关联
- 选跳过：不修改不落盘，直接交付
- **设计文档不是代码**：challenger 的编码常识类质疑（空值校验、日志、资源释放等）记录到报告即可，不修改设计文档。判断标准见 CHALLENGER_REPORT.md 的「质疑过滤」部分。

**自动修改规则**：
- 🔴 阻断项：自动按照评审报告中的修改建议修改文档
- 🟡 警告项：自动按照评审报告中的修改建议修改文档
- 🟢 建议项：记录但不强制修改

**循环终止条件**：
- 无 🔴 阻断且无 🟡 警告 → 评审通过
- 已重复 3 次仍有问题 → 停止自动修改，将剩余问题告知用户

**输出格式**：

```text
🔄 自动评审结果
━━━━━━━━━━━━━━━━
第 N 次评审：
- 🔴 阻断：X 个（已自动修复）
- 🟡 警告：Y 个（已自动修复）
- 🟢 建议：Z 个（记录供参考）

✅ 评审通过 / ⚠️ 需要人工处理

[如有剩余问题，列出需人工处理的问题表格]
```

**challenger 二次质疑输出**：见 [CHALLENGER_REPORT.md](CHALLENGER_REPORT.md) 决策分支部分。

### 场景推演（challenger 通过后执行）

challenger 二次质疑通过后，**自动调用 `scenario-rehearsal` skill 进行场景推演**。

核心规则：
- 以执行者（用户角色/自动化程序）为入口，走完整流程
- 双重验证：数据走向 + 关键设计点实现
- 推演报告输出后**不自动修改**，向用户提供 3 个选项：🔧 修改设计 / 📁 报告落盘 / ⏭️ 跳过
- 选修改：按推演发现的问题修改设计文档 → design-review 验证 1 轮
- 选落盘：写入 `design/scenario-rehearsal.md` + `req update` 注册关联
- 选跳过：不修改不落盘，直接交付

**推演发现的问题分类处理**：
- 遗漏场景/流程缺陷：修改设计文档
- 数据问题：修改数据流图或设计文档
- 设计冲突：统一设计方案

**输出格式**：

```text
🎬 场景推演结果
━━━━━━━━━━━━━━━━

推演覆盖：X 个角色 / Y 个场景
问题发现：🔴 阻断 X 个 / 🟡 警告 Y 个 / 🟢 建议 Z 个

评审结论：❌ 不通过 / ⚠️ 有条件通过 / ✅ 通过

请选择后续行动：
1. 🔧 修改设计
2. 📁 报告落盘
3. ⏭️ 跳过
```

**场景推演详细流程**：见 `scenario-rehearsal` skill。

### 单文档场景

落盘单文件，按 SINGLE_DOC.md 的 14 章质量自检清单执行，同样进入自动评审循环。

### 后续行动选择

设计文档评审通过后，向用户提供后续行动选择：

```text
🚀 后续行动选择
━━━━━━━━━━━━━━━━

设计文档已完成并通过评审。请选择后续行动：

1. 📡 补充 API 设计
   使用 api-design 技能将设计文档中的 demo 接口升级为详细的 API 设计文档（推荐，当设计涉及 API 接口时）

2. 📋 生成测试计划
   使用 test-planner 技能基于设计文档生成测试计划

3. 📝 生成实施计划
   使用阶段 6 生成独立的实施计划文档

4. ⏭️ 跳过
   不进行后续操作，结束设计流程

请选择 [1/2/3/4]：
```

**触发条件**：仅当设计文档中包含 API 接口设计章节时，才推荐选项 1。

---

## 需求管理集成

当项目配置了 `.requirements/config` 时，design-craft 在落盘归档（阶段 5）后自动执行以下集成操作：

### 自动触发条件

项目中存在 `.requirements/config` 且 `storage_path` 指向有效目录。

### 集成步骤

1. **写入设计文档**到需求目录后，调用 `req update` 注册文档关联并更新状态：

```bash
# 单文档场景
req update {REQ-NNN} \
  --docs add design/DESIGN.md,design --status 设计中 --changelog "完成技术设计"

# 多文档场景：父文档 + 子文档分别注册
req update {REQ-NNN} \
  --docs add design/DESIGN.md,design \
  --docs add design/S01_子需求名称_DESIGN.md,design \
  --status 设计中 --changelog "完成技术设计（N 个子需求）"
```

2. **获取需求上下文**（阶段 0 需求成熟度判定时）：如果用户提供了 REQ-ID，先读取需求信息作为设计输入：

```bash
req list --id {REQ-NNN} --deps
```

3. **错误处理**：
   - 需求 ID 不存在 → 提示用户先创建需求，跳过集成
   - 文件锁超时 → 自动重试 1 次，仍失败则告知用户
   - 状态校验失败 → 提示具体错误，不自动修复

### 存储路径映射

| 产出物 | 存储路径 | docs 类型 |
|--------|----------|-----------|
| 父文档 | `design/DESIGN.md` | `design` |
| 子文档 | `design/S{NN}_{名称}_DESIGN.md` | `design` |
| 实施计划 | `design/IMPL_PLAN.md` | `design` |
| 代码调研 | `reference/code-survey.md` | `reference` |

---

## 反模式（不要做）

### 结构层面
- ❌ 复杂需求用单文档承载或拆分后不提供一览图：复杂度稀释，用户无法建立全局感
- ❌ 术语跨子需求混排或引用不存在的接口定义：破坏归属和一致性

### 流程层面
- ❌ 跳过阶段 0/2 直接出大纲：浪费 token 或导致设计跑偏
- ❌ 跳过代码现状调研直接设计：可能导致设计与现有代码风格、架构不一致
- ❌ 用户没确认就连续输出多个阶段产物或一次性填充所有子文档：无法纠偏或上下文爆炸
- ❌ 发现 ❌ 子需求时仍硬写设计或回退时保留旧产出：违反劝退义务，必须丢弃旧产出
- ❌ 自动评审循环超过 3 次或跳过 challenger 二次质疑：可能陷入死循环或遗漏深度审查
- ❌ challenger 发现问题后不询问用户直接修复或修复后再进入新的 challenger 循环：设计类问题需人工权衡，防止无限递归

### 内容层面
- ❌ 章节内容堆砌或把"不在范围内"写成空话：缺乏实质内容
- ❌ 子文档间重复写共享术语、背景或接口签名与父文档不一致：破坏一致性
- ❌ 决策点无被否决方案、非功能性需求未标注默认假设、待定问题写"无"但存在未决依赖：缺乏完整性
- ❌ 代码不写文件路径、API 接口无 Demo 返回示例、接口未确定就先写实现：缺乏可执行性

## 附加资源

- 单文档快速通道：[SINGLE_DOC.md](SINGLE_DOC.md)
- challenger 二次质疑：[CHALLENGER_REPORT.md](CHALLENGER_REPORT.md)
- 子需求章节模板：[SUB_TEMPLATE.md](SUB_TEMPLATE.md)
- 代码现状调研：`code-survey` skill
- API 详细设计：`api-design` skill（设计文档完成后推荐）
- 语义分析示例 / 拆分示例 / mermaid 速查 / 反模式清单：[reference.md](reference.md)