搞软件这行画架构图这件事我算是折腾过很多轮了。早些年用Visio一个框一个框拖后来换draw.io再后来用PlantUML写代码生成图每换一次工具就安慰自己“这次终于省心了”。结果呢架构一调整图就得跟着改改着改着就懒得改了最后图成了摆设新人看架构全靠问人。所以第一次看到GitHub上archify这个项目我的第一反应是这思路有点对——让AI代理直接读代码库自动生成一张能交互的架构图而不是给你一堆要自己渲染的Mermaid文本。这篇文章就聊聊archify到底解决了什么问题、它是怎么设计的、实操起来有哪些坑以及我实测下来觉得它真正值钱的地方在哪。先说清楚archify是什么。它不是一个画图软件也不是又一个Diagram-as-Code框架而是给AI代理准备的一个“技能模块”。所谓技能模块就是给代理配好的一套指令、脚本和输出规范让代理拿到你的代码仓库之后能自动完成从代码解析、依赖分析到生成可交互架构图的全流程。适合谁看如果你手里有维护起来很费劲的老系统或者团队每次画架构图都要开会拉齐半天又或者你已经在用Claude、GPT这类工具辅助写代码那archify这类的思路应该能给你不少启发。1. 为什么架构图这事值得交给AI代理来做1.1 传统画图流程的“死结”图永远慢代码半拍先说个扎心的事实绝大多数项目的架构图在诞生的那一刻就已经开始过期了。原因很简单画图是个独立于编码的额外工作你得先理解系统再决定画哪些层、哪些模块、哪些依赖然后手动维护图形元素的位置和连线。代码一天提交十几次架构图一个月更新一次就算勤快了。用PlantUML这类DSL工具会好一点至少图是用文本描述的能进Git。但你仍然得手动维护模块划分、依赖关系改动一大还是容易乱。draw.io这种拖拽工具就更不用说了多人协作时经常出现“两个人同时改一张图最后互相覆盖”的经典事故。我见过不少团队最后干脆放弃维护架构图靠口头传承“这个服务大概是这样你自己看代码吧”。1.2 代理画图的本质把“读代码”和“画图”都自动化AI代理和传统脚本最大的区别在于它能做“阅读理解”。传统方式想自动生成架构图得靠静态分析工具比如依赖扫描但这类工具生成的往往是一张几千个节点的巨型图根本没有抽象层级人看了等于没看。而AI代理可以分步骤干活先扫一遍目录结构、读关键配置文件、看核心服务的入口代码然后像一个有经验的工程师一样归纳出“这个系统大概有用户服务、订单服务、网关这几层”再提炼依赖关系最后生成一张人能看懂的图。archify这种“技能模块”的形式相当于把上面这整套思路固化成了可复用的代理流程。你不需要每次重新跟代理解释“帮我看看项目结构然后画图”而是直接调用技能代理就知道该按什么顺序读取、怎么分析、输出什么格式的图。这就像把老师傅的经验写成了一份标准作业指导书谁拿起来都能干活。1.3 为什么强调“可交互”而不是一张静态图片静态架构图最大的问题是信息密度没法按需展开。一张图既要能总览全局又要能看清某个服务内部的细节这本身就是矛盾的。交互式架构图能解决这个矛盾总览时只看顶层模块点进去能看到子模块再点能看到具体类或接口的依赖关系。archify着力做可交互输出我觉得是踩对了点。它生成的不是简单导出PNG而是像一个独立的网页应用能缩放、能拖拽、能点击节点查看详情。这一点在评审会上特别有用可以直接投屏点着节点讲“这个服务依赖那三个下游”比指着一张静态图比划半天清楚多了。2. archify 的核心设计拆解2.1 “技能模块”到底是个什么形态如果你用过Claude的Agent Skills或者看过一些开源的skill仓库就会发现这类模块通常就是一个目录里面放一个说明文件加若干脚本。archify大概率也是这个套路一个SKILL.md或者类似的说明书告诉代理“你的任务是什么、按什么步骤做、输出什么格式”再配几个辅助脚本比如依赖提取器、HTML渲染模板。这种设计的好处是极度透明。你随时能打开技能定义文件看它到底让代理做了什么而不是把一个不透明的黑盒丢给代理“自动处理”。而且技能模块不绑定特定代理只要是能读入指令的代理工具理论上都能用。这就让项目有了很强的可移植性——今天你用Claude明天换Gemini只要技能定义是通用的就能继续用。2.2 靠什么读懂代码库静态分析与代理理解的结合要把代码库变成有结构的架构图光靠AI“感觉”是不行的必须有确定性的分析打底。我猜archify的流程里包含一个静态分析步骤先扫描项目里的模块边界提取文件和目录的依赖关系搞清楚哪些代码属于同一个业务域。这一步可以用现成的工具链也可以靠脚本简单解析关键是先拿到一份“机器能看懂”的依赖清单。拿到清单之后才轮到AI代理出场。代理根据这份清单结合它读到的README、配置文件、API定义给每个代码模块赋予业务语义——比如“这一堆文件是订单域那部分是支付回调”。这个环节里“语义理解”和“静态事实”互相校准不容易出现AI凭想象胡说的情况。等语义归并完成代理再把最终结果转换成可交互图的节点和边。整个过程有点像一个项目组里先让脚本统计代码依赖再让资深的工程师归类整理。2.3 可交互图的输出格式没有标准答案但有明智选择输出端的选型也很关键。常见方案有这么几种输出方案优点缺点适用场景Interactive Mermaid / Mermaid Live Editor生态成熟文本易读交互能力相对较弱快速预览、嵌入文档D3.js / ECharts / Cytoscape.js 等前端可视化库交互丰富、支持按需展开模板代码量较大需要深度交互的应用React Flow / Node-RED 风格的拖拽界面观感现代、操作友好依赖前端工程化能力团队内部工具、评审演示静态图片 点击跳转链接实现最简单“交互”程度有限轻量级场景、快速出图我在实操中倾向于认为真正好用的可交互架构图生成器会在后端输出一份结构化的JSON或GraphML数据前端只负责渲染。这样无论你想换哪个可视化库都只需要换一个渲染模板数据层面完全不用动。archify如果走的是这个路线那它将来兼容新前端框架的成本就会很低。3. 实操过程用 archify 生成一张可交互架构图接下来这部分是我实际动手过程中的记录和心得环境是macOS代理工具用的Claude Code其他支持技能模块的工具同理。整个过程分四步准备技能文件、配置代理、跑分析、看结果。我带大家一步步过。3.1 环境准备拉取技能并安装到代理目录首先从GitHub上把archify仓库拉下来。如果你平时已经把代码库放在本地这一步解压或者git clone到某个工作目录即可。git clone https://github.com/你的用户名/archify.git cd archify把技能模块复制到你的代理技能目录里。以Claude Code为例一般是.claude/skills/或~/.claude/skills/mkdir -p ~/.claude/skills/archify cp -r archify/* ~/.claude/skills/archify/这里有一个比较关键的细节技能目录的名称一定要跟SKILL.md里声明的name保持一致否则代理可能识别不到这个技能。我就吃过一次亏把目录名改成了“archify_backup”结果代理怎么都调不出技能排查很久才发现是目录名的锅。3.2 配置代理确认技能被正确加载装好之后启动你的代理工具直接问一句“你现在会哪些技能”正常情况下代理应该会列出archify。如果没有先检查技能目录位置对不对再看代理的配置里有没有开启自定义技能加载的开关。我建议第一次跑的时候用一个结构清晰的中小型项目来试别一上来就拿几十个微服务的仓库开刀。先拿一个单体应用、两三个模块、几十个文件的项目跑通全流程确认技能能正常输出图再逐步增加复杂度。跟学开车一个道理先在人少的路段练手别直接上高架。3.3 运行技能给你要分析的仓库路径技能加载好了之后用法很简单直接把仓库路径交给代理/archify /path/to/your/project如果你的代理支持斜杠命令这大概是最直观的调用方式。不支持斜杠命令的话就在对话里自然描述“用archify技能分析一下当前项目生成架构图”。接下来代理会干活你可以观察到它的执行过程先扫描目录结构再看依赖清单然后归纳模块最后生成可视化文件。整个过程耗时取决于项目大小小项目一两分钟大项目可能得等上好几分钟。这里不要催宁愿让它一次分析完也别中途打断重来打断容易导致上下文丢失后半段输出质量反而下降。3.4 解读输出可交互图到底长什么样跑完之后工作目录下会出现生成的HTML文件、JSON数据文件和一份简单报告。我建议优先打开HTML文件直接在浏览器里看交互效果。你会看到类似下面这种结果顶层是一张系统全貌图每个模块是一个大的节点节点之间用线连接表示依赖。双击某个模块节点可以展开它内部的子模块相当于从系统级下钻到服务级。点击某个具体的服务节点侧边栏会显示这个服务的描述、所属域、依赖的下游清单。支持拖拽节点微调布局缩放视图看细节还能搜索节点名快速定位。我第一次看到生成结果时说实话有点意外虽然谈不上多惊艳但信息组织得确实像那么回事——顶层归纳没有太碎下钻的粒度又足够细用作技术方案评审的辅助材料完全够格。4. 常见问题与排查技巧实录再顺手的工具落地过程中也免不了踩坑。这里集中整理几个我在使用中遇到的高频问题以及对应的排查思路权当一份速查表。如果你动手跑的时候撞上类似情况能少走点弯路。4.1 代理生成的依赖方向不对这个坑我遇到过不止一次。有些服务A调用B但生成的图里箭头方向画反了从B指到了A。原因通常是代理在分析时把“依赖声明”和“实际调用”的先后关系搞混了也可能是导入的依赖清单本身方向就反了。排查思路分两步第一步回到静态分析阶段生成的原始依赖数据里确认代码里究竟是哪个方向。第二步检查技能定义里对“边的方向”有没有明确说明比如“source指向consumer被依赖方作为target”。如果没有建议在技能说明里补上方向定义把“消费者指向提供者”这句话写明确。这事关后面所有图的质量值得花几分钟改一下技能定义文件。4.2 大项目分析超时或者内存爆炸项目文件太多时代理容易出现分析超时或者直接把内存吃满最后进程崩掉。这个问题在大型monorepo里尤其常见几万个文件一次性扫再聪明的代理也扛不住。我的建议是分层处理先让archify跑顶层目录和核心配置文件生成粗粒度架构图确认整体结构没问题之后再挑重点模块逐个跑子图最后手动把子图链接到顶层图的节点上。你可以给技能配置一个“排除列表”把build目录、node_modules、vendor等无关代码全部排除掉分析量能直接降一半以上。另外给代理一个明确的线索“只需要关注src和lib目录”也能有效减少无意义的扫描。4.3 图太“碎”了全是底层类看不到架构代理的默认倾向是把看到的东西都画出来结果就是一张图上千个节点别说看了缩放都费劲。这其实不是bug是上下文里的业务约束不够。解决办法是给技能加一条“抽象层级阈值”比如低于多少个文件的组件不单独出模块节点而是归并到上一级又比如只在第三层及以上才展示类和接口往下层级的细节全部折叠起来只有点击时再展开。我习惯在技能说明里写清楚“优先用业务语义聚合文件技术细节收纳到内部即可图上只保留架构决策级别的节点。”加上这句话之后生成的图质量会有肉眼可见的提升。4.4 代理无法理解某些超大的单体仓库还有一种比较棘手的情况项目代码写得很烂模块之间纠缠不清目录结构混乱注释几乎没有。这种情况下代理生成出来的图会显得很“勉强”节点划分东一块西一块依赖关系也理不顺。这时候别硬撑先手动给代理补一点上下文。比如在技能调用时额外告诉它“这三个目录实际上属于同一个订单域那边两个是通用的基础设施”相当于先给人脑一个骨架再让代理在这骨架上去细化。实战下来这种“人工先粗划分代理再细分析”的配合方式比纯让代理硬看代码要稳定得多。下面把上面几个高频问题汇总成一张速查表方便你对照排查现象可能原因推荐处理方式依赖箭头方向反了依赖清单方向定义不清在技能说明中明确“消费者→提供者”方向分析中途卡死或超时项目文件过多或包含无用目录配置排除列表限定分析范围分层出图图节点过碎、像类图不像架构图缺少抽象层级约束增加聚合阈值业务归类优先技术细节折叠混乱单体仓库无法归纳上下文信息不足代理难做划分人工先粗分业务域再让代理细化依赖关系技能加载不出来目录名与技能名不一致检查技能目录命名确保与SKILL.md声明一致5. 从单一工具看AI辅助开发的演进方向聊完实操再往大了说两句。archify这一类项目的价值其实不完全在“画架构图”这个动作本身而在于它在尝试把“理解一个陌生系统”这件事模块化、流程化。以前看一个不熟悉的代码库再资深的工程师也得从README看到配置、从入口跟到调用链反复翻找才能形成全局认知。现在代理加技能模块可以把这个过程压缩到几分钟且结果能沉淀成可交互的结构化文档。代理对项目的理解怎么沉淀是现在很多团队在探索的问题。archify给出的答案是建一套标准化的“技能”机制。有了这套机制“分析代码库”就不只是线上聊天的临时能力而变成了可以反复调用、持续改进的资产。你对技能定义里的提示词做一次优化之后所有用它生成的架构图都能受益。这跟给团队沉淀一份好的工程规范是同一个逻辑只不过现在规范的执行方变成了AI。另外生成的这份结构化数据也不该只当一次性图表用。我尝试过把archify输出的JSON再喂给其他工具做服务依赖巡检比如定期比对“图上画的依赖”和“代码里实际的依赖”是否一致。这么做之后架构图从一个静态的结果变成了有生命力的监控对象技术债哪里正在积累一对比就能看出来。如果你团队里有治理微服务依赖的需求强烈建议试试这个方向。还有一个小技巧把archify生成的HTML丢到团队内部的文档系统里比如Confluence、语雀这些支持iframe嵌入的平台评评审、带新人、做技术分享都能直接用。新同事入职看架构与其发一份点不动的PPT不如发一个能放大缩小、点击下钻的交互图理解速度完全是两个级别。我个人在实际使用中最大的体会是别指望AI一次就画出完美的架构图也别因为第一次输出不够满意就放弃。更务实的做法是把archify当成一个“制图助手”你先通过技能定义和人工提示给它“揉”出正确骨架再让它不断细化修正。磨合到第三、四次你自己都会摸出一套最适合当前代码库的配置参数这时候AI画图的速度和准确度是纯手工画图完全没法比的。最后再分享一个后续可以扩展的方向如果项目里已经有代码规范、架构决策记录ADR、甚至部署拓扑数据尽量想办法把它们作为额外上下文喂给技能模块。代理掌握的信息越接近一个“真正了解系统的老员工”它画出来的图就越接近你心里那种“怎么看都舒服”的状态。把AI当画图工具有限把它当懂业务的协作伙伴才是这类技能模块真正开始发力的地方。