1. 为什么AI画的架构图总差那么点意思这两年AI辅助编程已经卷到飞起写代码、补测试、做Code Review都有人用Agent在跑。但有个场景我一直觉得特别拧巴就是让AI画架构图。你给它一段业务描述它能给你画出一个看起来非常专业、布局规整、颜色协调的架构图乍一看好像什么都有。可只要仔细一核对问题就全出来了——组件关系对不上、服务之间调用方向画反、数据库和缓存混为一谈、甚至某些模块根本不存在是从别的项目里“幻觉”过来的。这种图真拿去评审基本被喷到怀疑人生。我自己在项目里反复试过好几轮包括让Cursor、Claude、GPT直接生成Mermaid、PlantUML也试过让它们输出Draw.io的XML结果都差不多单看一张图感觉能打80分放到真实系统里一验证很多关键细节是错的。这背后的原因其实不复杂——LLM本质是个概率模型它对“架构图”的理解更多来自训练数据里的“共性样本”而不是你当前系统的“真实约束”。你让它画一个微服务架构图它大概率会画一个非常标准甚至平庸的图所有组件都是同类项目的“平均脸”跟你的实际系统对不上。后来我们换了个思路不再要求AI“一次性画对”而是给它的产出加了一条“验收流水线”。这就是archify这个工具链在做的事情。简单说它把AI画架构图的流程从“一句话→出图”改成了“需求描述→结构化架构描述→自动验收检查→通过才渲染出图”不通过就打回去重画。这套流程跑通之后AI产出的架构图从“看起来像那么回事”变成了“经得起校验的真实交付物”我觉得这才是AI辅助架构设计真正能落地的姿势。这篇文章就围绕这条“验收流水线”展开适合正在折腾AI Agent辅助架构设计、或者想把AI画架构图从demo级别提升到能进评审级别的团队。文章里会讲清楚这条流水线为什么能解决AI画图不靠谱的问题也会给出可以直接复制的实操方案和踩坑记录。2. 先拆解问题AI画架构图的四类典型翻车现场在讲archify怎么解决之前我先把AI画架构图最常见的几类问题列出来。这不是空谈是我实际让模型画图时反复踩到的坑理解这些问题之后你才能明白为什么“加一条验收流水线”比“换一个更聪明的模型”更值得投入。2.1 看起来完整实则关系全错这是最隐蔽也最危险的问题。AI生成的架构图从视觉上非常完整每个服务、数据库、网关都画出来了线条也连上了但你深究就会发现调用方向是反的、数据流向是错的、服务和数据库之间直接连接而不是通过中间层。比如我让AI画一个订单系统的架构它很乖地画出了订单服务、用户服务、支付服务然后给订单服务画了一条线直接指向用户数据库。这在图面上完全看不出来有什么问题但真实系统里订单服务根本不应该直连用户库它应该走用户服务的接口。这类错误靠人眼看图很难发现因为你图都画出来了注意力全在布局好不好看上很难逐条核对线条语义。2.2 幻觉式组件图里多了几个不存在的服务另一个高频问题是组件幻觉。AI会基于训练数据里的“典型套路”补全一些你根本没提过的模块比如流量监控平台、日志采集Agent、配置中心。如果这些组件恰好在你系统里存在那问题不大但很多时候它补充的模块你压根没有或者技术选型完全对不上。我遇到过一个典型案例让AI画我们一个内部工具的系统架构它在图里放了一个Kafka消息队列。但我们那个工具的核心逻辑是同步调用完全没有引入消息队列。图和真实系统一旦对不上这张图就失去了架构图最核心的价值——作为团队沟通的共同语言。2.3 格式对了语义校验完全缺失这个问题在Mermaid这一类基于文本的图表里尤其明显。AI生成的Mermaid语法往往完全正确能顺利渲染甚至节点样式都挺好看。但语法正确只代表“能画出来”并不代表“画对了”。打个比方你作文每句话的语法都是通的不代表文章内容是对的。Mermaid语法校验只能保证图能渲染它不会检查订单服务到底该不该连用户库也不会检查组件命名是否符合你们团队的规范。大部分AI画图流程就死在这一步——渲染能过就觉得AI完成任务了实际上最关键的语义正确性压根没有校验机制。2.4 改了需求图就全乱最后一种情况更让人头疼你让AI基于同一个系统改一点小需求比如“把订单服务改成异步处理”结果AI重新生成了一张全新的图。新图和旧图风格不一致、组件命名变了、布局全乱甚至原来正确的部分也被改写。架构图作为长期维护的资产这种不可控的变动非常致命团队无法基于AI产出的图做渐进式维护。3. archify的核心思路给AI画图加一条“验收流水线”我接触archify的时候第一反应是“这不是一个画图工具而是一个校验工具”。它的核心逻辑其实和软件开发里的CI/CD非常像——你在提交代码的时候必须有测试把关不合格就构建失败。archify就是把这个思想搬到了架构图生成流程里AI生成的设计稿必须通过结构化校验才能算“验收通过”。整条流水线分成四个环节定义输入约束、生成结构化架构描述、执行自动校验、通过后渲染出图。下面逐个拆解。3.1 第一步把“画一张图”变成“生成一份带约束的结构化描述”传统AI画图模式是“描述性输入→图像输出”中间没有任何中间产物。archify的流水线则多了一个关键步骤——AI先生成一份结构化的架构描述文件而不是直接输出Mermaid或图片。这份描述文件我习惯用JSON格式还有项目里也在用YAML。它包含四类核心信息组件清单、组件属性、依赖关系和约束规则。{ version: 1.0, components: [ { id: order-service, name: 订单服务, type: service, protocol: HTTP, belongsTo: order-domain }, { id: order-db, name: 订单数据库, type: database, engine: PostgreSQL } ], dependencies: [ { from: order-service, to: user-service, type: HTTP, description: 获取用户信息 } ], constraints: { mustNotConnect: [service-to-service, database-to-database], allowedProtocols: [HTTP, gRPC] } }你可能觉得这个步骤很多余——直接让AI画图多快搞一个中间JSON不是很麻烦吗但恰恰是这个中间产物让后续的自动化验收成为可能。Mermaid只有视觉信息计算机无法知道“订单服务”和“用户数据库”之间那条线的语义是什么而结构化描述让每个组件、每条依赖都变成了可校验的数据。这是整条流水线的基础。3.2 第二步谁来判断“合格”——三层校验体系有了结构化描述之后就可以对它做自动校验了。archify按照我的观察是分了三层来做验收每一层解决一类特定问题正好对应我在前面列的几类翻车现场。第一层是语法层校验。描述文件本身的格式是否正确、字段是否完整、组件ID是否唯一、依赖关系的两端节点是否存在。这层校验最简单任何一个写过程序的人都能实现但它能拦住最基础的错误比如AI生成的组件被依赖引用但定义缺失。第二层是逻辑层校验。这是最关键的一层也是“验收流水线”价值最大的地方。它检查的是架构描述符不符合系统基本逻辑比如服务不能直连数据库如果团队规定必须走存储层、两个服务之间的依赖不能循环、依赖类型必须匹配组件支持的协议等。这个校验规则完全是团队自定义的你可以在配置文件里声明。第三层是策略层校验。比如合规检查——某些组件不允许出现在边界区域标签检查——所有组件必须带有负责人标签安全检查——敏感数据流向是否经过脱敏节点。这一层校验本质上是把团队的技术规范和架构设计约定沉淀成机器可读的规则。三层校验合在一起本质上就是把原本依赖专家人肉Review的事情变成了自动化检查。它的核心思路是架构图不应该是一次性生成的结果而应该像代码一样可以通过流水线持续校验、持续演进。3.3 第三步校验不通过怎么办——反馈闭环架构图校验失败之后最关键的是如何反馈给AI进行修正。archify的处理方式是把校验失败的具体原因和上下文信息回传给AI Agent然后让Agent基于这些反馈进行针对性修复而不是简单粗暴地重新生成一张图。我在实际使用中觉得这个细节特别重要。如果只是简单返回“校验失败请重新生成”AI往往会陷入“改了一个错误又引入另一个错误”的循环。但如果你告诉它“订单服务不允许直连订单数据库需要经过数据访问层”AI就能根据这条明确反馈做精准修复。这其实跟我们人改代码的思路一样——Bug反馈信息越具体修复效率越高。修复过程通常是迭代式的校验失败 → 把错误信息拼接到提示词中 → AI重新生成结构描述 → 再次校验。正常情况下两三轮迭代基本就能通过验收。如果超过五轮还没通过那大概率是需求描述本身有问题需要人工介入澄清需求而不是让AI继续烧Token瞎试。4. 实操从零搭一条AI架构图验收流水线前面讲了原理这块直接上实操。我用一套完整的流程说明怎么把archify这套思想落地到自己的项目里包括工具安装、规则配置、Agent接入和CI集成。整个过程我不依赖任何必须付费的商业服务核心就是一个命令行工具加一段Agent配置。4.1 初始化项目骨架首先你需要一个archify命令行工具。我目前用的是社区版直接通过包管理器安装即可。npm install -g archify/cli archify init my-arch-project初始化命令会生成一个标准目录结构my-arch-project/ ├── archify.config.js # 校验规则配置 ├── architecture/ │ └── system-description.json # 架构描述文件 ├── contexts/ │ └── system-context.md # 系统上下文提示词 └── output/ └── render/ # 渲染产物目录这个目录结构本身就在暗示工作流程先在contexts里定义清楚系统上下文和约束然后让AI生成architecture里的结构化描述接着通过archify.config.js执行校验通过后渲染到output目录。4.2 配置团队自定义校验规则校验规则是整条流水线的灵魂。archify.config.js里最核心的配置就是这个rules数组我强烈建议架构师在这里投入时间因为规则越贴合团队实际情况流水线的价值就越大。module.exports { version: 1.0, rules: [ { id: no-service-db-direct-connection, type: logical, severity: error, description: 服务不允许直连数据库必须经过数据访问层, match: { dependency: { fromType: service, toType: database }, unless: { existsComponent: { type: data-access-layer } } } }, { id: no-dependency-cycle, type: logical, severity: error, description: 服务之间不允许出现循环依赖, check: acyclic }, { id: component-owner-tag-required, type: policy, severity: warning, description: 每个组件必须有owner标签, match: { component: { type: * } }, require: { tag: owner } } ] };这里有几个设计和选型的原因想展开说一下。第一个规则no-service-db-direct-connection解决的是我认为最普遍的架构图错误——服务直连数据库。这个规则在真实的业务系统里非常重要因为直连数据库意味着绕过了业务逻辑层会导致数据一致性、安全审计等一系列问题。把这条规则固化成自动化校验之后AI生成图的时候只要敢让服务直连数据库流水线直接就亮了红灯。第二个规则no-dependency-cycle做的是循环依赖检测。微服务架构中服务A调服务B、服务B调服务A这种循环依赖一旦形成调用链会变得非常不可控而且难以排查。acyclic检查原理上就是对这个有向图做拓扑排序如果存在环就无法形成有效的拓扑序列检验效率也是很高的。第三个规则是策略层的典型应用强制每个组件带owner标签。我管它叫“可追溯性强制”这个在团队超过十个人之后特别重要。架构图如果出现一个没人认领的服务在系统变更的时候根本不知道该找谁确认规范的团队管理会直接把它做成强制规则。4.3 定义系统上下文提示词接下来是定义一份高质量的“系统上下文”提示词。这个文件会作为AI生成架构描述时的唯一事实来源质量直接决定AI输出的准确性。我自己总结了一个比较稳定的模板要素包括系统边界、技术选型、组件清单和约束条件。# 用户订单系统架构描述 ## 系统边界 这是一个电商平台的订单子系统负责订单创建、查询、状态流转。 只与用户系统、支付系统和商品系统交互不涉及物流系统。 ## 技术选型 - 后端服务Java 17 Spring Boot同步HTTP/REST接口 - 消息队列暂不引入所有调用均为同步 - 数据库PostgreSQL每个服务独享库 - 网关Spring Cloud Gateway ## 允许存在的组件类型 service (HTTP服务)、database (数据库)、gateway (网关)、cache (缓存) ## 明确禁止的组件 - 不存在的中间件Kafka、RabbitMQ - 不带业务归属的通用组件如日志系统、监控平台 ## 关键约束 - 服务之间的调用必须通过HTTP接口 - 服务不允许直连其他服务的数据库 - 组件必须标注所属领域order/user/payment/product这个上下文文件的重点不在于篇幅多长而在于把边界和约束说清楚。实际使用中AI生成架构图时的很多幻觉都是因为上下文里缺少明确的“禁止清单”。你如果不说“不引入Kafka”AI很可能因为训练数据里常见的电商架构而主动加上消息队列。4.4 调用AI生成架构描述并执行验收定义好上下文之后就可以进入生成和验收的循环了。我通常是用它配合Cursor或Codex之类的Agent在项目目录里执行一个命令让Agent读取contexts/system-context.md并生成架构描述文件。archify generate --context contexts/system-context.md \ --output architecture/system-description.json \ --prompt 订单子系统包含用户端订单创建、订单查询、订单状态流转这个命令内部做的事情是调用底层AI模型把context文件、用户prompt和archify内置的“输出Schema约束”组装成一个完整提示词然后将AI输出解析成结构化的JSON文件。生成之后立刻执行验收archify validate architecture/system-description.json --config archify.config.js执行结果有两种PASS或FAIL。PASS意味着这张架构图已经通过了你团队定义的绝大部分核心校验规则后续可以交给人工做最后确认FAIL则会输出具体的错误清单比如哪条规则被违反了、涉及哪些组件ID等。我在本地跑的最常见错误截图类似这样[FAIL] no-service-db-direct-connection 订单服务(order-service) → 用户数据库(user-db) 服务不允许直连数据库必须经过数据访问层 [WARN] component-owner-tag-required 组件 payment-service 缺少 owner 标签拿到FAIL反馈之后直接把这段错误信息回传给你用的Agent让它基于反馈修改。大部分情况下AI都能根据“那条线不该连”、“哪个组件缺标签”这类具体反馈做出修正。4.5 验收通过后渲染出图校验通过之后就可以渲染成图形了。archify本身支持Mermaid和PlantUML等主流渲染格式我喜欢用Mermaid因为它对GitHub和团队知识库的支持特别好。archify render architecture/system-description.json \ --format mermaid \ --output output/arch.mmd渲染得到的Mermaid文件就是标准的文本格式可以直接放进Markdown里展示也可以配合Mermaid Live Editor等工具生成PNG或SVG。关键在于这个Mermaid文件的内容是从通过验收的结构化描述映射出来的组件和依赖已经经过校验所以图形的准确性和直接从AI嘴里生成的图完全是两个质量等级。5. 进阶玩法把验收流水线接入AI Agent工作流和CI到了这一步你其实已经拥有了“生成架构图→自动验收→修改→再验收”的完整闭环。但这个闭环还停留在本地手动操作阶段真正让流水线发挥最大价值的是把它接入Agent工作流和CI管道。5.1 和Cursor/Codex等AI编程工具集成现在很多AI编程工具都支持自定义Skill或指令让Agent按照特定流程工作。我在Cursor里注册了一个“架构图生成”的Skill核心内容就是要求Agent必须遵循archify的“生成→验收→修复→再验收”循环。你是一名架构师。当用户要求生成架构图时必须按以下步骤执行 1. 读取 contexts/system-context.md 中的系统约束。 2. 将用户需求映射为架构描述写入 architecture/system-description.json。 3. 执行 archify validate直接读取错误输出。 4. 根据错误列表逐条修复架构描述直到全部校验通过。 5. 校验通过后执行 archify render 输出最终图。 6. 向用户展示最终图并说明关键设计决策。这个指令看着简单实际效果非常显著。在没有这套工作流之前让Agent画图基本就是猜有了这套工作流之后Agent的行为模式从“单次生成”变成了“面向验收标准的迭代优化”。本质上这就是把质量门禁前移让Agent在一开始就朝着“容易通过验收”的方向生成结果质量自然就稳定了。5.2 在CI里增加架构图回归检查架构图是活的资产和代码一样需要持续维护。我们在CI管道里加了一个archify检查任务每次有新的架构描述提交到仓库都会自动执行校验保证图不会“悄悄画错”。下面是我们在GitHub Actions里的示例配置name: architecture-check on: pull_request: paths: - architecture/** - archify.config.js jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install -g archify/cli - run: archify validate architecture/system-description.json这个CI任务的效果很直接只要有人改了架构描述文件CI自动跑校验没过就直接阻断合并。从源头上杜绝了“架构图在PR里看起来没问题合并后发现连组件都没了”这种事故。我个人的建议是初期可以只把“error”级别的规则设为阻断项比如循环依赖、服务直连数据库这类把“warning”级别规则比如组件缺owner标签先留作提示观察一段时间后再决定是否升级为阻断项。这样可以避免一上来规则太严导致团队抵触。6. 常见问题与排查技巧实录实际操作中总会遇到各种问题我把这几个月折腾这套流水线遇到的典型问题集中整理一下给后来人排雷。6.1 组件ID频繁变化无法做增量对比最初我们很头疼一个问题AI每次生成的组件ID都是随机的比如上一次管订单服务叫order-service下一次就变成order-svc。这导致我们没法把两张图做自动对比无法追踪架构的变更。后来我们在archify.config.js里配了别名映射机制允许给组件设置alias比如{ id: order-svc, aliases: [order-service, order-center, 订单服务] }这样即使AI换了ID我们也能通过别名把它归一化到统一命名空间。对于要长期维护架构图的团队这个配置非常有必要。6.2 逻辑校验规则写得太死误伤正常场景刚开始规则写得比较严格时出现过把正常场景判错的情况——典型例子是缓存组件和服务之间的关系是双向的服务会读取缓存、写缓存、缓存回源也会调用服务接口这种场景如果用简单的依赖方向校验很容易误判。我的调整思路是为规则增加“场景白名单”比如某个规则只在特定上下文下生效或者给特定组件类型放行。{ id: cache-access-pattern, type: logical, severity: error, match: { dependency: { fromType: cache, toType: service } }, except: { componentTags: [read-through-cache] } }写规则的时候多想想真实场景别一刀切。架构校验的目的是帮团队减少无效沟通不是为了造一个完美的形式系统。6.3 Agent陷入修复循环反复改不完这个问题也很常见。Agent在校验失败后盲目重试每次改一个地方又引入新问题白白消耗Token和精力。我的经验是设置一个“迭代上限”一般三轮之内如果没有明显收敛就停下来人工介入。另外在反馈信息里加上“当前是第N次修复请优先修复error级别问题不要修改已验证通过的组件”这种约束能显著提高Agent的修复效率。6.4 架构描述文件太大超出模型上下文窗口当系统比较复杂时AI生成的描述文件可能非常大再次请求时会超出上下文窗口限制。我们的解法是把大系统拆成子域处理比如订单域、支付域、用户域各自生成描述文件然后通过archify的merge功能合并成整体archify merge architecture/order-domain.json \ architecture/payment-domain.json \ architecture/user-domain.json \ --output architecture/system-description.json这种方式既降低了单次生成的复杂度又能通过合并步骤整体校验跨域依赖是否正确一举两得。6.5 Mermaid能渲染但图里节点错位最后这个小问题看似和校验无关但体验上很影响观感。Mermaid渲染长名称节点时布局经常错乱。我会在render前给所有组件统一加短ID并使用显示名展示render: mermaid: idPrefix: cmp useDisplayName: true这样既能保证美工上的整齐也不影响结构的确定性。细节虽小但评审会上架构图是否美观确实会影响非技术人员对整体设计的认可度。7. 使用心得与实际效果这套验收流水线跑下来快两个月了最直接的感受是AI画的架构图从“能看”变成了“能用”。怎么定义这个能用就是拿到图上线评审团队不会因为基础结构错误吵来吵去评审时间至少缩短了一半。以前让AI画架构图人肉Review至少要过好几遍先看组件对不对再看连线方向再核对命名规范最后还得检查有没有不该出现的幻觉模块。现在这些检查全部自动化了人工只需要专注在“这样设计是否合理”这类更高层级的问题上而不是被低级错误消耗精力。当然这套方案也不是没有代价。前期在配置规则上需要投入一定时间尤其是把团队的技术规范沉淀成机器可读的规则这活儿本身就需要架构师深度参与。另外整个流程比普通的“一句话出图”要多几个步骤如果你只是临时画一张示意性质的图那直接用AI生成更快没必要上流水线。但只要是稍微成规模、需要长期维护的系统架构这条验收流水线的价值很快就体现出来了——它把架构图从一次性产物变成了可持续维护、可自动回归检查的工程资产。我个人觉得这也是AI辅助架构设计的正确打开方式不是让AI自由发挥替你决策而是让AI作为执行者在明确的验收标准下替你高效干活。最后再分享一个小技巧如果你刚开始尝试别一上来就搞很复杂的规则体系。挑最痛的三个问题先落地比如禁止服务直连数据库、禁止循环依赖、强制组件归属标签跑通一两个项目之后再根据团队反馈逐步加规则。规则不是越多越好能让流水线挡住真实错误、帮团队省时间才是核心目标。