如果你维护过一个超过半年、迭代了十几个版本的项目大概率经历过这样的场景文档里的架构图还是三个月前的单体结构代码仓库里却已经拆出了四五个微服务模块。新同事入职对着过期的架构图研究了半天最后只能默默打开代码自己捋。手动画架构图的真正痛点不是“画得不好看”而是维护成本高到没人愿意持续更新。draw.io、ProcessOn 这些工具解决的是“怎么画”的问题却没有解决“怎么让图跟上代码”的问题。现在 AI Agent 的能力越来越强已经有开发者开始用“Skill”机制让 AI 直接读代码、抽依赖、生成架构图。这篇文章不是教你用提示词让 AI 画一张示意图而是带你搭建一套可以复用、可以纳入团队工作流的架构图生成 Skill。读完你会明白真正值钱的不是“让 AI 画图”而是让 AI 按照统一的架构模型从真实代码中提取结构、生成规范化的架构视图。1. 这篇文章真正要解决的问题先下一个判断架构图问题本质上是信息同步问题而不是绘图问题。传统流程是“人读代码 → 人脑建模 → 手动绘图”这套流程有三个致命缺陷第一时效性差。开发平时要写业务代码、修 Bug、做 Code Review很少有人会专门在每次接口变更后去更新架构图。于是架构图的更新频率远远落后于代码变更频率。第二个人色彩重。每个人对“架构图”的理解不同。有人画部署架构有人画服务依赖有人画时序调用。不同人画出来的图信息粒度和表达方式完全不一样团队协作时沟通成本很高。第三验证成本高。画好的架构图怎么确认它和当前代码一致靠人肉抽查。但大型项目的调用关系非常多人工抽查很难覆盖全面。那 AI Skill 方案改变了什么它改变了流程的前半段。不再是“人读代码、人脑建模”而是“AI 读代码、AI 提取关系、AI 生成规范图、人做审查”。人在这个流程中只做两件事定义规范、审查结果。这两件事恰恰是机器不擅长、而人最擅长的事情。这篇文章适合谁主要是三类读者正在维护中大型项目的后端工程师需要定期输出架构文档。团队里负责技术规范、想推广 AI 工具链的架构师或技术 Leader。对 Agent Skill 机制感兴趣想看看它能落地到什么程度的 AI 应用开发者。如果你只是偶尔画一张系统示意图这篇文章里提到的方案会显得“过重”。但如果你需要持续维护团队架构文档这套思路可以直接复用。2. 什么是 Skill为什么它适合生成架构图2.1 从“对话式 AI”到“流程式 AI”普通用户接触 AI 编程助手时习惯是“给它一段提示词它给你一段回答”。这种对话式交互适合一次性问题但不适合需要稳定重复执行的任务。Skill 是 Agent 体系里的一种能力封装机制。它把一个特定任务涉及的行为规范、执行步骤、约束条件、脚本工具打包成一个结构化单元。当 Agent 识别到当前任务匹配某个 Skill 时会按照 Skill 里的定义去执行而不是自由发挥。通俗理解普通提示词是“你告诉 AI 做什么”Skill 是“你告诉 AI 遇到这类任务时应该按什么流程、什么标准、什么格式去做”。2.2 SKILL.md 是核心入口在主流 Agent Skill 设计里一个 Skill 通常包含两部分一个SKILL.md文件描述技能名称、适用场景、执行步骤、输入输出约定。可选的辅助脚本或资源文件用于执行需要确定性逻辑的操作。以 Claude Agent Skill 为例工作区中一个 Skill 的典型目录结构如下skills/ architecture-diagram/ SKILL.md scripts/ extract_structure.py verify_mermaid.py当 Agent 被分配到与“生成架构图”相关的任务时它会读取SKILL.md按照里面定义的流程来行动。2.3 为什么 Skill 机制适合架构图场景架构图生成任务有一个特点输入是固定的代码目录过程是确定的读代码、抽依赖、建模、出图输出是有规范约束的图表语法、分层规则、命名规则。这种任务非常适合用 Skill 来固化原因有三点行为可预期。同一份代码无论谁发起任务AI 都会按照同一套规范输出不会今天画成流程图、明天画成部署图。知识可沉淀。团队对架构表达的规范可以直接写进SKILL.md新人使用同样流程也能输出符合团队标准的架构图。结果可验证。Skill 可以携带校验脚本比如检查 Mermaid 语法是否合法、检查是否包含分层标记把“画图”从玄学变成工程。如果只看表面很多人会误以为“Skill 就是预设好的提示词”。实际上Skill 的价值在于它把行为约定、执行步骤和确定性校验三者组合在了一起这正是生成架构图这种半结构化任务所需要的。3. 架构图的“代码逻辑”三种表达方式怎么选在进入实操前先解决一个基础问题AI 生成的架构图应该用什么格式输出架构图的表达方式不止一种各有适用场景。这里对比三种主流方式表达方式优点缺点典型场景Mermaid语法简单、Git 友好、支持流程图/时序图/类图复杂布局能力有限服务依赖图、系统概览、CI 文档内嵌PlantUML图形元素丰富、支持多种 UML 图语法相对繁琐、中文字体容易出问题UML 类图、时序图、部署图draw.io XML与桌面/网页绘图工具无缝配套XML 冗长、人工编辑困难需要后续手工微调、对排版要求高的图从“让 AI 自动生成并持续维护”这个角度看我的建议是优先选 Mermaid 作为默认输出格式。原因很简单Mermaid 是文本格式可以直接放进 Markdown 文档、GitLab/GitHub 渲染也可以被 diff。Mermaid 语法对 AI 来说非常友好生成的准确率高很少出现结构性错误。Mermaid 可以直接嵌入 Confluence、Notion 或团队 Wiki无需额外安装绘图软件。如果你想表达更复杂的 UML 关系比如类之间的继承、组合、聚合可以升级到 PlantUML。但大多数项目的架构概览Mermaid 的flowchart和graph已经完全够用。另外推荐在 Skill 中引入 C4 模型思路。C4 模型把架构图分成四个层次Context系统上下文、Container容器、Component组件、Code代码。生成架构图时不要试图在一张图里画完所有信息而是根据读者角色选择层级。例如给产品经理看Context 层只需要项目与外部系统的交互。给运维看Container 层展示服务、数据库、消息队列等部署单元。给开发看Component 层展示模块内部的主要组件和调用关系。在 SKILL.md 里明确“默认输出哪个层级”可以避免 AI 把不相关细节堆进一张图。4. 环境准备跑通一个能读代码的 Agent本文所有示例的操作思路不绑定特定工具版本。以当前主流 Agent 编程工具为例你需要准备以下环境支持 Skill 机制的 AI Agent 工具如 Claude 系产品或支持自定义 Skill 的编程助手。Git 命令行工具用于代码仓库克隆和变更对比。Python 3 环境用于运行结构提取和校验脚本。一个可以访问的目标项目代码库建议先用中小型项目测试。这里需要说明不同工具的 Skill 目录结构和加载方式有差异。如果你用的是 Claude Code通常是在项目根目录创建.claude/skills/目录如果用其他编程助手可能是在配置目录下创建。本文重点演示通用结构实际路径以你所用工具的官方文档为准。一个最小可用的 Skill 工作区结构如下your-project/ .claude/ skills/ architecture-diagram/ SKILL.md scripts/ extract_structure.py render_mermaid.py不需要额外安装中间件。Skill 里的脚本只做两件事遍历代码目录结构、生成 Mermaid 文本。真正理解和建模交给 Agent 完成。如果你使用的是不支持自定义 Skill 的通用对话式 AI也可以把SKILL.md的内容作为提示词模板粘贴给 AI 使用效果会打折扣但核心思路不变。5. 核心流程拆解从代码目录到架构图一次完整的“AI 边读代码边出图”过程可以拆成五个步骤。这五个步骤不是随意排列的每一步都对应一个容易出错的环节。5.1 定位代码范围第一步告诉 AI 要分析哪个目录、哪些文件。不要直接扔整个仓库给 AI尤其是大型项目。合理的做法是限定在核心业务模块先梳理主链路。如果 AI 工具支持代码索引或仓库上下文可以明确指定扫描路径例如src/main/java/com/example/order。这一步决定后续建模的边界。5.2 读代码与提取结构AI 会读取指定目录下的源码文件重点关注服务类、接口类的定义。方法之间的调用关系。依赖注入如 Spring 的Autowired、Resource。数据库访问层的实体和仓储接口。对外暴露的 HTTP 接口Controller 层。关键点在于不要让 AI 只数文件要让它区分“架构关键元素”和“实现细节”。类是架构元素某一行字符串拼接不是。在 Skill 里必须明确这句话否则 AI 会把大量无关信息写进图里。5.3 建模与分层提取完结构后AI 需要按 C4 分层思想组织信息系统与外部系统有哪些交互。项目内部有哪些部署单元服务、数据库、缓存。每个部署单元内部有哪些主要组件。组件之间是什么调用关系。这一步是整条链路里最难约束的。建议在 SKILL.md 里给一个固定的建模模板让 AI 按照模板输出中间结果再由脚本转成 Mermaid。5.4 生成架构图AI 根据建模结果生成 Mermaid 代码。这里容易踩坑的是AI 生成的 Mermaid 语法偶尔不完整比如节点之间存在未定义关系或引用了不存在的节点。所以需要脚本做一次语法校验。5.5 校验与迭代最后用校验脚本检查 Mermaid 语法同时检查是否符合 Skill 里定义的命名规范。如果校验失败AI 根据错误信息修正如果通过把结果写入项目文档。整体流程可以用一句话概括AI 负责理解和建模脚本负责确定性和校验人负责审查和决策。6. 完整示例一个可复制的“架构图 Skill”下面给出一个可以直接复制到项目里试用的骨架。再次强调这不是某个特定产品的现成 Skill 源码而是一个通用实现思路你需要根据所用工具做少量调整。6.1 创建 SKILL.md文件路径.claude/skills/architecture-diagram/SKILL.md--- name: architecture-diagram description: 分析指定代码目录输出当前代码架构的 Mermaid 架构图。 --- # 架构图生成 Skill ## 适用场景 当用户要求分析项目代码并生成架构图时使用。 ## 执行流程 1. 定位作用域 - 询问或确认要分析的代码目录。 - 如果用户未指定默认分析当前目录下 src/ 主目录。 2. 提取结构 - 读取目标目录下源码文件。 - 提取以下元素 - Controller / API 接口 - Service 服务类 - Repository / DAO 数据访问层 - 外部依赖第三方 API、中间件、数据库 - 忽略纯工具类、常量类、测试代码、配置样例。 3. 建模分层 - 先确定系统边界当前代码是否与其他系统交互。 - 再确定容器层服务、数据库、缓存、消息队列。 - 最后确定组件层每个服务内部的主要模块。 4. 生成 Mermaid - 使用 flowchart LR 作为默认方向。 - 每个节点命名规则模块名_组件名如 order_service。 - 使用 subgraph 表达分层关系。 - 只保留架构相关调用关系不展示方法级细节。 5. 校验和输出 - 调用 scripts/render_mermaid.py 校验生成的 Mermaid 语法。 - 输出最终架构图代码。6.2 编写校验脚本文件路径.claude/skills/architecture-diagram/scripts/render_mermaid.py#!/usr/bin/env python3 校验并尽量渲染 Mermaid 图文本。 import re import sys def validate_mermaid(text: str) - list: 对 Mermaid 文本做基础结构检查返回错误列表。 errors [] if not text.strip().startswith(flowchart) and not text.strip().startswith(graph): errors.append(Mermaid 必须以 flowchart 或 graph 开头) if text.count(--) 0 and text.count(---) 0: errors.append(图中未发现任何关系连线) # 检查是否存在只定义未引用的孤立节点 defined set(re.findall(r\b([A-Za-z_][A-Za-z0-9_]*)\[, text)) referenced set( re.findall(r--\|?([A-Za-z_][A-Za-z0-9_]*)\|?\[, text) ) | set( re.findall(r\|?([A-Za-z_][A-Za-z0-9_]*)\|?\[, text) ) for node in defined: if node not in referenced: errors.append(f节点 {node} 可能未被任何关系引用) return errors def main(): if len(sys.argv) 2: print(用法: python render_mermaid.py mermaid_file) sys.exit(1) with open(sys.argv[1], r, encodingutf-8) as f: content f.read() errors validate_mermaid(content) if errors: print(校验失败:) for err in errors: print(f - {err}) sys.exit(1) print(校验通过Mermaid 代码可正常渲染。) if __name__ __main__: main()这个脚本的逻辑很简单检查 Mermaid 是否以flowchart或graph开头、是否包含关系连线、是否包含孤立节点。实际使用时可以在此基础上接入 Mermaid 官方的语法解析器做更严格的检查。6.3 生成架构图的调用示例文件路径.claude/skills/architecture-diagram/examples/request.md请使用 architecture-diagram Skill分析当前仓库中 src/main/java 目录下的代码生成一张系统架构图。 要求 1. 按 C4 的 Container 层组织图的内容。 2. 只展示服务、数据库、消息队列、外部系统之间的调用关系。 3. 输出 Mermaid 格式保存到 docs/architecture.md。实际使用中你可以直接在 Agent 对话窗口里输入类似这样的请求。Agent 读到 Skill 后会按照SKILL.md里的流程执行。6.4 为什么这套结构比“提示词”更稳定这里真正容易踩坑的地方是AI 在没有约束的情况下生成架构图时经常“自由发挥”。比如你提出“画一张架构图”它可能画成 UML 类图也可能画成部署图因为“架构图”本身是个模糊概念。而 Skill 把“架构图”明确成了分析src/目录、提取 Controller/Service/Repository、按容器层建模、输出flowchart LR。这几条约束一加上输出结果就稳定得多。脚本的价值同样不可忽视。如果只靠提示词AI 生成 Mermaid 后你还需要自己复制到渲染器里检查语法。有了校验脚本AI 在输出前就会自动纠正部分错误。7. 运行结果与效果验证运行这套 Skill 时你期望看到的结果是一个可渲染的 Mermaid 代码块。以一个小型订单服务项目为例可行的验证路径如下。7.1 运行命令在 Agent 中发起任务后Skill 会自动执行以下等效流程# 查看当前代码根目录结构 find src/main/java -type f -name *.java | head -20 # 运行结构提取脚本示例实际脚本按需实现 python scripts/extract_structure.py --path src/main/java --output /tmp/structure.json # 将生成的 Mermaid 文本保存为文件 cat docs/architecture.md EOF # 系统架构图 mermaid flowchart LR subgraph 客户端 app[前端应用] end subgraph 服务端 api[OrderController] -- svc[OrderService] svc -- repo[OrderRepository] end subgraph 数据层 db[(MySQL)] mq[RabbitMQ] end app -- api repo -- db svc -- mq EOF EOF # 校验 Mermaid 语法 python scripts/render_mermaid.py docs/architecture.md7.2 判断成功标准Agent 输出的结果包含完整的flowchartMermaid 代码。图中节点包含 Controller、Service、Repository 等分层信息。图中没有出现无意义节点比如某个类名拼写错误。校验脚本输出“校验通过”。你能在支持 Mermaid 的文档平台中正常渲染出图。7.3 失败时先看哪里如果生成的架构图不对按以下顺序排查看 SKILL.md 是否被加载。可以在对话里直接问 Agent“你是否加载了 architecture-diagram Skill”如果没加载说明目录结构或配置不对。看代码目录有没有选对。很多情况下 AI 默认分析了整个仓库导致信息量过大图显得很乱。解决方法是在请求里写明路径。看建模模板有没有生效。检查输出图是否包含subgraph分层。如果没有说明 SKILL.md 中的建模约束没有被严格遵循可以在请求中补充。8. 常见问题与排查方法在实际使用中新接触这套方案的开发者最常遇到下面几类问题。问题现象可能原因排查方式解决方案Agent 完全不执行 Skill 流程Skill 目录放错位置检查工具文档确认 Skill 加载路径将 Skill 放入正确的 skills 目录并重启会话生成的图信息量过大、杂乱没有限定分析目录观察输出节点数量在请求中明确指定具体模块目录图里出现大量工具类、常量类建模模板未说明忽略规则查看 SKILL.md 是否有过滤说明在提取结构步骤中补充“忽略无状态工具类”Mermaid 渲染时报错语法不完整或节点名包含特殊字符运行校验脚本定位错误在脚本中加入特殊字符清洗逻辑中文字体乱码或显示异常渲染平台不支持中文字体在渲染平台查看字体设置使用英文节点名中文内容放入 subgraph 标签多次生成结果结构不稳定Skill 约束不足对比两次输出图的差异在 SKILL.md 中补充更严格的建模模板生成的图中存在循环依赖但显示错误循环依赖导致渲染异常检查 Mermaid 是否支持该渲染方向将循环依赖关系单独标注或用文档说明这里补充一个容易被忽略的点Mermaid 对节点名的要求比较严格。如果你的代码里有类名包含.或-直接作为节点 ID 会导致解析错误。校验脚本中可以做一层清洗把非法字符替换为下划线。import re def clean_node_id(name: str) - str: # 将点号和横线等非法字符替换为下划线 return re.sub(r[^a-zA-Z0-9_], _, name)9. 最佳实践与工程建议9.1 一次只画一个层级最常犯的错误是让 AI 在一张图里既画部署架构、又画组件依赖、还画方法调用。正确做法是参考 C4 模型一个任务只输出一个层级的图。想画系统上下文就只关注系统边界想画容器层就只关注服务、数据库、中间件想画组件层才深入代码目录。这个约束写进 SKILL.md能显著提高图的可用性。9.2 把 Skill 纳入团队仓库Skill 不是个人工具它应该和项目代码一起管理。当团队对架构表达达成共识后把SKILL.md和脚本放进项目仓库所有成员在同一套规范下生成架构图输出才能保持一致。同时建议在README中写清使用场景减少团队成员的试错成本。9.3 控制 AI 的读取权限架构图生成任务只需要 AI 读取代码不需要它修改代码。在使用 Agent 工具时尽量把权限限制为只读。尤其是不要给 Agent 大范围的自动执行权限避免它在生成架构图时顺便“修复”了某个不该动的文件。安全性方面如果项目涉及敏感信息还应该确认 AI 工具的代码读取机制是否符合公司的数据合规要求。9.4 与代码变更流程结合起来手动画架构图的问题在于“更新滞后”。AI 生成架构图的价值不在于某一次帮你画好而在于它把更新成本降到了足够低。当代码发生较大结构调整时重新运行 Skill几分钟就能得到一份与当前代码一致的架构图。更进一步可以在 CI 流程中加入“架构漂移检查”用 Skill 生成新架构图对比旧架构图如果差异超出阈值提醒维护者更新文档。不过这个方案依赖团队已有的 CI 体系初期不建议直接引入先把单次生成跑通再说。9.5 保留人工审查环节AI 生成架构图再快也不能替代架构师判断。原因很简单架构图不只是代码事实的投影还包含设计意图。某个服务之间存在依赖代码里能看出来但为什么这样设计、后续准备怎么演进代码里看不出来。所以最合理的分工是AI 负责“事实层”快速准确地输出代码结构人负责“意图层”在 AI 输出上补充背景、标注风险和演进方向。两者结合架构图才真正有价值。10. 总结与下一步实践方向这篇文章不是要告诉你“AI 已经能自动画架构图了”而是想帮你理清一个更准确的判断AI 真正改变的是架构图的维护成本而不是绘图本身的成本。我们要解决的核心问题从来不是“图怎么画得好看”而是“代码变了、文档没跟上”的资源错配。Skill 机制把读代码、建模型、出图、校验这一系列动作固化成了可复用流程让架构图从一份启动时画一次的死文档变成一个可以随时重跑的活文档。如果你准备动手尝试建议按这个路径实践找一个中小型项目不要一开始就挑战超大仓库。按照文章第 6 节的骨架搭一个最小可用 Skill。先让 AI 生成一次 Container 层架构图人工审查补充遗漏。跑通后再逐步增加组件层、校验脚本和团队规范。后续可以继续深入的方向包括结合 PlantUML 处理更复杂的 UML 关系、把架构图与 CI 变更检查打通、支持多模块聚合项目的增量分析。对于已经用 AI 辅助编程的团队这个 Skill 可以算是一个低成本、高回报的尝试。它不改变你的技术栈也不要求团队重构流程只是把“人肉更新架构图”这件没人愿意做的事交给了更适合它的 AI。建议收藏备用下个项目迭代时直接试一试。 用AI Skill从代码自动生成架构图：告别手动维护
如果你维护过一个超过半年、迭代了十几个版本的项目大概率经历过这样的场景文档里的架构图还是三个月前的单体结构代码仓库里却已经拆出了四五个微服务模块。新同事入职对着过期的架构图研究了半天最后只能默默打开代码自己捋。手动画架构图的真正痛点不是“画得不好看”而是维护成本高到没人愿意持续更新。draw.io、ProcessOn 这些工具解决的是“怎么画”的问题却没有解决“怎么让图跟上代码”的问题。现在 AI Agent 的能力越来越强已经有开发者开始用“Skill”机制让 AI 直接读代码、抽依赖、生成架构图。这篇文章不是教你用提示词让 AI 画一张示意图而是带你搭建一套可以复用、可以纳入团队工作流的架构图生成 Skill。读完你会明白真正值钱的不是“让 AI 画图”而是让 AI 按照统一的架构模型从真实代码中提取结构、生成规范化的架构视图。1. 这篇文章真正要解决的问题先下一个判断架构图问题本质上是信息同步问题而不是绘图问题。传统流程是“人读代码 → 人脑建模 → 手动绘图”这套流程有三个致命缺陷第一时效性差。开发平时要写业务代码、修 Bug、做 Code Review很少有人会专门在每次接口变更后去更新架构图。于是架构图的更新频率远远落后于代码变更频率。第二个人色彩重。每个人对“架构图”的理解不同。有人画部署架构有人画服务依赖有人画时序调用。不同人画出来的图信息粒度和表达方式完全不一样团队协作时沟通成本很高。第三验证成本高。画好的架构图怎么确认它和当前代码一致靠人肉抽查。但大型项目的调用关系非常多人工抽查很难覆盖全面。那 AI Skill 方案改变了什么它改变了流程的前半段。不再是“人读代码、人脑建模”而是“AI 读代码、AI 提取关系、AI 生成规范图、人做审查”。人在这个流程中只做两件事定义规范、审查结果。这两件事恰恰是机器不擅长、而人最擅长的事情。这篇文章适合谁主要是三类读者正在维护中大型项目的后端工程师需要定期输出架构文档。团队里负责技术规范、想推广 AI 工具链的架构师或技术 Leader。对 Agent Skill 机制感兴趣想看看它能落地到什么程度的 AI 应用开发者。如果你只是偶尔画一张系统示意图这篇文章里提到的方案会显得“过重”。但如果你需要持续维护团队架构文档这套思路可以直接复用。2. 什么是 Skill为什么它适合生成架构图2.1 从“对话式 AI”到“流程式 AI”普通用户接触 AI 编程助手时习惯是“给它一段提示词它给你一段回答”。这种对话式交互适合一次性问题但不适合需要稳定重复执行的任务。Skill 是 Agent 体系里的一种能力封装机制。它把一个特定任务涉及的行为规范、执行步骤、约束条件、脚本工具打包成一个结构化单元。当 Agent 识别到当前任务匹配某个 Skill 时会按照 Skill 里的定义去执行而不是自由发挥。通俗理解普通提示词是“你告诉 AI 做什么”Skill 是“你告诉 AI 遇到这类任务时应该按什么流程、什么标准、什么格式去做”。2.2 SKILL.md 是核心入口在主流 Agent Skill 设计里一个 Skill 通常包含两部分一个SKILL.md文件描述技能名称、适用场景、执行步骤、输入输出约定。可选的辅助脚本或资源文件用于执行需要确定性逻辑的操作。以 Claude Agent Skill 为例工作区中一个 Skill 的典型目录结构如下skills/ architecture-diagram/ SKILL.md scripts/ extract_structure.py verify_mermaid.py当 Agent 被分配到与“生成架构图”相关的任务时它会读取SKILL.md按照里面定义的流程来行动。2.3 为什么 Skill 机制适合架构图场景架构图生成任务有一个特点输入是固定的代码目录过程是确定的读代码、抽依赖、建模、出图输出是有规范约束的图表语法、分层规则、命名规则。这种任务非常适合用 Skill 来固化原因有三点行为可预期。同一份代码无论谁发起任务AI 都会按照同一套规范输出不会今天画成流程图、明天画成部署图。知识可沉淀。团队对架构表达的规范可以直接写进SKILL.md新人使用同样流程也能输出符合团队标准的架构图。结果可验证。Skill 可以携带校验脚本比如检查 Mermaid 语法是否合法、检查是否包含分层标记把“画图”从玄学变成工程。如果只看表面很多人会误以为“Skill 就是预设好的提示词”。实际上Skill 的价值在于它把行为约定、执行步骤和确定性校验三者组合在了一起这正是生成架构图这种半结构化任务所需要的。3. 架构图的“代码逻辑”三种表达方式怎么选在进入实操前先解决一个基础问题AI 生成的架构图应该用什么格式输出架构图的表达方式不止一种各有适用场景。这里对比三种主流方式表达方式优点缺点典型场景Mermaid语法简单、Git 友好、支持流程图/时序图/类图复杂布局能力有限服务依赖图、系统概览、CI 文档内嵌PlantUML图形元素丰富、支持多种 UML 图语法相对繁琐、中文字体容易出问题UML 类图、时序图、部署图draw.io XML与桌面/网页绘图工具无缝配套XML 冗长、人工编辑困难需要后续手工微调、对排版要求高的图从“让 AI 自动生成并持续维护”这个角度看我的建议是优先选 Mermaid 作为默认输出格式。原因很简单Mermaid 是文本格式可以直接放进 Markdown 文档、GitLab/GitHub 渲染也可以被 diff。Mermaid 语法对 AI 来说非常友好生成的准确率高很少出现结构性错误。Mermaid 可以直接嵌入 Confluence、Notion 或团队 Wiki无需额外安装绘图软件。如果你想表达更复杂的 UML 关系比如类之间的继承、组合、聚合可以升级到 PlantUML。但大多数项目的架构概览Mermaid 的flowchart和graph已经完全够用。另外推荐在 Skill 中引入 C4 模型思路。C4 模型把架构图分成四个层次Context系统上下文、Container容器、Component组件、Code代码。生成架构图时不要试图在一张图里画完所有信息而是根据读者角色选择层级。例如给产品经理看Context 层只需要项目与外部系统的交互。给运维看Container 层展示服务、数据库、消息队列等部署单元。给开发看Component 层展示模块内部的主要组件和调用关系。在 SKILL.md 里明确“默认输出哪个层级”可以避免 AI 把不相关细节堆进一张图。4. 环境准备跑通一个能读代码的 Agent本文所有示例的操作思路不绑定特定工具版本。以当前主流 Agent 编程工具为例你需要准备以下环境支持 Skill 机制的 AI Agent 工具如 Claude 系产品或支持自定义 Skill 的编程助手。Git 命令行工具用于代码仓库克隆和变更对比。Python 3 环境用于运行结构提取和校验脚本。一个可以访问的目标项目代码库建议先用中小型项目测试。这里需要说明不同工具的 Skill 目录结构和加载方式有差异。如果你用的是 Claude Code通常是在项目根目录创建.claude/skills/目录如果用其他编程助手可能是在配置目录下创建。本文重点演示通用结构实际路径以你所用工具的官方文档为准。一个最小可用的 Skill 工作区结构如下your-project/ .claude/ skills/ architecture-diagram/ SKILL.md scripts/ extract_structure.py render_mermaid.py不需要额外安装中间件。Skill 里的脚本只做两件事遍历代码目录结构、生成 Mermaid 文本。真正理解和建模交给 Agent 完成。如果你使用的是不支持自定义 Skill 的通用对话式 AI也可以把SKILL.md的内容作为提示词模板粘贴给 AI 使用效果会打折扣但核心思路不变。5. 核心流程拆解从代码目录到架构图一次完整的“AI 边读代码边出图”过程可以拆成五个步骤。这五个步骤不是随意排列的每一步都对应一个容易出错的环节。5.1 定位代码范围第一步告诉 AI 要分析哪个目录、哪些文件。不要直接扔整个仓库给 AI尤其是大型项目。合理的做法是限定在核心业务模块先梳理主链路。如果 AI 工具支持代码索引或仓库上下文可以明确指定扫描路径例如src/main/java/com/example/order。这一步决定后续建模的边界。5.2 读代码与提取结构AI 会读取指定目录下的源码文件重点关注服务类、接口类的定义。方法之间的调用关系。依赖注入如 Spring 的Autowired、Resource。数据库访问层的实体和仓储接口。对外暴露的 HTTP 接口Controller 层。关键点在于不要让 AI 只数文件要让它区分“架构关键元素”和“实现细节”。类是架构元素某一行字符串拼接不是。在 Skill 里必须明确这句话否则 AI 会把大量无关信息写进图里。5.3 建模与分层提取完结构后AI 需要按 C4 分层思想组织信息系统与外部系统有哪些交互。项目内部有哪些部署单元服务、数据库、缓存。每个部署单元内部有哪些主要组件。组件之间是什么调用关系。这一步是整条链路里最难约束的。建议在 SKILL.md 里给一个固定的建模模板让 AI 按照模板输出中间结果再由脚本转成 Mermaid。5.4 生成架构图AI 根据建模结果生成 Mermaid 代码。这里容易踩坑的是AI 生成的 Mermaid 语法偶尔不完整比如节点之间存在未定义关系或引用了不存在的节点。所以需要脚本做一次语法校验。5.5 校验与迭代最后用校验脚本检查 Mermaid 语法同时检查是否符合 Skill 里定义的命名规范。如果校验失败AI 根据错误信息修正如果通过把结果写入项目文档。整体流程可以用一句话概括AI 负责理解和建模脚本负责确定性和校验人负责审查和决策。6. 完整示例一个可复制的“架构图 Skill”下面给出一个可以直接复制到项目里试用的骨架。再次强调这不是某个特定产品的现成 Skill 源码而是一个通用实现思路你需要根据所用工具做少量调整。6.1 创建 SKILL.md文件路径.claude/skills/architecture-diagram/SKILL.md--- name: architecture-diagram description: 分析指定代码目录输出当前代码架构的 Mermaid 架构图。 --- # 架构图生成 Skill ## 适用场景 当用户要求分析项目代码并生成架构图时使用。 ## 执行流程 1. 定位作用域 - 询问或确认要分析的代码目录。 - 如果用户未指定默认分析当前目录下 src/ 主目录。 2. 提取结构 - 读取目标目录下源码文件。 - 提取以下元素 - Controller / API 接口 - Service 服务类 - Repository / DAO 数据访问层 - 外部依赖第三方 API、中间件、数据库 - 忽略纯工具类、常量类、测试代码、配置样例。 3. 建模分层 - 先确定系统边界当前代码是否与其他系统交互。 - 再确定容器层服务、数据库、缓存、消息队列。 - 最后确定组件层每个服务内部的主要模块。 4. 生成 Mermaid - 使用 flowchart LR 作为默认方向。 - 每个节点命名规则模块名_组件名如 order_service。 - 使用 subgraph 表达分层关系。 - 只保留架构相关调用关系不展示方法级细节。 5. 校验和输出 - 调用 scripts/render_mermaid.py 校验生成的 Mermaid 语法。 - 输出最终架构图代码。6.2 编写校验脚本文件路径.claude/skills/architecture-diagram/scripts/render_mermaid.py#!/usr/bin/env python3 校验并尽量渲染 Mermaid 图文本。 import re import sys def validate_mermaid(text: str) - list: 对 Mermaid 文本做基础结构检查返回错误列表。 errors [] if not text.strip().startswith(flowchart) and not text.strip().startswith(graph): errors.append(Mermaid 必须以 flowchart 或 graph 开头) if text.count(--) 0 and text.count(---) 0: errors.append(图中未发现任何关系连线) # 检查是否存在只定义未引用的孤立节点 defined set(re.findall(r\b([A-Za-z_][A-Za-z0-9_]*)\[, text)) referenced set( re.findall(r--\|?([A-Za-z_][A-Za-z0-9_]*)\|?\[, text) ) | set( re.findall(r\|?([A-Za-z_][A-Za-z0-9_]*)\|?\[, text) ) for node in defined: if node not in referenced: errors.append(f节点 {node} 可能未被任何关系引用) return errors def main(): if len(sys.argv) 2: print(用法: python render_mermaid.py mermaid_file) sys.exit(1) with open(sys.argv[1], r, encodingutf-8) as f: content f.read() errors validate_mermaid(content) if errors: print(校验失败:) for err in errors: print(f - {err}) sys.exit(1) print(校验通过Mermaid 代码可正常渲染。) if __name__ __main__: main()这个脚本的逻辑很简单检查 Mermaid 是否以flowchart或graph开头、是否包含关系连线、是否包含孤立节点。实际使用时可以在此基础上接入 Mermaid 官方的语法解析器做更严格的检查。6.3 生成架构图的调用示例文件路径.claude/skills/architecture-diagram/examples/request.md请使用 architecture-diagram Skill分析当前仓库中 src/main/java 目录下的代码生成一张系统架构图。 要求 1. 按 C4 的 Container 层组织图的内容。 2. 只展示服务、数据库、消息队列、外部系统之间的调用关系。 3. 输出 Mermaid 格式保存到 docs/architecture.md。实际使用中你可以直接在 Agent 对话窗口里输入类似这样的请求。Agent 读到 Skill 后会按照SKILL.md里的流程执行。6.4 为什么这套结构比“提示词”更稳定这里真正容易踩坑的地方是AI 在没有约束的情况下生成架构图时经常“自由发挥”。比如你提出“画一张架构图”它可能画成 UML 类图也可能画成部署图因为“架构图”本身是个模糊概念。而 Skill 把“架构图”明确成了分析src/目录、提取 Controller/Service/Repository、按容器层建模、输出flowchart LR。这几条约束一加上输出结果就稳定得多。脚本的价值同样不可忽视。如果只靠提示词AI 生成 Mermaid 后你还需要自己复制到渲染器里检查语法。有了校验脚本AI 在输出前就会自动纠正部分错误。7. 运行结果与效果验证运行这套 Skill 时你期望看到的结果是一个可渲染的 Mermaid 代码块。以一个小型订单服务项目为例可行的验证路径如下。7.1 运行命令在 Agent 中发起任务后Skill 会自动执行以下等效流程# 查看当前代码根目录结构 find src/main/java -type f -name *.java | head -20 # 运行结构提取脚本示例实际脚本按需实现 python scripts/extract_structure.py --path src/main/java --output /tmp/structure.json # 将生成的 Mermaid 文本保存为文件 cat docs/architecture.md EOF # 系统架构图 mermaid flowchart LR subgraph 客户端 app[前端应用] end subgraph 服务端 api[OrderController] -- svc[OrderService] svc -- repo[OrderRepository] end subgraph 数据层 db[(MySQL)] mq[RabbitMQ] end app -- api repo -- db svc -- mq EOF EOF # 校验 Mermaid 语法 python scripts/render_mermaid.py docs/architecture.md7.2 判断成功标准Agent 输出的结果包含完整的flowchartMermaid 代码。图中节点包含 Controller、Service、Repository 等分层信息。图中没有出现无意义节点比如某个类名拼写错误。校验脚本输出“校验通过”。你能在支持 Mermaid 的文档平台中正常渲染出图。7.3 失败时先看哪里如果生成的架构图不对按以下顺序排查看 SKILL.md 是否被加载。可以在对话里直接问 Agent“你是否加载了 architecture-diagram Skill”如果没加载说明目录结构或配置不对。看代码目录有没有选对。很多情况下 AI 默认分析了整个仓库导致信息量过大图显得很乱。解决方法是在请求里写明路径。看建模模板有没有生效。检查输出图是否包含subgraph分层。如果没有说明 SKILL.md 中的建模约束没有被严格遵循可以在请求中补充。8. 常见问题与排查方法在实际使用中新接触这套方案的开发者最常遇到下面几类问题。问题现象可能原因排查方式解决方案Agent 完全不执行 Skill 流程Skill 目录放错位置检查工具文档确认 Skill 加载路径将 Skill 放入正确的 skills 目录并重启会话生成的图信息量过大、杂乱没有限定分析目录观察输出节点数量在请求中明确指定具体模块目录图里出现大量工具类、常量类建模模板未说明忽略规则查看 SKILL.md 是否有过滤说明在提取结构步骤中补充“忽略无状态工具类”Mermaid 渲染时报错语法不完整或节点名包含特殊字符运行校验脚本定位错误在脚本中加入特殊字符清洗逻辑中文字体乱码或显示异常渲染平台不支持中文字体在渲染平台查看字体设置使用英文节点名中文内容放入 subgraph 标签多次生成结果结构不稳定Skill 约束不足对比两次输出图的差异在 SKILL.md 中补充更严格的建模模板生成的图中存在循环依赖但显示错误循环依赖导致渲染异常检查 Mermaid 是否支持该渲染方向将循环依赖关系单独标注或用文档说明这里补充一个容易被忽略的点Mermaid 对节点名的要求比较严格。如果你的代码里有类名包含.或-直接作为节点 ID 会导致解析错误。校验脚本中可以做一层清洗把非法字符替换为下划线。import re def clean_node_id(name: str) - str: # 将点号和横线等非法字符替换为下划线 return re.sub(r[^a-zA-Z0-9_], _, name)9. 最佳实践与工程建议9.1 一次只画一个层级最常犯的错误是让 AI 在一张图里既画部署架构、又画组件依赖、还画方法调用。正确做法是参考 C4 模型一个任务只输出一个层级的图。想画系统上下文就只关注系统边界想画容器层就只关注服务、数据库、中间件想画组件层才深入代码目录。这个约束写进 SKILL.md能显著提高图的可用性。9.2 把 Skill 纳入团队仓库Skill 不是个人工具它应该和项目代码一起管理。当团队对架构表达达成共识后把SKILL.md和脚本放进项目仓库所有成员在同一套规范下生成架构图输出才能保持一致。同时建议在README中写清使用场景减少团队成员的试错成本。9.3 控制 AI 的读取权限架构图生成任务只需要 AI 读取代码不需要它修改代码。在使用 Agent 工具时尽量把权限限制为只读。尤其是不要给 Agent 大范围的自动执行权限避免它在生成架构图时顺便“修复”了某个不该动的文件。安全性方面如果项目涉及敏感信息还应该确认 AI 工具的代码读取机制是否符合公司的数据合规要求。9.4 与代码变更流程结合起来手动画架构图的问题在于“更新滞后”。AI 生成架构图的价值不在于某一次帮你画好而在于它把更新成本降到了足够低。当代码发生较大结构调整时重新运行 Skill几分钟就能得到一份与当前代码一致的架构图。更进一步可以在 CI 流程中加入“架构漂移检查”用 Skill 生成新架构图对比旧架构图如果差异超出阈值提醒维护者更新文档。不过这个方案依赖团队已有的 CI 体系初期不建议直接引入先把单次生成跑通再说。9.5 保留人工审查环节AI 生成架构图再快也不能替代架构师判断。原因很简单架构图不只是代码事实的投影还包含设计意图。某个服务之间存在依赖代码里能看出来但为什么这样设计、后续准备怎么演进代码里看不出来。所以最合理的分工是AI 负责“事实层”快速准确地输出代码结构人负责“意图层”在 AI 输出上补充背景、标注风险和演进方向。两者结合架构图才真正有价值。10. 总结与下一步实践方向这篇文章不是要告诉你“AI 已经能自动画架构图了”而是想帮你理清一个更准确的判断AI 真正改变的是架构图的维护成本而不是绘图本身的成本。我们要解决的核心问题从来不是“图怎么画得好看”而是“代码变了、文档没跟上”的资源错配。Skill 机制把读代码、建模型、出图、校验这一系列动作固化成了可复用流程让架构图从一份启动时画一次的死文档变成一个可以随时重跑的活文档。如果你准备动手尝试建议按这个路径实践找一个中小型项目不要一开始就挑战超大仓库。按照文章第 6 节的骨架搭一个最小可用 Skill。先让 AI 生成一次 Container 层架构图人工审查补充遗漏。跑通后再逐步增加组件层、校验脚本和团队规范。后续可以继续深入的方向包括结合 PlantUML 处理更复杂的 UML 关系、把架构图与 CI 变更检查打通、支持多模块聚合项目的增量分析。对于已经用 AI 辅助编程的团队这个 Skill 可以算是一个低成本、高回报的尝试。它不改变你的技术栈也不要求团队重构流程只是把“人肉更新架构图”这件没人愿意做的事交给了更适合它的 AI。建议收藏备用下个项目迭代时直接试一试。