AI 画的架构图，凭什么值得你发进群？

大家好！我是瓜哥。前互联网技术副总裁，现在带队死磕 AI 编程。

AI 几分钟读完你的代码库，吐出一张架构图。配色、图标、箭头都挺像那么回事，你右键存图，正要拖进团队群，手停了。

你在怕什么？

• 怕它连了一条根本不存在的依赖，同事顺着追问，你当场答不上来

• 也怕这图和代码对不上，过俩月，它变成一张误导新人的废纸

这样的图，一眼看过去很像回事，但你也很清楚 「准确性」才是底线。

为了解决这个事，我挑了个 github 开源项目，拿自己在跑的真实项目来测。

工具是个叫 archify 的画图 skill。Claude Code、Cursor、Codex 这些 AI 编程工具，都能装。

我照着它的操作手册，一步一步自己跑，我想看看，产出的架构图到底靠不靠谱？

结果有点反直觉，第一张真正能用的图，我改到 第七版 才拿到。前面六版，全被它自己打了回来。

接下来，我就把全过程拆给你看。

如果你也在自己折腾产品、天天跟 AI 写代码较劲，那这个号你大概率会觉得对味。

一、你犹豫的那一下，怕的到底是？

1. 架构图出错，代价从来不是难看

① 一条凭空多出来的线

架构图和海报是两回事。海报丑一点，问题不大，架构图上多画一根线，可能就是一次 严重错误。

咱也不能全推给模型幻觉吧，落到画图上，翻车就两种形态，没连的给连上了，连了的给画反了。

人看到一张显得很完整的图，会默认每根线都被查过。

一根脑补出来的线，会顺着图往下走，错误会流进评审会，流进新人入职文档，也流进故障排查过程。

② 一张对不上代码的图

图也是有 保质期 的。

代码每天都在动，图停在上个月。

新人照着旧图理解系统，去找一个早就改名的服务。

这种坑，我猜不少人都踩过。

2. 以前手动画，为什么没这个负担

① 判断权一直在你手里

以前你画错，锅是你的，你也清楚错在哪。现在 AI 三分钟交卷，省下来的时间，有一大半得花在确认 它有没有糊弄你 上。

这才是 AI 生成的架构图，咱不敢发到团队群里的真正原因。

二、真实项目，前六版全被打回

1. 先说我拿什么测的

① 一个在跑的真实项目，不是演示 demo

我拿自己在做的一个 AI 写作产品测的，代号 typeflow。它是 Next.js 写的全栈应用，数据库用 Prisma 管。仓库里压着一份 ARCHITECTURE.md，54KB，是份 写得极细的架构文档。

挑它，是因为它有真实的模型接口、数据库和支付回调。画错了，我自己一眼看得出来。

工程上最常用的两种图，我各画一张。一张系统运行时架构，一张充值支付的时序图。

2. 头两关，先管住你乱说

① 字段写错，图压根不渲染

archify 不让 AI 直接吐 SVG。

SVG 你可以理解成一种拼图片的代码，它要求先填一张结构化的 JSON 表。有哪些节点、各自什么类型、谁连到谁，一格一格写清楚。

我第一版手滑，给一个节点加了个它不认识的字段，换别的 skill，图大概也就糊里糊涂画出来了。

它的反应是直接报错，拒绝渲染，它还精确指到第几行、哪个字段不合法、只允许怎么改。

② 标了出处，就得现场核对

我想让图更可信，给几个关键节点标了源码文件。比如这个服务对应 skillRuntime.ts。

规矩是：要标出处，先把仓库地址和具体哪一次提交钉死。再开着本地仓库，让它一个文件一个文件去核对。

我让它查 commit（代码提交记录），它把我标的 7 个文件，在这次提交里挨个查了一遍，确认都真实存在，这才放行。

引用绝对不能悬空。

明确要求图必须来自真实代码，它就真去代码里翻，图和某一版代码 绑在一起。

3. 最意外的一关，管你看着行

① 九项全绿，浏览器照样拒收

改到第五版，九项静态检查全过了。

• 线不许穿过方块

• 两根线不许糊成同一条会看错的走廊

• 标签不许压在别的线上

• 拐角线段短于 16 像素

规格和成品各算了一个指纹，文件多少字节，统一汇报。走到这步，看着已经算画完了。

最后，非常聪明的开一个浏览器，把图 实际打开量一遍，1440×900 / 2048×1320 分辨率，明暗两种主题都验证了一遍。

浏览器拒收的 v5

最终通过的 v7

② 它逼我做减法，而不是打补丁

具体怎么修的？

我第一反应是加东西，把线掰一下，添个拐角，把图缩一点。

更好的方式：先删低价值的内容，删完还不行再加控制。

archify 还做了详细定义：

1. 不许裁内容

1. 不许塞内部滚动条

1. 不许硬拉高度

1. 不许靠缩小字蒙混

再跑一轮，第七版，总算全部通过。

三、连起来看，替你防三个毛病

1. 防它自己脑补

① 每根线都得白纸黑字写出来

图上每一根连线，都必须在那张表里显式声明，没写的，绝不替你猜这两个服务应该有点关系。

这一条看着很严苛，其实最值钱。

普通自动画图最吓人的地方，就是它会用常识把节点合理地连起来。

宁可画面不全，也不能补一根没被确认的连接线。

2. 防差不多行了，也杜绝硬报喜

① 看着整齐，不等于真没毛病

人眼审图有个漏洞，颜色一好看，细节就容易被放过。

这个 skill 不关心好不好看，它只负责量。

穿没穿方块，有没有共用歧义走廊，拐角够不够 16 像素，这些全是能量出来的硬指标。

我那张图一次被挑出十九处，多数我肉眼根本看不出来。

② 没过就是没过，不许糊弄

它有句规矩我很喜欢，大意是：命令没成功退出，永远不能描述成成功，报错了，就不许说已完成。

把证据分成三档，不许混为一谈。

• 静态检查过了，只代表规则没违反。

• 浏览器过了，只代表真打开能用。

• 至于好看不好看，得人亲眼看。

四、我又让它画了一张涉钱的图

1. 挑了条最不能错的链路

① 支付时序，错一步都是事故

光画架构还不够，我让它画第二张，用户充值，钱怎么走。

这条链路上有几个错了就出事的点。

第三方的回调是异步的，回调要验签名。同一笔通知可能来两次，说人话就是重复通知绝不能重复加钱。前端只能轮询自己服务器，确认到账，才提示成功。

这些全是这个 skill 从架构文档和真实代码路由里抄的，回调地址也是真的，一个字没编。

2. 它又一次倒在浏览器上

① 十七根消息怎么塞进一屏

时序图是竖着排的。

我第一版一口气塞了 17 根消息，又高又长。

浏览器一量，页面高 1721 像素，900 的屏幕得滚两屏。再次拒收，跟第一张 一模一样的毛病。

我先去翻官方自己通过验收的范例，看它什么尺寸，12 根消息，扁宽布局。

我合并了三根纯往返的消息，比如查询状态和返回状态并成一句，最终完成支付时序图的绘制。

五、但有两件事，它真的帮不了你

画对不等于想对，AI 能核对图上的事实，却不能替你决定系统该怎么设计。

1. 它管画对，不管想对

① 真正的判断还是你做的

得说句公道话，不能指望 AI 帮你做决策。

这张图为什么可信，源头在先老老实实读完了那份几十页的架构文档。哪条是主干，哪根边重要，全是人定的。

archify 能保证你写进去的东西画得没毛病、出处查得到。

但这个服务设计，链路怎么抽象，这可不是这个 skill 的负责范畴。

你喂给它的理解是错的，skill 会非常严谨地帮你把错误画漂亮。

2. 它有保质期，也有门槛

① 图钉在某一次提交上

它现场核对的，是我填的那一次 commit，代码继续迭代，图就开始过期。

新版本代码，需要新图，咱还得重新跑，它 不会自己盯着代码更新。

写在最后

回到开头那个动作：图就在手里，这次肯定敢发了！不是因为图更好看了，是因为手里多了几样证据。

• 一份带类型的规格

• 九项机器验收

• 七个被现场核对过的源码出处

• 四档真实浏览器的测试结果

好看与否，咱自己再看一眼。

通过这个工具，我越发强烈的感受：

AI 的产出能不能信，关键不在模型多聪明。

关键在它外面，有没有套一层可执行的验收协议，这套思维和做事方式，其实就是 Harness 的理念，AI 很强大，要驾驭好这匹动力强劲的野马，最重要的是精心打造一套适配的马具，然后才是驾马驰骋。

你要自己试，一行命令装上：npx skills add tt-a1i/archify -g。

最后，提醒一句：装好只是开始，真正决定这张图的价值的，还是你到底读没读懂自己的系统。

扩展阅读

• 项目仓库：https://github.com/tt-a1i/archify

• 它写给 AI 的那份行为契约 SKILL.md：https://raw.githubusercontent.com/tt-a1i/archify/main/archify/SKILL.md

• 它署名派生的前身项目 Cocoon 版：https://github.com/Cocoon-AI/architecture-diagram-generator