让AI代理读懂代码库：archify自动生成可交互架构图

搞软件这行，画架构图这件事我算是折腾过很多轮了。早些年用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 可交互图的输出格式：没有标准答案，但有明智选择

输出端的选型也很关键。常见方案有这么几种：

我在实操中倾向于认为，真正好用的可交互架构图生成器，会在后端输出一份结构化的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 代理无法理解某些超大的单体仓库

还有一种比较棘手的情况：项目代码写得很烂，模块之间纠缠不清，目录结构混乱，注释几乎没有。这种情况下，代理生成出来的图会显得很“勉强”，节点划分东一块西一块，依赖关系也理不顺。

这时候别硬撑，先手动给代理补一点上下文。比如在技能调用时额外告诉它“这三个目录实际上属于同一个订单域，那边两个是通用的基础设施”，相当于先给人脑一个骨架，再让代理在这骨架上去细化。实战下来，这种“人工先粗划分+代理再细分析”的配合方式，比纯让代理硬看代码要稳定得多。

下面把上面几个高频问题汇总成一张速查表，方便你对照排查：

5. 从单一工具看AI辅助开发的演进方向

聊完实操，再往大了说两句。archify这一类项目的价值，其实不完全在“画架构图”这个动作本身，而在于它在尝试把“理解一个陌生系统”这件事模块化、流程化。以前看一个不熟悉的代码库，再资深的工程师也得从README看到配置、从入口跟到调用链，反复翻找才能形成全局认知。现在代理加技能模块，可以把这个过程压缩到几分钟，且结果能沉淀成可交互的结构化文档。

代理对项目的理解怎么沉淀，是现在很多团队在探索的问题。archify给出的答案是建一套标准化的“技能”机制。有了这套机制，“分析代码库”就不只是线上聊天的临时能力，而变成了可以反复调用、持续改进的资产。你对技能定义里的提示词做一次优化，之后所有用它生成的架构图都能受益。这跟给团队沉淀一份好的工程规范是同一个逻辑，只不过现在规范的执行方变成了AI。

另外，生成的这份结构化数据，也不该只当一次性图表用。我尝试过把archify输出的JSON再喂给其他工具做服务依赖巡检，比如定期比对“图上画的依赖”和“代码里实际的依赖”是否一致。这么做之后，架构图从一个静态的结果变成了有生命力的监控对象，技术债哪里正在积累，一对比就能看出来。如果你团队里有治理微服务依赖的需求，强烈建议试试这个方向。

还有一个小技巧：把archify生成的HTML丢到团队内部的文档系统里，比如Confluence、语雀这些支持iframe嵌入的平台，评评审、带新人、做技术分享都能直接用。新同事入职看架构，与其发一份点不动的PPT，不如发一个能放大缩小、点击下钻的交互图，理解速度完全是两个级别。

我个人在实际使用中最大的体会是：别指望AI一次就画出完美的架构图，也别因为第一次输出不够满意就放弃。更务实的做法是，把archify当成一个“制图助手”，你先通过技能定义和人工提示给它“揉”出正确骨架，再让它不断细化修正。磨合到第三、四次，你自己都会摸出一套最适合当前代码库的配置参数，这时候AI画图的速度和准确度，是纯手工画图完全没法比的。

最后再分享一个后续可以扩展的方向：如果项目里已经有代码规范、架构决策记录（ADR）、甚至部署拓扑数据，尽量想办法把它们作为额外上下文喂给技能模块。代理掌握的信息越接近一个“真正了解系统的老员工”，它画出来的图就越接近你心里那种“怎么看都舒服”的状态。把AI当画图工具有限，把它当懂业务的协作伙伴，才是这类技能模块真正开始发力的地方。