Archify：让编码代理生成的代码架构可校验、不腐化

1. 这个项目到底解决的是什么问题

编码代理这两年有多火，不用我多说了。你让 Cursor、Claude Code 或类似工具在代码库里加个功能、改个接口，它噼里啪啦一顿操作，几十个文件说改就改。代码能跑，测试能过，看起来一切完美。但你有没有想过一个问题：这堆被 Agent 改完的代码，它架构上到底变成什么样了？

我之前在一个中等规模的后端项目里做过一次实验：让编码代理连续开发两周，中途没有人工介入补文档。两周后我把项目的模块依赖图、服务调用关系和关键数据流导出来一看——好家伙，跟最初的架构设计相比，至少偏了三个层级。新增的模块直接绕过了网关调用内部服务，缓存层的边界被打破，本该隔离的业务领域之间出现了诡异的跨层依赖。

这不是编码代理的问题，而是我们把架构可视化和代码变更之间的节奏彻底搞丢了。

传统做法是架构师画图、开发照着做、文档定期更新。可一旦开发主力变成 AI，这个节奏根本追不上。Agent 每几十分钟就提交一次大规模变更，靠人去同步更新架构图，等于让一个人去给正在全速冲刺的赛车画轮胎磨损曲线，画完早就不是现场了。

Archify 做的就是这件事：让编码代理在产出代码的同时，直接产出可校验的架构图。而且这个架构图不是从某个人的脑海里回忆出来的，是从代码本身实时提取的。我第一眼看到它的思路时，第一反应是“终于有人把架构图从 PPT 时代拉回到代码时代了”，第二反应是“这个方向如果做对了，七周涨七倍多不奇怪”。

我试用过不少架构图软件和技术架构图工具。它们大多逃不过一个命运：刚开始画的时候极其精美，半年之后全部作废。因为手工维护的图一定会和代码脱节。系统架构图一旦和真实代码对不上，它从“协作工具”降级成“入职培训教材”，再过半年连教材都当不了，因为新人照着图去读代码会发现处处对不上，反而增加困惑。Archify 踩的点很准：架构图不应该靠“画”，应该靠“发现”。这也正是它能跟编码代理打配合的核心原因——Agent 改代码是高频的，架构感知也必须高频，否则一切架构治理都是空谈。

所以这篇内容主要围绕几个问题展开：Archify 到底怎么用、它为什么强调“可校验”、在实际项目里怎么把它嵌入日常研发流程。适合正在重度使用编码代理的团队、对架构可视化有执念但苦于维护成本的开发者、以及那些想知道“AI 时代架构文档到底该怎么活”的人。

2. 核心设计拆解：Archify 的方式为什么有杀伤力

2.1 架构图不是画出来而是长出来的

市面上的架构图软件，无论是画布类的、拖拽类的还是基于模板的，核心思路都差不多：给使用者一块白板，然后让人去表达自己脑中的架构。问题在于人的脑图永远落后于代码的实况。

Archify 反着来。它不让你画，它自己从代码仓库里扒。你给它一个代码库，它做静态分析、依赖解析、结构识别，然后生成一套反映仓库真实状态的架构图。这个过程更像“长出来”而非“画出来”，图中每一个节点和连线在代码里都有对应依据。

我当初刚接触这类工具时，第一反应是“静态分析生成的图会不会很乱”，毕竟做过软件架构图的人都懂代码里总有各种历史包袱和临时 hack，机器能分清主次吗？Archify 的处理手法是把图分层：高层业务模块是一层、进程与部署关系是一层、代码级的依赖是一层。你看到的是可折叠可下钻的图，而不是一张塞满上千个节点的巨型蜘蛛网。

这个设计解决了架构可视化最大的痛点：单一视角必然失真。CEO 想看的系统架构图、后端负责人想看的微服务架构图、一线开发想看的方法级调用链，这三者的抽象层级完全不同。如果工具只提供一种图，那它一定不能满足任何一方。Archify 的做法是让架构图自带“缩放语义”，不同层级之间可以平滑跳转，从模块到包再到类的依赖关系一路追下去，每一层都保持可读性。这跟我用过的静态代码分析工具完全不一样，那些工具生成的调用图密密麻麻，实用性很差，而 Archify 是按架构语义组织图的，组件、领域边界、依赖方向都清清楚楚。

2.2 “可校验”这三个字才是真正的护城河

很多架构工具只解决“生成”环节，但 Archify 最值钱的地方在“校验”。

什么叫可校验？就是这张架构图不是一张不可变的事实，而是可以被当成规则来验收代码的约束条件。Archify 允许你定义架构规则——比如“订单服务不能直接访问用户数据库”“所有跨服务调用必须经过 API 网关”“基础设施层禁止反向依赖领域层”——然后它把这些规则变成持续检查项，每次代码变更后自动验证架构图是否仍然成立。

这套思路让我想起基础设施领域的 IaC。基础设施即代码之所以能流行，不是因为它能把服务器配置可视化，而是因为配置可以被 diff、被 review、被纳入版本控制、被回滚。架构图要是只活在截图里，它就永远是文档。可一旦架构图变成代码库的结构化事实、可以被校验、可以在 CI 里跑规则，它就成了一种“架构即代码”的实践。

我跟朋友聊这个点时他说了一句很准确的话：“这相当于给架构图装了测试用例。”以前保证架构不腐化靠的是架构评审会上人的自觉，现在靠的是机器在每次提交时自动做检查。哪个服务多了一条不该有的依赖、哪个模块被反向调用，这些问题在代码合入之前就会被架构校验拦下来，而不是等系统乱到不可收拾才靠人工去考古。

具体展开的话，Archify 的校验能力大概分三个层次。第一层是结构校验：声明式地检查“A 模块不能依赖 B 模块”“C 层不能引用 D 层”。第二层是基于语义的校验：它能识别代码里的实际调用行为、框架注解、中间件接入方式，从而判断是否存在绕过既定通信方式的隐性通道。第三层是演进校验：对比两次架构快照，展示新增了哪些模块、哪些依赖方向被反转、哪些边界被打破。这三层结合起来，架构健康度就不只是感性的“代码有点乱”，而是被量化成了可审计的指标。

注意：可校验架构图的真正价值不在于“它画得对”，而在于“它是团队约定俗成的准绳”。如果规则定义得太粗，拦不住真问题；太细，开发者会被规则烦死，最后集体绕过你。这个平衡点需要团队根据自己的研发节奏来调。

2.3 定位：Archify 是编码代理的仪表盘

用 Archify 一段时间后，我更愿意把它当成编码代理的仪表盘，而不是传统意义的架构图软件。你让 Agent 干活的时候，它到底打算怎么改代码？它会不会破坏已有的架构边界？它新增的组件有没有绕开设计约束？这些以前只能靠 code review 时人眼去盯，现在通过 Archify 能在架构图上直观地看到。

具体场景我试过：给一个已有微服务架构的仓库提需求“增加用户积分变动的事件通知”，编码代理会自己评估应该改哪些服务。没有 Archify 之前，你只能等它改完以后在 diff 里人肉核对模块变更是否合理。有了 Archify，Agent 干活的同时，架构图会实时变化，新增了哪些节点、新增了哪些调用关系、触碰了哪些边界，一目了然。你可以在 Agent 提交代码之前就发现“它直接让积分服务连了用户中心的只读库副本”这种设计隐患。

这个定位很聪明。现在做编码代理赛道的团队太多了，做架构图软件的传统厂商也够多，但 Archify 卡的位置是二者交叉的空白区：不是帮人画图，不是替人写代码，而是让人能看懂 Agent 写的代码在架构层面干了什么。

3. 实操篇：把 Archify 用起来

3.1 快速上手：Archify 到底怎么用

先回答最常见的“Archify 怎么用”这个问题。由于 Archify 仍处于快速迭代阶段，不同版本的实际接入方式可能略有差异，但核心流程是稳定的。

第一步是接入代码仓库。通常用 GitHub App 安装或 CLI 方式授权，Archify 会读取仓库的代码结构和依赖关系。对于本地仓库也可以直接通过命令行扫描，它会识别项目类型、包管理器配置、模块划分方式。这一步和传统静态分析工具差别不大，关键是后续使用方式很不同。

第二步是让它生成首张架构图。扫描完成后，Archify 会输出一个结构化的项目概览页，不同层级之间的依赖关系会画成可交互的图。在微服务架构图这个场景里，你看到的是一个服务节点一张图，服务之间的调用关系用连线表示，颜色能标识健康度和边界清晰度，系统架构图和技术架构图都能在这里切换视图。

第三步是体验玩法中的精髓——写规则。拿我现在一个仓储系统为例，我写了一条“inventory 模块不得反向依赖 order 模块”的规则。输入的自然语言类型是 schema 结构，然后选择受影响的服务和禁止的依赖方向，保存之后它就开始作为守护规则运作了。之后我再让 Agent 改代码，一旦它新增的调用违反了这条规则，Archify 会在代码合入前给出明确的架构冲突报告。

提示：第一次接入的仓库最好选一个“核心架构尚算清晰”的项目，不要拿一团乱麻的历史遗留系统做实验。原因很直接：如果当前代码结构本身已经严重偏离理想架构，规则一开就会报海量错误，你会在噪音里耗尽耐心，误判工具不好用。先把工具用在能带来正反馈的地方。

3.2 接入编码代理：Cursor、Claude Code 场景实测

我测试环境里最常用的搭配是“Claude Code + Archify”。

以前用 Claude Code 改一个大型服务仓库，它会自己总结“我改动了哪些文件、为什么这么改、涉及哪些模块”。这个总结是文本形式的，信息密度有限。有时候改完代码，模块之间的关系变化了，Agent 可能根本没意识到这也算一种破坏性变更。

接了 Archify 之后情况完全不同。在 Agent 动手改代码前，我可以在 Archify 里导出一份当前架构约束文件，让 Agent 在开工前先阅读，相当于给了它一份“架构红线清单”。然后 Agent 在实现功能时，会把架构规则当成显性约束。我自己试的时候是直接把生成的拓扑文件和规则定义丢给 Claude Code，告诉它“你要在上述架构约束内实现功能，如果必须碰边界，必须明确说明理由”。它的最终输出质量上了一个台阶，不是代码正确性的提升——本来就能跑——而是它不再写“技术上正确但架构上很脏”的代码。

这个流程推荐大家试一下，只需三步：在 Archify 里打开目标服务的架构全景，导出当前架构约束描述，然后在给编码代理的 system prompt 里添加上下文。实际项目里，这套“先看架构再写代码”的顺序能显著减少 Agent 乱穿依赖的毛病。用过 Cursor 做大型重构的读者应该深有体会——工具越强，越需要有边界约束。

3.3 日常开发流程中的最佳实践

我建议把 Archify 嵌入团队开发流程的四个关键节点，而不是当成一个想起来才瞅一眼的工具。

第一，编码任务开始前。让 Agent 或者人类开发者先看一眼最新架构图，知道当前的模块边界和依赖规则。很多架构违规其实不是恶意，纯粹是开发者不知道这里有边界。一张清晰的架构图能极大降低无知性违规。

第二，编码任务结束时。让 Agent 自查这次改动在架构层面的影响，Archify 能自动对比代码变更前后的架构图，输出一份“本次变更涉及模块及新增依赖”的报告。这比人工 review 时对着 diff 猜要高效得多。

第三，CI 检查中。把架构规则作为流水线的一个检查步骤，类似 lint 和单元测试，一旦有新的依赖关系违反规则就 fail。这一步不能省，靠人自觉不如靠机器强制。

第四，定期架构评审会。不用再让架构师临时准备 PPT 了，直接打开 Archify 的架构演进时间线，对比过去一个月架构健康度的变化趋势。

我用下来最大的体会是，团队的质量底线提高了。以前架构劣化是温水煮青蛙：今天加一个临时的跨层调用，下周又来一个，一个月后架构就烂到谁也说不清了。现在每一次违规都会在变更发生时被点出来，开发者在当下就能处理，而不是几个月后靠一次大型重构来还债。

3.4 与常规架构图软件的核心差异对比

为了帮助大家更直观理解 Archify 和传统工具的区别，我用一张表格梳理两者在不同维度上的表现差异。

传统架构图软件的核心用户是“画图的人”，产品的成功标准是画出来的图美不美观。Archify 的核心用户是“看架构和维护架构的人”，产品的成功标准是这张图能不能在代码演进过程中保持真实、能不能提前拦住架构劣化。这两种工具的演进方向在未来会越来越分化，一个偏向表达设计意图，另一个偏向记录代码现实。两者都有存在价值，但如果说要和编码代理打配合，后者显然在频率和自动化程度上占据先天优势。

4. 架构图与编码代理结合深水区：避坑经验与案例复盘

4.1 自动生成的架构图能替代架构师吗

先说结论：不能，但能让架构师把精力花在更有价值的事情上。

自动生成的架构图更像“代码 CT 扫描结果”，它客观反映现状，但它本身不对“这个现状好不好”做价值判断。架构师真正值钱的判断力这时候派上用场：现状是否可接受？需要怎样的演进路径？哪些技术债该现在拆、哪些可以再扛一扛？

Archify 生成的软件架构图和系统架构图，给架构师提供了一张值得信任的事实底稿。有了这张底稿，架构评审的重心就可以从“确认现状”转向“规划未来”。以前开架构评审会，一半时间在解释系统现状，现在架构图摆在那里，所有人都承认这是当前的真实情况，大家有更多时间讨论目标设计方案。这个过程让我感受很深的一点是：工具最大的价值不是替代人做决策，而是让人的决策所基于的信息基础变得可靠。

4.2 三个被低估的副作用

除了图本身的价值，我观察到 Archify 这类工具至少带来三个容易被忽略的正面效果。

第一个是新成员上手速度提升。新员工面对一个中大型代码库，最大的障碍不是读不懂单段代码，而是形成心智模型太难。有了准确及时的架构图，新成员可以直接先看图，再根据图按图索骥去读关键代码，效率提升显著。相比那些已经画了两年早就过期的“入职培训版系统架构图”，可信度完全是两码事。

第二个是消灭了一批伪讨论。团队讨论架构方案时，经常出现“我认为当前系统是这么跑的”“不对，其实是那样跑的”这类争论——仔细一查，两个人都没完全说对，系统已经被改得面目全非。有了实时准确的架构图，这类基于“记忆偏差”的伪讨论大幅减少，讨论起点变成同一份事实。

第三个是让跨团队协作的契约变硬。服务之间经常因为“你偷偷加了依赖我接口的频率”或者“你本来不该调用我这个内部方法”起冲突。有了明确的架构边界和可校验规则，服务间契约就从口头默契变成了可以自动执行的技术约束。

4.3 架构定义的落地姿势

Archify 里定义规则时有一个技巧，值得单独拿出来讲讲——从小而具体的规则起步。

最忌讳的是第一次就定义一套“完美架构约束”，把所有模块边界、依赖方向、通信规则全写进去。在实际项目中，这么做的结果通常是冲突爆炸，导致团队不是选择删除规则就是干脆放弃工具。正确姿势是先识别最痛的 3 到 5 条架构红线，写进规则里守护，运行稳定后再逐步追加。

我自己的经验是从“禁止反向依赖”和“禁止跨层直接调用”这两类规则开始试。它们定义起来很直观，检查逻辑也很清晰。等团队完全适应了规则系统运作，再添加服务间调用的白名单、数据流向的约束等更精细的规则。这个渐进的节奏能让工具在团队中逐渐站稳脚跟，而不是一上来就制造大量反抗。

独家心得：好的架构规则不是给开发找茬，而是把大家心照不宣的“潜规则”显性化。你可以在团队里做个调查：“当前这个系统有哪些‘实际不能做但没人写下来’的约定？”把这些潜规则整理成规则清单，往往比外部架构咨询师给出的通用方案更有效。

4.4 一个中小团队的实际接入复盘

我在自己的后端团队里实际跑了一个试点，用一个真实订单服务作为测试。

第一步，接入仓库并生成了初版微服务架构图，大概花了十几分钟。期间发现了一个本地依赖声明问导致的模块归属不准，这是扫描工具的典型问题，手动校正一下即可。

第二步，定义规则。我先选择了两条规则：订单模块不得反向依赖支付模块、所有 HTTP 入口必须经过网关层对外暴露。保存后跑了一次全量检查，立刻发现存量代码里已经有三处违规——都是很早之前“赶工期”留下来。

第三步，处理违规。我没有选择一次性清理，因为存量债务强行清理风险太大。我的处理方式是：存量三处违规先记录为已知债务，增量代码开始严格受规则约束。两周内团队新增和修改的代码没有产生一个新的违规，存量违规也在一个迭代周期内逐步清理。

我印象比较深的一次意外是，有个工程师在实现新功能时，为了省事一度考虑直接读取另一个服务的数据库表。以前这个操作很可能在 review 中被漏掉，因为人眼 review 很难在几百行 diff 里发现一个跨服务的数据源引用。这次代码一提交，Archify 立刻报出“检测到 module A 直接访问了 module B 的数据存储层”，并且会附上具体涉及的文件和代码行。工程师收到报告后自己就把实现方式改成了通过 API 调用，整个过程没有通过架构评审会，就被架构工具自动拦截和纠正了。

这个案例里最让我满意的不是某个具体的拦截成功，而是团队开始把架构图当成“活着的系统”来看待。有个后端同学甚至在开技术方案讨论时主动说：“我先把方案在 Archify 里模拟了一下，发现按这个方案要新增三处跨服务调用，边界被打破了，所以我看能不能先通过调整领域归属来规避。”这种意识上的转变，才是架构治理真正被团队接受的表现。

5. 架构感知会成为开发基础设施的标配

5.1 从增长看信号：编码代理生态的“下半场”

Archify 七周涨七倍多的增长速度，放在整个开发者工具领域不算常见的增长曲线。能出现这种指标，说明市场对“编码代理 + 架构治理”的需求非常旺盛。

这背后的逻辑其实不复杂：编码代理刚兴起的阶段属于“人口红利期”，谁能让 Agent 写更多代码谁就赢。但很快大家就发现，AI 写代码的能力已经超过人类让代码库保持整洁的能力——尤其当多个 Agent 并行开发时，技术上每个 Agent 都在严格完成自己那一小部分工作，但整体架构耦合度就会自然上升。行业里管这个现象叫“agent drift”，智能体漂移，指的是每个单独看来合理的代码变更，聚合起来却导致系统架构不受控地腐化。

Archify 的崛起正是踩在“Agent 红利期结束、治理期开始”的节点上。它不生产代码，它给代码的“生产结果”提供透明度和可治理性。打个比方，编码代理是发动机，Archify 是仪表盘和刹车系统——发动机越猛，刹车和仪表盘的价值就越凸显。一段代码跑得飞快却不知道它在哪个模块里干了什么、对整个系统架构造成了什么影响，这种“速度感”是危险的。

从更宏观的趋势看，我觉得未来的开发基础设施会有一层专门的“架构感知层”，承担“把代码事实转化为架构信息”这一基础能力，Archify 就是朝这个方向在长。它能成为编码代理的标配组件，不是因为它是一个杀手级应用，而是它补齐了 Agent 时代必不可少的可观测性和治理性缺口。

5.2 给开发者的动作建议

最后给不同角色的读者一些实用建议。

如果你是一线开发，我建议你至少体验一次 Archify 这类工具。它带给你的不是一个“汇报用的图”，而是让你对自己正在开发系统的边界有一种上帝视角。知道自己在整个系统里处于什么位置、自己的改动会影响哪些上下游，这种感知会显著提升你的架构决策质量。

如果你是技术 leader 或架构师，试着把“架构规则检查”加入你的 CI 流程。从两三条最关键的规则开始，跑通后再慢慢扩展。一个能自动拦截架构劣化的流水线，价值远高于一百张存满网盘的架构图。

如果你正在重度使用 Cursor、Claude Code 或自研 Agent，一定要在编码代理的工作流里加入“架构上下文交互”环节，把 Archify 生成的约束输入给 Agent，再对 Agent 输出执行架构校验。这一步能把你从一个“看代码执行结果”的人，提升为“看架构演进结果”的人。

工具会继续演，但核心需求不会变：代码越写越快，人越需要一张始终可信的地图。Archify 做的就是这个事——不是给你画一张假想的设计蓝图，而是让系统的真实架构对每个人可见、可校验、可守护。

我个人现在的习惯是：任何编码代理开工前，先给它一份 Archify 导出的结构事实；任何代码合并前，先看一眼架构检查的输出。这套流程不是多花时间，而是把原来花在“事后填坑”上的时间挪到了“事前防错”上，怎么算都值得。