作为后端开发，写详细设计一直是「费力不讨好」的环节： 搭章节框架占去半天时间，新人输出常是纯代码堆砌、不讲设计逻辑； 单体、分布式、微服务的文档结构差异大，每次都要从零调整格式； 试过用通用AI直接生成，要么内容空泛没落地细节，要么前后端接口对不齐，改起来比自己写还慢。
市面上大多数方案本质都是「自由写作」，没有强制约束，质量全靠提示词博弈。索性我把团队的设计规范、项目模板、输出逻辑全部固化下来，做了这套 detailed-design-doc-generator 详细设计自动生成技能。输入概要设计或功能清单，就能生成标准化详细设计文档，强制「文字先行」先讲逻辑再给代码，内置统一技术规范，前后端接口自动对齐。代码已完整开源。
先看效果：生成即交付的文档样例
拿电商核心的订单管理模块测试，输入简单的功能描述后，输出的模块设计片段如下，拿来就能直接用于评审：
### 3.1 订单管理模块
#### 3.1.1 功能概述
订单管理是电商核心交易模块，面向注册用户提供商品购买服务，覆盖订单创建、状态流转、查询详情、取消退款等能力，依赖商品、支付、用户三个外部模块。
#### 3.1.2 业务流程
**创建订单主流程**：
1. 用户从购物车选中商品发起结算
2. 调用商品模块校验库存，不足则直接提示用户
3. 计算订单金额：商品总价 - 优惠折扣 + 运费
4. 生成待支付订单，锁定库存30分钟
5. 用户完成支付后更新订单状态，通知仓储发货
#### 3.1.3 设计思路
- 状态机模式管控订单流转，避免if-else嵌套，保证状态变更合法
- 乐观锁实现库存扣减，防止并发超卖
- 本地消息表+补偿机制保障订单与库存数据最终一致
- 延迟消息队列实现待支付订单超时自动取消
#### 3.1.4 类设计骨架
@Service
@Slf4j
public class OrderServiceImpl implements OrderService {
@Autowired
private OrderMapper orderMapper;
// 核心业务方法实现...
}
完整文档会按选定模板的章节顺序输出，覆盖系统架构、全模块设计、数据库、接口、安全、性能等全部内容。
为什么通用AI写不好详细设计
不是提示词写得不够好，而是缺少确定性规则约束，很容易出现共性问题：
-
结构无标准：章节全凭模型自由发挥，不同项目、不同人写出来格式千差万别，团队没法统一归档
-
重代码轻设计：上来就堆工具类代码，不讲业务流程、设计思路与选型理由，文档失去评审价值
-
口径不一致：前后端分开生成时，接口路径、参数、响应格式经常对不齐，联调才发现问题
-
规模不匹配：小项目套大模板冗余啰嗦，大项目又缺漏容灾、治理等非功能设计
我们的方案核心是「协议驱动+强约束」，把模板、规范、输出顺序全部写死在规则里，从根源避免这些问题。
核心设计：三层约束保证文档质量
整套工具不靠提示词博弈，而是用三层固定规则约束输出质量，每次生成结果稳定可控。
1. 按规模匹配三套模板，不冗余也不缺漏
内置三套项目模板，自动根据项目规模、并发量匹配，不用强行套统一框架：
-
小型单体（9章）：适合3-5人团队、千级QPS以内的项目，精简核心章节，20-50页即可交付
-
中大型分布式（14章）：适合10-30人团队、万级QPS的系统，覆盖缓存、消息、安全、性能等完整设计
-
微服务架构（16章）：适合30人以上的团队，额外补充服务治理、分布式事务、多活容灾、全链路追踪等深度内容
2. 「文字先行」强约束，杜绝无意义代码堆砌
这是整套工具最核心的质量闸门：所有模块设计必须按「功能概述→业务流程→设计思路→类设计/代码」四步展开，缺少前三步任意环节都会自动补全，绝不允许直接输出代码。
-
功能概述：讲清模块定位、目标用户、核心能力与外部依赖
-
业务流程：拆解核心流转步骤，覆盖正常路径与关键异常分支
-
设计思路：说明技术选型理由、用到的设计模式、核心算法与权衡考虑
-
类设计/代码：最后输出业务骨架代码，不堆砌工具类实现
3. 内置统一规范，全团队输出口径一致
内置完整的技术规范手册，生成代码、接口、库表设计时自动对齐，包括：
-
Java后端分层结构、命名规则、统一响应、异常处理规范
-
数据库字段标准、索引设计原则、分库分表策略
-
缓存Key命名、一致性方案、穿透击穿雪崩防护策略
-
前后端接口全局统一：路径、方法、参数、错误码完全对齐，前端视角额外补充TS类型与Mock数据
同时支持增量生成，补充、修改单模块时仅输出对应章节，不用重复生成全文，大幅提升迭代效率。
技能结构与输出产物
技能目录结构
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 # 最终交付的标准化详细设计文档
如何使用
支持所有兼容 Skill 协议的主流智能体，部署和调用都非常简单：
-
将完整技能文件夹放入对应智能体的技能目录下
-
传入概要设计或功能清单，发送指令即可生成，例如：
基于这份概要设计，生成中大型项目后端视角详细设计
- 微服务架构建议选择分步生成，按服务治理、数据存储、单服务设计逐次输出，避免内容过长截断。
落地避坑：8个高频踩坑点
整理了实际使用中最容易踩的坑，帮你少走弯路：
-
不要缺信息就强行生成：尽量提供完整的概要设计或功能清单，信息不足会用默认值兜底，细节精度会下降
-
不要要求跳过业务描述：「文字先行」是质量核心，省略概述流程会让文档失去评审价值
-
微服务别选全量生成：内容量大会导致输出截断，分步生成更稳定，质量也更可控
-
选对输出视角：后端开发选后端视角，前端选前端视角，不用默认全栈，减少无关冗余内容
-
前后端用同一份输入生成：基于同一份概要设计生成，才能保证接口定义完全一致
-
大范围修改别直接改文档：优先调整输入后重新生成，保持文档结构标准化，局部微调再手动修改
-
小项目别套大模板：按团队规模和并发量选对应模板，避免为不需要的内容增加复杂度
-
别忽略自检提示：文档末尾的「需人工复核」标注要重点查看，核心模块建议额外人工评审
开源地址
全套代码已完整开源至 Gitee，协议驱动开箱即用，下载即可部署：
仓库包含：
-
完整 SKILL.md 技能定义与触发规则
-
小型/中大型/微服务三套项目模板
-
Java后端、数据库、Vue前端三类代码模板
-
完整技术规范参考手册 standards.md
-
标准目录结构与配置文件
部署调试遇到问题，欢迎评论区留言交流，也欢迎 Star 支持一下~
最后
你平时写详细设计最头疼哪部分？是理不清业务流程、定不好接口参数，还是团队格式难统一？ 欢迎评论区聊聊你的痛点，有需要补充的技术栈模板也可以留言。
如果这个工具对你有帮助，欢迎点赞👍 + 收藏⭐ + 关注，后续会持续更新更多开箱即用的Agent实战技能。
