| 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 |
命名规范说明
- 基本格式：
{项目或迭代版本}_{端}_应用设计说明书.md
- 示例：
V2.3_机器人引导_服务端_应用设计说明书.md
- 示例：
迭代三_视觉检测_客户端_应用设计说明书.md
{项目或迭代版本}：取需求规格或版本计划中的版本号、迭代号或项目简称{端}：根据设计范围选择 服务端 或 客户端；同时涉及两端时，分别输出两份文档- 影响面分析：与对应详设文档同名，将
应用设计说明书 替换为 影响面分析
四种工作模式
模式一：新建详细设计
用户描述一个新需求，从零生成设计文档和影响面分析。
步骤：
-
收集意图：与用户确认设计范围——涉及哪些模块、新增还是修改、有无参考的已有设计
-
探查输入：
- 按模板文件加载策略读取 应用设计说明书_模板.md（优先工程级路径，回退
references/，全文，仅初次新建时加载）
- 搜索并读取需求相关文档（从数据来源表中按需选择）
- 搜索受影响模块的 README
-
探查代码（每个受影响的模块）：
.h 文件：提取类声明、继承关系、public 方法签名.cpp 文件：搜索线程创建 (std::thread / pthread_create)、缓存结构 (DataCache / m_cache)、异常处理 (LOG_ERROR / try-catch)、SQL 语句 (CREATE TABLE)- 仅搜索与本次设计相关的文件
-
按章生成：
- 按模板骨架逐章生成。每章先读注释理解要求，再结合输入内容生成
- 需要 mermaid 图时，按模板文件加载策略读取 画图规范.md 的对应章节（见下方"Mermaid 图按需加载策略"）
- 生成顺序：第 1 章 → 第 2 章 → 第 3 章（全局设计 → 各模块）→ 第 4 章 → 第 5 章 → 第 6 章 → 第 7 章 → 第 8 章
- 第 3 章生成时，按模块顺序（被依赖的先写）
-
生成影响面分析：
- 按模板文件加载策略读取 设计变更影响面分析_模板.md
- 根据设计文档中的变更内容，填充客户端变更（第 2 章）和服务端变更（第 3 章）
-
输出：保存两个文件到输出位置
模式二：增量更新
在已有设计文档基础上增量修改。
步骤：
-
读取已有文档：读取当前版本的设计文档
-
确认上一轮已完成评审（强提示 + 默认继续）：
- 检查文档中是否仍残留
<mark> 标签、mermaid 黄色高亮块或"本轮变更说明"表
- 若存在，提示用户："检测到上一轮迭代标记未清理，建议先完成评审。如无需处理，将在 5 秒后自动清理并继续。"
- 用户不回应或确认继续时，默认清理旧标记并继续；用户明确拒绝时停止
-
清除上一轮标记：清除上一轮遗留的所有标记（见"迭代标记与清理规范"）
-
探查变更影响：
- 根据变更描述，确定受影响的章节
- 读取相关代码文件的最新版本
- 仅在受影响的章节范围内工作
-
增量修改：
- 只重写受影响的章节，未变更的章节保持原样
- 新增/修改的内容用
<mark>...</mark> 包裹
- 删除的内容：直接从正文和 mermaid 图中移除，不在文档中保留被删除的原文或旧图元素
- 在章节末尾或 mermaid 图下方的"本轮变更说明"表中，用文字列出删除项（删除项描述可标黄），说明删除原因
-
更新影响面分析：
- 对比新旧设计文档的差异
- 更新影响面分析中对应的客户端（第 2 章）/服务端（第 3 章）变更章节
- 新的影响项用
<mark> 包裹
-
输出：覆盖原文件
模式三：单独生成影响面分析
步骤：
- 按模板文件加载策略读取 设计变更影响面分析_模板.md
- 对比两个版本设计文档的差异（或 git diff）
- 提取变更的文件、接口、数据库、配置维度
- 填充客户端（第 2 章）和服务端（第 3 章）变更列表
- 标注 AI 推断项（"影响的关联产品"置信度低，标记需人工确认）
模式四：发布定稿
清除所有迭代标记，输出可提交评审的最终版本。必须由用户显式触发，禁止在增量更新中自动执行。
步骤：
- 清除全文档所有
<mark> 和 </mark> 标签（保留内容文本）
- 清除 mermaid 图中所有变更标记：
- 移除
fill:#FFD700 黄色高亮样式，恢复节点原色
- 移除
stroke:#FFD700 黄色描边/加粗样式
- 移除所有 mermaid 图下方的"本轮变更说明"表
- 将 TLDR 和正文中的
{占位符} 替换为实际内容
- 更新修订记录表中的版本号和日期
- 输出
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），作为后续差异化生成的依据。
优先级
- 用户显式说明为第一优先级：如果用户在触发 skill 时明确指定了操作类型（例如"这是一个新增需求"、"只做查询和导出"、"涉及增删改"），直接按用户说明分类，不再自动推断。
- 自动识别为第二优先级：用户未显式说明时，根据需求规格说明书中的功能需求描述自动识别。
自动识别规则
| 操作类型 | 典型关键词/语义特征 |
|---|
| 增（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 渲染器中显示黄色高亮背景
写之前必须先确认并清理：
- 确认上一轮标记已完成评审（模式二步骤 2，强提示 + 默认继续）
- 清除上一轮遗留的所有
<mark> 和 </mark> 标签
- 清除 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 版本兼容性差 |
删除元素的处理
- 直接从 mermaid 图中移除被删除的节点、连线或消息
- 在图下方"本轮变更说明"表中用文字记录删除项，删除项描述可标黄
- 定稿阶段由用户触发，确认后无额外清理工作
每个 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 |
清理步骤
写操作前执行：
- 移除全文档所有
<mark> </mark> 标签（保留内容）
- 移除 mermaid 图中上一轮遗留的黄色高亮样式：
- 所有
fill:#FFD700 恢复为原色
- 所有
stroke:#FFD700 恢复为默认
- 移除所有 mermaid 图下方的"本轮变更说明"表
- 上一轮已删除的节点/连线/消息已在当时移除，无需额外清理
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 中对应的 ## 标题，只读那一节到下一个 ## 为止
- 通用规范（
## 一、通用规范）在每个设计任务开始时读一次
- 不需要的图类型不加载
代码探查规则
- 确定范围：先和用户确认本次设计涉及哪些模块
- 定位代码：根据工程级模块索引找到每个模块的源码路径
- 按需提取：
| 目的 | 方法 |
|---|
| 接口描述 | 读 .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 |
输出注意事项
- 章节边界：每输出一个 H2 或 H3 章节后，暂停，确认内容后再继续
- Mermaid 语法：确保无语法错误——类名不含
{，箭头语法正确。正常生成的 sequenceDiagram 尽量不用 box/rect 着色；用于增量标记时，可用 box rgb(255, 215, 0) 高亮参与者、用 rect rgb(255, 215, 0) 包裹变更消息块
- 交叉引用：文内引用的章节编号必须与实际一致（如
参见 3.1.1 命名规范）
- TLDR：全文档完成后，最后写 TLDR 一行概括
- 占位符：模板中
{内容}、{类名} 等占位符，生成时替换为实际内容；无法确定的内容保留占位符并标注 <!-- 待确认 -->
- 表格完整性：每个表格至少包含表头和一行示例数据，空表格标注为"暂无"
