如果只是把“架构图”三个字丢给 AI让它自由发挥几分钟后你确实会得到一张视觉效果不错的图。可问题往往出现在评审会上同事指着其中一个服务模块问这个节点的依据是什么这条调用链是从哪份代码里读出来的这个模块是不是已经下线了你会发现那张图漂亮归漂亮却很难回答任何一个追问。这也是为什么我更关注 Archify 这类主打“可验证、能追路径”的 AI 架构图工具。标题里最有信息量的不是“AI 画架构图”而是“可验证”和“能追路径”。它暗示了一种判断架构图的真正难点从来不是画得多么美观而是画完之后团队敢不敢把它当成一个可以评审、可以追溯、可以长期维护的设计资产来使用。1. AI 生成架构图的最大问题不是画得丑而是画完以后没人敢用1.1 一张“好看但没依据”的架构图会带来什么问题过去两年不少 AI 绘图工具已经能根据一段描述生成 Mermaid 或 PlantUML 架构图。你给它一个“微服务系统包含用户服务、订单服务、支付服务”它确实能画出一个分层清晰、连线合理的结构图。但这类图大多存在一个共同问题它只是在“顺着你的话编一个合理的结构”并没有真正面对你的代码、配置、部署关系。这种图拿到项目里会有三个后果。第一它无法被复核。图中每个节点到底对应哪个服务、哪个模块、哪份配置没有人能说清。看起来合理但一旦要落地没人敢按它去改代码。第二它没有版本概念。今天生成一张明天需求变了再生成一张前后两张图之间的差异是什么是架构真的变化了还是提示词换了个说法完全不知道。第三它会形成一种“假确定性”。团队看到一张结构完整、标注清晰的图容易默认它是准确的从而跳过本该发生的追问。等上线后才发现实际依赖和图纸完全对不上返工成本远高于当初省下的半小时。1.2 架构图不是图画而是团队共识的凝固形式我倾向于把架构图理解成“团队对系统当前状态的共识凝固成的一份可读材料”。它必须能回答问题这个模块为什么存在它和旁边模块为什么有连线这个分组边界是谁定的这条依赖关系有没有代码或配置层面的证据一张架构图如果回答不了这些问题它不是“简化版”而是“失真版”。带失真图纸开工比没有图纸更危险。所以AI 画架构图这件事真正有价值的方向不是让模型学会更好的布局审美而是让生成结果能对齐事实、能标注来源、能在系统变化后追踪差异。Archify 之所以能从众多 AI 画图工具里获得 3.5 万 Star社区关注的核心未必是它“学会了画图”而是它尝试解决“画完以后怎么让人信”这个更关键的问题。2. “可验证、能追路径”背后是三类能力的组合从工程经验看一个能产出“可信架构图”的 AI 工具不会只靠模型一次性生成它通常会在流程里组合三类能力输入归一、可版本化输出、生成路径追踪。虽然不同工具实现方式有差异但这个框架可以帮我们理解 Archify 这类工具的设计逻辑。2.1 输入归一把零散资料整理成可计算的架构素材真实的架构信息很少集中在一份文档里。它散落在 README、Docker Compose 文件、Kubernetes 配置、OpenAPI 文档、接口定义、甚至同事的聊天记录里。如果一个工具只允许用户输入自然语言描述那么它生成的架构图必然停留在“大家口述的系统”层面而不是“真实运行的系统”层面。要接近真实就必须把多个来源的资料导入工具让 AI 在充分上下文上做抽取和推断。这就是输入归一的价值。它会做类似这样的事从部署配置里读取服务清单。从路由或 API 定义里抽取服务间的调用关系。从代码仓库结构里推断模块边界。从环境配置里识别外部依赖例如数据库、缓存、消息队列。把这些信息整合成一份标准的结构化输入交给大模型去生成。这一步看起来只是数据准备实际上决定了整条链路的天花板。输入只有一段描述输出的可信度就停留在“合理想象”输入有真实配置输出的可信度才有机会提升到“基本可核对”。2.2 可版本化的图输出Mermaid、PlantUML 与 JSON 的价值过去画架构图常用白板工具或可视化编辑器优点是自由缺点是几乎无法做内容追踪。你只能说“这张图看起来不一样了”却很难说清哪里变了、为什么变。Archify 这类工具如果真正解决问题通常会选择可版本化的图形格式作为输出层例如 Mermaid、PlantUML 或带结构化属性的 SVG/JSON。这种选择的工程意义非常大架构图以文本文件的形式进入 Git 仓库可以参与代码评审。每次变更都能生成 diff评审者可以看到哪个节点被删除、哪条依赖被新增。脚本和 CI 可以读取结构做自动检查。换句话说架构图从“一张像素图”变成“一种可读、可算、可测的代码资产”。这比单纯追求画面美观重要得多。2.3 生成路径追踪每次变更都能回放“能追路径”还有一个理解方向每次生成出来的架构图应该能追回到它由哪份输入、哪个版本、哪次提示词产生。这是工程化的关键。团队协作时架构图会反复迭代。如果没有记录生成路径很容易出现这种情况某次调整后一张原本经过评审的架构图被悄悄改错了但没人知道是谁改的、为什么改、用哪份新资料重新生成的。一种合理的做法是在生成架构图时同时输出一份元信息文件里面记录输入的源文件列表与哈希值。使用的生成模型或规则版本。生成时间与操作者。相对上一版的具体变更点。这样一来架构图就有了完整的生命周期。评审通过后后续任何变更都可以被审查。即使发现错误也能快速回退到上一版而不是重新靠记忆画图。3. 实操路径从零生成一张经得起追问的架构图讨论理念之后落到操作。无论使用 Archify还是使用同类架构图生成工具核心流程都比较接近。下面按一套通用可执行流程来拆解具体命令以你当前使用的版本为准。3.1 准备输入先用目录结构约束信息边界不要一上来就写提示词。先为你的架构资料准备一个固定目录。docs/arch-input/ ├── README.md # 系统总览 ├── docker-compose.yml # 服务编排信息 ├── k8s/ # 部署清单 ├── openapi/ # 接口定义 ├── docs/ # 历史设计文档 └── decision-records/ # 架构决策记录这一步的目的不是形式主义而是给 AI 划定信息边界。它只需要从这些真实资料里抽取架构事实而不是从通用知识里编造一个“类似系统长什么样”。如果你的系统还没有完整的部署配置和接口定义至少也把下面几个问题写清楚服务列表一共有哪些独立部署的服务调用关系谁调用谁数据依赖每个服务使用了哪些数据库或缓存外部依赖第三方支付、短信、对象存储等是否属于系统边界这些内容能作为初始输入让第一次生成的结果不至于完全跑偏。3.2 最小跑通先画一个模块再铺开整个系统很多人的习惯是一上来就把整个微服务系统丢给 AI。结果往往是上下文过长、关系混乱、生成结果一团乱麻。更稳妥的顺序是“小步验证再逐步扩展”。先从业务链路里挑一个独立模块例如“用户登录链路”输入它的服务清单、接口列表和依赖关系让工具生成这一条链路的架构图。检查无误后再逐步加入订单、支付、库存等模块。这样可以保证每一层增量都有依据出了问题也能定位是哪份输入不准确而不是整张图重新开始。3.3 图中嵌入标注或来源信息把证据画出来要提升架构图的可验证性可以在生成后给关键节点补充来源标注。如果工具支持可以要求输出带备注字段的格式。Mermaid 里常见的写法是给节点加上备注graph LR User[用户端] -- Api[API Gatewaybr/来源: docker-compose.yml L24] Api -- Order[订单服务br/来源: openapi/order.yaml] Order -- DB[(订单数据库br/来源: k8s/order-db.yaml)]这不是为了好看而是为了让任何看到图的人都能迅速找到第一手证据并顺着来源文件去核对。如果某个节点没有来源那就说明它是 AI 推测出来的必须单独标记清楚。3.4 生成后立刻做一次三方核对拿到第一次生成结果后不要急着修样式。用半小时做一次三方核对把问题消灭在早期。核对三元组是架构图、输入资料、真实环境。逐个检查图中每个服务是否都能在 docker-compose 或 k8s 配置里找到对应部署图中每条连线是否都能在接口文档、日志或代码调用中找到依据图中出现的数据库、缓存、消息队列是否和实际环境一致有没有被遗漏的关键节点例如反向代理、任务调度、定时任务核对完成后把发现的问题记录下来形成一份“差异清单”再回到工具里修正输入或标注重新生成一版。这个环节看起来慢却是整条链路里价值密度最高的一步。因为真正在建立可信架构图的不是 AI而是你和真实系统之间的核对过程。4. 架构图一旦不可信按链路去查根因不要在提示词上反复拉扯使用过程中最让人头疼的情况是生成结果“看起来合理但总是差一点”。很多人会立刻调整提示词反复让 AI 重新画。但架构图生成是一个多层链路问题可能出在任一层。只改提示词常常只是在没有定位的情况下随机调整。更有效的方法是按固定链路逐层排查。4.1 先给症状分类不要笼统说“画得不好”“画得不好”不是有效症状。把现象拆细缺节点系统里真实存在的服务没有出现在图中。多节点图中出现了系统里不存在的模块。连线错误服务之间的调用方向反了或者依赖关系无中生有。层级混乱业务域、服务、数据库、部署实例全部混在同一层。不稳定同样输入生成两次结果差异很大。格式问题Mermaid 渲染失败或输出内容无法被 CI 处理。不同症状对应不同根因。先明确是哪种再决定查哪层。4.2 五层排查链路从输入到工具边界依次核对第一层输入资料层。这是最常见的出错点。检查输入文件里是否有过时配置服务命名是否前后不一致接口文档是否缺失“订单服务”在 README 里叫 order在 k8s 里叫 order-service在 API 文档里叫 OrderServiceAI 很可能把它们当成三个不同节点。先把命名统一再重新生成。第二层上下文与提示词层。检查你给工具的范围描述是否清楚。有没有界定清楚图要表达的业务域有没有说明哪些属于外部系统、哪些属于内部服务有没有指定图的层级比如只看服务层还是要细化到实例层提示词不适合反复试错但适合一次性写清楚边界。第三层环境与依赖层。如果工具依赖模型 API或依赖本地解析器检查依赖版本是否匹配。部分工具对 Mermaid 语法版本有要求新旧语法混用会导致渲染失败。还有权限问题工具是否有权限读取 k8s 配置、OpenAPI 文档还是只读了部分文件权限缺失会直接导致信息缺漏表现就是图里少节点。第四层参数与稳定性层。有些工具在生成时会使用模型采样参数同一份输入会产生细微差异。检查生成日志里是否记录了随机种子、模型版本、温度参数。如果工具支持固定模型版本和随机种子让结果可复现。这对“能追路径”非常关键。第五层工具能力边界层。最后要承认一个现实任何工具都有边界。如果输入资料只有一段业务描述却要求生成一份能直接指导开发的详细架构图这不是工具能力问题而是任务本身缺少必要信息。工具没法替你把缺失的事实补齐。建议遇到问题不要连续修改提示词超过三次。三次仍然不对就回到输入资料和管理体系上排查。架构图生成的问题多数时候不在“画”这一步而在“喂给它的东西”这一步。5. 别让 3.5 万 Star 掩盖边界它适合什么又替代不了什么Archify 能获得 3.5 万 Star说明社区确实需要一种让 AI 生成架构更可信的思路。但 Star 数本质上只反映“关注度”不等于“生产环境成熟度”。在大规模引入之前先把适用边界想清楚。5.1 3.5 万 Star 的真实含义它至少说明三件事社区对“AI 生成架构图”有持续兴趣且对“可验证”“可追路径”这类能力有真实诉求。Archify 在易用性或输出形式上做对了一些事否则很难积累到这个量级。它已经获得不小的社区测试面相比无人问津的项目Bug 被发现的概率更高迭代速度可能更快。但它无法说明三件事官方没有给出明确的版本、团队背景和数据指标时不要默认它已经具备企业级稳定性和安全性。Star 不等同于生产验证。很多项目是开发者个人尝鲜比例高真正在核心业务里长期使用的案例未必多。它的默认能力是否适配你所在公司的技术栈要结合你的实际输入材料来验证。所以正确心态是认可它的方向但验证它对你是否可用。先做小范围试用再做选型判断。5.2 哪些场景适合哪些场景更适合人工画图从常见实践看Archify 和同类工具更适合四类场景老系统没有架构文档需要快速梳理出一个可信的初始版本。微服务数量多、部署关系复杂人工整理容易遗漏。架构文档长期不更新想在代码评审中同步维护架构图。团队评审时需要一个可辩驳、可定位来源的讨论对象。反过来有三类场景不适合硬套组织架构图、HTML 页面结构、自定义流程图这类非系统架构主题用通用画图工具更轻量没必要引入架构生成链路。需要展示严格的网络安全隔离、数据流向合规、权限边界时AI 生成的图只能作为底稿最终必须由安全或合规人员逐条确认。一次性的概念示意框图例如讲解某个算法或某个设计模式的示意图直接手绘或使用通用工具效率更高。5.3 一个可复用的验收框架架构图四问最后把经验沉淀成一个相对简单的验收方法。以后无论用 Archify还是用其他 AI 工具生成架构图都可以用这四个问题来完成最终验收。验收问题检查内容不通过时怎么办每个节点都有出处吗节点能否对到配置文件、接口文档、代码目录或 ADR回填来源资料删除无来源节点每条连线都能解释吗调用关系能否对到实际接口、事件或数据流补充调用依据修正或移除无法解释的连线层级和粒度一致吗是否把业务域、服务、实例、数据库混在同一平面按目标读者拆分成多视图重新生成可复现吗同一输入重新生成结果是否稳定是否有元信息记录固定模型版本和输入版本记录生成参数如果这四问都能通过那么这张架构图已经具备进入项目仓库、参与评审、支持后续变更追踪的基本条件。即使以后系统继续演进也可以把“重新生成架构图”当成一次可重复执行的任务而不是每次都要从零开始的一次性创作。这也正是我觉得 Archify 这类工具最值得关注的地方。AI 能不能画出好看的架构图早就不是核心问题。真正有价值的变化是架构设计这件事开始从“脑海里的一张图”变成“仓库里的一份可追踪、可验证、可迭代的资产”。有了这个变化架构评审、代码走查、知识传递的效率都会跟着改变。