接手过一个没人维护的老项目吗？十几个服务，几千个文件，模块之间的调用关系全靠猜，画个架构图得翻半天代码。如果再叠一层buff——这些代码还是AI编码代理产出的，那你面对的就是一大片“能跑但没人说得清”的逻辑黑盒。我之前用编码代理提PR提得飞快，代码量猛涨，可leader让我讲一下系统现在长什么样的时候，我当场卡壳。这就是Archify出现的意义：它让编码代理在理解代码的同时，直接输出可校验的架构图，而不是再靠人去读源码、画拓扑。
先给没接触过的朋友一句话总结：Archify是一个面向编码代理（coding agent）的架构分析工具，核心能力是把代码库的现状扫描成结构化架构图，并且支持规则校验。它跟“你说需求AI画张架构示意”完全不是一回事，图的每一个节点、每一条依赖边，都能对应到真实代码。适合谁用？天天跟编码代理打交道的开发者、要接手陌生仓库的人、以及想在代码评审里加一道架构卡点的团队。这篇文章我会从原理讲到实操，最后把踩过的坑一并倒出来。
1. 先把这个工具放到坐标上
1.1 编码代理时代，为什么“看懂代码”比“写出代码”更要命
以前说“读代码比写代码难”，是说维护老业务、理清历史债务。现在编码代理把“写代码”的门槛打下来了，结果就是“产出代码”和“理解代码”之间的剪刀差变得极其夸张。你可以让代理一小时干完过去一天的活，但代理不会主动告诉你它把这堆模块粘成了什么形状。
我见过不少团队，AI辅助开发占比越高，代码架构腐化越快。不是代理质量不行，而是没有人对“系统长什么样”这件事做实时跟进。传统做法是写架构文档、画Visio图，可代码三天一变，文档两周没更新，图就变成了博物馆展品。大家心里都清楚：图和代码一旦脱节，图就只配当PPT素材，不配当决策依据。
这个痛点在编码代理进入工作流之后被放大了。以前一个人写的代码量有限，架构漂移还能靠代码评审拦住；现在代理一天生成几百个文件的变更，reviewer连逐行看都看不过来，更别说脑内维持一张动态的系统拓扑图。Archify的切入点，就是把“维护架构图”这件事从人的负担变成工具的输出，而且确保它始终跟代码同步。
1.2 Archify到底解决了什么问题
一句话：它把架构图从“画出来的”变成了“算出来的”。Archify扫描代码库，通过静态分析提取组件、依赖、分层关系，再渲染成架构图。因为数据来源是真实代码，图里的任何信息都可以溯源回文件、类、接口调用。这不是AI看图说话，而是工程上的事实输出。
同时它提供一套校验机制。你可以定义架构规则，比如“controller层不能直接调用repository层”“不允许出现循环依赖”“payment模块不能被order模块反向依赖”。Archify会持续比对当前代码和规则，有违反就报出来。这就让架构图具备了“可执行”的属性，不只是给人看，还能当成自动化检查的一部分，挂在CI里或者编码代理工作流里当护栏。
我自己的体会：它本质上是把“架构治理”这个原本需要资深架构师人肉盯的事，下沉成了开发者日常就能跑的一条命令。不用等架构评审才发现依赖乱了，写完代码自己跑一遍Archify，红不红一眼就知道。对编码代理产出的代码，这种即时约束尤其重要。
1.3 七周七倍的增长，说明市场在为什么买单
“七周涨七倍多”这个数据，我第一反应是怀疑，仔细想想又觉得合理。编码代理工具本身已经够卷了，大家拼的是谁家代理能写更多代码；但写得多不等于写得好，也不等于系统可维护。Archify踩中的恰恰是编码代理浪潮最容易被忽略的副作用——代码量爆发式增长之后，架构理解和治理跟不上。说白了，它赚的是“AI带来效率，也带来混乱”这个矛盾的钱。
从产品形态看，Archify不是又造了一个IDE，而是以“skill”的形式寄生在现有编码代理生态里，用户不用切换工作流，在Trae这类工具里直接就能用。这种“轻接入、重价值”的打法，特别适合当下开发者对新增工具极其不耐烦的心态。我预测这类架构治理能力很快就会变成编码代理的标配，Archify只是在正确的时间点把这件事做成了可校验的闭环。
2. 原理拆解：可校验架构图是怎么来的
2.1 核心思路：从“AI画图”到“代码事实推导”
如果你用通用AI画架构图，流程通常是：把代码喂进去，让大模型总结模块划分、画依赖图。问题在于大模型是在“猜”，它根据文件名、目录名、import语句的上下文去推断某个目录是干什么的。猜得八九不离十的时候还行，一旦代码命名不规范、目录结构混乱，AI就会一本正经地画出错误架构。
Archify的思路完全不同。它的核心是静态分析引擎，不是大模型。代码先被解析成AST（抽象语法树），然后提取符号引用、模块依赖、接口调用关系，最后用图数据结构把这些关系组织起来。大模型在整个流程中可能只负责“解释”“生成报告”“跟用户对话”，但图的底层数据不是模型脑补的，是代码里真实存在的依赖关系。
这两者的差别可以用一句话概括：AI画图是“根据经验猜系统长什么样”，Archify是“根据代码算出系统长什么样”。猜的东西没法验证，算出来的东西可以。这就是“可校验”这三个字的底气。
2.2 “可校验”的三个层次：组件、依赖、边界
我理解的可校验，拆开看有三个层次。
第一个层次是组件级校验。Archify会把代码库划分成若干组件，这个划分不是随便画画，而是基于命名空间、目录边界、构建模块等规则生成。比如一个Maven多模块项目，每个module天然就是一个组件；对于单体仓库，则按照顶层目录或者package结构自动聚类。用户可以查看每个组件包含哪些文件，也可以手动调整组件的归属规则，保证图和代码的映射完全明确。
第二个层次是依赖级校验。组件之间的依赖关系从import、调用、消息传递等真实链路提取出来，方向、强度都有据可查。这一层最有价值的是能跑依赖分析：谁依赖了不该依赖的东西，哪里出现了环，哪里存在过度耦合，全部可以被检测出来。
第三个层次是规则级校验，也就是前面说的自定义架构规则。你可以用Archify支持的规则语法，把“业务层不依赖基础设施层”这种团队规范变成可执行断言。从此架构评审不用拍脑袋，给结论前先跑一遍规则，红就是红，绿就是绿。这三个层次叠加起来，架构图才真正配得上“可校验”这三个字。
2.3 一次架构分析背后实际发生的过程
我以一次在本地仓库跑Archify的完整经历为例，拆解一下后台到底发生了什么。
第一步是建立索引。Archify先扫描项目，识别构建配置（pom.xml、package.json、go.mod这类）、源码目录、以及测试和构建产物目录。默认会忽略node_modules、target、dist这类“噪音”目录，避免依赖关系里混入第三方库。这一步通常几秒到几十秒，取决于仓库大小。
第二步是解析依赖图。它会读取每个源码文件的import/require/include语句，再结合构建配置，把同模块内的引用归并成组件内依赖，把跨模块的引用标注成组件间依赖。注意这里不是简单的字符串匹配，走的是真正的符号解析，能区分“同一个类名的不同命名空间”“动态导入”“反射调用”这类复杂情况，这一步直接决定依赖图准不准。
第三步是架构建模。Archify把项目聚合成组件级模型，按约定检测层与层的关系。比如在Spring项目里，controller/service/repository的依赖方向可以被自动识别出来，生成架构图的同时，也生成一份“组件清单”，里面标注了每个组件的物理路径、对外暴露的接口、依赖的下游组件。
第四步才是渲染和校验。架构图渲染成可视化格式，同时把规则跑一遍，输出违规项列表、违规位置的源码锚点。整个流程下来，我拿到的不只是“一张图”，还有一份可以点开追踪到具体代码行的检查报告。
提示：Archify在建模阶段会把“测试代码”和“主代码”分开处理。别把测试代码算进业务依赖图里，否则你会在图中看到业务组件依赖了一堆JUnit工具类，那会严重影响判断。
3. 实操上手：Archify怎么装、怎么配、怎么用
3.1 第一步：安装CLI与项目初始化
Archify的官方分发方式主要是CLI工具，支持MacOS、Linux、Windows。安装没有特别复杂的依赖，唯一要注意的是本机得有对应语言的运行时，比如分析Java项目需要JVM，分析Node项目需要Node.js环境。装好CLI之后，在项目根目录执行初始化命令，它会生成一份配置文件，我这里是.archify/config.yml：
# .archify/config.yml project: name: order-service language: java buildTool: maven analysis: scanDirs: - src/main excludeDirs: - src/test detectCycles: true rules: - name: "controller-not-to-repository" description: "Controller 不允许直接依赖 Repository" from: "*Controller" to: "*Repository" action: error - name: "no-cross-boundary" description: "order 模块不得反向依赖 payment" from: "order.*" to: "payment.*" action: errorscanDirs和excludeDirs是第一优先级要调对的参数。我第一次用的时候没排除测试目录，结果图里全是测试代码的业务依赖，乱到没法看。detectCycles打开循环依赖检测，生成报告时会单独标出一块“环状依赖”区，这个功能在高耦合遗留系统里简直是指路明灯。
生成配置文件后，先手动跑一次完整分析，确认命令能正常结束，再接入其他工作流。这一步别跳，先验证基础链路是通的，后面出问题才分得清是配置问题还是工具问题。
3.2 第二步：把archify skill接入Trae
热搜里有人问“archify怎么用在trae”，这应该是大家最关心的部分。Archify目前的接入方式是以“skill”的形式暴露给编码代理，让代理在对话过程中按需调用Archify CLI。这里说的skill，可以粗浅理解成给编码代理装的“技能包”，里面写明了什么任务该调用什么命令、怎么解读命令输出。
我以Trae为例讲一下接入步骤。Trae支持skill配置，先确认本机Archify CLI已经安装好了，然后找到Trae的skill安装目录。如果你是通过market安装的，直接在技能市场搜Archify装就行；如果手动安装，就把Archify的skill描述文件放进Trae对应用户目录下的skills文件夹。装完之后重启Trae，在会话里提“使用archify分析当前项目”，编码代理会识别这个意图，自动调用Archify CLI，并把输出的架构图、规则报告整理后返回给你。
这里有个实操细节：不要只下一句“画个架构图”就完事。编码代理虽然聪明，但它并不知道你关注的是层级依赖还是模块边界、要不要排除测试、规则配置在哪。我建议在Prompt里把本次分析的意图讲清楚，例如“用archify分析当前仓库，只看主代码，把模块间的循环依赖列出来，并按严重程度排序”。给代理的任务越具体，它调用CLI时的参数就越精准，返回的报告也越贴合你的需求。
3.3 第三步：三种高频场景及Prompt模板
我实际用下来的场景主要三种，分别贴上具体Prompt，方便直接抄作业。
场景一：接手陌生仓库，快速搞清楚系统长什么样。
请使用 archify 分析当前项目。 要求： 1. 输出组件级架构图，标注每个组件的核心职责。 2. 列出组件之间的外部依赖，重点标出跨模块调用的方向。 3. 检测是否存在循环依赖，如果有，列出环上涉及的模块。 4. 给出整个仓库的“健康摘要”：模块数、依赖总数、环的数量。 请把结论整理成简洁的报告。这个Prompt适合入职第一天拉完代码就跑，十分钟内能对系统结构有概念，比漫无目的地浏览源码效率高得多。
场景二：编码代理要动一个大模块之前，先做影响面分析。
准备修改 order 模块下的订单状态机逻辑。 先运行 archify，重点分析以下信息： 1. order 模块依赖了哪些外部组件？ 2. 哪些上游组件反向依赖了 order 模块？ 3. 如果修改 order 模块的内部接口，影响面会涉及哪些模块？ 请给出受影响模块清单，并按依赖强度排序。加了这步之后，编码代理再改代码就不会是“盲改”了。它能明确知道牵一发动全身的地方在哪，改完还能自觉跑一遍Archify确认没破坏依赖方向。
场景三：代码评审阶段做架构级检查。
在本次变更中运行 archify，对比变更前后的架构差异。 重点检查： 1. 是否有新增的跨模块反向依赖。 2. 是否有对被禁止依赖规则的违反。 3. 是否出现了新的循环依赖。 把违规项按“error / warning”分类，并指出对应的源码位置。这个习惯养成后，架构问题会从“评审时靠人肉发现”变成“代理提交前自动发现”，从源头把问题挡住。
4. 常见问题与避坑指南
4.1 架构图和代码不一致，别急着怪工具
很多人第一次跑完Archify，对照代码一看，说“这图不对啊，这个模块明明没有依赖那个模块”。我遇到过几次，排查下来大部分都不是工具的问题，而是索引过期或者配置范围不对。
先说索引问题。Archify在本地会缓存分析结果，如果代码发生了大改动但缓存没刷新，出来的图就是旧状态。遇到图跟代码对不上，第一件事不要改规则，先在CLI里强制重新分析，很多“不一致”其实是缓存问题。
再说配置范围。还有一种情况是默认扫描范围比你预期的宽或者窄。比如手工创建的目录没被纳入扫描，或者某个古老目录被错误当成主代码。这时需要回到配置文件，在scanDirs和excludeDirs里手动校准，把边界划清楚。图只是分析引擎的输出，分析引擎喂了什么数据，图就长什么样，这句话值得记住。
4.2 monorepo太大跑不动怎么办
体量大的仓库第一次跑Archify，容易卡在依赖解析阶段。我踩过最大的坑是把整个monorepo丢进去扫，结果十几分钟没跑完。这个问题的解法不是硬扛，而是“化整为零”。
建议先按业务域把仓库拆成若干分析入口，比如先分析services/order模块，再单独分析services/payment模块，各自生成单独的架构图。等需要看全局的时候，再让Archify加载所有模块的中间分析结果做聚合。大多数情况下你关心的只是某一个业务域的依赖关系，没必要每次都全量分析。另外，构建产物目录和缓存目录请务必加入excludeDirs，我见过一个项目把.git目录都扫进去了，分析结果里多出一堆莫名其妙的依赖边。
4.3 架构规则怎么自定义才有意义
规则不是写得越多越好，写一堆没人认得的约束，最后只会变成“狼来了”。我建议从团队的代码评审记录里提炼规则：过去三个月在评审中被反复提到的架构问题，才是真正值得固化成规则的。
一开始定规则，建议只定三条核心的，并且要可执行、可理解。第一层定“禁止反向依赖”，比如订单模块不能反向依赖支付模块；第二层定“禁止跨层调用”，比如Controller不能跳过Service直连Repository；第三层定“禁止循环依赖”，任何环都要被标记。这三条搞定，就已经能挡住大多数架构恶化。
经验是，规则一旦报错太多，团队就会麻木，最后没人看。所以新增规则时宁缺毋滥，并且配上清晰的description，让开发者在看到违规提示时能立刻明白“为什么不行”，而不是面对一条天书般的报错。Archify的优势在于它允许这些规则和编码代理联动，代理修改代码之后自动重跑，让规则成为开发过程的一部分而不是事后审计。
5. 我个人的几点体会
把Archify真正用进日常流程之后，我最大的感受是：架构图终于从“交付物”变成了“守门员”。以前画架构图是为了应付文档要求，画完基本就进回收站了；现在Archify把架构图和代码放在同一时间轴上，代码变，图跟着变，规则跟着校验。开发者不用再为了画图而画图，架构信息成为开发过程里的实时副产品，这种感觉相当奇妙。
如果你刚开始接触，我建议别一上来就想把全公司的仓库都接进去，先从自己手头维护最频繁的那个小项目跑起来。把扫描范围调对、把核心三条规则配上、在Trae里验证一次端到端的分析，你很快就能体会到对代码库的掌控感提升了一个量级。等你在小项目上跑顺了，再逐步拓展到大仓、推进到团队CI里当门禁，这个过程会顺畅很多。
最后再分享一个小技巧：Prompt里让编码代理跑Archify时，记得加上“输出中附上关键文件的源码路径”这句话。这样拿到图的同事可以直接点进对应代码，不需要再翻半天目录验证。一个小改动，图的价值立刻翻倍。
