Archify：用AI生成可验证、可追踪的架构图

如果你在一个十几人的研发团队里画过架构图大概率经历过这样的场景方案评审前夜你打开 ProcessOn 或 draw.io对着一个半空的画布发愁好不容易画完第二天被同事追问“订单服务为什么依赖消息队列这条链路的调用方到底是谁”你翻了半天文档也没能给出一个能落到代码级的答案。过去两年AI 编程工具把自动化带到了架构设计环节输入一句“帮我画一个订单微服务架构图”模型能在十几秒内输出一张看起来很专业的图。但很多用过的团队会发现一个问题图很漂亮却经不起追问。它为什么这么画依据是什么代码改了之后这张图还能不能信这正是 Archify 这类工具切入的点。Archify 不是又一个“输入文字自动出图”的插件。从项目定位来看它强调的是两个词可验证Verifiable和可追踪Traceable。在 3.5 万 Star 的关注度背后它真正想解决的问题是让架构图从“一次性交付物”变成“能被规则校验、能被链路追踪的工程资产”。这篇文章会从三个角度展开第一Archify 与普通 AI 画图工具的本质区别第二怎么把它装到本地并接入 AI 编程工具包括在 Trae 这类环境中配合 Skill 使用第三一个从需求描述到架构定义、校验、追踪的完整示例以及新手很容易踩的几个坑。1. 这篇文章真正要解决的问题先聊一个反直觉的现象很多团队不是不会画架构图而是画了也没人信。1.1 架构图最常见的三个痛点我把日常工作中的架构图问题总结为三类第一个痛点是信息丢失。架构图是“人肉同步”出来的。A 同学画完系统架构图B 同学第二天改了服务的部署方式C 同学把 MySQL 换成了云数据库但那张 PPT 里的图还停留在上周。信息在传递过程中不断衰减最后图变成“仅供汇报”。第二个痛点是无法验证。普通的绘图工具只提供画布和图形画布不会告诉你“订单服务依赖了支付服务但支付服务反向依赖了订单服务构成了循环依赖”。这张图能不能成立全看画图人当时的状态好不好。第三个痛点是无法追踪。图上画了一个“用户服务”这个框代表什么是代码仓库里的哪个模块对应哪条业务需求如果产品改了规则我要改图上哪个部分大多数情况下这些问题没有答案。1.2 AI 画图工具解决了一半问题留下另一半传统 AI 画图工具解决的是“从文字到图形”的生成效率。你写一句提示词它给你一张图。但这类工具有一个共同问题模型理解的是自然语言不是你的系统真实现状。所以生成出来的架构图经常是“逻辑自洽但事实错误”——看起来节点齐全、连线规整实际依赖关系全是模型自己脑补的。到了评审会上一旦被问到“这条边是从哪来的”工具回答不了。Archify 的价值不在于把图画得更漂亮而在于把生成结果放进一套可验证的框架里。架构图里的节点和连接不是“画出来”的而是“推断出来的”并且在输出前会经过规则检查。换句话说AI 负责生成规则负责验证人负责决策。1.3 读完这篇文章你能获得什么这篇文章适合三类读者架构师和技术负责人想找到一种方式让团队架构图不再是“摆设”而是能够参与代码评审和变更管理的资产。后端与全栈开发经常被拉去画模块关系图、梳理调用链想用 AI 减少重复劳动同时保证输出结果可解释。AI 应用开发者正在调研或使用 Trae、Cursor、VS Code 等 AI 编程环境想了解“Skill 外部工具”如何落地到具体开发流程。读完你会明白Archify 这类工具不是要替代你的架构判断而是把“画图”从手工劳动变成“AI 生成 规则校验 路径追溯”的工程流程。AI 生成的架构图不是结论是草稿真正值钱的是那套能验证、能追溯的规则。2. Archify 的核心概念与适用场景在进入实操之前先把 Archify 的几个核心概念讲清楚。2.1 什么是 Archify从项目资料和社区讨论来看Archify 是基于 AI 的架构图生成与验证工具。它做的事情可以拆成三步解析读取你的项目代码、配置文件、部署描述或文档理解系统里有哪些组件以及它们之间的依赖关系。生成用 AI 把这些信息组织成结构化的架构描述再渲染成架构图。验证与追踪针对架构描述执行规则检查并保留每个元素到原始来源的追踪路径。它的输出不是一张“死图”而是一份结构化的架构描述。这份描述既可以被渲染成可视化架构图也可以被脚本、CI/CD 流程和其他工具消费。2.2 什么是“可验证”“可验证”是理解 Archify 的关键。普通的绘图工具画布上的框和线是没有语义的。Archify 则不同每一个节点和连接都带有类型和属性并且可以被规则约束。常见的验证规则包括依赖方向指定层只能依赖相邻层比如 Controller 不能直接依赖 DAO。循环依赖检测发现 A 依赖 B、B 依赖 A 的环阻断校验。边界约束某些组件不能出现在特定环境比如本地开发模块不能依赖生产环境配置。命名规范组件命名必须符合团队前缀或分层后缀。当 AI 生成完架构图后工具不会直接把结果交给用户而是先运行这些规则。验证通过才进入下一步验证失败则返回错误列表让 AI 或用户修正。这个概念在 AI 时代尤为重要。大模型一个显著的特性是“一本正经地胡说八道”如果生成结果没有规则兜底它输出的架构图可能看起来很专业实际经不起代码级审查。可验证机制相当于给 AI 生成结果加了一层保险。2.3 什么是“追路径”“追路径”解决的是“这个框从哪里来”的问题。比如架构图里有个节点叫“Payment Service”这个节点不是凭空出现的。Archify 会记录它是从payment-service这个代码仓库的pom.xml依赖解析出来的还是从architecture.yaml配置文件里定义的或者是从某次需求文档中提取的。有了追踪信息架构图就具备三个能力反向定位图上任何一个节点都能找到背后的代码路径或配置定义。变更感知代码或配置变了可以重新解析并对比架构图差异。评审依据评审时能够直接带着提问者去看原始代码位置而不是凭记忆解释。这也是 Archify 被称为“能追路径的架构图”的原因。2.4 Archify 与传统工具、普通 AI 绘图工具的对比对比维度传统绘图工具普通 AI 画图工具Archify 类工具核心能力手工绘制、排版自然语言转图片生成 校验 追踪信息来源人的记忆模型的训练知识项目代码、配置、结构化定义是否可验证否否是规则检查是否可追溯否否是可回溯到源文件变更维护成本高手工更新中重新生成低重新解析 校验适合场景汇报、概念说明快速草图工程资产、评审、CI CD这个对比也解释了为什么 Archify 会受到关注它把架构图从“画图工具”维度拉到了“架构治理工具”维度。对小型项目来说这个能力可能过剩但对微服务架构、多团队协作、审计要求高的项目验证和追踪几乎是刚需。3. Archify 环境准备与安装Archify 目前的形态偏向开发者工具通常以 CLI 或插件方式运行。下面介绍通用的准备思路具体命令以官方仓库 README 为准版本细节不建议在第一时间写死到脚本里因为它迭代速度很快。3.1 系统与运行环境操作系统macOS、Linux、WindowsWSL均可推荐在类 Unix 环境下使用因为依赖分析和 Shell 脚本生态更顺畅。运行时需要 Node.js 或 Python 环境。这类工具通常偏向 Node.js 生态建议提前装好 Node.js 18 以及 npm 或 pnpm。Git用于拉取仓库、读取代码变更和提交信息。AI 编程环境可选VS Code、Cursor 或 Trae 等支持 AI 插件/Agent 的编辑器用于体验“AI 对话 架构图生成”的工作流。如果暂时不确定自己的版本是否兼容更稳妥的方法是先看官方仓库的requirements、prerequisites或环境要求文档再决定安装方式。3.2 安装 Archify CLI以下命令是通用安装思路的示例包名和安装方式请以官方仓库说明为准# 使用 npm 全局安装 npm install -g archify/cli # 或者使用 pnpm pnpm add -g archify/cli # 验证安装 archify --version如果官方提供的是 Python 包则对应命令可能是pip install archify archify --version安装成功后可以先执行archify --help查看支持的子命令。通常你会看到init、generate、validate、trace、diff这五类指令分别对应初始化、生成、校验、追踪和对比变更。3.3 初始化项目工作区进入目标项目目录执行初始化命令创建架构描述文件cd your-project archify init执行后工具通常会在项目根目录生成类似下面的结构your-project ├── archify │ ├── architecture.yaml │ ├── rules.yaml │ └── templates │ └── default.json └── package.json目录说明architecture.yaml主架构定义文件描述组件、依赖、分层和标签。rules.yaml验证规则文件定义项目特有的架构约束。templates/default.json架构图渲染模板决定最终图表的布局和样式。这个阶段的重点是先让工具“知道”你的项目结构。如果后续要接入 AI 编程工具这份architecture.yaml就是 AI 生成结果的“锚点”。4. 与 AI 编程工具集成Skill 配置与 Trae 使用思路Archify 的命令行形态只是基础。真正让“3.5 万 Star”热度持续发酵的是它与 AI 编程工具结合后的工作流。很多人搜索“Archify 怎么用”“Archify 怎么用在 Trae”其实问的是同一件事怎么让 AI 帮我自动生成一份可以验证的架构图。4.1 为什么要把 Archify 接入 AI 编程工具在 AI 编程工具中模型天然擅长理解自然语言和生成文本但对“运行命令、读取文件、执行校验”这类操作并不直接擅长。Archify 恰好补齐了这个环节。接入后工作流变成你在 AI 对话框里输入“分析当前项目画一个业务架构图。”AI Agent 识别到这是一个架构分析任务。Agent 调用预置的 Archify Skill执行archify generate。工具解析项目代码生成架构描述并渲染出架构图。工具运行archify validate把校验结果返回给 AI。AI 根据校验结果修改架构描述再次输出。整个过程里AI 负责“对话和判断”Archify 负责“计算和校验”两者互补而不是让 AI 直接画一张不受约束的图。4.2 Skill 是什么“Skill”在 AI Agent 生态里可以理解为一种可复用的能力包一段结构化的提示词 一组工具调用约定 输入输出格式说明。它解决的是通用 Prompt 的脆弱性问题——不需要用户每次重复解释“你应该怎么画架构图、用什么命令验证”而是把流程固化下来。在 Archify 的场景里一个 Skill 通常包含触发条件什么问题启动这个 Skill。上下文要求需要读取哪些文件比如architecture.yaml、rules.yaml。执行步骤先运行什么命令后运行什么命令。输出格式交付的是图片、结构化 JSON 还是 Markdown 报告。校验逻辑如何判断生成结果是否通过规则检查。4.3 一个 Archify Skill 配置示例下面是一个通用 UML 风格的 Skill 配置结构示例。注意不同 AI 编程工具对 Skill 的定义格式不同有的是 Markdown 文件有的是 YAML有的放在.cursor/skills或.trae/skills目录。下面示例用于展示思路# 文件路径.trae/skills/archify/SKILL.md ## 名称 Archify 架构图生成与验证 ## 描述 当用户要求生成系统架构图、微服务架构图、业务架构图或需要分析 项目组件依赖关系时使用本 Skill。 ## 触发条件 - 用户输入包含架构图、依赖关系、模块关系、架构分析、archify - 项目根目录存在 architecture.yaml 或 package.json ## 执行步骤 1. 运行 archify generate --input . --format yaml解析项目结构。 2. 读取生成的 architecture.yaml检查组件名称和依赖是否完整。 3. 运行 archify validate --config architecture.yaml --rules rules.yaml。 4. 如果校验失败根据错误信息修改 architecture.yaml然后重新校验。 5. 校验通过后运行 archify trace --target 组件名 获取追溯路径。 6. 输出架构图链接和校验报告并按 Markdown 格式展示结果。 ## 输出要求 - 必须先执行 validate再展示最终架构图。 - 如果校验失败必须列出具体错误和修改建议。 - 最终输出需要给出关键组件的追踪路径例如订单服务 - src/services/order.rs4.4 在 Trae 中使用 Archify 的思路Trae 这类 AI 编程 IDE 的核心能力是让 Agent 读取项目代码并执行操作。把 Archify 接入其中的关键有两点第一在项目工作区中预置 Skill 文件。把上面这种SKILL.md放到工具约定的 Skill 目录下让 AI 知道“架构图任务”应该走哪套流程。第二保证 Archify CLI 在 PATH 中可用。IDE 里的终端会继承系统环境变量只有系统里能直接执行archifyAgent 才能调用它。如果 IDE 自带终端但找不到命令可以在 IDE 设置里手动指定 PATH或者在 Skill 中写清楚用npx archify或pnpm dlx archify来运行。第三指定工作区和输出目录。建议在architecture.yaml中显式声明输出目录避免 AI 把架构图生成到临时目录导致后续无法追踪版本变更。需要特别提醒的是不同 AI 编程工具对 Agent 权限的限制不同。有些环境默认不允许 Agent 自由执行系统命令你需要在工具设置中放开该项目的命令执行权限并限定允许的命令白名单避免 Agent 误操作。5. 完整示例从订单服务需求到可验证架构图下面用一个简化场景演示 Archify 的核心流程订单服务模块依赖分析与架构图生成。这个示例不依赖真实项目的完整代码重点展示配置文件的写法和命令执行顺序。5.1 场景说明假设项目中有一个订单系统包含以下模块order-api对外暴露 HTTP 接口。order-service核心业务逻辑。order-repository数据库访问层。payment-client调用外部支付服务。message-queue异步消息中间件。我们要生成的是一张微服务架构图要求体现模块依赖关系并验证“不能出现循环依赖”“API 层不能直接访问数据库层”这两条规则。5.2 创建架构定义文件首先在项目根目录创建architecture.yaml。下面是一个结构化定义示例# 文件路径archify/architecture.yaml version: 1.0 project: name: order-system description: 订单系统微服务架构 components: - name: order-api type: service layer: api tags: [orders, http] metadata: owner: team-orders - name: order-service type: service layer: application tags: [orders, core] metadata: owner: team-orders - name: order-repository type: service layer: data tags: [orders, database] metadata: owner: team-orders - name: payment-client type: client layer: integration tags: [payment] metadata: owner: team-payment - name: message-queue type: middleware layer: infrastructure tags: [mq, async] metadata: owner: team-platform dependencies: - source: order-api target: order-service type: call - source: order-service target: order-repository type: call - source: order-service target: payment-client type: call - source: order-service target: message-queue type: async这个文件的要点是组件必须有明确的type和layer依赖必须写清方向和类型。这样一来AI 解析出的结果就有了语义后续验证规则才能发挥作用。5.3 创建规则文件然后创建rules.yaml# 文件路径archify/rules.yaml rules: - name: no-cycle-dependency description: 禁止出现循环依赖 type: cycle-check level: error - name: api-layer-not-call-data description: API 层不能直接调用数据层 type: layer-rule level: error from: api to: data allow: false设计这两条规则的初衷很直接架构评审中最常翻车的就是循环依赖和跨层调用。把这两条规则固化成机器可检查的约束比评审时口头提醒要可靠得多。5.4 生成架构图执行生成命令archify generate --input . --config archify/architecture.yaml --format png这一步通常会完成三件事扫描项目目录与已有的architecture.yaml做合并或对比。生成可视化架构图。生成一份结构化 JSON 描述供后续校验和追踪使用。如果项目里还没有architecture.yaml部分版本也支持让 AI 先分析代码仓库自动生成初始版本。但更稳妥的做法是先手工定义核心组件再让工具去补全细节因为完全自动抽取的依赖经常包含大量第三方库噪音。5.5 执行验证架构图生成后立刻执行验证archify validate --config archify/architecture.yaml --rules archify/rules.yaml预期效果如果依赖关系中存在order-api - order-repository这样的跨层调用会收到一条api-layer-not-call-data错误。如果存在order-service - payment-client - order-service这样的环会收到一条no-cycle-dependency错误。当 AI 介入时它可以读取这些错误信息并自动修改architecture.yaml然后再次验证形成一个“生成—校验—修正—再校验”的闭环。5.6 追踪路径校验通过后可以查看某个组件的追溯路径archify trace --component order-service --config archify/architecture.yaml输出类似于{ component: order-service, definition_file: archify/architecture.yaml, source_paths: [ src/services/order-service.ts, src/domain/order.ts ], dependencies: [ { target: order-repository, type: call, verified: true }, { target: payment-client, type: call, verified: true } ] }这里展示的就是“追路径”的核心价值每个架构图上的组件都能回溯到具体的代码路径、定义文件和依赖关系。当评审会上有人质疑“这个服务依赖是不是多余”时你可以直接给出这份追踪结果而不是凭记忆争辩。6. 运行结果与效果验证很多人在本地跑完generate和validate之后最大的困惑是“怎么判断这次生成是否成功”。下面给出几个判断标准。6.1 验证成功的标准判断一次架构图生成是否成功不能只看“图片有没有生成”还要看三个层面生成层面命令退出码为 0架构图文件输出到指定目录。校验层面validate返回passed没有 error 级别的规则冲突。追踪层面关键组件的trace能返回具体源码路径和依赖定义而不是空结果。如果这三个层面都满足这次生成的架构图才具备进入评审流程的资格。6.2 验证失败时的排查顺序如果validate报错按以下顺序排查查看错误信息里的组件名和依赖方向。先判断是真实架构问题还是配置文件写错。检查architecture.yaml里的layer和type是否匹配规则。跨层报错经常是分层字段写错导致的。检查rules.yaml的from和to是否写反。一条规则写反会导致所有依赖都校验失败。确认是否读取了最新配置。有的版本有缓存修改配置文件后需要先清缓存或使用--no-cache。6.3 架构图与代码的漂移验证这是 Archify 类工具更进阶的价值代码变更后重新解析可以发现架构漂移。假设有同事在order-service里直接引入了order-repository的数据库连接池跨层调用但架构图还没有更新。此时重新运行archify generate --input . --config archify/architecture.yaml --format png archify validate --config archify/architecture.yaml --rules archify/rules.yaml新生成的架构图会反映出新增的依赖边并且规则引擎会立即提示跨层违规。这个流程让架构图不再是“画完就过期”的静态文件而是能被动反映项目真实结构的“活文档”。7. 常见问题与排查方法这里整理 Archify 使用过程中频率较高的几个问题供大家遇到问题时直接对照排查。问题现象可能原因排查方式解决方案生成的架构图缺少某些服务节点项目代码中服务的启动入口或部署文件未被扫描到检查扫描范围配置确认--input指向的是仓库根目录在architecture.yaml中补充缺失组件或调整文件扫描规则依赖关系与代码实际不一致AI 根据常见项目结构推测依赖未精确解析配置文件查看生成的 JSON 描述中该依赖边的来源修正architecture.yaml中的依赖声明再执行validate校验提示跨层调用但实际没有layer字段或from/to规则配置错误查看rules.yaml中的层级规则调整组件分层或规则方向在 Trae/Cursor 中无法调用 Archify 命令CLI 不在 IDE 的 PATH 环境中在 IDE 终端手动执行archify --version验证在 IDE 设置中补充 PATH或使用npx archify方式调用Archify Skill 未生效Skill 文件路径不符合工具约定查看 AI 工具的 Skill 目录要求将 SKILL.md 放到正确目录并检查文件名大小写大型仓库扫描慢依赖分析和代码解析耗时较长查看日志确认卡在哪个阶段先只扫描核心模块目录后续再扩展范围必要时排除第三方依赖目录重新生成后历史版本无法对比架构定义文件未纳入版本控制查看 git 状态确认architecture.yaml是否入库将archify目录纳入 Git用archify diff对比两次结果重点是遇到问题先看日志再看配置。Archify 的问题通常不是工具本身不可用而是输入的项目信息不够完整或者规则文件与项目实际结构不匹配。8. 最佳实践与工程建议工具本身只提供能力真正决定效果的是使用方式。下面几条建议是从工程化角度总结的适合团队推动落地时参考。8.1 把架构定义文件纳入版本控制architecture.yaml和rules.yaml应该被当成一等公民和代码一起提交到 Git。理由很简单架构图的价值在于“它是当前系统状态的快照”快照必须和代码版本对齐。这样每次代码评审、版本发布、架构变更都可以通过archify diff看到架构层面的差异而不是靠人工回忆“之前是怎么画的”。8.2 先定边界再交给 AIAI 生成的架构图再快也需要人先定义“项目的边界是什么”。边界包括哪些目录属于核心业务模块哪些是第三方依赖哪些组件需要纳入受控范围。在architecture.yaml中显式声明这些边界AI 才有据可依生成的图才不会把node_modules里几百个包全部画成节点。8.3 命名规范与分层规范同步落地如果团队的组件命名和分层本来就混乱工具能自动校验错误但无法替你决定“什么是正确的分层”。建议在引入 Archify 的同时同步制定两项规范组件命名规范比如api、service、repository、client、middleware后缀要与architecture.yaml中的type保持一致。分层边界规范明确哪些层之间可以互相调用哪些是硬禁止。把这些规范写成rules.yaml后每次校验都是在执行团队约定。8.4 把验证接入 CI/CD比本地执行更可靠的方式是把校验命令集成到持续集成流水线中。每次 MR 或 push 时自动执行archify validate --config archify/architecture.yaml --rules archify/rules.yaml如果校验失败流水线直接红灯提示开发者“你的变更破坏了架构规则”。这一步的价值是让架构治理从“评审时口头约束”变成“提交时自动拦截”。需要注意CI 环境需要单独安装 Archify CLI并保证访问仓库代码的权限是只读的避免流水线误改文件。8.5 安全边界与敏感信息处理架构描述文件里很容易混入敏感信息比如服务地址、数据库名称、内部域名。使用 Archify 时要注意不要在生产项目里公开架构图中的内部服务名和 IP。如果团队使用云端版本先确认项目数据是否会被发送到第三方模型服务。对安全敏感的项目优先使用本地模式确保代码内容和架构描述不出内网。在 Git 提交前检查architecture.yaml中是否包含密钥、token、内网地址等敏感字段。另一个容易忽略的点是工具如果支持云渲染架构图本身也可能成为信息泄露渠道。更稳妥的做法是在本地完成生成和渲染只把结果给别人看。8.6 从“画一张图”走向“架构治理”Archify 这类工具长期演进的方向是把架构图从“文档”变成“治理工具”。团队落地时可以分三个阶段推进第一阶段用 Archify 生成当前系统架构图先建立“可追踪”的习惯确保图上的每个节点都能回溯到代码。第二阶段把核心规则固化为rules.yaml在 CI 中加入校验初步实现“可验证”。第三阶段把架构变更纳入评审流程。每次重大改动先跑一次archify diff再看架构图的变化而不是在代码合并之后追悔。这套流程会让团队形成一种新的协作方式架构评审会不再看 PPT而是直接看结构和规则输出。这个转变比工具本身更有价值。9. 总结与后续学习方向回到开头的判断Archify 值得被关注不是因为它能“用 AI 画架构图”而是因为它把两个以前依赖人肉自觉的概念变成了可执行机制——可验证让架构图不再只是好看的表达可追踪让架构图不再是没有来源的空壳。这篇文章围绕 Archify 讲了几个关键点架构图的真正痛点不是画不出来而是无法验证、无法追踪、无法同步。Archify 的核心能力是“生成 校验 追踪”而不仅仅是 AI 渲染。通过architecture.yaml定义组件和依赖通过rules.yaml固化团队约束再用 CLI 在本地和 CI 中执行校验可以让架构图成为工程资产。接入 Trae 等 AI 编程工具时Skill 文件是关键它让 AI 知道“执行什么命令、按什么顺序、输出什么格式”而不是自由发挥。生产环境要格外注意敏感信息、权限控制和版本管理。如果你接下来想进一步实践建议按这个顺序展开先用archify init在现有项目里生成一份基础架构描述熟悉 CLI 命令。挑一个你熟悉的模块手工完善architecture.yaml加入依赖方向。编写 2 到 3 条核心规则跑通validate观察校验结果。再尝试把 Archify 作为 Skill 注册到你的 AI 编程工具里让 Agent 帮你自动完成一轮“生成—校验—修正”的流程。后续可以深入的方向包括多仓库架构治理、K8s 部署架构的自动解析、事件驱动架构与异步消息链路的追踪、以及把架构校验结果与内部效能平台打通。最后说一句关于 AI 工具的提醒不要盲目信任 AI 生成的架构图一定要让输出经过规则校验。真正让你放心的不是模型的聪明程度而是你愿意为它建立的验证和约束体系。架构图的价值从来不在画布上而在它能否经得起一次真实的代码级追问。