先从一个特别常见的场景说起。新同事入职、项目技术评审、季度技术汇报你都绕不开一张架构图。你真正耗时间的不是拖几个方框而是把散落在代码、文档、聊天记录和记忆里的模块关系全部捞一遍再用图形表达出来。更糟的是这张图往往画完就过时了下次版本一迭代没人愿意再花几个小时去更新它。过去一个月架构图 Agent 这个方向在 GitHub 上热度非常高。我做的项目在这个方向连续 5 天登上 GitHub 全球趋势榜第一我也因此进入了全球开发者趋势榜。这篇文章不是来晒数据的而是想认真拆解一下这类工具为什么会被这么多人关注它到底解决了什么问题真实使用中边界在哪里以及如果你想自己用起来应该从哪一步开始。1. 架构图为什么是个“高频但没人愿意做”的活先给一个反直觉的判断架构图的价值不在于“画得好看”而在于“让团队对系统的理解保持一致”。很多人把架构图当成交付物其实它更像团队沟通的公共语言。语言一旦失真沟通成本就会成倍增加。1.1 手工画图的真实成本不在画而在收集信息如果你仔细观察自己画架构图的完整过程会发现 70% 的时间都不是在拖拽图形而是在回忆、确认和查证。这个服务到底依赖哪个数据库那个模块是同步调用还是异步消息网关和鉴权服务之间的链路是不是上一轮重构时已经改掉了这些问题不搞清楚图画得再干净也是错的。我见过不少团队用白板、PPT 或专项绘图工具维护架构图。初期画一张大图确实有成就感但经过两三个版本迭代之后这张图的可信度就会急剧下降。原因非常简单代码在持续变化而图不会自己跟着变。更新架构图需要有人在排期之外额外付出时间这件事在真实开发节奏里通常排不上号。1.2 图一旦过时团队付出的隐性成本往往被低估架构图过时之后损失通常不是马上显现的而是慢慢渗透到日常协作里。新同事照着旧图理解系统先建立起一套错误认知再读代码时反复纠正自己。老同事讨论问题时每个人脑中的系统模型已经不一致聊了半天才发现版本对不上。架构评审时评审者看到的图和实际代码不一致评审意见自然容易跑偏。排障时如果架构图本身就是错的排查链路很容易被带进死胡同。文档体系里架构图通常是入口文档入口错了后面所有详细设计文档的可信度都会被打折扣。这些成本很难量化但每个在稍微复杂一点的项目里待过的人应该都有体感。1.3 为什么以前的自动化方案解决不了这个问题过去的方案无非两类。一类是手工画精度足够但维护成本太高。另一类是工具自动生成依赖固定规则只能画出包结构、类依赖关系这种静态骨架画不出真正的业务分层、数据流向和调用链路。翻译成大白话就是旧方案的瓶颈不是“画图能力”而是“理解能力”。它们不理解你的系统是做什么的不理解哪个模块是核心不理解为什么订单服务和支付服务之间要走消息队列而不是 HTTP 调用。没有这层理解生成出来的图就只是一堆方框和线的机械排列对真实沟通帮助有限。这正是架构图 Agent 出现后能迅速获得关注的原因。它把“理解架构意图”这件事从人身上转移到了大模型身上。你只需要描述系统有哪些模块、模块之间怎么交互Agent 就能生成一份结构完整的图定义。2. 架构图 Agent 真正改变的是“画图”这个动作本身2.1 从操作图形到表达意图门槛完全不一样传统画图的流程是打开工具、拖一个矩形、改文字、拖一条线、调整样式。每一步消耗的都是视觉和操作注意力而且工具越专业学习成本越高。使用架构图 Agent 的流程是用一两段话描述系统结构生成看结果再用自然语言提修改意见重新生成。这里的核心变化不是省了几分钟而是把动作模式从“操作图形”变成了“表达意图”。表达意图这件事对于大部分开发者来说本来就是每天都在做的事描述一个系统的模块和关系远比掌握一套复杂绘图工具的快捷键更容易。同时修改也变得非常自然——你不需要在画布上小心翼翼地对齐线条只要说“把支付服务拆成支付网关和支付核心两层”剩下的工作交给 Agent。2.2 让架构图从一次性交付物变成可复用的文档在我设计这个项目的时候最看重的一点是输出格式的开放性。生成出来的图定义不能只是一张 PNG 图片它应该能嵌进项目的 Markdown 文档能放进代码仓库做版本管理能被团队成员在代码评审里一起 review。这一点想明白之后一个更重要的变化跟着出现了架构图不再是某个人的私人产物而是团队可以共同迭代的文档。谁改了模块谁就顺手改一改对应的图定义成本远低于在绘图工具里改一份文件再重新导出、再上传到文档中心。架构图终于有机会跟着代码一起演进而不是每次都要等人专门“抽时间维护一下”。2.3 连续多天登上 GitHub 趋势榜背后是需求扎堆从社区反应看这个项目能连续 5 天排在 GitHub 全球趋势榜第一本质上说明它戳中了大量开发者的真实需求。架构图这件事几乎人人遇到过需求足够普遍Agent 直接生成图路径足够短生成结果十几秒就能看到反馈足够快。三个条件叠加项目在开发者社区的传播就非常自然。对 GitHub 用户来说趋势榜本身就是“最近大家在用什么”的信号当一个项目连续多天待在第一的位置上说明不是少数人试用完就离开而是有相当一部分用户反复使用并且愿意把它推荐给身边的人。3. 想真正用起来推荐这条最少走弯路的最小路径如果你也想把类似工具用起来不要一开始就把它当成一个“画图玩具”。按照下面这条路径走更容易在真实项目里落地。3.1 动手之前先想清楚这张图给谁看很多人一上来就输在这步。一张给老板看的业务架构汇报图和一张给新同事看的系统入门图要求完全不一样。前者重分层和业务边界后者重要素完整性和链路清晰度。读者不同图的粒度、注重点、甚至形式都要跟着变。我的建议是在生成架构图之前先问自己三个问题这张图的核心读者是谁这张图要回答什么问题这张图大概多久更新一次这三个问题的答案决定了你给 Agent 的描述该怎么写也决定了最后选什么格式输出。3.2 用一段结构化的描述做输入效果远好于一句“画一下架构”根据我自己的使用经验一个高质量的架构图生成提示词至少包含四类信息系统边界系统包含哪些模块哪些外部依赖不算在内。模块清单每个模块的职责一两句话即可但要准确。交互关系模块之间是 HTTP 调用、消息队列还是共享数据库。层次约定如果有明确分层比如网关层、应用层、数据层直接说清楚。常见写法请为以下系统生成架构图 - 模块Nginx 网关、用户服务、订单服务、支付服务、消息队列、MySQL、Redis - 关系Nginx 网关 - 用户服务/订单服务/支付服务订单服务 - 消息队列 - 支付服务所有服务共享 MySQL 和 Redis - 要求按“接入层 - 服务层 - 基础设施层”三层布局这里很容易踩的坑是把描述写得太模糊。模糊描述下Agent 只能靠猜测补全猜对了你开心猜错了你来回改最后还会觉得工具不好用。精确描述虽然要多写两句话但第一次生成基本就能用。描述方式典型输入生成结果模糊描述“画一下我们的系统”通用结构模块名和层级大概率不匹配结构化描述模块清单 关系 分层要求基本符合预期只需微调细节这不是 Agent 能力不行而是自然语言表达本身有信息密度差异。代码里的依赖是明确的你没在描述里写出来模型就只能靠推理去补推理出来的部分自然会有偏差。3.3 迭代比一次生成更重要留意这三个检查点我见过最常见的错误是生成一次不满意立刻下结论说不好用。实际上架构图 Agent 的使用方式更像和同事讨论架构需要来回确认。一个比较高效的迭代顺序是先看整体布局分层是否合理模块是否遗漏。再看关键链路核心调用链路有没有画反数据流方向是否正确。最后看细节命名是否符合团队习惯边界是否清晰。注意迭代时一次只提一个修改点比如“把支付服务拆成两层”或“把消息队列放到基础设施层”。一次提多个诉求模型很可能顾此失彼改完一个丢一个。4. 这类 Agent 背后到底做了什么4.1 核心链路理解、规划、生成、渲染一个架构图 Agent 的内部流程本质上可以拆成四步理解大模型读取用户输入识别模块、关系、层次等关键信息。规划把这些信息组织成图结构决定节点和连边的组织方式。生成输出一种标准的图定义语言比如 Mermaid 或 PlantUML。渲染把图定义转换成可视化的图形呈现给用户。这四步里最容易出问题的不是最后两步而是前两步。因为同一个系统可以用无数种方式画出来Agent 必须判断哪种表达方式最贴合用户意图。这也是为什么提示词质量直接影响最终结果的原因——你的输入越精确模型在“理解”和“规划”阶段的空间就越大。4.2 为什么输出用 Mermaid 这类文本格式文本化格式对 Agent 来说有天然优势。大模型擅长生成文本不擅长直接操作图形对象。Mermaid 用一套接近自然语言的 DSL 描述图结构模型理解和生成起来都相对容易。从工程角度看文本化格式的好处远不止于此可以放进 Git 做版本管理通过 diff 直观看到架构图的变更。可以嵌进 Markdown 文档在 GitHub、GitLab 等平台直接渲染。可以由 CI 流程自动检查生成结果是否合法提前发现图定义里的语法错误。用户可以直接修改图定义代码再重新渲染自由度远高于修改一张图片。这也解释了为什么文本化格式是关键设计决策。它把“最终产物”变成了“中间产物”用户拿到的不是一张死图而是一份可以继续编辑的工程文件。4.3 上下文注入才是决定生成质量的分水岭单靠一段描述模型能画出通用结构但画不出你项目的真实细节。这里的关键是上下文。如果把项目目录结构、关键文件摘要、甚至依赖关系注入到上下文里Agent 生成的质量会明显上升。但把整个代码库丢给大模型既不现实也没必要。更合理的做法是只注入与架构相关的部分项目目录树让模型了解模块组织方式。服务间的接口定义帮助模型判断调用关系。部署配置里的服务列表比如 Docker Compose 或 Kubernetes 的 service 名称。不过上下文注入同时也带来了隐私和成本的权衡。如果你的项目涉及敏感业务数据使用外部大模型服务之前一定要确认代码和描述信息会不会被发送到第三方。很多企业环境对此管控非常严格这一点后面会说。5. 把项目做到全球趋势榜第一踩过这几个坑项目上了榜单之后有很多人问我是怎么做到的。技术上的实现反而不是最难的部分最难的是做产品决策时不断踩坑又不断修正。这里把几个关键教训写出来供想做同类项目的同学参考。5.1 最大的坑一上来就想做“万能工具”项目早期我总想让工具覆盖所有场景微服务架构图、部署架构图、时序图、流程图还想要各种自定义样式。结果就是每个场景都只做到 60 分用户进来第一印象是“什么都能画但什么都不好用”。后来我把功能砍掉大半只保留一个核心场景用户描述系统Agent 生成架构图。把这条链路做到 90 分远比做十个 60 分的功能有价值。用户记住你的方式不是因为你功能多而是因为你在某个场景下真的能帮他把事办成。5.2 忽略输出的可编辑性等于砍掉用户一半的掌控感早期版本我有一个错误认知只要生成的图足够好用户就会接受。后来发现用户真正需要的不是一张“完美的图”而是一张“能改的图”。原因很简单Agent 生成的架构图不可能 100% 符合用户脑海里的结构用户拿到图之后必然要微调。如果输出只允许看图片用户想改一个模块名都无从下手但输出的是图定义代码用户自己改两行再重新渲染整个流程就顺了。这也解释了为什么文本化格式是核心设计决策。它把“最终产物”变成了“中间产物”用户拿到的是一份可编辑工程文件而不是一张死图。5.3 过度追求样式反而偏离了架构图的核心价值早期我把大量精力花在配色、布局、圆角、字体大小这些细节上。后来翻看用户反馈才发现真正被反复提及的关键词是“结构对不对”“链路清不清楚”几乎没有人因为配色夸过这个工具。架构图的核心是关系不是样式。样式只要足够清爽、不干扰信息传递就够了。把美化的工作留给渲染层让模型专心做结构理解这才是正确分工。一些看似不起眼的细节比如节点对齐、间距控制应该在渲染层自动处理。5.4 沉淀下来的三句话如果把这段经历压缩成三句话我会这样说先定义一个非常窄的核心场景把这个场景彻底打通比铺十个半成品场景更有价值。输出一定要可编辑、可版本化、能嵌进现有文档体系工具才能从“试用”变成“使用”。优先保证迭代速度而不是一次生成的完美度。用户愿意基于结果连续修改才是真实使用信号。6. 热度退去之后这类工具的真实边界在哪里趋势榜的热度总会过去真正留下来的是工具和用户工作流之间的匹配度。架构图 Agent 的边界在哪里值得认真说清楚。6.1 它不能替代人的架构判断架构图 Agent 是一种提效工具不是架构决策工具。它可以把已有的、甚至比较模糊的信息组织成图但它不会告诉你“这个系统的模块划分合不合理”“这里应该用消息队列还是直接调用”。这些判断仍然需要你对系统有真正的理解。换句话说它帮你把脑中的想法画出来但不负责帮你验证这个想法是否正确。架构设计里的取舍、权衡、前瞻性判断依然是人要做的事。6.2 系统越复杂越要“先拆后合”如果系统有成百上千个微服务直接让 Agent 生成一张总图结果大概率是一团乱麻。在这种情况下正确的用法是先按业务域拆分每个域单独生成一张架构图再生成一张域间关系总图。这是一种“先拆后合”的策略。不要指望一个模型吞下整个系统而是把复杂度拆成可控的粒度每张图只表达一个层级的信息。架构图本来就是分层的业务架构图、应用架构图、部署架构图本来就不应该画在同一张图里。6.3 隐私、安全和团队协作决定了它能不能长期用把代码目录、接口定义、部署配置注入给外部大模型服务这件事需要格外谨慎。如果是个人项目或公开代码库问题不大。如果涉及公司核心业务、未公开的业务逻辑、客户数据一定要先确认合规边界。企业内部如果允许私有化部署大模型这会是更安全的选择。这也是我认为这类工具在 To B 场景落地的最大约束之一。技术能力只是一层安全合规和部署方式往往才是决定能不能长期使用的关键。6.4 适合谁不适合谁场景是否适合说明快速出系统草图、做技术方案评审适合大幅缩短从想法到图形的过程给新同事做系统介绍适合快速生成一份可迭代的入门资料团队文档放在代码仓库里适合图定义可版本化管理随代码演进对图形美学有极高要求的外宣场景不适合需要专业绘图工具和人工精细调整含敏感数据且不能外传的企业环境不适合除非私有化部署否则有数据合规风险需要精确控制每个像素位置的出版级图表不适合Agent 的目标是表达结构不是精细绘图架构图正在变成一种“活的文档”这次项目登上 GitHub 全球趋势榜第一对我来说最值得记下的不是榜单数据而是验证了一个判断开发者真正需要的不是“更好的画图工具”而是“更低成本的沟通工具”。架构图 Agent 的长期价值在于它把架构图从静态交付物变成了可以持续迭代的动态文档。你不需要在每次架构调整时花上几个小时重画一张图只需要更新几行文字描述再生成一次。架构图终于可以跟着代码一起演进。如果你也想尝试这条路径我的建议是找一个你手头最熟悉、结构最清楚的系统开始。先别追求完美先用它跑通“描述 → 生成 → 迭代 → 嵌入文档”这个完整流程。等你体会到架构图不再过时的感觉之后自然会理解这里面的效率杠杆到底在哪里。