一、前言：写详细设计，一半时间在搭框架、堆重复代码
概要设计定了架构方向，详细设计才是真正指导开发的交付物，但写起来极其耗时间：要拆解模块类结构、定义接口参数、设计库表索引、梳理时序流程、补充异常处理；团队输出标准不统一，新人容易直接堆代码却不讲设计逻辑，老手又觉得重复劳动性价比低；小型单体、中大型分布式、微服务架构的文档结构差异大，每次都要从零搭章节框架。
市面上让 AI 写详细设计的方案，大多是自由生成、深浅不一，要么通篇讲概念没有落地代码，要么直接堆工具类代码却没有业务设计逻辑；更没有固定的文档结构与技术规范，每次输出质量全看提示词，改来改去效率极低。
本文带来 detailed - design - doc - generator 详细设计自动生成 Skill，输入概要设计或功能清单，自动生成标准化详细设计文档。内置小型/中大型/微服务三套项目模板，支持全栈/后端/前端三重视角切换；强制「文字先行」原则，每个模块必须先讲功能、流程、设计思路，最后才输出类设计与代码，杜绝无逻辑的代码堆砌；支持增量生成指定章节，内置统一技术规范库，生成的代码与设计符合团队开发标准。
✅ 读完本文你能收获
1、完整可落地详细设计自动生成 Agent Skill，包含 SKILL.md 协议定义、三套项目模板、多技术栈代码模板、规范参考手册；
2、三套规模模板适配：小型单体（9章）、中大型分布式（14章）、微服务架构（16章），按需匹配不冗余；
3、三重视角输出能力：全栈/后端/前端可切换，自动裁剪无关章节，避免无效内容；
4、「文字先行」强约束：模块设计必须按功能概述→业务流程→设计思路→类设计四步走，杜绝直接堆代码；
5、智能增量生成机制：自动识别增量修改意图，仅生成指定章节，节省 token、提升迭代效率；
6、内置统一技术规范库，覆盖 Java 后端、数据库、缓存、消息队列、Vue 前端、高并发、容灾七大类规范；
7、前后端接口一致性保障，多视角生成仍保持接口路径、参数、响应格式、错误码完全统一；
8、Trae / OpenClaw 双平台完整部署教程，附带落地避坑清单；
9、全套资源包可下载，无需逐段复制模板与规范。
二、detailed - design - doc - generator Skill 核心能力一览
2.1 核心功能清单
1、 三套项目模板自动匹配
根据项目规模、并发量、数据量自动匹配对应模板：小型单体9章精简交付、中大型项目14章完整设计、微服务架构16章深度覆盖治理、容灾、链路追踪等非功能设计。
2、 三重视角按需输出
- 全栈视角：前后端完整章节，适合架构师与全栈开发；
- 后端视角：侧重模块设计、数据库、接口、安全、性能、容灾，精简前端内容；
- 前端视角：侧重页面结构、组件设计、API封装、状态管理，数据库转换为 TypeScript 类型定义。
3、 「文字先行」强约束
每个模块必须严格遵循「功能概述 → 业务流程 → 设计思路 → 类设计」的输出顺序，先讲清楚做什么、怎么流转、为什么这么设计，最后才输出实现代码，避免文档变成无意义的代码堆砌。
4、 多技术栈原生支持
后端覆盖 Java/SpringBoot、Python/FastAPI；前端覆盖 Vue3、UniApp；数据库覆盖 MySQL、Redis、MongoDB；中间件支持 RabbitMQ、Nacos、Elasticsearch；支持 AI 模型集成场景设计。
5、 智能增量生成
自动识别用户的补充/修改意图，询问确认后仅生成指定章节，不重复输出已有内容；文档头部标注增量更新说明，清晰区分版本差异。
6、 微服务分步生成
微服务架构文档内容量大，默认提供分步生成选项：服务治理、数据库缓存、消息队列、单服务设计分步输出，避免一次性输出截断。
7、 内置统一技术规范
内置 standards.md 规范手册，生成代码、配置、设计时自动对齐规范，包括命名规则、分层结构、统一响应、字段标准、缓存设计、容灾等级等，输出风格统一。
8、 前后端接口一致性保障
无论选择何种视角，接口路径、HTTP方法、参数名、响应结构、错误码完全保持一致；前端视角额外补充 TypeScript 类型定义、API 调用函数、Mock 数据，保证前后端对齐。
9、 内部自检机制
生成后自动执行内部自检：章节完整性、DDL 语句完整性、接口定义完整性、必备字段合规性、代码聚焦业务逻辑等，不合格自动修正。
2.2 适合人群
- 后端/前端开发：快速输出模块详细设计，不用从零搭框架；
- 架构师、技术负责人：统一团队文档标准，保证设计质量；
- 项目负责人：快速输出设计方案，支撑评审与排期；
- 使用 Trae / OpenClaw 搭建本地 Agent 自动化工作流的开发者。
三、Skill 完整架构与执行流程
3.1 技能目录结构
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| .trae/skills/detailed-design-doc-generator/ ├── SKILL.md # 核心定义：生成流程 + 模板规则 + 质量约束 + 触发条件 ├── templates/ # 内置模板库 │ ├── small_project.md # 小型项目模板（9章，单体应用） │ ├── standard_project.md # 中大型项目模板（14章，分布式系统） │ ├── microservice_design.md # 微服务架构模板（16章，高并发高可用） │ ├── java-backend-template.md # Java后端代码骨架模板 │ ├── database-design-template.md # 数据库设计模板 │ └── vue-frontend-template.md # Vue3前端代码模板 ├── references/ │ └── standards.md # 技术栈设计规范参考手册 └── .gitignore |
运行后生成产物：
|--------------------------------------------------|
| <输出目录>/ └── <项目名>_详细设计文档.md # 最终交付的标准化详细设计文档 |
3.2 完整四步工作链路
1、 第一步：交互式上下文收集
Agent 主动确认5类信息：基础输入（概要设计/功能清单）、项目规模、技术栈选型、特殊需求（高并发/多租户/金融级安全等）、输出视角；信息不足时使用默认值兜底，并标注待补充。
2、 第二步：模板选择与加载
根据项目规模自动匹配对应模板；微服务场景额外询问生成策略：分步生成（推荐）或全量生成，避免内容过长截断。
3、 第三步：生成详细设计文档
严格遵循选定模板的章节顺序与层级，执行「文字先行」强约束；按选定视角裁剪章节；校验前后端接口一致性；最终输出标准 Markdown 格式文档。
4、 第四步：输出与自检
文档末尾附生成摘要：模板版本、技术栈、生成时间、章节覆盖、AI自检状态；内部自检不通过的内容标注「需人工复核」。
3.3 模块设计输出样例（片段）
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| markdown ### 3.1 订单管理模块 #### 3.1.1 功能概述 订单管理模块是电商系统的核心交易模块，面向注册用户提供商品购买服务。主要功能包括购物车结算生成订单、订单状态流转、订单查询与详情查看、订单取消与退款申请。本模块与商品模块、支付模块、用户模块存在交互依赖。 #### 3.1.2 业务流程 **创建订单流程**： 1. 用户从购物车选择商品，点击"去结算" 2. 系统校验商品库存（调用商品模块），库存不足则提示用户 3. 系统计算订单金额（商品总价 - 优惠券折扣 + 运费） 4. 生成订单记录（状态：待支付），锁定库存（30分钟） 5. 跳转支付页面，等待用户完成支付 6. 支付成功后，订单状态变更为"已支付"，通知仓库发货 #### 3.1.3 设计思路 - 状态机模式：订单状态流转采用状态机模式管理，避免 if-else 嵌套，确保状态流转合法 - 乐观锁：库存扣减使用乐观锁（version 字段），防止并发超卖 - 最终一致性：订单创建涉及库存扣减，采用本地消息表+补偿机制保障数据最终一致 - 超时取消：待支付订单30分钟未支付自动取消，使用延迟消息队列实现 #### 3.1.4 类设计 @Service @Slf4j public class OrderServiceImpl implements OrderService { @Autowired private OrderMapper orderMapper; // 核心业务方法... } |
四、核心设计体系
4.1 三套项目规模模板
|---------|-----|----------------------------------------------|---------|
| 模板类型 | 章节数 | 适用场景 | 文档规模 |
| 小型项目模板 | 9章 | 团队3-5人、单体应用、数据量<100万、并发<1000 QPS | 20-50页 |
| 中大型项目模板 | 14章 | 团队10-30人、3-10个服务、数据量100万-1亿、并发1000-10000 QPS | 50-150页 |
| 微服务架构模板 | 16章 | 团队30人以上、10+服务、数据量>1亿、并发>10000 QPS | 150页以上 |
|-------------------------------------------|
| 微服务模板额外覆盖服务治理、分布式事务、多活容灾、混沌工程、全链路追踪等深度内容。 |
4.2 三重视角输出规则
|------|----------------------------------------|-------------------------|-------------------------|
| 视角 | 核心保留章节 | 精简/省略章节 | 特殊处理 |
| 全栈视角 | 全部章节 | 无 | 标准完整输出 |
| 后端视角 | 系统架构、模块设计、接口、数据库、缓存、消息队列、安全、性能、容灾、异常处理 | 前端设计仅保留接口定义说明 | 接口定义侧重后端实现细节 |
| 前端视角 | 系统架构（简化）、接口设计、前端详细设计、附录Mock数据 | 后端深度设计章节精简，数据库转换为TS类型定义 | 接口补充TS类型、API调用函数、Mock数据 |
4.3 「文字先行」强约束（核心质量闸门）
所有模块设计必须按四级结构展开，严禁跳过业务描述直接输出代码：
1、 功能概述：讲清模块做什么、给谁用、解决什么问题、依赖哪些外部模块；
2、 业务流程：按步骤描述核心业务流转，包含正常路径与关键异常分支；
3、 设计思路：说明技术选型理由、用到的设计模式、核心算法与权衡考虑；
4、 类设计/代码：最后输出实现骨架，聚焦业务逻辑，不堆砌工具类完整实现。
|------------------------------------------------|
| 自检规则：若模块缺少功能概述、业务流程、设计思路任一环节，判定为格式错误，自动补全后再输出。 |
4.4 增量生成机制
- 触发条件：用户提到「补充某模块」「修改某章节」「新增某部分设计」等增量意图时自动触发；
- 交互逻辑：列出可增量生成的章节，用户确认后仅输出选定内容；
- 文档标识：增量生成的文档头部标注「增量更新说明」，明确本次覆盖范围，避免与历史内容混淆；
- 核心价值：节省 token 消耗，避免重复生成已有内容，提升迭代效率。
4.5 内置技术规范体系
内置 standards.md 统一规范手册，生成代码与设计时自动对齐，输出风格一致：
- Java 后端规范：分层结构、命名规则、统一响应、异常处理、单元测试模板；
- 数据库设计规范：命名规则、字段类型、必备审计字段、索引设计原则、分库分表策略；
- 缓存设计规范：Key 命名、数据类型选择、一致性方案、穿透/击穿/雪崩防护；
- 消息队列规范：Exchange/Queue 命名、消息格式、可靠性保障、死信队列处理；
- Vue 前端规范：项目结构、API封装、Pinia状态管理、路由设计、组件开发规范；
- 高并发设计：限流算法、缓存策略、容量规划；
- 容灾备份设计：四级容灾等级定义、备份策略、故障转移方案。
4.6 前后端接口一致性保障
无论选择何种输出视角，接口层全局统一：
- 接口路径、HTTP 方法、参数名、响应结构、错误码完全一致；
- 前端视角额外补充 TypeScript 类型定义、可直接使用的 API 调用函数、Mock 数据示例；
- 接口定义统一遵循 RESTful 规范，支持版本控制与幂等性设计。
五、SKILL.md 核心定义与触发指令
5.1 Frontmatter 基础定义
|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| yaml --- name: "detailed-design-doc-generator" version: 1.0.0 description: "根据概要设计文档生成软件开发项目详细设计文档。支持Java、MySQL、RabbitMQ、Nacos、Redis、MongoDB、Python、Vue、UniApp、AI模型集成等技术栈，适配小型、中大型、微服务等各种规模项目。当用户需要写详细设计文档、创建详细技术文档、基于概要设计输出接口与数据库设计时调用。" --- |
5.2 自动触发场景
向 Agent 发送如下指令，即可自动调用本 Skill：
1、基于这份概要设计，生成详细设计文档；
2、给订单模块写详细设计，包含类结构和数据库；
3、补一下用户模块的接口设计和异常处理；
4、trae 任务指令示例：使用 detailed-design-doc-generator 基于概要设计生成中大型项目详细设计，后端视角
六、双平台部署实操教程
方案1：Trae部署
1、将完整 detailed-design-doc-generator 文件夹放置项目路径 .trae/skills/；
2、新建任务，任务描述示例：
|-------------------------------------------------------------|
| 使用 detailed-design-doc-generator 基于系统概要设计文档，生成中大型项目后端视角详细设计 |
3、建议先提供完整的概要设计或功能清单，信息越全输出质量越高。
方案2：OpenClaw 平台部署
1、将技能文件夹复制到 ~/.openclaw/skills/detailed‑design‑doc‑generator/；
2、对话输入概要设计内容与需求，发送指令：
|-------------------------------------|
| 生成微服务架构的详细设计文档，分步生成，先输出服务治理与数据库设计部分 |
3、生成后可直接获取完整 Markdown 格式文档。
|-------------------------------------------------------|
| 使用提示：微服务架构强烈建议选择分步生成，避免单轮输出过长导致内容截断；复杂项目优先选择后端视角精简内容。 |
七、落地避坑8条指南
⚠️坑1：信息不足强行生成，内容空洞缺细节
解决方案：优先提供完整的概要设计或功能清单；信息不足时工具会使用默认值，可后续补充信息重新生成。
⚠️坑2：要求跳过业务描述直接写代码，文档只有代码没有设计逻辑
解决方案：工具强制「文字先行」约束，不要手动要求省略概述与流程；设计文档的核心是设计思路，而非代码堆砌。
⚠️坑3：微服务选全量生成，输出内容被截断
解决方案：微服务默认推荐分步生成，按服务治理、数据存储、单服务设计逐次输出；不要强行选择全量生成。
⚠️坑4：选错输出视角，冗余内容多、重点不突出
解决方案：后端开发选后端视角，前端开发选前端视角，无需默认选全栈视角，减少无关信息。
⚠️坑5：前后端分开生成，接口定义不一致
解决方案：统一基于同一份概要设计生成，工具内置接口一致性校验；不要前后端各自独立写需求。
⚠️坑6：生成后直接修改最终文档，下次生成被覆盖
解决方案：大范围调整优先修改输入后重新生成；仅局部微调再直接修改最终文档。
⚠️坑7：所有项目都用同一套模板，小项目过度设计
解决方案：按项目规模、团队人数、并发数据量选择对应模板，小型项目用精简版即可，避免为不需要的功能增加复杂度。
⚠️坑8：忽略自检环节，低级错误没发现
解决方案：生成文档末尾附有自检状态，标注「需人工复核」的部分请重点检查；核心模块建议人工评审设计合理性。
八、配套资源领取
全套落地资源包已上传本人主页资源区，可直接自助下载，包含：
1、Detailed-design-doc-generator 完整 SKILL.md 技能定义（生成流程、模板规则、质量约束、触发条件）；
2、三套项目模板：小型项目、中大型项目、微服务架构模板；
3、三类代码模板：Java 后端模板、数据库设计模板、Vue3 前端模板；
4、技术栈设计规范参考手册 standards.md；
5、技能目录模板、.gitignore 配置。
领取方式：前往本人主页资源区自助下载；部署调试遇到问题，欢迎评论区留言交流。
九、系列回顾
往期完结系列
「Agent Skills开发实战」完整12篇专栏，覆盖Skill底层开发、编排、项目落地手册。
Skill应用系列往期回顾
1、Skill 应用 01：资讯聚合 Skill｜过滤广告标题党，只看你关心的新闻资讯
2、Skill 应用 02：文档精读 Skill｜百页报告 / 论文一键提炼核心，告别逐字通读
3、Skill 应用 03：会议纪要 Skill｜1 小时会议整理 1‑2 小时？6 分钟自动生成纪要 + 待办，效率提升 15 倍
4、Skill 应用 04：合同审查 Skill｜上传合同自动识别风险点，输出避坑提示与修改建议
5、Skill 应用 05：电脑文件整理 Skill｜自动分类归档、去重清理、规整电脑杂乱文件
6、Skill 应用 06：SQL 批量自查 Skill｜22 条规则一键扫描，CI 门禁防全表扫描与注入
7、Skill 应用 07：Java 代码审查 Skill｜37 条规则一键扫描，RuoYi 项目 CI 门禁防 Bug
8、Skill应用08：单元测试自动生成Skill｜7类场景全覆盖，6大风险闸门保证用例跑得通
9、Skill应用09：PPT 大纲生成 Skill｜输入方案素材自动拆分逻辑章节，输出完整大纲 + 每页内容要点
10、Skill应用10：概要设计自动生成 Skill｜PRD 直接转架构方案，自动划分模块、梳理流程
十、文末互动
你平时写详细设计最头疼的是什么？是模块类设计、接口定义、数据库设计，还是异常流程梳理？
欢迎评论区聊聊你的设计文档痛点，如果需要新增技术栈模板，也可以留言。
觉得这份详细设计自动生成 Skill对你有帮助，欢迎点赞👍 + 收藏⭐ + 关注，持续更新开箱即用 Agent 实战技能！