夜雨聆风
项目文档写到头秃?Claude Code直接从代码生成概要设计,17张架构图全搞定
做项目的程序员都懂，写概要设计有多痛苦。
特别是那种”交付级”的设计文档——要画ER图、架构图、用例图、时序图、数据流图……光画图就够折腾了，画完还得对齐格式、调页眉页脚、保证跟模版一致。一个文档写三天，两天在画图。
最近手上一个项目，6个业务模块、80多张数据库表。我试着让 Claude Code 直接从项目代码生成概要设计，结果让我自己都没想到——17张图全部自动生成，打开 Word 就能交付。
看看效果
不废话，先看生成出来的 Word 文档长什么样。
这是 Claude Code 生成的文档目录，从引言到附录，章节结构完整。
翻开正文，每章每节都有配图。比如”总体业务流程”这一章，AI 根据代码里的 Controller、Service、Mapper 调用链，自动画出了完整的业务流程图：
系统管理模块的数据库表关系，AI 直接从 Mapper XML 和 Entity 类中提取字段和关联，生成了 ER 图：
注：因为是公司项目文档，所有不能把更详细的图贴出来，包括类图、时序图等。
用例图、流程图、架构图、ER图、类图、时序图……整整17张，全部是AI读完代码后自动画的。
这些图是怎么来的？底层用的是 Mermaid——一种用文本画图的语法。比如上面那个 ER 图，在 Markdown 里只需要写表名和关系：
mermaid
erDiagram USER ||--o{ ORDER : "下单" ORDER ||--|{ ORDER_ITEM : "包含" USER { string id PK string name string phone }
写几行文本，图就自动出来了。类似的还有 sequenceDiagram（时序图）、classDiagram（类图）、flowchart（流程图）等6种类型。
你可能想问：这些图是怎么从代码到Word的？往下看。
怎么做到的？三步搞定
整个流程其实就三步：生成Markdown → 生成Word → 渲染图片插入Word。
第一步：让AI读代码，生成Markdown版
关键是不要让AI凭空”写”文档，而是让它先读懂代码再写。
我把项目目录交给 Claude Code，告诉它：
“分析这个项目所有模块的Controller、Entity、Mapper XML，提取每个模块的功能、数据库表、业务流程，然后按照概要设计说明书的结构输出Markdown文档，每个章节配上对应的Mermaid图。”
它先扫了一遍项目结构，然后逐个模块读 Controller、Entity、Mapper XML，把接口、表结构、业务逻辑都提取出来。
这一步大概用了10分钟。6个模块全部分析完，生成了17张图的 Markdown 文档。
你可能会问：生成的图准不准？
说实话，ER图和架构图的准确率很高——因为它直接读的 Mapper XML 和 Entity 类，表名、字段、关系都是从代码里提取的，不是凭空编的。时序图和流程图需要人工核对业务逻辑，但框架已经搭好了，改比从零写快太多。
第二步：匹配模版，生成Word文档
我把公司的概要设计模版（.doc格式）喂给 Claude Code，让它分析模版的格式——字体、字号、页边距、标题样式。
然后用 docx-js（一个JavaScript的Word生成库）按照模版格式生成 Word。黑体18pt的一级标题、黑体16pt的二级标题、宋体9pt的正文、页边距70.9pt——全部对齐。
核心代码其实不复杂，关键是要把模版的格式参数摸清楚：
javascript
// docx-js 标题样式配置styles: { default: { document: { run: { font: "宋体", size: 18 } } // 18 = 9pt }, heading1: { run: { font: "黑体", size: 36, bold: false } }}这里有个坑：黑体标题看着像加粗，但模版里其实 bold=false。如果你不检查模版原始格式，直接设 bold=true，生成出来的标题会比模版粗一圈。
第三步：Mermaid图渲染成图片，插入Word
Markdown里的图虽然能预览，但甲方打开 Word 看到的是代码，不是图。需要把 Mermaid 渲染成 PNG 再插进去。
用 mermaid-cli（Mermaid官方的命令行工具）：
npm install @mermaid-js/mermaid-climmdc -i diagram.mmd -o diagram.png -w 1200 -b white17张图，一行命令批量渲染。
然后用 python-docx 把渲染好的 PNG 逐张插入 Word 文档的对应位置：
到这里，一份完整的概要设计文档就出来了。从代码到Word，30分钟。
但实际过程中，我踩了不少坑。
这些坑我替你踩了
坑1：功能结构图太长，一页放不下
用 Mermaid 画功能结构图的时候，我一开始用了 graph LR（从左到右布局）。
问题出在哪？一个根节点连着8-9个子节点，从左到右排列，必然是一条竖长条。实际生成的图 5.1cm宽 × 51.3cm高——一张图顶三页纸，字根本看不清。
解决方案就一行：改用 graph TB（从上到下布局），让子节点横向展开。同样的内容，改成 TB 之后变成 14cm宽 × 1.5cm高。
经验：单根节点+多个平行子节点的结构，必须用 graph TB，别用 graph LR。
坑2：单图节点超过20个就该拆分
一张用例图里塞了5个子系统、4个角色、30多个功能节点。渲染出来字小得像蚂蚁。
后来我按角色拆成了3张：管理员一张、医生一张、客服+主任一张。每张图节点控制在10个以内，文字清晰。
坑3：页眉页脚用代码重建，格式全乱
第一次我让 Claude Code 用代码重新画页眉——公司Logo加上文档名称。结果打开一看，Logo偏了、文字挤了、边框没了。
搞了快一个小时，最后发现最靠谱的方法是：直接从模版解压，拷贝XML文件过去。
模版 .docx 本质上是个ZIP包，解压后 word/header1.xml 就是页眉，word/footer1.xml 就是页脚，连Logo图片一起拷贝过去，格式完美一致。
坑4：图片尺寸没约束，撑爆页面
渲染出来的PNG直接插入Word，有的图高度超过50cm。A4纸可用高度才24.7cm，一张图能占三页。
最后写了个Python脚本，把所有图片统一约束在 14cm × 18cm 以内：
MAX_W = int(14.0 * 360000) # EMU单位MAX_H = int(18.0 * 360000)这个踩坑经历，我已经整理成了一份生成指南，文末可以获取。
手写 vs AI生成
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
我测试下来，AI生成的版本作为初稿交付完全没问题。后续只需要微调一些措辞和业务描述的细节，大概再花30分钟就能定稿。
对比原来从头写三天，效率提升非常明显。
写在最后
总结几条实践经验：
1、先写Markdown再转Word——Markdown迭代快，Mermaid图可以随时预览，确认没问题再生成Word
2、图超过20个节点就拆分——按角色拆、按模块拆都行，别一张图塞太多
3、页眉页脚直接从模版拷贝XML——不要试图用代码重建，省下来的时间够你再生成一份文档了
4、Mermaid图的布局方向比内容更重要——单根多子节点用 graph TB，别用 graph LR，差距巨大
设计文档最难的不是写字，而是让图和文字对得上。当AI能直接从代码画出ER图和架构图，最耗时的那一步就消失了。
福利：完整生成指南
上面只是挑了几个关键坑讲。实际从代码到 Word 的过程中，还有不少细节——模版格式怎么提取、.doc 转 .docx 怎么处理、图片插入顺序反了怎么修……
我把这些全部整理成了一份 《概要设计文档生成指南》，内容包括：
1、模版分析：页边距、字体、页眉页脚的提取方法和代码2、代码分析：用 AI 扫描项目的具体指令和关注维度3、Mermaid 图：6 种图的适用场景、布局原则、配色方案4、Word 生成：docx-js 的关键配置和 DXA 单位换算5、图片渲染：mermaid-cli 渲染流水线和尺寸约束脚本6、踩坑清单：12 个实际遇到的坑和对应解决方案7、验证清单：交付前 9 项必检项
拿到这份指南，配合 Claude Code，你自己的项目也能 30 分钟出一份初稿。
关注公众号，回复「概要设计生成指南」即可获取。
觉得有用？先收藏，下次写设计文档的时候直接翻出来用。
如果本文对你有帮助，不妨点个免费的赞和收藏备用。
👇 关注Gallop，让AI提升你的效率
👉 添加我的微信（gallop_liu），备注“加群”，交流并分享个人的一些资料。