1. 先说结论AI画架构图的“最后一公里”卡在验收我最近把几个项目的架构图都丢给AI重画了一遍包括微服务架构图、系统架构图、技术架构图覆盖了从单体拆分到混合部署的好几种场景。得出的感受和很多人一样AI画出来的图第一眼很唬人方框、箭头、分层该有的都有但真要拿去做技术评审或者对接研发落地总有那么几处经不起细看。不是AI不会画图而是AI缺少一条验收流水线。先解释一下这个场景。架构图本质上不是一张图而是一份语义交付物。它不是给人“看个大概”的而是要回答几个非常具体的问题系统里有哪些组件组件之间通过什么协议交互数据流向哪里哪些模块属于同一层如果AI只是把常见架构图的版式背下来再根据你的prompt里几个关键词拼出一张图那出来的东西大概率是“形式正确、语义存疑”。archify这个skill干的事情就是在AI画图前加了一层“让AI先感知工程现状”在画完图以后又加了一条“验收流水线”让AI自己检查自己画的图是不是真的能被代码实现、能不能被评审接受。说白了就是给AI配了一个架构评审搭档。这篇文章我会从为什么要做验收、archify是怎么设计这条流水线的、四道关卡各查什么、以及我已经踩过的坑这几个维度把这套思路完整拆给你。不管你是架构师、技术Leader还是经常被AI画图气到的开发都能从中找到可以直接抄走的做法。2. 为什么AI画的架构图总在“差不多”和“差很多”之间横跳2.1 看着对细想就崩先举一个我踩过的例子。我让AI画一个订单中心的微服务架构图prompt里写了“订单服务、库存服务、支付服务、消息队列、数据库”五分钟不到图出来了服务拆分、数据存储、异步消息分层很清楚颜色也舒服。但往细了看问题就来了支付服务和订单服务之间画的是同步HTTP调用可我们实际是异步回调加对账库存服务的数据库被画成了独立实例但生产环境里它和订单服务共用了一套MySQL实例消息队列倒是画了但没标Topic没标消费者等于白画。这些问题AI自己发现不了因为它画图的时候只依赖语言模型对“架构图应该长什么样”的先验知识根本没有对照工程的真实情况。它不知道代码里FeignClient指向哪个服务不知道Gateway路由了哪些路径更不知道哪些表其实在一个库里面。这就是“看着对”和“差很多”之间的鸿沟。图的信息熵很高但准确率经不起推敲。2.2 组件幻觉架构图里的“无中生有”AI画架构图还有一个非常典型的毛病我称之为“组件幻觉”。就是你给它一个“用户认证模块”的需求它会非常自然地画出一个“统一认证中心”再配一个“Token管理服务”。可是翻遍你的代码仓库根本没有这两个服务。为什么会出现这种情况因为大模型从海量架构文档里学到的模式是“认证应该独立成服务”它把概率最高的结构当成了事实而不是基于你的代码抽象出来的事实。画出来的图越漂亮往往越容易脱离现状。在真实业务里架构图的第一属性是“对齐现状”第二属性才是“表达未来”。如果图里画了一堆不存在的组件评审会上第一个被挑战的就是你而不是AI。2.3 代码和架构图在AI眼里是两套平行宇宙更深一层的问题在于现在的AI编程助手比如Cursor、Copilot、Claude Code它们对代码库的感知能力已经很强了能改bug、能重构、能加功能。但在画架构图的时候它们普遍没有把代码库的感知能力和画图能力打通。代码在AI眼里是一个世界架构图在AI眼里是另一个世界。你让它改代码它能精准定位到某个Service你让它画架构图它能流畅地编造出一套结构。这两个世界之间缺一条数据通路。archify的设计思路就是先把这条路打通画图之前先让AI去读工程结构、分析依赖、提取模块边界把这些信息作为“绘图素材”喂进去画完图之后再让AI基于同一份工程感知去校验图里的每一个组件、每一条边看它是不是真的存在于现状里。那些“画完图发现和代码根本不是一回事”的问题基本就是出在这个环节。3. archify到底是什么一个给AI配的“架构验收员”3.1 它不是一个绘图工具而是一个工程上下文感知器很多人看到archify第一反应是“又一款画架构图的工具”。还真不是。archify本身不负责把方框和箭头画得多好看它更接近一个带“验收能力”的AI Agent技能包跑在Claude这类支持Skill机制的AI编程环境里帮助AI在做架构图之前先把工程上下文吃透并在输出之前完成自检。你可以把它理解为平时我们嘴上说“画图前先看一下代码”但AI没有这个习惯你也不一定记得手动把代码结构喂给它。archify把这个动作固化成了流程。它做的最核心的一步是让AI在画图前先回答三个问题代码仓库里到底有哪些模块和服务模块之间真实的依赖关系是什么样的目前的分层、命名、协议、部署方式是否符合可描述的架构规律这三个问题回答完AI就从一个“会画架构图的语言模型”变成“懂这个项目的架构图制作者”。后面画的图才有资格进入验收环节。3.2 验收流水线不是“检查一遍”那么轻我在最初接触这个思路的时候以为所谓的验收就是在AI画完图之后加一句“请检查一下有没有错误”。实践下来发现完全不是那么回事。一句“请检查”是无效的。因为语言模型在没有外部规则和标准的情况下检查自己刚才生成的图只是用自己的“平均审美”再看一遍大概率觉得哪都挺好。它没有标准没有边界没有参照物检查等于白查。archify的做法是把“验收”拆成四道关卡每一道都绑定具体的规则、参照物和失败条件。只要有一关不过AI就必须重新生成。这个流程和我们写代码时跑CI流水线是一个逻辑不是写完代码顺手看一眼而是让自动化流水线按照既定的规则集去判断通过还是不通过。后面我会把四道关卡一个个拆开讲先大概列一下第一关语法结构检查确认图本身格式正确、没有孤立节点、没有断路。第二关完整性检查确认prompt里提到的关键组件、角色、数据流都被表达进去了。第三关语义映射检查确认图中的概念能对应到代码仓库里真实存在的模块。第四关架构规范检查确认分层、依赖方向、命名规则与团队约定一致。这一整套走下来才配叫“验收流水线”。4. 验收流水线的四道关卡每一关我都实战过4.1 第一关语法与结构检查先把“画错”的图拦下来第一关最简单也最基础。它检查的是架构图的“语法层”对应到代码里就是“这代码能不能编译通过”。具体查这么几项节点ID是否唯一有没有两个组件用了同一个ID或者引用了不存在的组件ID。边的两端是否存在比如你画了一条从“订单服务”到“支付服务”的箭头但“支付服务”这个节点根本没定义这条线就是一条悬空线。节点是否孤立如果某个节点没有任何边连着它那它要么是多余的摆设要么是漏了依赖关系。分层和分组是否明确每个组件是不是都能归属到某一个明确的层、域或子系统里面而不是散落一地。我用的是Mermaid格式来承载架构图原因很简单Mermaid是纯文本结构可以被程序化解析和校验适合流水线式处理。如果直接让AI输出一张图片或SVG验收就没法自动化了。之所以把“格式正确”当成一道关卡而不是直接默认AI能做好是因为实际测试下来AI真的经常画错。有一次我让它画一个带消息队列的图它把Kafka画成了一个节点但根本没和任何服务连线——在格式层面它就是一张废图。这类错误靠人眼其实也能发现但既然要做流水线就要让机器能自动识别而不是每次盯着看。4.2 第二关完整性检查确认所有关键需求都被表达第二关的职责是防止“漏画”。AI画图的时候如果prompt里一口气提了12个模块它经常只画出8个剩下4个就无声无息地丢了。不是它不想画而是在生成过程中被前面那些更抢眼的组件边缘化了。完整性检查的思路是把用户原始需求里的每一个关键元素抽象为“检查项”然后逐项确认它是否出现在最终的架构图里。检查项的来源可以是一个清单也可以是针对项目预设的关键组件表。我常用的做法是让archify基于项目的backend目录、pom.xml或package.json里的模块声明自动生成一张“应出现组件清单”再和AI画出来的图做一次diff。清单上的所有组件必须在图里找到对应节点否则回到生成阶段重新画。打个比方这就像点菜以后对着小票核对菜品少了哪道菜得上菜窗口说一声。AI画图也一样不能画完就装傻得有人对单子。4.3 第三关语义映射检查让图和代码“说同一种语言”这是我认为整个验收流水线里最有价值的一道关卡也是archify区别于普通绘图指令的核心。语义映射检查要解决的问题是图里每一个组件代码仓库里是不是真的有对应物。具体做法是让AI在画图前用“代码感知”能力生成一份“工程语义索引”。索引里记录的是所有微服务模块名从目录结构、pom.xml、package.json提取服务之间真实的调用关系从FeignClient、RestTemplate、RPC注解、HTTP调用代码里识别共享资源的使用情况比如哪些服务连了同一个数据源、哪些服务共用了同一个Redis集群对外暴露的接口列表。画完图之后对照这个索引逐个检查。如果图里画了一个“统一配置中心”但工程语义索引里根本没有配置中心相关的模块那这条组件就要被标记为“疑似虚构”要求AI要么删掉要么在图里显式标注为“规划中组件”。这一步直接解决的就是前面说的“组件幻觉”问题。它把AI从“凭经验画图”拉回到“基于事实画图”的轨道上相当于给AI配了一份工程审计底稿。4.4 第四关架构规范检查把团队约束也装进流水线最后一关对应的不是“代码能不能跑”而是“代码写得规不规范”。架构图也一样必须符合团队的架构约定。我平时会为项目维护一份architecture-rules.yaml里面存了团队约定俗成的规则例如rules: - name: 禁止跨层调用 desc: Web层不能直接依赖Infrastructure层 violation: 当前图中Web模块直接连接了MySQL节点 - name: 依赖方向 desc: 领域层不能反向依赖应用服务层 violation: 当前图中OrderDomain指向了OrderApplication - name: 模块边界 desc: 订单域与库存域的领域服务不得互相依赖 violation: 库存域服务节点直接依赖订单域服务节点archify会读取这份规则文件把图翻译成结构化的组件依赖关系再逐条比对这些规则。命中violation就回炉重画。我刚搭建这套规则的时候花了小半天时间专门校准规则因为写得太严会误伤写得太松等于没写。后来慢慢形成了自己的节奏第一天先只配两条最基础的规则比如“分层不能乱”和“反向依赖不可接受”跑顺了以后再逐步加更多约束。这样不会一上来就被一堆误报淹没。5. 一次完整的实战从“一团乱麻”到“可交付的架构图”5.1 我拿什么项目做的实验我选了一个训练用的订单系统仓库来跑完整流程。这个仓库大概是7个微服务包含网关、订单、库存、支付、用户、消息中心、物流有Feign调用关系有Kafka的Topic有MySQL和Redis规模不大但五脏俱全。之前的痛点就是每次画出来的架构图都“很标准但不对”。实验目标有四个图里所有服务必须能在代码仓库里找到同名模块。服务间连线必须和代码里的真实调用关系一致。数据存储节点必须标注真实使用的中间件类型。图必须符合团队的分层规则。5.2 改造前AI直接画的“标准答案”我先把同样的prompt丢给原生AI环境画了一次作为对照。画出来的图结构很漂亮网关层、应用层、数据层泾渭分明订单服务、支付服务、库存服务各就各位消息队列作为异步通道贯穿全局。但对照真实代码一查就露馅了。第一图里把“库存服务”画成了完全独立的一个服务但实际上仓库里库存相关的能力是嵌在订单服务内部的一个子模块对外并没有独立的服务名。第二图里画了“定义了一个用户服务”但查询用户信息的调用其实是网关直接对接用户库完成的并没有经过用户服务这个中间层。第三支付回调那条链路在图里是完全缺失的因为AI不知道。这其实就是“画了个寂寞”。5.3 改造后archify加持下的流程加了archify之后整个流程变成了这样先让AI执行工程感知任务读仓库的目录结构、解析依赖声明、扫一遍调用关系输出一份“工程语义索引”格式大概是服务清单 - gateway: 基于Spring Cloud Gatewayroutes包含/order/**, /payment/** - order-service: 提供订单创建、订单查询Feign调用inventory-service - inventory-service: 提供库存扣减 - ... 共享资源 - MySQL: order-service和user-service共用同一实例 - Kafka: order-service发布order_created事件payment-service订阅这份索引会作为上下文被固定住画图时不允许超出这个范围。随后AI基于索引画图。画完第一版后流水线开始跑第一关卡结构检查发现节点没有孤立的问题但是网关到用户服务的一条连线引用了未定义节点打回重画。第二版修正了格式问题进入第二关完整性检查时发现prompt里提到的“消息中心”没有出现在图里再次打回。第三版补上了消息中心第三关语义映射检查发现了新的问题——具体如下。5.4 关键的一次打回语义映射救场我印象最深的是第三版被第三关拦截的那一次。当时AI画的图里有一个“统一认证中心”单独画了一层看起来也很合理。但语义映射检查对比工程语义索引后发现仓库里既没有auth-service这个模块也没有认证中心相关的组件整个认证逻辑只是通过网关里的一段Filter实现。按照验收规则出现这种情况有两条出路删掉图上这个组件改为在网关层标注“内置认证过滤器”保留组件但必须在图上明确标注“规划中”并补充说明现状是网关Filter实现。我选择了第一条因为这次画图的目标是对齐现状不是画目标架构。如果是为了做架构演进规划第二条才是对的。这两种场景的目标不一样验收规则也就该不一样。这是很关键的一点架构图分“现状图”和“目标图”验收流水线必须接受“场景参数”输入你自己得先想清楚这次画的是哪一种图。5.5 改完以后的图长什么样第四版通过全部四道关卡。图里7个微服务全部对应代码仓库里的真实模块会话关系按代码里的Feign调用修正Kafka的Topic和消费者关系标注清晰MySQL被画成order-service和user-service共享的同一个存储节点网关层标注了内置认证Filter。拿给同事看大家第一反应是“这图没问题就是咱们系统现在的样子”。这就对了。架构图的最大价值和最朴素目标就是让看完图的人说一句“对这就是咱们的系统”而不是说“这图画得真高级”。6. 已经有代码库的老项目怎么把archify接进来6.1 第一步不是画图而是让AI“感知现状”如果你拿到的是一套已经跑了很久的存量系统没有清晰的模块边界也没有现成的架构文档直接让archify去画图它会不知道从哪下手。这时候第一步不是画图而是让AI先把“现状”摸清楚。我推荐的顺序是先跑一次工程扫描拿到服务清单和依赖关系再对着这份清单和开发聊一轮确认哪些是遗留模块、哪些是废弃接口、哪些是正在重构的部分最后把确认过的信息汇总成一份“现状基线”交给archify作为画图的起点。这就像拍X光片得先让人站好位置射线打过去才能看到骨头长什么样。你连现状都没摸清画出来的图再专业也只是给一个错误的现状画了张精美的肖像。6.2 增量演进而不是推倒重来我见过不少团队在引入AI辅助架构治理的时候脑子里想的都是“让AI生成一版完美架构图替换掉以前所有不准确的文档”。这个想法风险很高。更好的做法是“增量演进”先只画一个服务让它过完四道关卡验收验收通过后再逐步扩到服务组、分层、跨域依赖。每次扩充都重新跑一遍完整流水线而不是让AI一口气画出全貌。原因很简单大的生成任务出错率几乎是指数级上升。与其最后面对一张“哪里都不太对”的大图不如一张图分四次生成每次验收哪怕中间改来改去容错率也高得多。我的实际经验是第一次接入archify建议只挑一个业务域比如订单域把它画明白跑通全流程。等团队所有人都理解“验收流水线”是怎么回事了再扩展到全系统。这比一上来就铺全量稳妥得多。7. 接这个流水线容易踩的坑我替你踩过了7.1 评估器规则写太死误报多到想放弃这个是第一大坑。第一次跑验收流水线我为了让AI严格按照我的标准画图定了十几条规则结果1/3的图都被误伤。比如“禁止跨层调用”这条我把Web层到Infrastructure层的一根线判为违规但那条线其实是Web层通过数据库访问接口做数据兜底查询这在某些非严格DDD项目里是允许的。后来学乖了第一版只配两条最核心的规则比如“图内不得出现代码仓库中不存在的服务”和“依赖方向不得反向”。跑顺以后再一条一条加业务相关的约束。不要妄图一步到位评估规则永远是逐渐打磨出来的。7.2 AI会把上下文里的“示例”当“事实”抄进去还有一个很有意思的问题。我在提示词模板里放了一段示例架构图本意是告诉AI“最后画出来的图就长这样”。结果AI在正式输出的图里直接把这几个示例组件也画进去了。这类问题在验收环节其实不太容易被发现因为示例组件命名通常很有迷惑性比如说“PaymentService”“UserAuth”听着就像真实模块。但在语义映射检查一关就会暴露因为它们不存在于工程语义索引里。所以提示词里的示例尽量用一些明显的占位名比如“ExampleService”避免和真实模块混在一起被AI抄进图里。7.3 验收通过不等于架构合理别把流水线当万能这一点必须说清楚也是最容易被忽略的。验收流水线能保证的是“图符合事实、符合规则”但它不能保证“图里的架构是合理、可演进、可维护的”。例如AI完全可以通过语义映射校验真实地画出一个“所有服务直连数据库、没有缓存、没有消息队列”的架构图。这张图所有步骤都能通过因为图的每一笔都是事实。但问这个架构好不好那可不一定。所以验收流水线的定位是“底线保障”而不是“质量代言”。它防止的是低级错误和不实之处真正的架构评审、技术权衡还需要人来完成。Architecture review is a human process, AI only helps you with the paperwork.8. 顺着这条思路还能做什么我个人在实际操作中的体会是archify的价值不局限于“画架构图”它的底层逻辑——让AI先感知工程、再表达、再自检——可以被复用到很多AI编程场景。比如可以让AI在生成技术方案文档之前先读取相关模块的代码输出“方案落地影响范围”再写正文。比如可以让AI在准备代码评审之前先扫描当前分支变更输出“变更风险清单”再逐条评审。这本质上都是“先感知后表达再验收”的思维。如果你手头正好有被AI架构图画得头疼的项目可以试试这套思路。先从最简单的一版规则开始画之前让AI先列服务清单画之后让AI逐项确认图里的组件都能在清单里找到。就这两步已经能拦掉一大半“看着挺对、其实全错”的问题。再往下等你习惯了这种“给自己加一道验收关卡”的工作方式再慢慢把更多规范加进去让AI替你守住更多不该犯的错。