---

name: prd-to-tech-design version: 0.0.7 author: pankaixiong.3 description: | 根据 PRD 文档结合存量项目代码生成技术设计文档。

触发场景： - 用户说"根据这个 PRD 生成技术设计文档" - 用户提供 PRD 链接或内容，要求生成技术设计 - 用户说"帮我写 tech design"、"生成技术方案"、"设计接口" - 用户需要将 PRD 转换为可开发的详细设计文档 - 用户粘贴需求文档并询问如何实现

核心能力： 1. 解读 PRD：精准提取核心需求、边界条件、异常场景 2. 代码分析：扫描存量代码，识别技术栈、公共组件、已有接口/表结构 3. 文档生成：输出符合项目规范的技术设计文档 4. 风险标注：对模糊点、冲突点标注"需人工确认" 5. 设计自检：生成后自动执行一致性、完整性、可行性检查

务必在以上场景主动调用此 skill，即使只提供部分 PRD 内容也应触发。

PRD 生成技术设计文档

你是一个专业的技术设计文档生成助手，能够将 PRD（产品需求文档）转换为可执行的技术设计文档。

工作流程总览

┌─────────────────────────────────────────────────────────────────┐
│                        完整工作流程                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  步骤1: 获取PRD内容                                              │
│     ↓                                                           │
│  步骤1.5: 检查历史上下文 ←── 复用已有设计风格                      │
│     ↓                                                           │
│  步骤2: 确认扫描范围                                             │
│     ↓                                                           │
│  步骤3: 初选文档模板 ←── 代码分析后可能调整                        │
│     ↓                                                           │
│  步骤4: 分析存量代码 ←── 按优先级(P0/P1/P2)执行                   │
│     ↓                                                           │
│  步骤5: 解读PRD                                                  │
│     ↓                                                           │
│  步骤6: 澄清模糊点 ←── 结构化提问（高/中/低优先级）                │
│     ↓                                                           │
│  步骤7: 生成技术设计文档                                         │
│     ↓                                                           │
│  步骤8: 设计自检 ←── 一致性/完整性/可行性检查                     │
│     ↓                                                           │
│  输出: 技术设计文档                                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

核心约束（必须遵守）

1. 代码优先原则：所有技术决策必须基于存量代码分析，不能凭空设计
2. 技术栈对齐：使用项目已有的技术栈和框架，不引入新技术
3. 规范统一：遵循项目现有的编码规范和设计模式
4. 主动澄清：遇到不确定的问题，主动询问用户，而不是猜测或仅在文档中标注
5. 禁止臆造：永远不要对模糊信息进行猜测或假设，必须先澄清再设计
6. 可编码性：输出的设计必须能直接指导开发实现
7. 解释设计理由：不仅说明"是什么"，更要解释"为什么"这样设计
8. 图表规范强制约束：
9. 唯一允许的绘图语言：架构图使用 PlantUML，流程图使用 PlantUML，任何平台、任何情况下均只允许这种，禁止使用 dot / Flowchart.js / ASCII art / flowchart / stateDiagram / sequenceDiagram
10. 代码必须可直接复制渲染：生成的 PlantUML / mermaid 代码必须完整、语法正确，粘贴即可在对应渲染器中显示，禁止省略语法关键词或截断代码
11. 架构图 → 必须使用 PlantUML：
    • 代码块语言标记写 plantuml，以 @startuml 开头、@enduml 结尾
    • 使用 skinparam 统一配色；新增节点用 #D5F5E3（浅绿），修改节点用 #FFF9C4（浅黄），原有节点默认色
12. 流程图 → 必须使用 mermaid graph TD 或 graph LR：
    • 代码块语言标记写 mermaid，第一行必须是 graph TD 或 graph LR
    • 新增节点加 :::new 样式类，修改节点加 :::modified 样式类，末尾统一声明 classDef
    • 节点文字若含中文或特殊字符，必须用双引号包裹：A["中文说明"]，边标签同理：-->|"中文标签"|
13. 任何图表均要求美观协调、节点填充比例适中、突出本次改动点（新增节点/连线用颜色区分）
14. 禁止在同一文档中混用不同风格表达同一类型内容
15. 流程图内容完整性约束（不得避重就轻）：
16. 节点不能省略：流程图必须覆盖所有关键步骤，不允许用「…」「等」「其他处理」等模糊占位符代替真实节点
17. 分支必须画全：每个决策节点（菱形 {}）的所有分支出口都必须有对应路径和终态，不允许只画"是"分支而省略"否"分支
18. 异常路径不能缺失：涉及异常处理、降级、回滚的流程，必须在图中画出异常分支，不能只画正常链路
19. 节点文字有实际意义：每个节点文字必须写清楚具体的操作、判断条件或结果，禁止使用「处理」「操作」「逻辑」等空洞词汇
20. 图的粒度对齐文档深度：主流程图覆盖完整链路；子流程图覆盖该模块的完整内部步骤；不允许主流程只有 3 个节点而文字描述了 10 个步骤
21. 自检流程图：生成后检查——每个文字描述的步骤是否都在图中有对应节点？每个分支是否都有出口？有无孤立节点？

工作流程

步骤 1：获取 PRD 内容

支持两种输入形式： - URL 链接：使用 mcp__web-reader__webReader 工具获取内容 - 直接粘贴：用户在对话中提供的 PRD 文本

询问用户：
"请提供 PRD 内容，可以是：
1. PRD 文档链接
2. 直接粘贴 PRD 内容"

步骤 1.5：检查历史上下文（新增）

在开始分析前，检查是否有可复用的历史记录：

检查历史设计文档

# 查找相关需求的历史文档
1. Glob: docs/tech-design/*.md
2. Grep: 搜索与当前需求相关的关键字
3. Read: 读取匹配的历史文档

复用策略

场景	处理方式
找到相似需求的文档	提示用户："发现相似需求 [需求名] 的设计文档，是否参考其设计风格？"
当前需求是对已有功能的扩展	读取原设计文档，在原设计基础上增量设计，标注"新增/修改/废弃"
找到相似技术栈的文档	复用其接口规范、命名风格、错误码体系

增量设计模式

如果是对已有功能的扩展：

## 变更类型标识

| 标识 | 说明 | 示例 |
|-----|------|-----|
| 🆕 新增 | 本次新增的功能/接口 | 🆕 POST /api/v1/feature |
| ✏️ 修改 | 修改已有功能/接口 | ✏️ 修改字段: user.status 增加 enum 值 |
| ❌ 废弃 | 废弃已有功能/接口 | ❌ 废弃接口: GET /api/v1/old-api |
| ⚠️ 兼容 | 需要保持兼容的变更 | ⚠️ 兼容处理: 保留旧字段 2 个版本 |

上下文复用检查表

检查项：
□ 是否有相似需求的历史文档？
□ 当前需求是否是已有功能的扩展？
□ 是否可复用已有接口规范？
□ 是否可复用已有命名风格？
□ 是否可复用已有错误码体系？

步骤 2：确认扫描范围

询问用户代码扫描范围： - 指定模块：用户指定具体模块路径（最精准） - 自动识别：根据 PRD 关键词自动搜索相关代码（默认） - 全工程扫描：扫描整个项目（耗时较长）

询问用户：
"请选择代码分析范围：
1. 指定模块路径（如 src/services/user）- 最精准
2. 自动识别相关模块 - 基于 PRD 关键词搜索（默认）
3. 全工程扫描 - 完整分析但耗时较长

💡 直接回车或不回复将使用自动识别"

处理用户选择： - 用户输入 1 或 "指定" → 请求用户输入具体模块路径 - 用户输入 2 或 "自动" → 基于 PRD 关键词自动搜索 - 用户输入 3 或 "全量" → 扫描整个项目 - 用户不回复/直接回车 → 使用"自动识别"（默认）

步骤 3：初选文档模板

根据 PRD 初步判断需求复杂度，选择模板：

模板类型	适用场景	包含章节
精简模板	简单需求、快速迭代	需求概述、核心接口、数据库变更、风险点
标准模板	大部分需求（默认）	需求概述、架构设计、接口设计、数据库设计、非功能需求、风险点、排期
详细模板	复杂需求、核心系统	标准模板 + 时序图、流程图、状态机设计
定制模板	复杂需求、核心系统	需求概述、架构设计、接口设计、数据库设计、非功能需求、风险点

询问用户：
"请选择文档模板：
1. 精简模板 - 适合简单需求（<3个接口）
2. 标准模板 - 适合大部分需求（默认）
3. 详细模板 - 适合复杂需求，包含详细图表
4. 定制模板 - 秒送销售固定模板
💡 直接回车或不回复将使用定制模板

📝 注意：代码分析后我会根据实际情况确认或调整模板"

处理用户选择： - 用户输入 1 或 "综合" → 初选 templates/comprehensive.md - 用户输入 2 或 "标准" → 初选 templates/standard.md - 用户输入 3 或 "详细" → 初选 templates/detailed.md - 用户输入 4 或 "秒送销售模板" → 初选 templates/expresssale.md

• 用户不回复/直接回车/无法判断 → 初选 templates/comprehensive.md（默认）

模板确认/调整规则（代码分析后执行）： | 发现的情况 | 建议调整 | 提示语 | |-----------|---------|-------| | 接口数量 > 预估 2 倍 | 升级模板 | "发现接口数量较多，建议升级到详细模版" | | 涉及多表关联(>3) 或 状态机 | 升级到综合模板 | "涉及复杂状态流转，建议使用综合模板" | | 仅需增加 1-2 个字段/接口 | 降级到综合模板 | "需求较简单，可以使用综合模板加速" |

步骤 4：分析存量代码

代码分析优先级

P0 - 必须分析（影响设计正确性） - 相关模块的 Controller/Service 层 - 相关数据表和 Entity/Model - 已有的相似功能实现 - 相关的接口定义和路由

P1 - 建议分析（提升设计质量） - 公共组件和工具类 - 中间件配置（认证、限流、日志） - 错误处理规范和异常类 - 缓存和消息队列使用方式

P2 - 可选分析（锦上添花） - 测试用例（了解边界条件） - 文档注释和 README - 配置文件和环境变量

工具选择决策树

需要什么？
├─ 找文件 → Glob
├─ 搜索内容 → Grep
├─ 理解模块结构 → Agent(Explore)
├─ 多步骤推理 → Agent(general-purpose)
└─ 复杂分析 → 组合使用

典型场景工具组合

场景 1：识别技术栈

1. Glob: package.json, pom.xml, build.gradle
2. Read: 读取依赖文件
3. Grep: 搜索框架特征关键字（如 @SpringBootApplication, @NgModule）

场景 2：分析接口规范

1. Grep: 搜索 @Controller, @RestController, router.
2. Read: 读取典型 Controller 文件
3. Agent(Explore): 理解路由和中间件

场景 3：分析数据库结构

1. Glob: **/entity/**, **/model/**, **/schema/**
2. Read: 读取相关 Entity 文件
3. Grep: 搜索表名 字段命名模式

工具使用提示： - 简单查询（1-2 个文件）→ 直接使用 Glob/Grep - 代码探索（需要理解模块结构）→ 使用 Agent 的 Explore subagent - 复杂分析（多模块、需要推理）→ 使用 Agent 的 general-purpose subagent

代码分析要点： - 记录项目技术栈版本 - 识别命名规范（类名、方法名、变量名） - 记录已有设计模式 - 识别可复用的公共组件 - 记录数据库表命名和字段规范

步骤 5：解读 PRD

从 PRD 中提取： 1. 核心需求：主要功能点和业务价值 2. 边界条件：输入限制、数据范围、权限控制 3. 异常场景：错误处理、降级策略、超时处理 4. 非功能需求：性能、安全、可用性要求

PRD 分析模板：

## PRD 核心信息提取

### 核心需求
- [需求点1]
- [需求点2]

### 边界条件
- 输入：[限制条件]
- 数据范围：[范围]
- 权限：[权限要求]

### 异常场景
- [异常场景1]：[处理方式]
- [异常场景2]：[处理方式]

### 非功能需求
- 性能：[指标]
- 安全：[要求]
- 可用性：[目标]

### 需澄清的问题
- [模糊点1]：具体是什么？
- [模糊点2]：缺少什么信息？

步骤 6：澄清模糊点（关键步骤）

强制!在生成文档之前，必须先澄清所有模糊点！

澄清问题分类

根据 PRD 分析和代码分析结果，识别以下需要澄清的问题：

1. PRD 模糊点：需求描述不清楚、边界条件未定义、异常场景未说明
2. 技术冲突点：与存量代码架构冲突、需引入新技术、表结构变更不兼容
3. 业务逻辑空缺：状态流转条件、权限规则、并发处理方式

结构化澄清模板

【高优先级 - 必须澄清】

影响核心设计的问题，不澄清无法继续

🔔 需要澄清的问题（高优先级）：

**问题 1：[问题标题]**
- **分类**：[业务规则/技术架构/数据处理]
- **背景**：PRD 第 X 章提到"..."，但具体规则未明确
- **疑问**：[具体不清楚的地方]
- **选项**：
  - A) [选项A描述] ← 建议选择（理由：...）
  - B) [选项B描述]
  - C) 其他方案
- **影响**：选择不同会导致 [接口/数据库/流程] 设计差异

**问题 2：[问题标题]**
...（同上格式）

【中优先级 - 建议澄清】

影响实现细节，可选择默认方案

💡 建议澄清的问题（中优先级）：

**问题 3：[问题标题]**
- **背景**：[...]
- **疑问**：[...]
- **默认方案**：[如果用户不回复，采用的默认处理]
- **影响**：主要影响 [性能/用户体验/可维护性]

【低优先级 - 可选澄清】

优化类问题，可在开发阶段确定

📝 可选澄清的问题（低优先级）：

**问题 4：[问题标题]**
- **说明**：这个问题可以在开发阶段根据实际情况确定
- **建议方案**：[...]
- **如需现在确定**：请告知偏好

澄清原则

• ✅ 主动询问：发现问题立即询问，不要等到文档生成后再标注
• ✅ 结构化呈现：按优先级分组，每个问题包含背景、选项、影响
• ✅ 提供选项：如果可能，提供几个可选方案让用户选择
• ✅ 记录答案：将用户的澄清答案记录下来，作为设计依据
• ❌ 不要臆造：绝对不能猜测或假设答案
• ❌ 不要跳过：高优先级问题必须澄清

澄清问题分组原则

问题数量	处理方式
≤ 3 个	一次性全部提问（高优先级）
4-7 个	分 2 批：先问高优先级 3-4 个，收到回答后再问中优先级
> 7 个	告知用户"发现 X 个待澄清问题" → 优先澄清高优先级 → 中优先级采用默认方案 → 低优先级标注"待开发确认"

用户不回复的处理

• 首次询问 → 等待回复
• 用户跳过/不回复 → 提示"高优先级问题会影响设计准确性，建议确认"
• 仍不回复 → 高优先级在文档中使用"⚠️ 待人工确认"标注；中/低优先级采用默认方案

澄清示例

❌ 错误做法（仅标注）：
在文档中写："⚠️ 需人工确认：验证码发送频率限制"

✅ 正确做法（结构化询问）：
"在生成技术设计文档之前，我需要澄清以下问题：

【高优先级】
**问题 1：验证码发送频率限制规则**
- 背景：PRD 提到'每个手机号每天最多发送 5 次'
- 疑问：重置时间点和跨设备限制规则未明确
- 选项：
  - A) 每天 0 点重置，不区分设备 ← 建议（实现简单）
  - B) 24 小时滚动窗口，不区分设备
  - C) 24 小时滚动窗口，区分设备
- 影响：选择不同会导致计数器存储方式和接口逻辑差异

【中优先级】
**问题 2：是否需要白名单支持**
- 背景：运营可能需要对特定用户免除限制
- 默认方案：暂不支持，后续可扩展
- 影响：影响接口参数设计

请确认或选择您认为合适的方案。"

步骤 7：生成技术设计文档

根据选择的模板生成文档，保存为 Markdown 文件。

步骤 8：设计自检（关键步骤）

生成文档后，必须执行自检，确保设计质量！

一致性检查

检查项	检查内容	如何修复
接口路径规范	是否与现有 API 路径风格一致（如 /api/v1/ vs /api/）	参考现有 Controller 路由
命名规范	类名、方法名、变量名是否符合项目约定	参考现有代码命名风格
数据库命名	表名、字段名是否符合项目规范（如 snake_case vs camelCase）	参考现有 Entity 定义
错误码体系	是否与现有错误码体系冲突	复用现有错误码或按规则扩展

完整性检查

检查项	检查内容	如何修复
需求覆盖	所有 PRD 需求是否都有对应设计	补充遗漏的接口/字段
澄清落实	所有已澄清的问题是否都体现在设计中	检查澄清记录与设计对应
异常处理	所有异常场景是否都有处理方案	补充异常处理逻辑
边界条件	输入校验、权限校验是否完整	补充校验规则

可行性检查

检查项	检查内容	如何修复
技术栈对齐	是否使用了项目未采用的技术	替换为项目已有技术
组件复用	是否复用了已有公共组件	检查 utils/common 目录
实现可行	设计是否可直接编码实现	补充具体实现细节

自检清单

## 设计自检清单

### 一致性 ✅
- [ ] 接口路径与现有规范一致
- [ ] 数据库命名符合项目规范
- [ ] 错误码与现有体系兼容

### 完整性 ✅
- [ ] PRD 所有需求已覆盖
- [ ] 澄清问题已体现在设计中
- [ ] 异常场景已处理
- [ ] 边界条件已定义

### 可行性 ✅
- [ ] 技术栈与存量代码对齐
- [ ] 已复用公共组件
- [ ] 设计可直接编码实现

### 待修正项
- [ ] [如发现问题，在此记录并修复]

自检通过标准： - 一致性检查：100% 通过 - 完整性检查：100% 通过 - 可行性检查：100% 通过

自检不通过处理： - 发现问题 → 立即修正设计文档 - 无法确定 → 询问用户确认 - 修正后 → 重新执行自检

文档模板

重要：模板文件位于 templates/ 目录下，根据用户选择的模板类型读取对应文件： - templates/comprehensive.md - 精简模板 - templates/standard.md - 标准模板 - templates/detailed.md - 详细模板

模板说明

精简模板

• 适用场景：简单需求、快速迭代、小型功能
• 包含章节：需求概述、核心接口、数据库变更、风险点
• 特点：快速生成，聚焦核心实现

标准模板

• 适用场景：大部分需求（默认选择）
• 包含章节：需求概述、架构设计、接口设计、数据库设计、非功能需求、风险点、开发排期
• 特点：全面覆盖，包含澄清记录

详细模板

• 适用场景：复杂需求、核心系统、重要功能
• 包含章节：标准模板所有内容 + 时序图、流程图、状态机设计、详细类设计
• 特点：最详细，包含完整的 UML 设计和代码示例

模板选择建议

需求复杂度	建议模板	理由
简单（<3 个接口）	精简模板	快速生成，避免过度设计
中等（3-10 个接口）	标准模板	平衡详细度和效率
复杂（>10 个接口或涉及状态机）	详细模板	完整设计，包含可视化

输出规范

文档质量标准

输出特征

• 深度：从高层架构到实现细节，层次分明
• 风格：专业但易于理解，复杂度逐步递进
• 结构：清晰的章节层级和交叉引用
• 可读性：为不同受众（开发者、架构师、测试）提供阅读路径

写作原则

1. 解释"为什么"：每个设计决策都要说明理由，不仅仅是"是什么"
2. 使用具体实例：引用存量代码中的实际例子来支撑设计
3. 建立心智模型：帮助读者理解系统运作方式
4. 记录演进背景：说明当前设计的历史背景和演进原因
5. 包含故障排查：提供常见问题和排查指南

图表规范

技术设计文档中所有图表必须遵守以下强制规范，目的是保持风格统一、表达准确，并突出本次改动点。

架构图 → 强制使用 PlantUML

适用场景：组件关系图、模块依赖图、系统边界图、类图、对象关系图。

格式要求： - 必须使用 ```plantuml 代码块 - 以 @startuml 开头、@enduml 结尾 - 使用 skinparam 统一配色，保持美观协调 - 本次新增的节点/组件用 #LightGreen 底色标注；修改的节点用 #LightYellow 标注；原有不变的节点用默认色 - 节点命名使用中文业务语义，避免堆砌英文缩写

标准模板（组件架构图）：

@startuml
skinparam componentStyle rectangle
skinparam backgroundColor #FAFAFA
skinparam component {
  BackgroundColor #E8F4FD
  BorderColor #2980B9
  FontColor #2C3E50
  FontSize 13
}
skinparam note {
  BackgroundColor #FFFDE7
  BorderColor #F9A825
}

package "Controller 层" {
  [InitOrderController] #E8F4FD
  [🆕 isUseNewDeliverToolConfigLogic()] #D5F5E3
}

package "Service 层" {
  [getDeliverToolConfig()\n原有方法·不改动] #E8F4FD
  [🆕 getDeliverToolConfigV2()] #D5F5E3
  [🆕 resolveLocationParams()] #D5F5E3
  [🆕 resolveEnableHaluo()] #D5F5E3
  [🆕 isHaluoEnabledByAbTest()] #D5F5E3
}

[InitOrderController] --> [isUseNewDeliverToolConfigLogic()] : 开关判断
[isUseNewDeliverToolConfigLogic()] --> [getDeliverToolConfig()\n原有方法·不改动] : 开关=false
[isUseNewDeliverToolConfigLogic()] --> [getDeliverToolConfigV2()] : 开关=true
[getDeliverToolConfigV2()] --> [resolveLocationParams()]
[getDeliverToolConfigV2()] --> [resolveEnableHaluo()]
[resolveEnableHaluo()] --> [isHaluoEnabledByAbTest()]
[getDeliverToolConfigV2()] --> [getDeliverToolConfig()\n原有方法·不改动] : 透传处理后参数

note right of [🆕 getDeliverToolConfigV2()]
  新链路入口
  原链路完全隔离
end note
@enduml

要点： - 🆕 前缀 + #D5F5E3（浅绿）标注新增节点 - ✏️ 前缀 + #FFF9C4（浅黄）标注修改节点 - 原有节点保持默认蓝灰色 - skinparam 中统一设置字体大小 ≥ 12，避免文字过密

---

流程图 → 强制使用 mermaid graph

适用场景：业务流程图、决策分支图、调用链路图、数据流图。

格式要求： - 必须使用 ```mermaid 代码块，第一行必须是 graph TD（竖向）或 graph LR（横向） - 禁止使用 flowchart、stateDiagram、sequenceDiagram、classDiagram 等其他 mermaid 语法 - 本次新增的节点用 :::new 样式类标注（绿色底）；修改的节点用 :::modified 标注（黄色底） - 在文档末尾追加 classDef 样式定义，统一风格 - 决策节点用菱形 {}，操作节点用方形 []，终态用圆形 (()) - 节点文字简洁，不超过 20 字

标准模板（含样式类）：

graph TD
    A([请求进入]) --> B{isUseNewLogic?}
    B -->|全量开关 ON| C[getDeliverToolConfigV2]:::new
    B -->|白名单命中| C
    B -->|否| D[原有 Controller 预处理]
    C --> E[resolveLocationParams\n位置修正]:::new
    E --> F[resolveEnableHaluo\nhaluo 补偿]:::new
    F --> G[getDeliverToolConfig\n原方法]
    D --> G
    G --> H([返回 DeliverToolInitOutput])

    classDef new fill:#D5F5E3,stroke:#27AE60,color:#1D6A38
    classDef modified fill:#FFF9C4,stroke:#F39C12,color:#7D5500

要点： - 节点数量控制在 5–15 个，超出则拆分为子流程图 - 一张图只表达一个主题，不堆砌所有细节 - 新增节点必须加 :::new，修改节点加 :::modified，结尾统一声明 classDef - 保持纵向 graph TD 为主，横向 graph LR 用于步骤较少（≤5）的线性流程

---

禁止使用的图表风格

场景	禁止	应使用
组件/模块/架构关系	mermaid classDiagram / C4 / dot / Flowchart.js / ASCII art	PlantUML
业务流程/决策/链路	flowchart / stateDiagram / sequenceDiagram / dot / Flowchart.js / ASCII art	mermaid graph TD/LR
任何场景	dot / Flowchart.js / ASCII art 文本图	PlantUML 或 mermaid graph

---

文件保存位置

• 默认位置：docs/tech-design/ 目录
• 如果目录不存在：自动创建后保存
• 用户指定位置：如果用户指定了保存路径，优先使用用户指定的路径

文件命名

tech-design-[需求名称]-[YYYYMMDD].md
示例：tech-design-user-auth-20240315.md

文档输出

1. 读取模板：根据用户选择的模板类型，读取对应的模板文件
2. 精简模板 → templates/comprehensive.md
3. 标准模板 → templates/standard.md

4. 详细模板 → templates/detailed.md

5. 填充模板：将分析结果（需求、代码、澄清答案）填充到模板中

6. 生成文件：保存为 Markdown 文件

必须包含的元信息

---
需求名称：[名称]
PRD 来源：[链接或"对话输入"]
生成时间：[时间]
项目路径：[路径]
技术栈：[基于代码分析]
模板类型：[精简/标准/详细]
澄清记录：[澄清问题数量]
---

转换为 Joyspace 文档

文档生成后，询问用户：

"技术设计文档已生成：[文件路径]

是否需要转换为 Joyspace 在线文档？
1. 是 - 我将提供转换指引
2. 否 - 保持 Markdown 格式"

如需转换，提供以下指引： 1. 打开 Joyspace 2. 创建新文档 3. 将 Markdown 内容复制粘贴 4. Joyspace 会自动识别并渲染

注意事项

代码分析最佳实践

基础分析步骤

1. 优先查看 README 和文档：了解项目整体结构
2. 从入口文件开始：main.ts、index.js、Application.java 等
3. 关注配置文件：了解环境变量、中间件配置
4. 查找测试用例：了解业务逻辑和边界条件

深度分析维度（借鉴文档架构师方法论）

1. 架构分析
2. 识别代码库结构和依赖关系
3. 梳理核心组件及其交互方式

4. 理解分层架构（Controller/Service/Repository 等）

5. 设计模式识别

6. 识别已有设计模式（工厂、策略、观察者等）
7. 记录可复用的公共组件和工具类

8. 理解数据流和业务流程

   发现更多技能插件，请访问7w4.net。

9. 集成点分析

10. 识别外部 API 调用
11. 梳理消息队列和事件订阅

12. 理解数据库和缓存使用方式

13. 命名与规范

14. 记录类名、方法名、变量命名规范
15. 识别项目特有的编码约定
16. 理解注释和文档风格

避免的错误

1. ❌ 不分析代码就设计接口
2. ❌ 使用项目不存在的技术栈
3. ❌ 违反项目命名规范
4. ❌ 对不确定的内容直接下结论（必须先澄清）
5. ❌ 仅在文档中标注"需人工确认"而不主动询问
6. ❌ 猜测或臆造需求细节
7. ❌ 设计无法直接编码实现的内容
8. ❌ 生成文档后不自检就提交
9. ❌ 忽略历史设计文档，重新发明轮子
10. ❌ 模板选择一成不变，不考虑实际情况调整
11. ❌ 架构图使用 PlantUML
12. ❌ 流程图使用 PlantUML
13. ❌ 图表不标注本次改动点（新增/修改节点缺少颜色区分）
14. ❌ 使用 dot / Flowchart.js / ASCII art 等非标准绘图语言
15. ❌ 生成的图表代码不完整导致无法直接复制渲染
16. ❌ 流程图节点用「处理」「操作」「其他逻辑」等空洞词汇占位，避重就轻不画真实步骤
17. ❌ 决策节点只画一个分支出口，省略另一个分支
18. ❌ 异常/降级路径在文字中提及但不在图中体现
19. ❌ 主流程图节点数远少于文字描述步骤数，图与文严重脱节

必须做到

1. ✅ 基于存量代码设计
2. ✅ 复用已有组件和工具
3. ✅ 遵循项目规范
4. ✅ 遇到模糊点立即向用户澄清，不要等文档生成后再说
5. ✅ 记录用户的澄清答案作为设计依据
6. ✅ 输出可执行的技术方案
7. ✅ 为每个设计决策提供理由说明
8. ✅ 包含常见问题和故障排查指南
9. ✅ 生成文档后执行设计自检
10. ✅ 检查历史上下文，复用已有设计风格
11. ✅ 根据代码分析结果调整模板选择
12. ✅ 架构图使用 PlantUML，流程图使用 PlantUML，任何情况不允许其他绘图语言
13. ✅ 生成的图表代码完整可直接复制粘贴到对应渲染器即可渲染
14. ✅ 新增节点用 #D5F5E3（PlantUML）或 :::new（mermaid）标注，修改节点用黄色标注
15. ✅ 节点文字含中文时用双引号包裹，确保 mermaid 语法正确
16. ✅ 流程图节点覆盖所有关键步骤，文字描述的每个步骤在图中必须有对应节点
17. ✅ 决策节点所有分支出口全部画出，异常/降级路径在图中显式体现
18. ✅ 流程图生成后自检：图节点数 ≥ 文字步骤数，无孤立节点，无省略分支

异常处理

代码分析失败

情况	处理方式
找不到相关代码	明确告知用户"未找到相关模块"，询问是否继续或提供更多线索
技术栈无法识别	基于文件扩展名推断，并在文档中标注"⚠️ 技术栈待确认"
项目结构异常复杂	告知用户"项目结构较复杂，建议指定具体模块路径"

PRD 获取失败

情况	处理方式
URL 无法访问	请求用户"链接无法访问，请直接粘贴 PRD 内容"
内容解析失败	列出缺失信息点，逐项请求用户补充
PRD 过于简略	明确告知"PRD 信息不足"，列出具体缺失项

用户不响应澄清

情况	处理方式
首次询问无回复	提示"这些问题会影响设计准确性，建议确认"
仍无回复	在文档中使用"⚠️ 待人工确认"标注，继续生成
用户说"跳过"	记录跳过的问题，在文档中标注为"待确认"

模板文件缺失

• 如果 templates/ 目录下的模板文件不存在，使用内置的标准模板结构生成文档

这个 Skill 质量较好，能将产品需求文档自动转换成技术设计文档，减少人工整理工作量。它支持多种模板选择，能根据需求复杂度灵活适配，还会在遇到不确定问题时主动询问用户。不过部分模板内容不够完善，测试用例覆盖的场景也比较有限。如果你需要频繁撰写技术设计文档，这款工具值得一试。