不知道你有没有遇到过这样的场景项目做了一两年代码越堆越多团队文档里那张架构图还停留在上个季度甚至去年。新人入职想快速了解系统长什么样你只能打开 draw.io 或者 ProcessOn对着目录结构一个一个拖框、拉线、调样式好不容易画完了代码评审一过图又过时了。这种“手动拖框画架构图”的方式在单体小项目里还能凑合一旦涉及微服务、领域拆分、多模块协作人肉维护架构图基本等于给自己挖坑。而架构图这东西恰恰是微服务架构图、业务架构图、系统架构图这类需求里最容易被反复提及的“高频刚需”。本文想分享一个更省力的思路借助 AI 编程助手的 Skill 机制让 AI 自己读取代码仓库分析模块依赖直接生成架构图描述并渲染成图。整个过程不需要你手动拖任何框。1. 为什么需要让 AI 边读代码边出图1.1 架构图的真正价值很多人对架构图的理解还停留在“画给别人看的示意图”实际上架构图是开发和协作过程中的核心沟通语言。系统规模变大以后没有人能靠记忆掌握全部模块的关系新同学 onboarding 需要靠图快速建立全局认知做技术评审时需要靠图对齐边界排查线上问题时也需要靠图定位调用链。架构图不应该是一张“一次性产出、后续靠人肉同步”的静态文档而应该是和代码库保持同步的“活文档”。可惜大多数团队做不到这一点因为手动维护的成本太高了。1.2 手动绘制的主要痛点第一个痛点是图和代码脱节。画完的架构图放在 wiki 里代码重构后没有人记得去更新三个月后图就成了“历史文物”不仅没有价值还会误导人。第二个痛点是维护成本高。目录结构调整、模块拆合、依赖变更每一次都要重新拖框拉线。对于一个几十个模块的中型项目绘制和调整一张完整的架构图可能要花费一整天。第三个痛点是容易遗漏。代码里的隐式依赖、动态加载、反射调用靠人眼去看很容易漏掉而漏掉依赖关系的架构图反而会让读者产生错误的认知。第四个痛点是因人而异。不同人画的架构图粒度不一样有人画到服务层有人画到方法调用级没有统一标准导致每次接手都要重新理解。1.3 核心思路AI Agent Skill既然手动画图这么痛苦能不能让 AI 替我们读代码、找依赖、出架构图当然可以。AI Agent 本身具备阅读理解代码的能力但直接对模型说一句“帮我画架构图”结果往往不可控。它可能会漏掉某些目录或者输出格式五花八门。这时候就需要 Skill 机制出场。Skill 可以理解为一个“给 AI 安装的领域技能包”。你把架构分析的方法论、代码扫描的脚本、输出格式的约定都写进 Skill 里AI 在收到“分析架构”指令时就会按 Skill 定义的流程去执行先扫描代码再分析依赖最后输出统一格式的架构描述调用渲染脚本生成图片。这就是标题里说的“Skill 让 AI 边读代码边出图”。2. Skill 到底是什么2.1 Skill 与普通 Prompt 的区别很多人用过 Prompt比如在对话框里写一句“请分析一下当前项目的架构”这本质上是一次性指令。但 Skill 不一样它更像是一个“可复用的方法包”。Skill 不是简单的一句话而是一个包含指令、示例、脚本、规则的目录结构。AI 在读取 Skill 之后会按照里面定义的工作流去执行任务而不是临时根据一句 Prompt 自由发挥。举个例子普通 Prompt 是“帮我分析架构”AI 可能输出一段文字而 Skill 会规定“先运行 Python 脚本扫描依赖 - 读取依赖 JSON - 按分层规则归类 - 生成 DOT 格式图描述 - 调用 Graphviz 渲染 PNG”。每一步都是确定的、可重复的。2.2 Skill 的组成结构以 Claude Code 等 AI 编程工具为例一个 Skill 通常由下面几部分组成SKILL.mdSkill 的说明文件包含元信息name、description和具体执行指令。可选资源文件例如 Python 扫描脚本、分析规则、示例输出等。它的目录结构大致是这样.claude/skills/ └── code-architect/ ├── SKILL.md └── scripts/ └── analyze_structure.pyAI 在对话过程中会根据用户意图匹配description里描述的场景找到合适的 Skill然后读取SKILL.md中的指令来执行任务。2.3 Skill 能做什么Skill 的适用场景非常广不只是架构图。比如代码审查、单元测试生成、数据库脚本编写、API 文档整理都可以做成 Skill。拿架构图这个场景来说Skill 可以把“架构分析”这件事从“依赖模型临时发挥”变成“一套标准流程”。同一个 Skill 可以从 Python 项目复制到 Java 项目从单体项目复制到微服务项目只要有配套的扫描脚本AI 就能快速产出统一风格的架构图。3. 环境准备与版本说明3.1 本文演示环境本文以 Claude Code 作为 AI 编程助手进行演示辅助脚本使用 Python 3架构图渲染使用 Graphviz。示例项目是一个简化版的 Python 订单服务包含 API 层、Service 层、Repository 层和 Model 层。需要说明的是AI 编程客户端目前迭代速度比较快不同版本的 Skill 目录结构和配置项可能存在差异。本文重点演示的是“思路和流程”具体字段需要根据你使用的工具版本微调。3.2 安装 AI 编程助手如果你还没有安装 Claude Code可以按下面的命令安装。安装前需要确保本机有符合官方要求的 Node.js 环境。npm install -g anthropic-ai/claude-code安装完成后在项目目录下执行claude如果你是其他 AI 编程工具的用户例如 Codex CLI安装方式类似npm install -g openai/codex这里不展开聊具体工具的差异关键在于理解这类工具都支持让 AI 访问本地文件系统并执行命令这正是“读代码出图”的基础能力。3.3 准备一个示例项目为了演示我们先创建一个简化的电商订单服务项目目录结构如下order-service/ ├── api/ │ ├── __init__.py │ └── routes.py ├── service/ │ ├── __init__.py │ ├── order_service.py │ └── payment_service.py ├── repository/ │ ├── __init__.py │ ├── order_repo.py │ └── user_repo.py ├── models/ │ ├── __init__.py │ ├── order.py │ └── user.py └── main.py各模块之间有明确的调用关系main.py启动应用api/routes.py接收 HTTP 请求调用service层处理业务逻辑service层依赖repository层做数据访问repository层依赖models层定义的数据结构。这是一个典型的分层架构非常适合用来验证架构图生成效果。3.4 安装架构图渲染工具我们选择 Graphviz 作为渲染工具因为它支持命令行调用方便自动化。安装方式如下macOSbrew install graphvizUbuntu / Debiansudo apt-get install graphvizWindows 可以使用 wingetwinget install graphviz安装完成后执行dot -V能输出版本信息说明安装成功。4. 核心原理AI 如何“读懂”代码并画出架构图4.1 整体流程拆解让 AI 边读代码边出图核心流程可以拆成三步。第一步是扫描与收集。AI 遍历项目目录找出所有代码文件并提取文件之间依赖关系。这个步骤通常可以交给一个 Python 脚本完成AI 负责调用脚本并解释结果。第二步是架构抽象。AI 拿到依赖清单后根据目录结构、分层规则和模块命名把杂乱的文件依赖整理成有层次的架构关系。比如把api/下的文件归为接口层把service/下的文件归为业务层。第三步是图描述生成与渲染。AI 将架构关系输出为文本描述的图语言比如 DOT、Mermaid 或 PlantUML然后调用渲染工具生成 PNG、SVG 等图片文件。4.2 依赖识别的粒度选择在扫描代码时粒度直接影响图的可用性。如果直接分析到每一个文件一个中型项目可能生成上百个节点图根本没法看。所以更合理的策略是分粒度先按服务或模块画容器图再按包或目录画组件图按需深入到文件级别。Skill 里可以约定好默认粒度例如“优先按一级目录分析模块边界跨模块依赖用 import 关系标识同模块内文件依赖自动聚合”。4.3 常见语言的依赖提取规则不同编程语言的依赖表达方式不同Skill 里的扫描脚本需要针对语言做适配。下面是几种常见语言的依赖提取规则语言依赖表达方式示例Pythonimport/from ... import ...from service.order_service import OrderServiceJavaimport语句import com.example.service.OrderService;JavaScript / TypeScriptimport/requireimport { OrderService } from ./service/orderService;C / C#include指令#include order_service.hGoimport语句import example.com/project/service脚本的功能是把这些 import/include 关系提取出来转成统一的模块依赖 JSON。AI 再基于这个 JSON 做架构归纳。4.4 为什么选择文本图语言架构图的最终产物通常是图片但 AI 生成图片并不靠谱因为 AI 绘图模型很难精确排版复杂的架构图。更稳的做法是让 AI 生成“文本图语言”再由渲染工具生成图片。文本图语言的优势非常明显可版本化可以放进 Git 里做 diff可自动化一条命令就能渲染成 PNG/SVG可编辑不需要打开图形软件手动调整。Graphviz 的 DOT 语言就是一个典型例子。它的基本语法很简单digraph order_service { api/routes.py - service/order_service.py; service/order_service.py - repository/order_repo.py; }这类文本结构对 AI 来说非常容易生成因为本质上只是把依赖 JSON 转换成有向边的集合。4.5 AI 的架构抽象逻辑AI 拿到依赖清单后并不是简单地把每个文件都画成一个节点而是会做抽象归纳。比如识别出api/、service/、repository/、models/这些目录天然属于不同层然后按照层来分组。在分层架构中AI 还会去识别“跨层调用是否合理”。比如api层直接依赖了repository层这通常意味着代码结构有问题AI 可以在架构说明里标注出来。这就是“读代码出图”比“手动拖框”更有价值的地方它不仅能画图还能发现潜在的架构问题。5. 完整实战编写一个读代码出架构图的 Skill5.1 创建 Skill 目录在项目根目录下创建 Skill 目录mkdir -p .claude/skills/code-architect/scripts目录结构如下.claude/skills/code-architect/ ├── SKILL.md └── scripts/ └── analyze_structure.py5.2 编写 SKILL.mdSKILL.md是整个 Skill 的核心它告诉 AI 在收到“分析架构”指令时应该做什么。文件路径是.claude/skills/code-architect/SKILL.md。--- name: code-architect description: 分析当前代码仓库的模块结构和依赖关系生成架构图描述并渲染为图片。适用于系统架构图、微服务架构图、模块依赖图等场景。 --- # Code Architect Skill 当用户要求“分析架构”或“画出架构图”时按照以下流程执行。 ## 1. 扫描项目 运行下面的 Python 脚本扫描项目依赖 bash python3 .claude/skills/code-architect/scripts/analyze_structure.py .脚本会输出 JSON 格式的依赖关系例如{ api/routes.py: [service.order_service, service.payment_service], service/order_service.py: [repository.order_repo, models.order] }2. 架构分析根据依赖 JSON 和项目目录结构完成以下分析将文件按目录维度归类到不同层例如接口层、业务层、数据访问层、模型层。整理层与层之间的调用关系。标记不合理依赖例如业务层反向依赖接口层、接口层直接访问数据访问层。如果项目包含多个服务先按服务维度拆分再分析服务内部模块。3. 生成架构描述使用 DOT 语言输出架构图描述。生成规则每个分层使用 subgraph 表示颜色可以区分。节点使用“模块名”命名避免直接使用完整文件路径。跨层依赖使用有向边表示并标注依赖类型。示例digraph architecture { rankdirTB; subgraph cluster_api { label接口层; API Routes; } subgraph cluster_service { label业务层; Order Service; Payment Service; } API Routes - Order Service; API Routes - Payment Service; Order Service - Order Repo; Payment Service - User Repo; }4. 渲染图片将 DOT 描述保存为architecture.dot并调用 Graphviz 渲染dot -Tpng architecture.dot -o architecture.png dot -Tsvg architecture.dot -o architecture.svg渲染完成后向用户说明图片路径和架构分析结论。需要注意的是上面 SKILL.md 里包含了三个反引号的代码块这在文件中是正常的 Markdown 嵌套。我在这里用文字描述是为了方便阅读实际文件内容应该是一个完整的 Markdown 文档。 ### 5.3 编写 Python 扫描脚本 SKILL.md 中提到的 analyze_structure.py 脚本职责是扫描 Python 项目并提取依赖关系。文件路径是 .claude/skills/code-architect/scripts/analyze_structure.py。 python #!/usr/bin/env python3 扫描 Python 项目提取模块依赖关系输出 JSON。 import os import re import sys import json # 匹配 import xxx 或 from xxx import yyy IMPORT_RE re.compile( r^\s*(?:import|from)\s([\w.]), re.MULTILINE ) # 扫描时需要跳过的目录 SKIP_DIRS {.git, __pycache__, .venv, venv, node_modules, .idea, .vscode, dist, build} def scan_python_files(project_root): 返回项目下所有 .py 文件的相对路径列表。 py_files [] for dirpath, dirnames, filenames in os.walk(project_root): dirnames[:] [d for d in dirnames if d not in SKIP_DIRS] for filename in filenames: if filename.endswith(.py): full_path os.path.join(dirpath, filename) rel_path os.path.relpath(full_path, project_root) py_files.append(rel_path) py_files.sort() return py_files def extract_imports(filepath): 提取文件中所有 import 的顶层模块名。 try: with open(filepath, r, encodingutf-8, errorsignore) as f: content f.read() except OSError: return [] imports IMPORT_RE.findall(content) # 归一化模块名去重并排序 normalized set() for item in imports: parts item.split(.) top_module parts[0] if top_module not in (__future__, __main__): normalized.add(top_module) return sorted(normalized) def build_dependency_graph(project_root): 构建文件粒度的模块依赖图。 files scan_python_files(project_root) graph {} for rel_path in files: full_path os.path.join(project_root, rel_path) imports extract_imports(full_path) if imports: graph[rel_path] imports return graph def main(): project_root sys.argv[1] if len(sys.argv) 1 else . graph build_dependency_graph(project_root) print(json.dumps(graph, indent2, ensure_asciiFalse)) if __name__ __main__: main()这个脚本的核心逻辑不难理解scan_python_files负责递归查找.py文件extract_imports用正则提取依赖关系build_dependency_graph组装出文件 - 依赖模块的映射。当然这个脚本只处理了 Python 的静态 import对于动态导入和反射调用无能为力。这也是为什么需要 AI 参与AI 可以结合代码语义对脚本结果做出更合理的判断同时把缺漏标注出来。5.4 运行 Skill 让 AI 出图环境准备好之后在项目根目录启动交互式编程助手claude然后输入指令请使用 code-architect 技能分析当前项目的架构并生成架构图。正常情况下AI 会先读取.claude/skills/code-architect/SKILL.md识别出这是一个“架构分析”任务然后按 SKILL.md 中定义的流程执行运行扫描脚本根据 JSON 结果分析分层生成 DOT 描述调用dot命令渲染图片。5.5 查看生成的架构图AI 生成的 DOT 描述大致像下面这样digraph order_service { rankdirTB; subgraph cluster_api { label接口层; API Routes; } subgraph cluster_service { label业务层; Order Service; Payment Service; } subgraph cluster_repository { label数据访问层; Order Repo; User Repo; } subgraph cluster_models { label模型层; Order Model; User Model; } API Routes - Order Service; API Routes - Payment Service; Order Service - Order Repo; Payment Service - User Repo; Order Repo - Order Model; User Repo - User Model; }保存为architecture.dot后执行渲染命令dot -Tpng architecture.dot -o architecture.png dot -Tsvg architecture.dot -o architecture.svg渲染完成后项目目录下会出现architecture.png和architecture.svg两个文件。打开图片就能看到一张分层清晰的架构图并且这张图是从当前代码实时生成的和代码保持一致。6. 常见问题与排查思路在实际使用中Skill 出图过程可能会遇到一些问题。下面整理几个高频问题。问题现象常见原因解决思路AI 找不到 SkillSkill 目录路径不正确或SKILL.md里的name、description写得不够明确检查.claude/skills/目录结构确认name字段和用户指令能匹配上依赖扫描结果为空Python 脚本没有执行权限或项目目录传错手动运行python3 .../analyze_structure.py .验证脚本输出生成的图太大看不懂粒度太细每个文件都成为一个节点修改 SKILL.md让 AI 先按目录聚合模块再输出依赖关系非 Python 项目无法扫描analyze_structure.py只匹配了.py文件扩展脚本支持 Java、JS、Go 等语言的 import/include 提取或在 SKILL.md 中约定让 AI 直接分析目录结构AI 生成的 DOT 语法报错模型拼写错误或节点名包含特殊字符在 SKILL.md 中增加示例并对节点名做转义处理敏感代码不宜上传当前 AI 服务使用云端模型代码可能被发送至外部 API使用私有化部署模型或先在脱敏副本上分析其中需要着重说明的是最后一个问题。代码仓库往往包含业务核心逻辑和敏感配置在使用任何云端 AI 编程助手时都应该先确认代码是否允许上传。如果团队对代码合规要求很高可以选用支持私有化部署的模型或者用脱敏后的目录结构图做架构梳理而不是直接分析原始代码。7. 最佳实践与工程建议7.1 按粒度分层出图架构图不是越详细越好。建议参考 C4 模型的思想把架构图分成几个层级。系统上下文图描述整个系统与外部系统的关系适合给产品和跨团队同事看容器图描述服务、数据库、消息队列等部署单元适合运维和架构评审组件图描述服务内部的模块划分适合开发人员代码级图只在需要分析具体调用链时使用不建议高频生成。在 Skill 设计上可以把粒度作为参数传给 AI比如“画出组件级架构图”和“画出容器级架构图”使用不同的分析策略。7.2 Skill 指令要写具体Skill 的质量很大程度上取决于SKILL.md的指令质量。模糊的指令比如“分析项目结构”会让 AI 无所适从明确到“扫描哪些目录、过滤哪些文件、按什么规则分层、输出什么格式”才能保证结果稳定。建议在 SKILL.md 里加入一两个输出示例并把可能出错的边界情况写清楚。AI 编程模型的指令遵循能力比想象中强只要给了明确的示例生成结果的格式一致性会大幅提升。7.3 用 CI 自动更新架构图既然架构图可以通过命令行生成那就可以把它接入 CI/CD 流程。比如在代码合并到主干后自动触发架构图生成任务把最新的 SVG 文件提交到文档仓库或者上传到内部知识库。这样做的好处是架构图永远和代码保持同步团队不再需要“专门抽时间维护架构图”。需要注意的是CI 里运行 Skill 需要配好 AI 工具的 API 凭证和项目权限并且要处理好输出文件的版本管理避免每次构建都产生无效 diff。7.4 安全边界与权限控制让 AI 读取代码并执行命令本质上等于把本地开发环境的部分控制权交给了模型。因此在安全层面有几条原则值得遵守。第一只在经过授权的项目中使用这类 Skill不要在包含敏感信息的私人仓库里乱跑第三方的 Skill 包。第二扫描脚本中的目录过滤规则要尽量完善避免把node_modules、.venv这类无关目录扫进去。第三如果使用了云端模型建议在团队内部明确哪些仓库可以交给 AI 分析哪些仓库必须由人工处理。7.5 让 Skill 真正成为团队资产架构图 Skill 做成之后不要只放在个人电脑上。可以把整个.claude/skills/code-architect目录提交到团队的代码仓库这样新同事 clone 项目后立刻就能用同一个 Skill 生成架构图风格统一流程一致。更进一步可以把常见的架构评审规则也写进 Skill例如“禁止业务层反向依赖接口层”“禁止循环依赖”等。AI 在出图的同时可以顺带输出一份架构健康检查报告。这样“画架构图”这个动作就不再只是画图而变成了一次自动化的架构巡检价值高出一个层级。如果你也受够了手动拖框画架构图不妨按本文的思路花半小时写一个属于自己的架构图 Skill。下一次要出图的时候你只需要敲一行指令剩下的交给 AI。