write-design-doc

name	write-design-doc
description	编写 C++ 项目的详细设计文档和设计变更影响面分析。当用户说要写详细设计、生成设计文档、做影响面分析、描述功能需求要写设计、或者说"把这个需求的设计写出来"时触发。也用于增量更新已有设计文档、以及清除迭代标记输出最终版。

详细设计编写 Skill

从需求规格、概要设计、项目代码等输入，生成符合模板规范的详细设计文档和设计变更影响面分析。

---

模板文件

模板和规范文件优先从工程级路径读取，若工程级路径不存在，则回退到 references/ 目录。当使用 references/ 下的引用文件时，必须告知用户。

文件	用途	优先读取路径	回退路径	何时加载
应用设计说明书模板	详细设计文档模板，含每章的 AI 注释指令	projects/{工程名}/docs/04-设计/应用设计说明书_模板.md	references/应用设计说明书_模板.md	仅在初次新建时加载。增量更新直接修改已有文档，不重新加载模板
设计变更影响面分析模板	影响面分析模板，相对独立	projects/{工程名}/docs/04-设计/设计变更影响面分析_模板.md	references/设计变更影响面分析_模板.md	仅在生成或更新影响面分析时加载
mermaid 画图规范	Mermaid 图表绘制规范，约 1000 行	projects/{工程名}/docs/04-设计/画图规范.md	references/画图规范.md	按需按章节加载

---

数据来源（输入）

下表列出生成详细设计文档时需要的输入数据。根据当前设计范围，只加载相关的输入。

仓库级输入

类别	说明	推荐路径
需求规格说明书	版本目标、功能需求	Program/software/docs/02-需求/需求规格说明书.md
需求影响分析矩阵	影响范围	Program/software/docs/02-需求/需求影响分析矩阵.md
系统架构总览	分层架构、通信拓扑、设计约束	Program/software/docs/01-总览/系统架构总览.md
客户端概要设计	客户端概设	Program/software/docs/03-概设/客户端概要设计.md
服务端概要设计	服务端概设	Program/software/docs/03-概设/服务端概要设计.md
通信协议	跨工程通信方式、消息格式	Program/software/docs/04-协议/通信协议.md
全局错误码	错误码分段、通用错误码	Program/software/docs/04-协议/全局错误码.md
服务端工程说明	核心流程、状态机、异常模式	Program/software/docs/07-工程说明/server.md

工程级输入

类别	说明	推荐路径
架构总览	本工程分层架构	projects/{工程名}/docs/01-总览/架构总览.md
目录结构	本工程目录约定	projects/{工程名}/docs/01-总览/目录结构.md
模块索引	模块依赖关系、影响面速查	projects/{工程名}/docs/03-模块依赖/模块索引.md
模块 README	类图、接口签名、文件路径	projects/{工程名}/docs/03-模块依赖/{模块名}/README.md
编码规范	本工程编码约束	projects/{工程名}/docs/02-规范/编码规范.md

代码输入

类别	路径模式	提取内容
公共接口	components/include/ 下对应 .h	类声明、继承关系、public 方法签名
业务实现	components/business/ 下对应 .cpp	函数调用链、线程创建、缓存操作、SQL 语句、异常处理

---

输出位置

产出物	路径	文件名命名规范
详细设计文档	projects/{工程名}/docs/04-设计/	{项目或迭代版本}_服务端/客户端_应用设计说明书.md
影响面分析	projects/{工程名}/docs/04-设计/	{项目或迭代版本}_服务端/客户端_影响面分析.md

命名规范说明

1. 基本格式：{项目或迭代版本}_{端}_应用设计说明书.md
   • 示例：V2.3_机器人引导_服务端_应用设计说明书.md
   • 示例：迭代三_视觉检测_客户端_应用设计说明书.md
2. {项目或迭代版本}：取需求规格或版本计划中的版本号、迭代号或项目简称
3. {端}：根据设计范围选择 服务端 或 客户端；同时涉及两端时，分别输出两份文档
4. 影响面分析：与对应详设文档同名，将 应用设计说明书 替换为 影响面分析

---

四种工作模式

模式一：新建详细设计

用户描述一个新需求，从零生成设计文档和影响面分析。

步骤：

1. 收集意图：与用户确认设计范围——涉及哪些模块、新增还是修改、有无参考的已有设计

2. 探查输入：

   • 按模板文件加载策略读取 应用设计说明书_模板.md（优先工程级路径，回退 references/，全文，仅初次新建时加载）
   • 搜索并读取需求相关文档（从数据来源表中按需选择）
   • 搜索受影响模块的 README

3. 探查代码（每个受影响的模块）：

   • .h 文件：提取类声明、继承关系、public 方法签名
   • .cpp 文件：搜索线程创建 (std::thread / pthread_create)、缓存结构 (DataCache / m_cache)、异常处理 (LOG_ERROR / try-catch)、SQL 语句 (CREATE TABLE)
   • 仅搜索与本次设计相关的文件

4. 按章生成：

   • 按模板骨架逐章生成。每章先读注释理解要求，再结合输入内容生成
   • 需要 mermaid 图时，按模板文件加载策略读取 画图规范.md 的对应章节（见下方"Mermaid 图按需加载策略"）
   • 生成顺序：第 1 章 → 第 2 章 → 第 3 章（全局设计 → 各模块）→ 第 4 章 → 第 5 章 → 第 6 章 → 第 7 章 → 第 8 章
   • 第 3 章生成时，按模块顺序（被依赖的先写）

5. 生成影响面分析：

   • 按模板文件加载策略读取 设计变更影响面分析_模板.md
   • 根据设计文档中的变更内容，填充客户端变更（第 2 章）和服务端变更（第 3 章）

6. 输出：保存两个文件到输出位置

---

模式二：增量更新

在已有设计文档基础上增量修改。

步骤：

1. 读取已有文档：读取当前版本的设计文档

2. 确认上一轮已完成评审（强提示 + 默认继续）：

   • 检查文档中是否仍残留 <mark> 标签、mermaid 黄色高亮块或"本轮变更说明"表
   • 若存在，提示用户："检测到上一轮迭代标记未清理，建议先完成评审。如无需处理，将在 5 秒后自动清理并继续。"
   • 用户不回应或确认继续时，默认清理旧标记并继续；用户明确拒绝时停止

3. 清除上一轮标记：清除上一轮遗留的所有标记（见"迭代标记与清理规范"）

4. 探查变更影响：

   • 根据变更描述，确定受影响的章节
   • 读取相关代码文件的最新版本
   • 仅在受影响的章节范围内工作

5. 增量修改：

   • 只重写受影响的章节，未变更的章节保持原样
   • 新增/修改的内容用 <mark>...</mark> 包裹
   • 删除的内容：直接从正文和 mermaid 图中移除，不在文档中保留被删除的原文或旧图元素
   • 在章节末尾或 mermaid 图下方的"本轮变更说明"表中，用文字列出删除项（删除项描述可标黄），说明删除原因

6. 更新影响面分析：

   • 对比新旧设计文档的差异
   • 更新影响面分析中对应的客户端（第 2 章）/服务端（第 3 章）变更章节
   • 新的影响项用 <mark> 包裹

7. 输出：覆盖原文件

---

模式三：单独生成影响面分析

步骤：

1. 按模板文件加载策略读取 设计变更影响面分析_模板.md
2. 对比两个版本设计文档的差异（或 git diff）
3. 提取变更的文件、接口、数据库、配置维度
4. 填充客户端（第 2 章）和服务端（第 3 章）变更列表
5. 标注 AI 推断项（"影响的关联产品"置信度低，标记需人工确认）

---

模式四：发布定稿

清除所有迭代标记，输出可提交评审的最终版本。必须由用户显式触发，禁止在增量更新中自动执行。

步骤：

1. 清除全文档所有 <mark> 和 </mark> 标签（保留内容文本）
2. 清除 mermaid 图中所有变更标记：
   • 移除 fill:#FFD700 黄色高亮样式，恢复节点原色
   • 移除 stroke:#FFD700 黄色描边/加粗样式
3. 移除所有 mermaid 图下方的"本轮变更说明"表
4. 将 TLDR 和正文中的 {占位符} 替换为实际内容
5. 更新修订记录表中的版本号和日期
6. 输出

---

AI 生成约束

所有由本 Skill 生成的文档（含 AI-native 版详设文档和影响面分析）必须遵守以下约束。这些规则不写入模板正文，而是作为 Skill 生成指令的一部分执行。

统一标识规则

生成文档时，为下列对象分配唯一 ID，并确保跨章节引用一致：

对象类型	ID 前缀	示例	使用位置
需求	REQ-	REQ-001	需求追踪、功能说明、实现任务
接口	IF-	IF-001	接口契约、接口变更、实现任务
数据表	TBL-	TBL-001	表汇总、数据库变更、实现任务
风险	RISK-	RISK-001	风险与注意事项、实现任务
实现任务	TASK-	TASK-001	实现任务清单

规则：

• ID 按文档内首次出现顺序递增编号。
• 同一对象在不同章节中引用时必须使用相同 ID。
• 实现任务清单中的 关联接口/表/风险 列必须填写对应 ID。

枚举取值约束

以下字段只能使用指定枚举值，禁止自由文本：

字段	允许取值
操作类型	增 / 删 / 改 / 查
影响评估	无影响 / 增加 / 减少 / 待评估
兼容策略	兼容 / 不兼容 / 自动迁移 / 手动配置 / 需迁移脚本
严重程度	高 / 中 / 低
线程安全	是 / 否 / 部分
置信度	高 / 中 / 低

置信度判定规则

置信度	判定规则
高	可直接从代码或需求原文验证，无跨模块推理
中	需要跨文件或跨模块推理，存在一定合理假设
低	需要跨工程/跨产品推断，或信息不足，必须人工确认

低置信度项标注要求

• 影响面分析中置信度为“低”的推断项，必须在表格中用 <mark> 或加粗方式突出显示。
• 不在表格中预填写确认人、确认结论、确认日期。
• 增量更新或发布定稿前，需检查所有低置信度项是否已被人工处理（直接修改或删除 <mark>）。

性能指标三元组

所有性能相关表格必须包含：

字段	说明
基线值	变更前的测量值；无法确定时填“需人工填写”
目标值	变更后期望达到的测量值；无法确定时填“需人工填写”
测量方法	如何测量，如单请求压测、并发压测、内存监控等

接口运行语义

接口契约表必须包含以下字段：

字段	说明
超时	接口调用超时时间；不适用时填 N/A
重试	失败重试次数；不适用时填 N/A

证据来源要求

影响面分析中的 AI 推断项必须填写证据来源：

推断类型	证据来源示例
影响的模块	代码分析：include/Xxx.h、调用链搜索结果
影响的关联产品	跨工程关联推断；置信度为低时必须标注
性能影响	代码变更范围、调用链分析
回退策略	变更内容、配置文件变更

---

分析设计原则

本 Skill 在需求分析、方案设计和影响面评估阶段必须遵循以下原则。这些原则约束 AI 的推理过程，而非文档格式。

1. 证据优先原则

所有分析结论必须绑定可验证证据来源（需求条目、接口契约、数据模型、调用链、历史缺陷等）。无证据来源的推断必须标注为低置信度。

2. 可证伪原则

每个结论必须给出反证路径和验证方式，确保结论可被推翻或验证，而不是只可证明、不可推翻。

3. 不确定性显式化原则

对推断项必须标注置信度（高/中/低）。低置信度项必须进入人工确认清单，并在表格中用 <mark> 或加粗方式突出显示。

4. 冲突即停止原则（分析阶段）

发现需求与约束、接口与数据模型、设计与实现现实冲突时，停止继续细化设计，先输出冲突清单并等待解决。

5. 影响面前置原则

在设计阶段就完整列出文件、接口、数据库、配置、性能影响，不把影响面留到开发阶段补全。

6. 契约优先与版本化原则

先定义接口契约，再设计流程；涉及变更时，先定义版本策略与兼容边界。

7. 可回滚优先原则

方案设计时同步给出回退路径、数据可逆性判断、升级失败触发条件。

8. 性能守恒原则

无基线和目标时，不允许写“无影响”；必须说明测量口径和阈值。

9. 变更边界原则

明确包含与不包含范围，超范围项必须单列并重新评估。

10. 可追踪闭环原则

确保需求-设计决策-验证项可一一映射，为开发阶段提供可执行输入。

---

CRUD 分类规则

在进入具体模块设计前，先识别本需求/模块涉及的操作类型（增 Create、删 Delete、改 Update、查 Read/Query），作为后续差异化生成的依据。

优先级

1. 用户显式说明为第一优先级：如果用户在触发 skill 时明确指定了操作类型（例如"这是一个新增需求"、"只做查询和导出"、"涉及增删改"），直接按用户说明分类，不再自动推断。
2. 自动识别为第二优先级：用户未显式说明时，根据需求规格说明书中的功能需求描述自动识别。

自动识别规则

操作类型	典型关键词/语义特征
增（Create）	新增、创建、添加、插入、导入、注册、生成、初始化、上传
删（Delete）	删除、移除、卸载、注销、清空、回收、废弃、下架
改（Update）	修改、更新、编辑、变更、调整、配置、设置、启用/禁用、重置、状态变更
查（Query）	查询、查看、搜索、筛选、列表、详情、统计、导出、报表、历史记录

自动识别过滤规则

关键词匹配容易产生误判，需结合上下文过滤：

过滤场景	示例	处理
否定词	"不支持删除"、"无法修改"、"禁止查询"	该关键词不计入对应操作类型
非操作对象	"删除键"（键盘按键）、"查询语言"、"配置文件更新"	判断动作是否有明确的业务数据对象，无对象则过滤
日志/记录类描述	"更新日志"、"删除记录查看"、"历史修改记录"	若关键词用于描述记录本身而非业务操作，过滤或降级为"查"
将来/计划态	"计划新增"、"未来可能删除"	未在本次版本落地的操作，不计入
单一出现且无宾语	文本中只出现"删除"二字，未说明删除什么	置信度标为低，提示用户确认

多操作混合

一个需求可能同时包含多种操作。识别结果用逗号分隔列出，例如：增、改、查 或 增、删、改、查。

置信度标注：

• 高：关键词明确 + 有明确操作对象 + 无否定词
• 中：关键词明确但对象模糊，或存在需过滤的上下文
• 低：仅出现单一关键词且无宾语，或用户描述与自动识别结果冲突

对于中/低置信度的识别结果，在生成时标注 <!-- 待确认 -->，并提示用户核对。

对生成的指导

识别出的 CRUD 类型用于指导后续章节生成：

• 3.x.1 功能说明：明确写出"本模块提供 XX 的[增/删/改/查]能力"
• 3.x.2 模块结构及依赖：配置界面类模块可划分子模块时，优先按 CRUD 拆分（如 XxxAddPage、XxxEditPage、XxxQueryPage）
• 3.x.3 类关系图 / 3.x.4 核心类描述：按 CRUD 组织接口或类，接口命名倾向 addXxx / removeXxx / updateXxx / queryXxx
• 3.x.5 核心流程说明：每个主要操作类型一个 H5 子章节，分别画时序图
• 3.x.9 数据缓存说明：查操作关注缓存命中与失效策略；改操作关注缓存更新与一致性
• 3.x.10 测试要点：按 CRUD 生成覆盖黄金路径、异常路径、边界条件的测试场景
• 6.3 物理设计：查操作关注索引设计；改操作关注事务与并发控制；删操作关注级联与外键约束
• 影响面分析：服务端接口变更和数据库变更按 CRUD 分组列出

---

迭代标记与清理规范

多轮迭代时，让评审者一眼看出本轮改了什么。

新增/修改标记

• 本轮新增或修改的文本、表格行、列表项用 <mark>...</mark> 包裹
• 未修改的旧内容不包裹
• <mark> 标签在大多数 Markdown 渲染器中显示黄色高亮背景

写之前必须先确认并清理：

1. 确认上一轮标记已完成评审（模式二步骤 2，强提示 + 默认继续）
2. 清除上一轮遗留的所有 <mark> 和 </mark> 标签
3. 清除 mermaid 图中上一轮遗留的黄色高亮块和"本轮变更说明"表

删除标记

删除的内容直接从正文和 mermaid 图中移除，不在文档内保留被删除的原文或旧图元素。

若需让 reviewer 了解删除情况，在章节末尾或 mermaid 图下方的"本轮变更说明"表中列出删除项，删除项描述可用 <mark>...</mark> 标黄以突出显示。

示例：

**本轮变更说明**：

| 元素 | 变更类型 | 说明 |
|------|----------|------|
| 新接口 | 新增 | 新增替代接口 |
| <mark>旧接口</mark> | <mark>删除</mark> | <mark>已废弃，由新接口替代</mark> |

Mermaid 图变更标记

mermaid 代码块内无法使用 <mark> HTML 标签，统一使用 黄色高亮块（#FFD700） 表示新增/修改。删除的元素/消息直接从图中移除，不在图中保留灰色、注释或任何标记。

按图表类型的标记方式（优先使用稳定语法）

图表类型	新增/修改	删除	说明
flowchart / classDiagram	节点：style Node fill:#FFD700,color:#000 连线：linkStyle N stroke:#FFD700,stroke-width:4px	直接移除节点/连线	style 和 linkStyle 在 flowchart/classDiagram 中稳定支持
erDiagram	实体：style Entity fill:#FFD700,color:#000	直接移除实体/关系	ER 图变更较少，优先通过文字说明
sequenceDiagram	参与者：box rgb(255, 215, 0) ... end 包裹新增/修改的参与者 消息块：rect rgb(255, 215, 0) ... end 包裹新增/修改的消息	直接移除该消息行	避免使用 style/classDef 修饰参与者，不同 Mermaid 版本兼容性差

删除元素的处理

1. 直接从 mermaid 图中移除被删除的节点、连线或消息
2. 在图下方"本轮变更说明"表中用文字记录删除项，删除项描述可标黄
3. 定稿阶段由用户触发，确认后无额外清理工作

每个 mermaid 图下方必须补充"本轮变更说明"表：

**本轮变更说明**：

| 元素 | 变更类型 | 说明 |
|------|----------|------|
| 新节点 | 新增 | 新增 XXX 处理节点 |
| <mark>旧连线</mark> | <mark>删除</mark> | <mark>原确认逻辑移入 C</mark> |

示例 1：flowchart（新增节点、修改连线）

flowchart LR
    A["服务A"]
    B["服务B"]
    C["服务C"]

    A --> B
    B --> C

    style C fill:#FFD700,color:#000
    linkStyle 1 stroke:#FFD700,stroke-width:4px

本轮变更说明：

元素	变更类型	说明
C	新增	新增服务C
B->C	修改	原为 B->D，D 已删除
B->D	删除	D 不再使用

示例 2：sequenceDiagram（新增参与者、修改消息）

sequenceDiagram
    participant A as 服务A
    participant B as 服务B

    box rgb(255, 215, 0) 新增服务C
        participant C as 服务C
    end

    A->>B: 查询数据

    rect rgb(255, 215, 0)
        B-->>A: 返回结果
    end

本轮变更说明：

元素	变更类型	说明
C	新增	新增服务C作为后续确认处理方
B-->>A: 返回结果	修改	原为"返回数据"
B->>A: 旧的确认消息	删除	确认逻辑移入C

清理步骤

写操作前执行：

1. 移除全文档所有 <mark> </mark> 标签（保留内容）
2. 移除 mermaid 图中上一轮遗留的黄色高亮样式：
   • 所有 fill:#FFD700 恢复为原色
   • 所有 stroke:#FFD700 恢复为默认
3. 移除所有 mermaid 图下方的"本轮变更说明"表
4. 上一轮已删除的节点/连线/消息已在当时移除，无需额外清理

---

Mermaid 图按需加载策略

画图规范.md 约 1000 行，按需读取，不全文加载。按模板文件加载策略优先从工程级路径读取。

加载映射

模板章节	需要的图	读取规范的章节
2.2 系统结构	系统上下文图 / 软硬件拓扑图	## 四、系统上下文图 或 ## 十四、软硬件拓扑图
2.2 系统结构	子系统上下文图	## 五、子系统上下文图
3.1.2 全局类关系图	类图	## 十三、类图（连接线类型 + C++ 映射 + 示例）
3.x.2 模块结构及依赖	模块结构及依赖图	## 六 / ## 七 / ## 八
3.x.3 类关系图	类图	## 十三、类图（连接线类型 + C++ 映射 + 测量框架类图）
3.x.5 核心流程说明	流程时序图（类）	## 十二、流程时序图(类)
3.x.6 核心线程说明	线程图（模块内）	## 十五、线程图（模块内示例）
4.1 跨模块线程说明	线程图（模块间）	## 十五、线程图（模块间示例）
5. 接口设计	系统接口图	## 四、系统上下文图（系统接口图变体）
6.2 逻辑设计	E-R 图	## 十七、E-R 图
7. 软件目录结构	—	不需要 mermaid

加载规则

• 每章绘制前，搜索 mermaid画图规范.md 中对应的 ## 标题，只读那一节到下一个 ## 为止
• 通用规范（## 一、通用规范）在每个设计任务开始时读一次
• 不需要的图类型不加载

---

代码探查规则

1. 确定范围：先和用户确认本次设计涉及哪些模块
2. 定位代码：根据工程级模块索引找到每个模块的源码路径
3. 按需提取：

目的	方法
接口描述	读 .h 的 public 方法签名
类关系	读 .h 的继承声明、成员指针、智能指针
核心流程	读 .cpp 关键函数的调用链
线程	grep 搜索 std::thread、pthread_create、std::async
缓存	grep 搜索 DataCache、m_cache、m_map
数据库	grep 搜索 CREATE TABLE、INSERT INTO、sqlite3
异常	grep 搜索 LOG_ERROR、try、catch

---

输出注意事项

1. 章节边界：每输出一个 H2 或 H3 章节后，暂停，确认内容后再继续
2. Mermaid 语法：确保无语法错误——类名不含 {，箭头语法正确。正常生成的 sequenceDiagram 尽量不用 box/rect 着色；用于增量标记时，可用 box rgb(255, 215, 0) 高亮参与者、用 rect rgb(255, 215, 0) 包裹变更消息块
3. 交叉引用：文内引用的章节编号必须与实际一致（如 参见 3.1.1 命名规范）
4. TLDR：全文档完成后，最后写 TLDR 一行概括
5. 占位符：模板中 {内容}、{类名} 等占位符，生成时替换为实际内容；无法确定的内容保留占位符并标注 <!-- 待确认 -->
6. 表格完整性：每个表格至少包含表头和一行示例数据，空表格标注为"暂无"