被一张架构图反复折磨过的朋友应该能理解下面这个场景需求文档写了三版代码都跑通了结果要让新人理解系统全貌你还得手动画架构图。更气人的是好不容易画完产品又加了一个模块整张图推倒重来。后来我试着把这件事交给 AI让大模型直接生成架构图结果能画和能画对完全是两码事。这也是我接触 archify 的原因。archify 是一个以架构图生成为核心目标的 Agent 技能skill它的输入是一段模糊的自然语言需求输出是一份经过校验、可渲染的架构图文本Mermaid 或 PlantUML顺手的话还会附带组件清单和关键决策说明。它不重新发明大模型而是把画架构图这件事固化成一套可复用的工作流让 Agent 先像架构师一样思考再像画图工一样落笔。这篇文章我会从为什么需要它、技能内部如何设计、怎么在 Trae 等 Agent 工具里跑通、实测踩过哪些坑以及如何把它变成团队基础设施这几个角度展开。无论你是刚接触 Agent 开发的新手还是已经在折腾 skill 封装的老手我相信都能从这里拿到一点可以直接抄作业的东西。1. 被架构图反复折腾之后我为什么把画图这件事交给 Agent 技能1.1 大多数人让 AI 画图的真实体验先说一个可能人人都有过的经历。你直接打开一个大模型对话框输入给我画一个电商系统架构图模型通常会“哗”地给你一段 Mermaid 代码。复制到渲染器里图确实出来了但你盯着图看三秒钟就会发现几个问题数据库选了 MySQL 和 Redis可你为什么需要 Redis消息队列用的是 Kafka但如果你的业务量一天只有几千单这个选型本身就是过度设计图里甚至出现了推荐系统可你根本没提这个需求。这不是大模型笨而是普遍情况下的自由发挥太多了。大模型默认按照它脑海里最常见的标准答案来画图并不会主动追问你的系统是单体还是微服务用户量级多少需要高可用吗团队熟悉什么技术栈这些关键信息一旦缺失生成出来的架构图就是通用模板图。它看着专业却和你的业务毫无关系。我最初的做法是在 prompt 里堆很多要求你必须先问清楚需求再给出图不要乱加组件要分层……但 prompt 越长模型越容易顾此失彼而且每次都要重新写一遍这段咒语。直到我意识到这类重复性的、有明确流程的任务本质上是技能的范畴而不是对话的范畴。1.2 普通对话画图的三个断层用对话形式让大模型画图之所以体验不稳定是因为中间有三层明显断层。第一层是需求断层。用户给的信息往往是不完整的比如只说做一个后台管理系统。围绕这个概念可以画出权力巨大的图——管用户、管订单、管库存、管报表但真实需求可能只是给运营做一张每日数据看板。大模型没有一套强制性的需求澄清流程它倾向于直接生成而不是先把自己不懂的地方问清楚。第二层是选型断层。架构图的核心不是图形而是技术决策。你选 MQ 是因为要削峰填谷还是因为有现成的集群不用白不用你引入缓存是为了扛热点还是为了应付面试官的追问架构图的约束条件来自业务场景普通对话不会自动帮你补齐这个场景背后有哪些选型约束的思考过程。第三层是校验断层。画架构图不是写完代码就结束还要检查组件关系是否闭环、调用链是否合理、是否出现孤儿节点。普通对话里大模型不会主动做这一步反正图画出来它就已经完成了任务。archify 这类 skill 解决的就是这三层断层。它不是简单地告诉 Agent你画一张漂亮的架构图而是给 Agent 一套完整的操作手册和约束规则让它顺着这条路径走完需求分析、方案决策、绘制输出、自检修复的全流程。1.3 用技能而非插件是一种更轻的思路有人可能会问为什么不做成独立工具或插件而要封装成 Agent skill我的理解是技能skill在 Agent 生态里更像外挂的操作手册不依赖运行时、不需要单独部署服务本质是一份结构化指令。它可以随 Agent 工具链一起版本管理也可以跟随具体的 Agent 框架加载。这意味着架构图生成能力可以灵活地附着在任何支持 skill 机制的 Agent 产品里比如 Trae、Cursor 这类 AI 编程工具也可以放进自己的自动化测试链路里。今天这个文章讲的 archify恰恰就是这种思路。你要做的不是再装一个软件而是让已有的 Agent 学会一套工作流。2. archify 技能的核心设计让 Agent 先当架构师再当画图工2.1 Skill 和普通 Prompt 的区别到底在哪很多人对 skill 的理解是把一大段 prompt 存起来下次调用。这个理解方向没错但忽略了 skill 真正的价值它定义了过程而不仅仅是定义了答案。普通 Prompt 像是给实习生丢一句话你画个架构图给我。 结果是实习生凭感觉发挥好坏看运气。Skill 则像给实习生一套标准作业流程先看用户需求说明识别不清楚的地方再去问问完之后把需求拆成业务模块、技术组件、交互关系再根据约束条件做技术选型最后按规定格式输出输出前还要自查一遍。所以在 archify 里画图只占整个 skill 很小的一部分更多篇幅是在交互流程和决策规则。它把怎么一步步得到一张可信架构图的过程固定下来让 AI 的行为更稳定。2.2 archify 工作链路里最重要的四步我用下来的感受是archify 把整个流程收敛成了四个核心环节。第一个环节需求解析与信息补全。用户给出的原始描述通常只有几个关键词比如订单系统。Archify 会先根据既有上下文判断信息完整度缺什么补什么。它未必会像聊天机器人一样连续追问十句话让用户烦躁而是会结合场景主动做合理的假设并在最终输出里标注假设。比如假设系统面向 C 端用户不需要复杂权限体系若面向企业内部请补充说明。这种处理比不停追问到用户崩溃更现实。第二个环节架构风格与组件选型。架构图应该是分层架构还是微服务网状架构同步调用还是异步消息这里必须有一套决策逻辑。archify 一般会根据业务特征做取舍高并发场景优先引入缓存和队列强一致场景强调数据库事务边界团队规模小则优先减少中间件数量。这在技能里并不体现为复杂的算法而是落到几十条 if-then 风格的规则描述里。第三个环节按规范绘制。输出格式必须统一否则下游没法消费。archify 通常支持 Mermaid 和 PlantUML 两种文本形式并且有明确的节点命名规则、分组规则、标注规则。这个环节最怕 AI 自创语法所以技能文件里通常会给出格式示例和禁区清单。第四环节自检与修复。输出完成后要求 Agent 以审稿人视角重新检查是否存在孤立节点、是否存在重复组件、依赖方向是否合理、是否符合用户指定的约束。发现问题就自己改而不是交差。下面整理了一张对比表方便看清用普通对话和用 archify 技能之间的差异。维度直接问大模型使用 archify 技能需求澄清通常直接生成先解析缺失信息必要处做假设选型依据模型自由偏好绑定业务场景推导输出格式不稳定固定 Mermaid / PlantUML 规范自检修复基本没有强制二次校验闭环可复用性每次重新调教一次封装随处加载2.3 我落地用的参考 Skill 结构我没有办法把 archify 官方仓库里的 SKILL.md 原文搬过来告诉你因为不同渠道获取到的版本可能有差异。但根据我实际封装和复用的经验它的核心骨架长这样。下面这是我整理的简化版本结构足够说明问题--- name: archify description: 根据自然语言需求生成系统架构图可输出 Mermaid 或 PlantUML 格式适用于单体、微服务、分层架构。 ---# 技能架构图生成 ## 执行流程 1. 收集背景信息 - 从用户描述中提取业务目标、核心角色、核心流程、非功能需求。 - 若信息不足以决策列出最多三个关键问题让用户补充用户明确表示按默认处理时采用默认假设并在输出中注明。 2. 确定架构风格 - 根据用户量、团队规模、部署环境选择单体分层 / 模块化单体 / 微服务。 - 规则示例 - 中小业务量优先单体分层避免过度设计。 - 存在明显独立扩展诉求时才考虑微服务。 - 强实时交互优先同步 API任务型处理优先消息队列。 3. 确定组件清单 - 只允许纳入必要的组件禁止无依据添加缓存、消息队列、搜索引擎。 - 每个组件必须能在需求背景中找到存在理由。 4. 绘制输出 - 默认输出 Mermaid 格式按 用户层 / 接入层 / 应用层 / 数据层 分组。 - 节点命名规则英文模块名必要时加中文注释。 - 如用户要求 PlantUML则按 PlantUML 语法输出。 5. 自检 - 检查孤立节点、重复组件、单向依赖是否被违反。 - 检查是否超出用户约束。 - 发现问题回到第 4 步修正后重新输出。 ## 输出格式模板 每次输出必须包含三部分 - 架构图文本 - 组件清单表组件名 / 职责 / 选型理由 - 关键假设说明 ## 禁止事项 - 禁止使用 Mermaid 之外的未确认语法。 - 禁止在用户未要求时添加高可用、容器编排等复杂元素。 - 禁止直接输出图片或非文本格式。这个结构的好处是它把隐性的架构能力变成了显性的操作规则。Agent 不依赖某个神秘模型突然变聪明只要按流程走结果通常不会差。3. 实操在 Trae 等 Agent 工具里跑通一个真实架构图任务3.1 环境准备与安装位置我是在 Trae 里深度使用 archify 的。这倒不是因为 archify 只能配 Trae而是我主力开发工具就是它。常见的加载方式是把 skill 目录放到 Agent 工具约定的技能目录下比如工作区的.trae/skills/archify/或者某些版本支持的全局技能目录。不同版本对技能目录的扫描位置不完全一样最稳妥的办法是先打开设置界面搜索 skill 相关配置确认目录路径再动手。如果你的 Agent 工具支持直接导入技能包那就更省事。把 archify 的 skill 文件夹包含 SKILL.md 和可选的辅助脚本整个拖进去即可。安装完成后建议先做一个最简验证新建一个对话输入用 archify 画一个简单的待办事项系统架构图。如果 Agent 开始走技能流程而不是直接甩一段 Mermaid说明加载成功。这个验证动作看起来多余但很值得做。我的经验是很多技能没生效的问题根源不在技能本身而在 Agent 没有按照预期触发它。有些 Agent 框架需要你在提示词里显式点名技能名技能描述写得再清楚也没用。所以实操第一课搞清楚你的工具是自动路由技能还是手动指定技能。3.2 怎么描述需求才能让输出真正可用技能不是魔法它的上限取决于喂给它的需求质量。用了 archify 一段时间后我总结了一个需求描述模板信息不一定每条都填但关键项不能漏。业务背景我们要做一个面向小区住户的物业报修系统 核心用户住户、物业维修工、物业管理员 核心流程住户提交报修单 → 系统分派给维修工 → 维修工上传处理结果 → 住户确认完成 非功能要求需要支持图片上传预计每日报修量 200 单以内需要消息通知 技术偏好团队熟悉 Java希望优先 Spring Boot 生态 输出要求Mermaid分层架构图把这五六个信息给足agent 在分析阶段就不会瞎猜。尤其是业务背景和核心流程两块它们决定了架构图的边界——哪些模块必须有哪些模块可以砍掉。比如上面这个例子套上用户量 200 单/天的约束后消息队列和秒杀系统这种设计就没必要出现了一个单体的 Spring Boot 应用加 MySQL再挂一个 Redis 做待分配任务缓存就足够。反过来如果只写帮我画一个物业报修系统架构图你大概率会收到一个包含 Nginx、Redis、Kafka、MongoDB、ES 的全家桶式架构表面上什么都齐了实际上没有一个能落地。3.3 完整案例从一句话到订单系统架构图拿一个最常见的订单系统来演示。我输入的需求是做一个订单系统用户下单后调用库存扣减支付成功后通知仓库发货运营后台可以查询订单列表和退款。单量不大团队只有五六个人。在 archify 的约束下Agent 通常会走以下流程先解析出核心实体是订单、库存、支付、通知、运营后台然后根据单量不大、团队小判断采用单体分层架构而非微服务再把跨模块调用收敛为内部方法调用。最终输出类似下面这样的 Mermaid 文本此处仅展示文本格式可复制到任意 Mermaid 渲染器graph TD U[用户] -- WEB[Web 端] ADM[运营管理员] -- CONSOLE[运营后台] subgraph 接入层 WEB CONSOLE end subgraph 应用层 API[API 层] ORDER[订单模块] STOCK[库存模块] PAY[支付模块] NOTIFY[通知模块] end subgraph 数据层 DB[(MySQL)] CACHE[(Redis)] end WEB -- API CONSOLE -- API API -- ORDER API -- STOCK API -- PAY API -- NOTIFY ORDER -- DB STOCK -- CACHE STOCK -- DB PAY -- DB NOTIFY -- CACHE同时它会附上组件清单里面解释为什么用 Redis 而不是 Kafka支付结果通知和订单状态缓存都属于低频低延迟操作一个 Redis 足够Daily 单量几百单的场景引入消息队列只会增加运维负担。这个解释正是我个人认为 archify 最值钱的部分——架构图本身可能还能靠人工画但选型理由让新人也能看懂为什么这么设计。4. 实测中踩过的坑和完整的排查记录4.1 agent execution terminated due to error. 这类执行中断用 archify 的过程中我最常碰到的问题就是一个突兀的报错信息agent execution terminated due to error. 第一次看到很崩溃因为这行提示几乎没有定位价值。我后来逐步排查发现这类错误在 Agent 技能场景里通常对应三个成因。第一个是工具调用循环超时。如果 skill 里配置了必须调用某个外部工具比如联网搜技术文档而 Agent 框架执行工具调用的时间超出限制会话就会终止。排查办法是把技能文件中涉及外部工具的步骤去掉改成纯文本判断大部分情况下问题就消失了。第二个是上下文过长导致模型输出中断。当技能包含过多示例、对话轮次又很长时模型生成中途可能触发长度限制。我的做法是压缩 SKILL.md 里的示例数量把冗长的示例放到独立的 reference 文件里按需读取而不是一次性全部塞给模型。第三个是输出结构突变导致解析失败。有些 Agent 框架会严格解析模型的工具调用参数一旦模型输出了格式不匹配的内容整个执行链就会被判定为错误终止。这个问题比较棘手降低 prompt 复杂度、避免在 SKILL.md 里放嵌套过深的 JSON 示例会有效很多。排查这类问题我给一个固定顺序先看 Agent 日志确认报错发生在哪一步再关掉 skill 里的额外工具最后简化技能文件内容。三步走完绝大多数终止错误都能解决。4.2 图太大渲染失败以及复杂系统的拆分思路第二个高频坑是图画出来了但渲染器不给力。微服务一多Mermaid 里全是节点和连线浏览器直接卡死或者布局乱到没法看。这不是 archify 的问题而是所有文本化绘图方案的通病。我的处理办法是控制单图复杂度。具体来说在需求里强制加上单图节点不超过 15 个超过则按模块拆分这一条规则。一个三十个微服务的系统不画一张全景图而是拆成系统上下文图一张、核心链路图三四张、每个服务内部组件图单独画。每张图聚焦一个层级反而比一张巨型全景图更有指导意义。archify 的 skill 机制对这件事件的帮助在于你可以在技能文件里预设拆分策略遇到复杂系统时先输出一张顶层上下文图再按业务域分别输出子图。这其实也是 C4 模型的核心思想不同层级解决不同问题别指望一张图承载所有信息。4.3 组件幻觉怎么压制组件幻觉是我发明的一个说法就是指 Agent 在架构图里添加了并不存在的组件。最常见的幻觉对象包括 Redis、Kafka、Nginx、Kubernetes——这几个词在大模型训练语料里出现频率太高模型一画架构图就习惯性地往上堆。压制办法有两个。第一个办法是在技能文件的禁止事项里写死比如在用户没有明确提及分布式需求时禁止出现消息队列、容器编排、服务网格等领域组件需由业务背景推导出必要性后方可加入。这能明显降低幻觉率但并不能根除因为大模型对否定指令的遵循能力有限。第二个更有效的办法是强制每个组件必须写出选型理由。当 Agent 被要求解释为什么这里需要 Redis时它自己就会在生成阶段过滤掉那些站不住脚的组件。这个思路和代码评审里让你解释设计理由是同一个道理。我现在在 archify 里同时启用这两条规则实测下来虚假组件的出现频率低了很多。4.4 和其他 skill、agent 组合时的优先级问题当你给 Agent 挂了不止一个技能时会产生一个新问题Agent 到底按照哪个技能执行我有一次同时开了 archify 和另一个专门用来写接口文档的技能结果向 Agent 提需求时它一会儿按 archify 的流程走一会儿又触发接口文档技能输出变得非常混乱。解决方式同样落在 skill 设计层面一是把触发条件写清楚比如在 archify 的 description 里强调当用户需要架构图、系统设计图、组件关系图时必须优先使用本技能二是在 Agent 框架层面配置技能优先级或别名直接按名称调用不依赖模型自己判断。这个道理也适用于 agent 之间的协作多个 agent 各管一段时边界一定要清晰否则执行链会乱成一锅粥。5. 从个人效率工具到团队基础设施archify 还能怎么用5.1 让 Agent 自动巡检代码仓库并生成架构图架构图的一个尴尬之处是画完即过时。代码一直在变架构图停在画完那天。后来我尝试把 archify 往 CI 流程里推让 Agent 定期读取仓库代码解析模块依赖再调用 archify 的流程生成当前实际架构图最后和基准版本做对比。这样任何一次模块被揉成一团或循环依赖悄悄出现的变更都能在图表层面直接暴露。这个用法本质上是把架构图生成从一次性人工行为变成了自动化检测工具。热词里经常出现自己搭建 agent 进行自动化测试我觉得架构图一致性检查完全可以算一类轻量级自动化测试。它不需要额外写复杂的静态分析工具只是用好 Agent 的代码阅读能力和 archify 的绘制规范就能收获一份持续更新的架构视图。5.2 用架构图反哺开发评审先看图再动代码另一个我实际执行过的场景是评审前置。以前我们做设计评审大家对着文字方案争论半天还经常漏掉边界。现在流程改成方案写完后先用 archify 生成候选架构图团队成员先看图再讨论。图能暴露很多文字描述里被掩盖的问题比如你这个模块 A 和模块 B 互相依赖图上看起来就是一个环。这种做法的副作用是Agent 画出来的图不一定符合团队约定俗成的规范比如某些团队喜欢把所有外部依赖画在右边某些团队习惯把数据流从左到右。我的建议是不要奢求初次生成完全符合团队规范而是把 archify 当成草稿纸先把逻辑关系画出来再按团队规范微调。它真正的价值是把大量机械绘图工作干掉让你把精力留在决策上。5.3 理解 skill、agent 与执行框架的关系边界用了大概一个月后我最大的体会是很多人把 skill、agent 和 harness 这三层东西混为一谈导致工具使用效率很低。简单说skill 是操作手册agent 是决策大脑harness 是执行骨架。archify 属于最外层的 skill它不负责智能决策只负责提供规范和流程。Agent 读了这个 skill 之后才知道该按什么路径执行而 harness 则在更底层处理工具调用循环和上下文管理。这个区分不是学术概念。你在排查 archify 的 bug 时如果问题出在模型决策上那是 agent 层的事如果问题出在技能没被正确加载那是 skill 层的事如果是工具调用总在固定节点崩掉那你要去看 harness 的日志。把它分层理解之后排错效率高很多。最后说一点个人实际使用后的感受。以前我觉得画架构图是设计师或架构师的活离开发者很远现在我觉得架构图更接近团队沟通的通用语言。archify 这类技能真正解放的不是画图的几十分钟而是强迫每个人在画图前想清楚边界和选型的那段时间。它把隐性知识外化成显性流程这对团队协作的价值比省下的一张图大得多。