ARTICLE · 1024426
08 让 AI 画架构图,缺的不是画图工具,是这五条约束
一、一张干净漂亮、而且有两个盒子是编的图
进一个跑了几年的老项目，比「帮我分析一下架构」更进一步的做法，是让 AI 直接画出来：
「请画出这个项目的架构图。」
Claude Code 会给你一张结构非常干净的图：
分层清晰，命名规范，箭头方向也都对。
问题是这个项目里没有缓存层，也没有消息队列。整个仓库搜不到一行 Redis 客户端代码，CMakeLists.txt 里也没有任何 MQ 相关的依赖项。这两个盒子是补出来的。
为什么会补？因为「请画出这个项目的架构图」这条指令，对模型来说最省力的解法不是去读你的代码，而是回忆它见过的几万张「标准企业架构图」，然后往里填你项目的名字。而它见过的那些图里，绝大多数都有缓存和消息队列。
更麻烦的不是它编，是你的反应。
同样一句错误的判断，写成文字你会追问，画成图你会直接收下。 「系统采用缓存以提升读取性能」这句话你多半会停一下——哪来的缓存？但一张分层图上多出一个标着 Cache Layer 的方框，你的眼睛会把它当成既成事实。图长得像结论，而结论是不需要论证的。
图的说服力是免费附赠的。可信度不是。
二、但图恰恰是你手里最好的测谎工具
上面那件事的教训不是「别让 AI 画图」。恰恰相反。
先看一句纯文字的架构描述：
运动模块负责轨迹规划，并通过 EtherCAT 与驱动器通信。
这句话没有错。它的问题是没法错——你没有任何办法证伪它。「负责」是什么意思？哪个文件？规划完之后交给谁？中间跨了几次线程？这句话放在任何一个运动控制项目里都成立，所以它对你的项目其实什么都没说。
现在把同一件事画成一条箭头：
MotionService → MotionKernel
信息量看着更少，但性质完全变了。这条箭头逼出了两个必须表态的问题：这两个节点在不在？这个方向对不对？ 而且它们都有唯一答案，都能在半分钟内查完。
这就是画图真正的收益：图不允许含糊。 文字能靠模糊措辞活下来，图必须交出节点和边——每一个节点是一次「它存在」的断言，每一条边是一次「它调用它」的断言。一张 12 个节点、15 条边的架构图，就是 27 个可以逐条判错的断言。
可视化只是副作用。真正发生的事情是：你把 AI 那份含含糊糊的理解，压成了一份可以对账的清单。
老项目尤其需要这件事。新项目的知识链条是「架构 → 代码」：先有设计文档和接口约定，再有实现。老项目跑了五年之后，链条只剩下一半：
代码 → 代码 → 代码 → 不知道为什么这么设计
设计文档过期了，画图的人离职了，唯一还准确的东西是代码本身。这种状态有个名字叫 Architecture Lost（架构失忆）：架构还在运行，但已经没有任何一份文档描述它。
把架构从代码里重新提取出来，就是「画图」这件事在老项目上的全部意义。
三、图上没有源码依据的箭头，等于没有这条箭头
既然图是一组断言，那就必须逐条对账。对账的动作只有一句话：
请告诉我这条箭头对应哪些代码。
假设 Claude Code 画了 RobotService → MotionManager。你追这一句，它就必须交出具体位置：RobotService.cpp 第几行调用了 MotionManager::execute()。交得出来，这条箭头升级成事实；交不出来——它会自己发现刚才那条是推的。
Diagram as Evidence，不是 Diagram as Decoration。 这是这件事上最值得记住的一句话。
顺带说一个反直觉的收益：这套追问其实也是给 AI 用的自检工具。你没办法验证「RobotService 调用了 MotionManager」这句话——它太顺了，读过去毫无摩擦。但你可以验证一条箭头。把结论画成图，等于强制 AI 把自己的每一步推断摊开到能被单独指认的粒度。
所以让 AI 画图时，约束要写死这五条：
不允许猜测模块；
不允许补充不存在的组件；
每个模块必须有源码依据；
每条依赖必须能定位到具体文件和函数；
不确定的关系标记为
Unknown，不要连实线。
第五条是给它留的出口。不给出口，它只能把不确定的关系画成实线——因为你要的是一张「完整」的架构图，而「完整」这个词本身就在逼它编。
四、顺序错了，验证就来不及
上面这套对账有一个前提：你得在相信这张图之前做，而不是之后。
这就决定了流程的顺序。错的顺序是：代码 → 直接画图。对的顺序，中间多一道门：
中间那一步——先要文字结论，确认了再要图——是整个流程里最容易被省掉、也最不能省的一步。
原因是修正成本完全不对等。文字结论错了，你回一句「Service 不在 RPC 上面，它在下面」，AI 改一行就完事；等它已经画出一张漂亮的分层图，你不仅要让它重画，还得先把自己脑子里那张已经存进去的假地图擦掉。假地图比没有地图更贵，因为你会拿它去做决策。
第五步同样别省。图画完之后还要再问一遍：「请逐条检查图中每条关系是否能在源码中找到依据。」
图也要过验证。 这句话听着像废话，但绝大多数人拿到图就直接开始改代码了。
五、一张图只回答一个问题
「请画出这个项目的架构图」失败的另一个原因，是这句话要的东西太多。
一张图同时表达分层、依赖、调用顺序、数据流、线程归属，结果是每一项都半对半错，而且没有一项能被单独验证——你没法说「这张图错了」，只能说「这张图有点不对」。
拆开。一张图只回答一个问题，而且每类图都有自己的验证锚点：
注意最右边那一列。 每类图的验证锚点不一样，这正是它们不能混在一张图里画的原因——混在一起，你就没有任何一个明确的对账对象了。
还有一条经验：最值得先画的是时序图，不是架构图。 架构图告诉你系统长什么样，时序图告诉你一次业务到底怎么走，而后者才是你改造时真正要动的东西。
六、为什么这类图一律用 Mermaid，而不是 Visio
Mermaid 不是画图软件，它是用文本描述图：
graph TD A[Application] --> B[SDK] B --> C[RPC] C --> D[API Server] D --> E[Motion Kernel]
这五行文本渲染出来就是一张分层架构图。
选它的表面理由是 AI 最擅长生成文本。真正的理由是另外三件事。
它能进 Git。 一张 PNG 在版本历史里是一团二进制，一个 .mmd 文件的每次修改都能 diff 出来——上个季度谁往架构里加了一条依赖，看提交记录就知道。
它能被 review。 「这条箭头对应哪些代码」这个追问，在文本上可以逐行标注和批注；在图片上你只能截图画圈。
它能重新生成。 这条最关键：代码变了，图必须跟着变。 如果最终成果只是一张导出的 PNG，它从导出那一刻就开始过期了。
所以图的正确落盘方式是源文件，而不是图片：
docs/└── architecture/ ├── overview.md ├── system.mmd ├── module-dependency.mmd ├── call-chain.mmd └── sequence/ ├── startup.mmd ├── motion.mmd └── io.mmd
至于渲染成 PNG——那是发布和汇报时的最后一步，不是成果本身。
七、从 Prompt 到 Skill：别把这些要求讲第二十遍
到这里你已经攒了一整套要求：先文字结论再画图、五条禁止猜测的约束、六类图分开画、用 Mermaid、存进 docs/architecture/、画完逐条验证。
问题来了——这些你要每次重新打一遍。
这就是 Prompt 和 Skill 的分界线。一条普通 Prompt「请帮我画一个系统架构图」，AI 大概会给你一张图，但下面这些它一件都不保证：
Prompt 是一次性的指令，Skill 是可复用的能力。 Skill 把一整段流程固化下来：输入 → 标准化分析 → 结构化建模 → 生成图 → 按约定路径保存 → 验证依据。
而写画图 Skill 的时候，真正值钱的不是配色和布局那部分，是那五条禁止猜测的约束。它们是整个 Skill 里唯一决定图可不可信的内容，也是最容易在手打 Prompt 时被漏掉的内容——你赶时间的那一天，漏掉的一定是它们。
八、可以直接抄走的一段 Prompt
请分析当前项目，并生成架构图。要求：1. 先分析项目，不要修改任何代码。2. 从 README、构建文件、程序入口开始。3. 找出主要模块及其职责。4. 分析模块之间的真实依赖关系。5. 分析主要调用链。6. 不允许猜测不存在的模块。7. 每个模块和依赖关系都必须能在源码或配置中找到依据。8. 无法确认的关系明确标记为 Unknown，不要连实线。9. 使用 Mermaid 输出架构图。10. 同时给出每条关键依赖对应的源码位置（文件 + 函数）。11. 最后逐条检查架构图与源码是否一致。
这段 Prompt 的价值不在第 9 条「输出架构图」。在于第 6 到第 11 条把 AI 逼进了一个位置：它必须把自己的理解变成一份可以被逐条检查的工程模型，而不是一段读起来很像答案的话。
图上没有源码依据的箭头，等于没有这条箭头。
九、今晚就能做的一件事
不用挑大项目。挑一个你自己维护的模块，让 Claude Code 画一张它的依赖图——什么约束都别加，就一句「画出这个模块的依赖图」。
拿到图之后做两件事：
数一下图上有几个节点，然后去构建脚本里逐个找。 找不到的那些，就是它替你补出来的。
挑三条箭头，逐条问「这条对应哪个文件的哪一行」。 记下有几条它答不上来，或者能给出文件却说不清函数。
答不上来的箭头数除以你问的箭头数，就是这张图的编造率。大多数人第一次做这个练习会拿到一个让自己不太舒服的数字——而这个数字，衡量的是你在没有约束的情况下，对 AI 输出的信任被高估了多少。
你有没有见过一张画错了、却被当成正确架构用了很久的图？ 是入职时前辈发的那张 PPT 截图，还是 Wiki 上三年没人动过的那张？最值得聊的是那种「大方向对、但少画了一条箭头」的图——它比全错的图危险得多，因为它每天都在被验证成功。