设计文档生成器

概述

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

何时使用

仅在以下情况使用本 skill：

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

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

单文档快速通道

若需求简单判定可走单文档模式，加载 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 命令获取需求信息：

# 查看当前所有需求
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 但精简输出（省略价值判定等已讨论内容）
低	走完整标准流程

成熟度高时的输出格式：

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

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

---

阶段 1：需求摘要确认

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

输出格式：

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

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

---

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

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

核心问题

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

三个动作

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

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

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

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

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

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

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

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

关键约束

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

---

阶段 2.3：交互对象总览

目的

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

触发条件

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

输入

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

输出

1. 交互对象清单

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

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

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

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

类型说明：

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

2. 调用关系图（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、消息队列、数据库中间件等均作为独立节点纳入
• 不确定关系：标注 [待确认]，直接询问用户，不自行假设
• 不替代后续设计：此图是"协作拓扑"，不是详细时序图或流程图

输出格式

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

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

【调用关系图】（mermaid 图）

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

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

---

阶段 2.5：需求拆分

触发条件（默认触发）

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

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

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

拆分动作

1. 识别子需求：将需求拆为 N 个边界清晰的子需求，每个子需求需满足：

   • 有独立的触发场景和使用主体
   • 可独立定义接口契约
   • 可独立验证

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

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

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

输出格式

🔀 需求拆分
━━━━━━━━━━━━━━━━

【复杂度判定】
- 结论：默认拆分 → 生成 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。

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

输出格式：

📋 设计文档大纲

【父文档】<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 格式的响应示例，非最终数据格式，仅用于直观理解接口行为

// 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/ 目录。

✅ 设计文档已生成

父文档：<路径>（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。

核心规则：

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

自动修改规则：

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

循环终止条件：

• 无 🔴 阻断且无 🟡 警告 → 评审通过
• 已重复 3 次仍有问题 → 停止自动修改，将剩余问题告知用户

输出格式：

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

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

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

challenger 二次质疑输出：见 CHALLENGER_REPORT.md 决策分支部分。

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

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

核心规则：

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

推演发现的问题分类处理：

• 遗漏场景/流程缺陷：修改设计文档
• 数据问题：修改数据流图或设计文档
• 设计冲突：统一设计方案

输出格式：

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

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

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

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

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

单文档场景

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

后续行动选择

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

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

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

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 注册文档关联并更新状态：

# 单文档场景
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，先读取需求信息作为设计输入：

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
• challenger 二次质疑：CHALLENGER_REPORT.md
• 子需求章节模板：SUB_TEMPLATE.md
• 代码现状调研：code-survey skill
• API 详细设计：api-design skill（设计文档完成后推荐）
• 语义分析示例 / 拆分示例 / mermaid 速查 / 反模式清单：reference.md