Menu
编写 C++ 项目的详细设计文档和设计变更影响面分析。当用户说要写详细设计、生成设计文档、做影响面分析、描述功能需求要写设计、或者说"把这个需求的设计写出来"时触发。也用于增量更新已有设计文档、以及清除迭代标记输出最终版。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Generate comprehensive test cases from already analyzed or decomposed requirements specifications. Use when the input is a completed requirements breakdown, feature specification, PRD analysis, user story map, acceptance criteria list, or module/function requirements and the user wants test case design, scenario expansion, module-based test flows, coverage review, or exportable test case documents in Markdown, Excel/XLSX, CSV, or document formats.
Use when refining an architecture or design document based on new learnings, before a rewrite. Use when you have an existing doc and related docs to cross-check against. Use when you need systematic section-by-section validation of decisions.
项目文档的全生命周期管理。支持：初始化文档（按阶段+范围选择性生成）、更新文档（扫描代码对比，输出差异并更新）。范围可指定仅仓库级/指定子工程/全部。与 project-structure-init 配合使用但不强制依赖。当用户说"初始化文档"、"更新文档"、"生成文档"、"补文档"、"刷新文档"、"同步文档与代码"、"检查文档"、"只初始化仓库级"、"只更新某个文档"时触发。
根据《软件工程目录规范》自动创建仓库级和工程级（C++）的完整目录结构及文档骨架。自动识别当前目录所属级别，仓库级则逐级向下完成全部初始化。当用户说"初始化项目结构"、"创建仓库目录"、"搭建工程结构"、"按规范创建目录"、"初始化docs"、"创建C++工程"时触发。增量创建，已存在的文件和目录不会覆盖。
系统性技术问题诊断框架。通过"边界收敛→分支诊断→假设验证→证据链→方案决策"五步法，将试错式排查变为结构化分析。当用户说"分析这个问题"、"报错了帮我看看"、"定位一下根因"、"帮我分析一下这个现象"、"这个Bug怎么查"、"内存泄漏/崩溃/性能退化/死锁怎么定位"、或描述了任何软件异常现象时触发。不用于产品需求分析或日常决策（那是 structured-thinking 的范畴）。
在代码提交（svn commit / git commit）前，自动执行一套完整的审查与提交辅助流程： 1. 阅读项目 CLAUDE.md 了解项目功能模块背景； 2. 阅读编码规范约束（统一编码约束、Qt 命名规范、日志规范）； 3. 自动调用 code-review-skill 对已完成的改动进行结构化评审； 4. 输出评审报告+修改说明，提交给用户进行确认； 5. 用户确认修复完成后，输出本次修改说明。 使用时机：用户说"要提交代码了"、"帮我审一下改动"、"看看这些改动有什么问题"、"准备 commit / svn ci"、或者直接描述需要提交评审的场景时，**必须**触发本 skill。 注意：本 skill 不直接执行 commit / push 等命令，仅输出报告和提交说明，由用户手动执行提交。
| name | write-design-doc |
| description | 编写 C++ 项目的详细设计文档和设计变更影响面分析。当用户说要写详细设计、生成设计文档、做影响面分析、描述功能需求要写设计、或者说"把这个需求的设计写出来"时触发。也用于增量更新已有设计文档、以及清除迭代标记输出最终版。 |
从需求规格、概要设计、项目代码等输入，生成符合模板规范的详细设计文档和设计变更影响面分析。
模板和规范文件优先从工程级路径读取，若工程级路径不存在，则回退到 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{项目或迭代版本}：取需求规格或版本计划中的版本号、迭代号或项目简称{端}：根据设计范围选择 服务端 或 客户端；同时涉及两端时，分别输出两份文档应用设计说明书 替换为 影响面分析用户描述一个新需求，从零生成设计文档和影响面分析。
步骤：
收集意图：与用户确认设计范围——涉及哪些模块、新增还是修改、有无参考的已有设计
探查输入：
references/，全文，仅初次新建时加载）探查代码（每个受影响的模块）：
.h 文件：提取类声明、继承关系、public 方法签名.cpp 文件：搜索线程创建 (std::thread / pthread_create)、缓存结构 (DataCache / m_cache)、异常处理 (LOG_ERROR / try-catch)、SQL 语句 (CREATE TABLE)按章生成：
生成影响面分析：
输出：保存两个文件到输出位置
在已有设计文档基础上增量修改。
步骤：
读取已有文档：读取当前版本的设计文档
确认上一轮已完成评审（强提示 + 默认继续）：
<mark> 标签、mermaid 黄色高亮块或"本轮变更说明"表清除上一轮标记：清除上一轮遗留的所有标记（见"迭代标记与清理规范"）
探查变更影响：
增量修改：
<mark>...</mark> 包裹更新影响面分析：
<mark> 包裹输出：覆盖原文件
步骤：
清除所有迭代标记，输出可提交评审的最终版本。必须由用户显式触发，禁止在增量更新中自动执行。
步骤：
<mark> 和 </mark> 标签（保留内容文本）fill:#FFD700 黄色高亮样式，恢复节点原色stroke:#FFD700 黄色描边/加粗样式{占位符} 替换为实际内容所有由本 Skill 生成的文档（含 AI-native 版详设文档和影响面分析）必须遵守以下约束。这些规则不写入模板正文，而是作为 Skill 生成指令的一部分执行。
生成文档时，为下列对象分配唯一 ID，并确保跨章节引用一致：
| 对象类型 | ID 前缀 | 示例 | 使用位置 |
|---|---|---|---|
| 需求 | REQ- | REQ-001 | 需求追踪、功能说明、实现任务 |
| 接口 | IF- | IF-001 | 接口契约、接口变更、实现任务 |
| 数据表 | TBL- | TBL-001 | 表汇总、数据库变更、实现任务 |
| 风险 | RISK- | RISK-001 | 风险与注意事项、实现任务 |
| 实现任务 | TASK- | TASK-001 | 实现任务清单 |
规则：
关联接口/表/风险 列必须填写对应 ID。以下字段只能使用指定枚举值，禁止自由文本：
| 字段 | 允许取值 |
|---|---|
| 操作类型 | 增 / 删 / 改 / 查 |
| 影响评估 | 无影响 / 增加 / 减少 / 待评估 |
| 兼容策略 | 兼容 / 不兼容 / 自动迁移 / 手动配置 / 需迁移脚本 |
| 严重程度 | 高 / 中 / 低 |
| 线程安全 | 是 / 否 / 部分 |
| 置信度 | 高 / 中 / 低 |
| 置信度 | 判定规则 |
|---|---|
| 高 | 可直接从代码或需求原文验证，无跨模块推理 |
| 中 | 需要跨文件或跨模块推理，存在一定合理假设 |
| 低 | 需要跨工程/跨产品推断，或信息不足，必须人工确认 |
<mark> 或加粗方式突出显示。<mark>）。所有性能相关表格必须包含：
| 字段 | 说明 |
|---|---|
| 基线值 | 变更前的测量值；无法确定时填“需人工填写” |
| 目标值 | 变更后期望达到的测量值；无法确定时填“需人工填写” |
| 测量方法 | 如何测量，如单请求压测、并发压测、内存监控等 |
接口契约表必须包含以下字段：
| 字段 | 说明 |
|---|---|
| 超时 | 接口调用超时时间；不适用时填 N/A |
| 重试 | 失败重试次数；不适用时填 N/A |
影响面分析中的 AI 推断项必须填写证据来源：
| 推断类型 | 证据来源示例 |
|---|---|
| 影响的模块 | 代码分析：include/Xxx.h、调用链搜索结果 |
| 影响的关联产品 | 跨工程关联推断；置信度为低时必须标注 |
| 性能影响 | 代码变更范围、调用链分析 |
| 回退策略 | 变更内容、配置文件变更 |
本 Skill 在需求分析、方案设计和影响面评估阶段必须遵循以下原则。这些原则约束 AI 的推理过程，而非文档格式。
所有分析结论必须绑定可验证证据来源（需求条目、接口契约、数据模型、调用链、历史缺陷等）。无证据来源的推断必须标注为低置信度。
每个结论必须给出反证路径和验证方式，确保结论可被推翻或验证，而不是只可证明、不可推翻。
对推断项必须标注置信度（高/中/低）。低置信度项必须进入人工确认清单，并在表格中用 <mark> 或加粗方式突出显示。
发现需求与约束、接口与数据模型、设计与实现现实冲突时，停止继续细化设计，先输出冲突清单并等待解决。
在设计阶段就完整列出文件、接口、数据库、配置、性能影响，不把影响面留到开发阶段补全。
先定义接口契约，再设计流程；涉及变更时，先定义版本策略与兼容边界。
方案设计时同步给出回退路径、数据可逆性判断、升级失败触发条件。
无基线和目标时，不允许写“无影响”；必须说明测量口径和阈值。
明确包含与不包含范围，超范围项必须单列并重新评估。
确保需求-设计决策-验证项可一一映射，为开发阶段提供可执行输入。
在进入具体模块设计前，先识别本需求/模块涉及的操作类型（增 Create、删 Delete、改 Update、查 Read/Query），作为后续差异化生成的依据。
| 操作类型 | 典型关键词/语义特征 |
|---|---|
| 增（Create） | 新增、创建、添加、插入、导入、注册、生成、初始化、上传 |
| 删（Delete） | 删除、移除、卸载、注销、清空、回收、废弃、下架 |
| 改（Update） | 修改、更新、编辑、变更、调整、配置、设置、启用/禁用、重置、状态变更 |
| 查（Query） | 查询、查看、搜索、筛选、列表、详情、统计、导出、报表、历史记录 |
关键词匹配容易产生误判，需结合上下文过滤：
| 过滤场景 | 示例 | 处理 |
|---|---|---|
| 否定词 | "不支持删除"、"无法修改"、"禁止查询" | 该关键词不计入对应操作类型 |
| 非操作对象 | "删除键"（键盘按键）、"查询语言"、"配置文件更新" | 判断动作是否有明确的业务数据对象，无对象则过滤 |
| 日志/记录类描述 | "更新日志"、"删除记录查看"、"历史修改记录" | 若关键词用于描述记录本身而非业务操作，过滤或降级为"查" |
| 将来/计划态 | "计划新增"、"未来可能删除" | 未在本次版本落地的操作，不计入 |
| 单一出现且无宾语 | 文本中只出现"删除"二字，未说明删除什么 | 置信度标为低，提示用户确认 |
一个需求可能同时包含多种操作。识别结果用逗号分隔列出，例如：增、改、查 或 增、删、改、查。
置信度标注：
对于中/低置信度的识别结果，在生成时标注 <!-- 待确认 -->，并提示用户核对。
识别出的 CRUD 类型用于指导后续章节生成：
XxxAddPage、XxxEditPage、XxxQueryPage）addXxx / removeXxx / updateXxx / queryXxx多轮迭代时，让评审者一眼看出本轮改了什么。
<mark>...</mark> 包裹<mark> 标签在大多数 Markdown 渲染器中显示黄色高亮背景写之前必须先确认并清理：
<mark> 和 </mark> 标签删除的内容直接从正文和 mermaid 图中移除，不在文档内保留被删除的原文或旧图元素。
若需让 reviewer 了解删除情况，在章节末尾或 mermaid 图下方的"本轮变更说明"表中列出删除项，删除项描述可用 <mark>...</mark> 标黄以突出显示。
示例：
**本轮变更说明**：
| 元素 | 变更类型 | 说明 |
|------|----------|------|
| 新接口 | 新增 | 新增替代接口 |
| <mark>旧接口</mark> | <mark>删除</mark> | <mark>已废弃，由新接口替代</mark> |
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 图下方必须补充"本轮变更说明"表：
**本轮变更说明**：
| 元素 | 变更类型 | 说明 |
|------|----------|------|
| 新节点 | 新增 | 新增 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> 标签（保留内容）fill:#FFD700 恢复为原色stroke:#FFD700 恢复为默认画图规范.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 |
{，箭头语法正确。正常生成的 sequenceDiagram 尽量不用 box/rect 着色；用于增量标记时，可用 box rgb(255, 215, 0) 高亮参与者、用 rect rgb(255, 215, 0) 包裹变更消息块参见 3.1.1 命名规范）{内容}、{类名} 等占位符，生成时替换为实际内容；无法确定的内容保留占位符并标注 <!-- 待确认 -->