Claude Code自动生成设计文档：design-doc-generator技能实战 ​

系统设计，图是最耗时的部分。design-doc-generator 技能让 Claude Code 自动生成全套设计文档——5 张 draw.io 架构图 + 6 张 Mermaid 图 + 完整 Word 文档。

一、痛点：写设计文档，图是最搞人的 ​

你肯定也经历过：

• 用 Visio 或 draw.io 手动画架构图，调对齐调半天
• ER 图要自己建表再画关系线，改一个字段，整张图的重心都变了
• 时序图 Mermaid 语法老忘，每次都要翻文档查 participant 怎么写
• 流程图的菱形判断框怎么摆才好看，纠结半小时
• 画完还要导出 PNG、插入 Word、调页边距、加编号……

**一套设计文档，10 多张图，3 天起步。**还不算需求变更后返工。

二、效果：一条指令，全套文档 ​

输入一份功能模块文档（普通 Markdown），一条指令，10 分钟后拿到：

核心亮点：

• 配色统一、布局一致
• 同一个模块在所有图里的颜色是一样的
• 自动生成目录索引
• 打开零弹窗

三、核心思路 ​

第一条：不同类型的图，用不同的工具 ​

第二条：每种图都有固定模板 ​

不会让 AI 从零开始「创作」一张图。

• 分层架构图：「左侧竖排彩色标签 + 水平色带 + 层间箭头」
• ER 图：Mermaid 的 erDiagram 语法
• 时序图：sequenceDiagram 语法

AI 做的事情是往模板里填内容，而不是发明一张图。这就是为什么每次生成的图都看起来很专业。

第三条：8 步流水线全自动 ​

四、使用步骤 ​

Step 1：准备功能文档 ​

一份普通的 Markdown 文档就行。不需要任何特殊格式，只要写清楚有哪些功能模块。

Step 2：安装 Skill ​

Skill 文件放在 .claude/skills/ 目录下，Claude Code 会自动加载。

Step 3：输入指令 ​

在终端里输入指令，指定文档路径和输出目录：

使用 design-doc-generator，根据 docs/prd.md 生成设计文档

Step 4：等待生成 ​

Claude Code 会自动完成所有 8 个步骤。你可以看到实时日志输出。

Step 5：打开文档 ​

直接打开生成的 .docx 文件。目录有页码、图片全部正确显示、打开零弹窗。

五、踩坑提醒 ​

坑 1：Word 打开弹「是否更新域」对话框 ​

原因：docx-js 里 updateFields 参数默认为 true。

解决方案：改掉参数，用 Word COM 做后处理刷新目录。

坑 2：draw.io 预览报错 ​

原因：节点超过 15 个时 URL 超长。

解决方案：超过 15 个节点直接写入文件，跳过预览。

坑 3：图片 ID 冲突 ​

解决方案：后处理阶段统一修复图片 ID。

六、质量检查清单 ​

自动执行 7 项质量检查：

七、依赖安装 ​

使用这个 Skill 需要先安装 draw.io Desktop：

https://github.com/jgraph/drawio-desktop/releases

八、写在最后 ​

核心不是「让 AI 画图」，而是给 AI 定好规则——模板、配色、工具选型。

• draw.io 负责形状类图（架构图、流程图）
• Mermaid 负责数据类图（ER 图、时序图）
• 最终产出是 Word 文档，不是 Markdown——能直接交付给团队

做系统设计，图不应该是最耗时的部分。把画图交给 AI，你只需要关注设计本身。

总结 ​

design-doc-generator 让设计文档从「体力活」变成「指令活」。

关键词：Claude Code设计文档, design-doc-generator, 系统架构图, ER图, 时序图, draw.io, Mermaid