接手一个中型微服务项目时最难的不是写业务代码而是先搞清楚系统里到底有哪些模块、它们之间怎么调用、数据流往哪个方向走。过去我会打开 draw.io新建一个空白画布然后开始拖框、拉线、填文字。说实话拖框本身很快真正慢的是画每一笔之前的大脑操作这个服务依赖哪个服务这个模块在代码里对应哪个目录这条线是同步调用还是异步消息这些问题不解决画出来的架构图只能骗自己。后来我换了一个思路不再把 AI 当成“问答工具”而是把它当成一个能读代码、能总结依赖、能输出图源的实习生。核心动作也不是写一段 Prompt 让它画图而是设计一个“Skill”——一套有输入、有处理步骤、有输出格式、有约束的指令流程让 AI 边读代码边出图。这样做的价值不是省掉拖框那几分钟而是把“从代码到架构认知”的整个流程变成可复用、可审查、可迭代的工作流。1. 先搞清楚大多数架构图难产不是因为不会用画图软件1.1 画图的真正成本在代码理解不在鼠标拖拽很多人以为架构图画得慢是因为工具操作不熟练。实际上一个熟悉 draw.io 或 ProcessOn 的人画二十个方框加二十条线熟练的话十分钟就能完成。真正昂贵的是“决定画什么”的过程这个服务到底有哪些对外接口它依赖了哪些外部中间件订单模块和支付模块之间的调用是 Feign 还是 RestTemplate定时任务、消息消费者、事件订阅这些非显性调用要不要画进图里这些问题都需要去读代码、查依赖、搜关键词。手动画图时这一步通常发生在脑海里画出来的结果只是把理解变成了图形。如果代码理解不到位图画得再漂亮也是错的。所以我越来越觉得画架构图的效率瓶颈不在“画图”这个动作而在“读代码”这个环节。谁能更快、更准确地读代码并提炼模块关系谁就能更快地产出架构图。1.2 人画图的顺序和 AI 画图的顺序不一样人画图时通常先有一个整体认知系统可以分成几层、几个核心域然后再细化到每个服务的依赖关系。这种“自上而下”的方式适合已经对系统有了解的人。AI 读代码出图路径其实更像“自下而上”先读目录结构再读关键文件识别模块边界最后把依赖关系聚合成图。如果直接让 AI “画一下整个系统架构图”它大概率会给出一个看起来很完整、但经不起细看的图。原因很简单没有限定分析范围也没有给 AI 一套稳定的处理步骤。这里就是 Skill 值得出现的地方。它不是为了取代人的架构判断而是把 AI 读代码时的动作标准化先做什么、后做什么、遇到不确定的地方怎么处理、最后输出成什么格式。标准化的结果是你每次拿它处理新项目时行为模式是一致的而不是每次重新想 Prompt。1.3 这个阶段 Skill 能提供什么预设上下文和输出协议如果只是临时让 AI 读一次代码那写 Prompt 就够了。但如果你希望团队里每个成员都能用同样的方式产出架构草图或者希望这个能力可以被反复调用那就需要把它封装成一个 Skill。一个典型的 Skill 包含几个部分功能描述这个 Skill 是干什么的适合在什么场景触发。输入要求需要用户提供什么信息比如仓库路径、要分析的重点模块、是否包含部署关系。处理步骤先读什么再总结什么最后输出什么。输出格式图源用什么语法、文字说明写到什么程度、不确定项怎么标注。约束不要修改代码、不要编造依赖、不要输出超出范围的模块。把这个结构写清楚后AI 就不再是“随机状态下的对话助手”而是一个带有工作协议的代码分析器。2. 我理解的 Skill一套可复用的 AI 工作流封装2.1 从 prompt 到 skill差异在哪里很多人会觉得 Skill 不就是把一段 Prompt 保存下来吗这样说也不算错但 Skill 的颗粒度通常更重。一段 Prompt 可能只解决一次具体任务帮我看看这几个类之间的关系。而一个 Skill 要解决一类重复任务任意给定一个代码仓库自动分析模块结构生成可维护的架构图源文件。从工程经验看两者的差异有三个方面稳定性Skill 有明确的处理步骤AI 不会因为换了一种问法就跳过关键环节。可维护性Skill 文件可以放在仓库里改一次全团队生效。可测试性你可以在多个项目上运行同一个 Skill比较输出质量再持续修正。所以我更愿意把 Skill 理解成“AI 的流程模板”而不是“写给 AI 的提示词”。它真正的价值在于把一次不可控的对话变成接近半自动化的流程。2.2 一个最小“读代码出架构图”Skill 的设计假设我们要设计一个名为code-architect的 Skill不需要做成插件只要是一个 Markdown 或 YAML 文件放进 AI 编程工具支持的规则目录即可。这里给出一个示例结构实际落地时你可以按自己用的工具调整格式name: code-architect description: 分析代码仓库的模块结构生成 Mermaid 架构图。 when_to_use: 用户要求生成系统架构图、依赖关系图、模块划分图时触发。 input: allowed_params: - target_path: 要分析的仓库路径或目录 - focus_area: 可选只分析某个模块/服务 - include_deployment: 可选是否包含部署组件 steps: 1. 读取 target_path 的目录结构优先查看 README、package 描述文件、pom.xml/go.mod 等。 2. 根据目录命名和入口文件识别模块边界。 3. 分析模块之间的 import、调用、消息队列、HTTP 客户端等依赖关系。 4. 汇总成模块清单和依赖清单。 5. 在不确定时标注 unclear不要编造关系。 output: format: markdown sections: - 模块清单 - 核心调用链 - Mermaid graph TD 代码块 - 待确认问题 constraints: - 不要修改任何源文件。 - 不要输出与代码事实不符的关系。 - 如果仓库过大先按目录层级分批分析。这个示例的核心不是命令本身而是它把 AI 的输出路径固定住了。你会发现真正决定输出质量的不是“请认真分析”这句话而是“先做什么、再做什么、拿不准怎么标注”这些流程约束。2.3 为什么选择 Mermaid 而不是直接生成图片在架构图场景里我强烈建议让 AI 输出 Mermaid 语法而不是让它直接生成一张图片。原因有几个Mermaid 是纯文本图源Git 能直接 diff审查和回滚都方便。生成图片需要额外渲染能力不是所有 AI 工具都能稳定产出高质量图片。文本图源可以继续交给 AI 修改加一个模块、删一条线都是文字操作。Mermaid 可以导入 draw.io 等工具再做精细调整流程是通的。很多 “架构图软件” 也支持从文本生成图但 Mermaid 生态更轻量几乎不需要安装很多文档平台和编辑器都内置支持。2.4 需要区分这不等同于让 AI“看一眼就懂架构”还要泼一盆冷水AI 读代码出图不是真的“看懂”了整个系统它更像是基于静态代码里的目录、调用关系、配置关键字做一个大概率推断。对于动态注册的接口、运行时反射、外部配置中心下发路由这些情况静态分析本身就有盲区。所以正确使用方式是把 AI 的产出当作“初稿”和“提取器”而不是最终结论。你需要拿着 AI 生成的模块清单对照真实的调用链做抽检再决定哪些线要保留、哪些线是误导。3. 实操从零开始让 AI 边读代码边出图3.1 准备一份最小可用的 Skill 文件如果你用的是支持自定义 Skill 的编程工具可以直接新建一个 Skill 文件如果暂时不支持也可以把下面的内容复制到项目根目录的说明文件里作为 AI 对话时的上下文规则。一个最小可用的版本可以这样写这里展示的是 Markdown 结构# Skill: code-architect ## 目标 给定一个代码仓库分析其模块边界和核心依赖生成 Mermaid 架构图。 ## 执行步骤 1. 先查看仓库根目录读取 README 或项目描述文件。 2. 列出顶层目录判断哪些是业务模块、哪些是基础设施、哪些是部署配置。 3. 对每个业务模块读取其核心入口文件、对外接口或用例目录。 4. 搜索模块之间的调用关系例如 import 语句、HTTP 客户端、消息生产者/消费者。 5. 整理成模块清单、调用关系清单。 6. 输出 Mermaid graph TD 代码块不要省略节点。 7. 对不确定的依赖关系输出到“待确认”小节不要编造。 ## 输出格式 - 模块清单表格包含模块名、对应目录、职责摘要。 - 调用关系列表格式为 A - B原因。 - Mermaid 代码图源。 - 待确认不确定项。这个文件不依赖某个特定产品它体现的是“让 AI 按照稳定流程工作”的思路。你完全可以根据自己的项目调整步骤。3.2 用一个小型项目先跑通不要一上来就丢一个巨型微服务仓库给 AI。我的建议是先找一个规模可控的项目比如由五六个模块组成的后端服务或中间件项目。跑通的标准不是“AI 成功输出一张图”而是AI 能按步骤执行而不是跳步。模块清单和目录结构基本对应。Mermaid 代码能直接渲染。待确认项被单独列出没有混入正式图里。第一次跑通后再逐步增加复杂度。如果你一开始就让 AI 分析几百个服务大概率会遇到上下文超限、输出混乱、关系遗漏这些问题。3.3 分步输出先模块总览再依赖关系再细节图我推荐把架构图分成三个层级而不是一步到位生成一张大图L1系统模块总览。只画顶层模块或服务不画内部细节。L2核心依赖关系。画出模块之间的主要调用链可以按业务链路分段。L3单模块细节。某个具体服务内部类与类或接口与实现的关系。这样做的好处是每一层图都足够小便于 AI 控制和人工 review。很多人一上来就要一张“全图”结果生成的图要么过大要么信息过载根本没法看。实际落地时可以让 AI 先输出 L1 和 L2L3 由你在需要时针对单个模块继续发问。3.4 示例一套可以复制的指令模板如果还没封装成 Skill也可以直接用下面这段指令效果接近请阅读当前仓库先不要写任何代码。 第一步查看仓库根目录和 README列出顶层目录。 第二步根据目录和关键入口文件识别业务模块。 第三步找出模块之间的依赖方式包括 import、HTTP 调用、消息队列。 第四步输出一个 Mermaid graph TD节点为模块名连线为依赖关系。 第五步对你不确定的关系统一放到“待确认”小节不要直接画到图上。这段指令看起来朴素但比“帮我画个架构图”要稳定得多。核心在于你给 AI 规定了读代码的顺序和输出协议。4. 参数、边界和常见坑单次跑通不等于稳定好用4.1 为什么 AI 生成的架构图看起来“很对”但逻辑有问题我也遇到过这种情况AI 输出的架构图结构完整模块划分看起来也合理但一比对实际代码就发现某条依赖关系根本不对。常见原因有三个。第一上下文窗口限制。AI 可能只读了部分文件尤其是仓库很大时它只看了顶层目录和几个入口文件就根据命名惯性补全了关系。第二把注释和文档当成事实。代码里写着“A 调用 B”但实际可能已经改成消息队列或者 A 里只有一段早已注释掉的代码。第三静态分析天然看不到运行时行为。比如服务发现、路由规则、动态代理这些不是简单 grep 能搞清楚的。所以无论 AI 生成的图有多顺眼都必须有人工校验环节。架构图不是代码生成结果它是决策产物需要人来负责。4.2 最容易踩的四个坑从实操来看有四个坑出现频率最高一次性让 AI 生成全量架构图。结果节点多到无法渲染关系也严重遗漏。没有限定分析范围。AI 把构建目录、测试目录、文档目录都当成业务模块图里混入大量噪声。混淆逻辑架构和部署架构。图里既有服务模块又有 MySQL、Redis、Nginx层次关系说不清楚。缺少“待确认”机制。AI 把所有依赖都画得言之凿凿实际上有些关系它根本没验证。这四个坑的本质是输入边界和输出协议没有设计好。Skill 文件里的 constraints 部分就是用来约束这些行为的。4.3 检查与修正横纵两层验证我自己常用两层验证法推荐你参考。纵向验证看模块划分是否和代码目录一致。每个模块在图中对应一个节点那么它在仓库里应当有一个相对独立的目录或服务入口。如果图里有一个“认证中心”但代码里找不到对应目录那这个模块很可能是 AI 根据上下文推测出来的。横向验证看调用关系是否在代码里有迹可循。A 指向 B那么 A 的代码里应该有调用 B 的接口、依赖坐标或消息主题。如果找不到任何痕迹就要把这条线移到待确认或者删除。这两层验证不需要查遍所有文件抽核心链路即可。重点检查那些会影响理解的关键路径比如支付回调、订单状态流转、消息幂等处理。4.4 如果 AI 没有输出图先按这个顺序排查遇到 AI 没有输出图、输出不完整或渲染失败时不要急着重发指令。按下面的顺序逐层排查排查层检查内容常见处理输入是否给足了仓库路径、重点模块、范围限制补充输入说明缩小任务范围上下文仓库文件是否过大AI 是否只读了一部分拆成多个子任务按模块逐一分析指令是否明确要求输出 Mermaid 代码块在指令里写明“输出 Mermaid graph TD”环境Mermaid 渲染器是否支持当前语法用 mermaid.live 或本地插件验证完整性输出图源是否有未闭合节点、中文引号等错误检查节点 id 是否重复标签是否规范这个排查顺序不一定覆盖所有情况但至少能把大多数问题定位到某一层。如果每层都检查过还是不行就要考虑是不是 AI 工具本身对仓库内文件访问权限有限制。5. 进阶把单次能力沉淀成一个团队可用的“架构图 Skill”5.1 沉淀流程从一次对话到一个可复用资产很多时候我们会在一次对话里把 Prompt 调得越来越好但关掉窗口就全忘了。下次另一个同事接手项目又要从零开始试。这种浪费可以通过沉淀 Skill 来避免。我的建议流程是先在一次对话里手动写清步骤验证能稳定产出可接受的架构图。把成功的那段指令整理成 Skill 文件去掉和具体项目强相关的内容抽象成通用描述。加入输出协议和约束Mermaid 格式、模块清单模板、待确认机制。把 Skill 文件放入仓库的docs/skills目录或团队统一维护的 AI 规则目录。每次在真实项目上使用后把暴露出来的问题回填进 Skill 的约束里。这样Skill 就不再是一次性 Prompt而是一份会持续进化的团队资产。5.2 团队使用时的几条约定如果团队里多人都会用 AI 辅助画架构图建议先立几条规定所有由 AI 生成的架构图必须在文档里标注“AI 生成人工校验”。这不是甩锅而是维护信息可信度。输出统一用 Markdown Mermaid避免有人贴图片、有人贴 draw.io 文件导致没法对比和复用。模块命名优先使用代码里的目录名或服务名不要另起一套业务叫法否则图对不上代码。待确认项必须有人跟进不能长期挂在那里。否则图里会留下大量不确定性。这些约定看起来不复杂但能显著降低团队协作成本。AI 擅长生成人负责确认两者要明确分工。5.3 和其他工具链结合Skill 产出的是文本和 Mermaid 图源这意味着它可以接入很多常见工具链Mermaid 代码可以直接渲染到文档站、WIKI、Markdown 笔记里。draw.io 支持从文本布局生成图形可以导入后再做可视化调整。CI 脚本可以检查 Mermaid 语法防止团队文档里出现渲染失败的图。后续还可以把架构图和代码变更联动让 AI 只更新受影响的部分。从工程角度看只要坚持“文本图源”这一原则架构图的生成、维护、审查就都可以纳入现有流程而不是变成独立的一次性成果。5.4 适用边界什么场景建议用什么场景不建议这个方案不是万能的。我自己会把适用场景分为三类。建议使用新接手一个存量项目想快速得到模块总览。架构评审前需要一张可讨论的依赖关系草图。模块重构前梳理当前调用链找出潜在影响面。团队成员不确定某个服务边界时用 AI 生成初稿作为讨论基础。不建议使用需要像素级精美、面向客户的架构图。AI 生成初稿后还是建议用专业绘图工具精修。系统规模极大、服务数量上百且调用关系复杂。此时应先用脚本或平台工具导出真实拓扑AI 适合做补充分析而不是全量画图。涉及内部敏感信息、不能外泄代码片的场景。需要确认 AI 工具的数据处理方式不满足安全要求就不要用。如果发现 AI 生成的图越来越像“正确的废话”说明这个场景不适合靠 AI 出图应该回到真实运行时数据去找拓扑。6. 最后想说的真正值钱的不是“自动画图”而是把判断过程沉淀下来用 Skill 让 AI 边读代码边出图这件事最吸引人的不是“省了手动拖框”而是它逼着我们把“如何从代码里识别架构”这件事变成明文的流程。过去架构师脑子里有一套隐性的读代码方法先看目录、再看入口、然后追调用链。这套方法很难传递新人只能靠自己摸索。而 Skill 可以把这套方法外化成文件让 AI 按路径执行也让每个同事都能看到原来生成架构图之前需要先做模块识别、依赖提取、不确定项标注。我觉得这比“AI 能不能自动画图”更重要。画图只是一个输出动作真正值钱的是你知道该让 AI 先读什么、按什么顺序处理、拿不准时怎么处理。这套判断过程一旦被沉淀成 Skill就不会因为你换了个项目、换了个工具而失效。如果你也想试建议不要从大项目开始。挑一个你自己比较熟的中小型仓库先写好上面那份最小指令让 AI 按步骤输出模块清单和 Mermaid 图。然后对照你已知的判断看看它哪里读对了、哪里读错了再把教训写回 Skill 文件里。大概迭代几次之后你会发现让 AI 出架构图这件事不再取决于运气而是取决于你把自己的经验封装得有多清楚。