Skill机制让AI自动读代码生成架构图，代码分析到可视化一步到位

最近很多团队开始用 Claude Code、Codex 这类 AI 编程助手处理代码库分析任务，但实际用下来发现一个问题：让 AI 总结代码逻辑、列依赖关系还行，一旦要“画架构图”，就变成它输出一堆描述，你还是得手动拖框、连线、调布局。这次我们来看一种新的解决思路——通过 Skill 机制，让 AI 边读代码边出图，直接把结果落在 Mermaid、Draw.io、PlantUML 这类架构图文件里。

先给结论：这个方案的核心不是某个现成的“画图软件”，而是一套给 AI Agent 用的“技能包”设计思路。你可以把它理解成给 Claude Code / Codex / Cursor 等编程助手装上一个“架构师外挂”，它会先扫描项目目录、识别模块依赖、生成调用关系，再按你指定的图类型输出架构图文档。整体运行不依赖高配 GPU，普通开发机即可，适合本地代码库、微服务项目、单体应用改造前的结构梳理。

本文会完整演示：Skill 是什么、如何设计一个自动读代码并出架构图的 Skill、怎么在本地装上跑通、如何拿真实项目验证效果，以及批量处理多个仓库的方法。如果你正在做老项目迁移、新同学 onboarding、代码评审前的模块梳理，这篇文章可以直接收藏。

1. 核心能力速览

从规格能看到，这个方向不再依赖“人手一个画图软件”，而是把“读代码—分析关系—出图—改图”全部交给 Agent 完成。你只需要定义清楚要什么粒度的图、什么格式、输出到哪个目录。

2. 适用场景与使用边界

Skill 自动画架构图最适合下面几类情况：

• 老项目接手：不知道十几个模块之间怎么调用的，让 AI 先扫一遍，生成模块依赖图。
• 微服务改造：Service 数量多、调用关系复杂，先生成服务级架构图，再决定拆分方向。
• 代码评审：评审前让 AI 生成本次改动涉及模块的架构影响图，方便讨论。
• 技术文档建设：架构图直接以 Mermaid / Draw.io 文件落到 docs 目录，后续可持续维护。
• 新成员 onboarding：通过自动生成的架构说明，快速了解项目全貌。

需要注意使用边界。Skill 自动生成的架构图更适合“模块级”“服务级”“文件目录级”的宏观展示，不适合逐行代码级别的调用可视化，因为提示词窗口和模型理解能力都有限。另外一个实际问题：如果项目里有大量自动生成代码、第三方依赖、加密混淆业务逻辑，AI 的分析结果可能出现偏差，架构图需要人工校核后使用。

合规方面也要重视。这个方案会读取本地代码并发送给编程助手的大模型接口处理，涉及公司私有代码、未公开商业项目、敏感业务逻辑时，必须先确认使用的模型服务是否符合内部数据安全规范。生成包含业务块的架构图、文档时，同样要注意数据脱敏和访问控制。

3. 环境准备与前置条件

开始之前，先准备一套最小环境。以下版本要求按常见实践给出，实际以你本机工具版本为准。

3.1 基础环境清单

3.2 检查本机环境

node -v python --version git --version

确认安装完成后，再确认你使用的编程助手 CLI 可用。以 Claude Code 为例：

claude --version

如果还没有登录，按提示登录并授权。这一步完成后，环境基本就绪。

3.3 一个测试用的示例项目

为了后面验证效果，可以先准备一个结构清晰的小项目，比如 Python 的 FastAPI 项目，或者 Node.js 的 Express 项目。以 Python 项目为例，常见结构如下：

sample-app/ ├── app/ │ ├── __init__.py │ ├── main.py │ ├── api/ │ │ ├── __init__.py │ │ ├── routers/ │ │ └── schemas/ │ ├── core/ │ │ ├── config.py │ │ └── security.py │ ├── models/ │ ├── services/ │ └── db/ ├── tests/ ├── requirements.txt └── README.md

目录层级清晰的项目，最适合观察 Skill 的输出质量。如果你的项目很大，建议先单独复制出一个小模块做测试，避免首次执行时间过长。

4. 架构图 Skill 方案设计

这一节是核心。所谓 Skill，本质上是一种结构化的“技能指令包”：它告诉 AI 要做什么、按什么步骤做、输出什么格式、放在哪里。我们不需要从零训练模型，只需要设计一套让 Agent 乖乖执行的规则。

4.1 Skill 目录结构

在 Claude Code 中，Skill 通常放在~/.claude/skills/或项目级.claude/skills/目录。这里我们先设计一个名为architecture-mapper的 Skill：

~/.claude/skills/architecture-mapper/ ├── SKILL.md ├── examples/ │ ├── system-overview.md │ └── service-dependency.md └── scripts/ └── analyze_imports.py

SKILL.md是核心文件，里面写了整个任务的执行规则。examples/放输出样板，让 AI 照着参考格式输出。scripts/放辅助脚本，比如统计 Python 文件 import 关系的脚本。

4.2 SKILL.md 示例

下面是一个可直接改用的 SKILL.md 模板。它定义了这个 Skill 的“职责边界”和“执行流程”。

--- name: architecture-mapper description: 自动扫描项目代码目录，分析模块、服务、依赖关系，生成架构图文档。 --- # Architecture Mapper 你是一个资深架构师，负责把代码库结构转换成清晰的架构图。 ## 适用输入 - 用户提供项目路径 - 用户指定输出格式（mermaid / plantuml / drawio） - 用户指定架构层级（系统级 / 服务级 / 模块级） ## 执行步骤 1. 使用 ls / find 命令查看项目根目录结构。 2. 识别主要编程语言、框架、入口文件。 3. 读取关键配置文件（package.json、requirements.txt、go.mod 等）。 4. 扫描源码目录，记录模块之间的 import / require / include 关系。 5. 按依赖关系整理出模块清单和调用方向。 6. 生成架构图文档，建议先输出 Mermaid 文本。 7. 对复杂调用关系，补充文字说明，标注风险点。 ## 输出要求 - 所有输出保存到 docs/architecture/ 目录。 - 文件名格式：architecture-overview.md、service-dependency.md。 - Mermaid 代码块可以直接被 Markdown 渲染。 - 若项目包含数据库，额外输出数据表关系说明。 - 对不确定的依赖关系，明确标注“需要人工确认”，不得臆造。 ## 注意事项 - 不分析虚拟环境目录（node_modules、venv、.venv、dist、build）。 - 不读取二进制文件、锁文件、密钥文件。 - 只做结构和依赖分析，不修改源代码。

这份SKILL.md的效果是：把“画架构图”从模糊需求变成明确的、可复用的执行协议。AI 每次触发该 Skill，都会按照同样的步骤去扫描、分析、输出。

4.3 辅助脚本示例

如果项目文件较多，可以让 Skill 先调用一个本地 Python 脚本来做 import 统计，再把结果喂给大模型。这一步能显著减少 token 消耗，也让分析更有依据。

下面是一个 Python 依赖扫描脚本示例，仅供参考，需要按实际项目结构调整：

import os import re import sys from collections import defaultdict def scan_python_imports(root_dir, ignore_dirs=None): if ignore_dirs is None: ignore_dirs = {'node_modules', 'venv', '.venv', 'dist', 'build', '__pycache__'} module_files = defaultdict(list) dependency_graph = defaultdict(set) for foldername, subdirs, filenames in os.walk(root_dir): subdirs[:] = [d for d in subdirs if d not in ignore_dirs] for filename in filenames: if filename.endswith('.py'): filepath = os.path.join(foldername, filename) try: with open(filepath, 'r', encoding='utf-8') as f: content = f.read() imports = re.findall( r'^\s*(?:from|import)\s+([a-zA-Z0-9_\.]+)', content, re.MULTILINE ) module_files[filename].append(filepath) for imp in imports: top_module = imp.split('.')[0] dependency_graph[filename].add(top_module) except Exception as e: print(f'[skip] {filepath}: {e}', file=sys.stderr) print('=== 文件分布 ===') for name, paths in sorted(module_files.items()): print(f'{name}: {len(paths)} 处定义') print('\n=== 依赖关系 ===') for name, deps in sorted(dependency_graph.items()): print(f'{name}: {", ".join(sorted(deps))}') if __name__ == '__main__': target_dir = sys.argv[1] if len(sys.argv) > 1 else '.' scan_python_imports(target_dir)

运行方式：

python scripts/analyze_imports.py /path/to/sample-app

脚本的好处是让“读代码”这一步不依赖模型对每个文件的逐一阅读，直接从静态扫描得到结构关系，再交给 AI 组织成架构图。

5. 安装部署与启动方式

5.1 安装 Skill 到 Claude Code

把上面的architecture-mapper目录放到全局 Skills 目录：

mkdir -p ~/.claude/skills/architecture-mapper # 将 SKILL.md、examples、scripts 按目录结构放好

如果希望这个 Skill 只对某个项目生效，可以放到项目的.claude/skills/下：

your-project/ └── .claude/ └── skills/ └── architecture-mapper/ ├── SKILL.md └── scripts/

5.2 启动并触发 Skill

进入目标项目目录，启动 Claude Code：

cd /path/to/sample-app claude

在对话中输入触发指令：

请使用 architecture-mapper Skill，分析当前项目结构，输出 Mermaid 格式的系统架构图。

如果 Skill 安装成功，Claude Code 会按 SKILL.md 里的流程自动执行：先扫描目录，再读取配置文件，再分析依赖，最后生成架构图。

如果你的编程助手不支持标准 Skill 目录，有一个替代思路：把SKILL.md的内容直接粘贴到系统提示词或项目说明文件中，再配合命令约定一样可以达到目的。本质上是把“让 AI 自己探索”变成“给 AI 一套固定工作流”。

5.3 输出示例

一个简单的 Mermaid 架构图输出可能是这样：

graph TD A[Client] --> B[API Gateway] B --> C[Auth Service] B --> D[Order Service] B --> E[User Service] D --> F[(Order DB)] E --> G[(User DB)]

这段文本保存到docs/architecture/architecture-overview.md，在支持 Mermaid 的 Markdown 查看器中即可自动渲染成图。用 Draw.io 或 PlantUML 的格式同理，只是语法不同。

6. 功能测试与效果验证

安装完 Skill，接下来跑一轮完整测试。这里给出一个可复用的验证流程。

6.1 测试一：目录扫描准确性

在对话中触发：

先不用生成图，用 architecture-mapper 列出项目根目录结构和每个目录的职责判断。

预期结果：

• 输出目录树
• 标注每个目录的疑似职责
• 识别入口文件

判断标准：目录树与真实项目一致，职责描述基本准确，没有把node_modules、venv也算进来。如果扫描结果包含大量无关目录，说明 SKILL.md 中的ignore_dirs规则需要补充。

6.2 测试二：模块依赖分析

输入：

分析 app/services 和 app/api 两个目录之间的依赖关系，输出模块调用方向。

预期结果：

• 列出从 api 层到 service 层的调用关系
• 标出循环依赖或可疑依赖

判断标准：依赖关系清晰、方向正确。如果 AI 分析出来的依赖和实际代码不匹配，可以使用辅助脚本analyze_imports.py的结果作为事实来源，让它基于脚本输出再画图。

6.3 测试三：架构图生成

输入：

使用 architecture-mapper 生成系统级架构图，格式 Mermaid，保存到 docs/architecture/。

预期结果：

• 在docs/architecture/下生成 Markdown 文件
• 包含完整 Mermaid 代码块
• 包含架构说明文字

判断标准：用支持 Mermaid 的工具打开后能正常渲染，图和目录扫描结果一致。如果 Mermaid 渲染报错，通常是语法问题，可以把生成的代码块贴到 mermaid.live 检查具体错误。

6.4 测试四：Draw.io 格式输出

输入：

重新生成 Draw.io 格式的架构图，保存为 .drawio 文件。

预期结果：

• 生成.drawio或.xml文件
• 可以用 draw.io 桌面版或在线版打开

判断标准：打开文件后能看到可编辑的图形元素，而不是纯文本。Draw.io 的 XML 结构较长，AI 输出时偶尔会出现标签不闭合的问题，建议让 AI 生成后用drawio --check验证。

6.5 成功与失败判断

7. 批量任务与 CI 集成思路

Skill 方案的一个优势是可以和脚本结合，批量处理多个项目。虽然当前实现不涉及后台队列服务，但通过命令行循环调用同样能覆盖批量场景。

7.1 多项目批量处理模板

假设你有多个仓库需要生成架构图，可以用脚本循环进入每个目录，调用编程助手的非交互模式执行任务。以 Claude Code 的 CLI 为例，大概是这样的流程：

for repo in /path/to/repos/*/; do echo "===== 处理 $repo =====" cd "$repo" claude -p "请使用 architecture-mapper Skill，分析项目结构，生成 Mermaid 架构图，并保存到 docs/architecture/" echo "完成: $repo" done

这里-p表示非交互模式执行提示词，具体参数名需要查你所用 CLI 的版本。如果组件不支持命令行直接传提示词，可以退一步：批量生成“架构图分析任务清单”，再逐个在交互窗口里执行。

7.2 CI 中定时更新架构图

对于持续演进的仓库，可以把 Skill 关联到 CI 流程中。思路是每次代码合并后自动跑一次架构分析，把更新的架构图提交到docs/architecture/。

# .github/workflows/architecture.yml 示例 name: Update Architecture Docs on: push: branches: [main] jobs: generate-architecture: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - name: Generate Architecture Diagram run: | claude -p "请使用 architecture-mapper Skill，分析当前项目，更新 docs/architecture/ 下的架构图" - name: Commit changes run: | git config user.name "arch-bot" git config user.email "bot@example.com" git add docs/architecture git commit -m "chore: update architecture docs" git push

需要注意的是：这种自动化流程涉及 CI 环境中调用大模型 API，请确认 API Key 的存储方式、费用上限和安全策略。建议先在本地跑通，再决定是否配置 CI。

7.3 任务日志与失败重试

批量任务如果项目数量多，建议为每个项目单独记录日志：

claude -p "..." > logs/$(basename "$repo")_$(date +%Y%m%d).log 2>&1

抓取日志后，可以快速发现哪个项目失败、失败在哪个环节。批量任务不是越多越好，每轮建议先处理 3 到 5 个项目，确认输出质量稳定后再扩大范围。

8. 资源占用与性能观察

很多人关心这个方案跑起来吃多少资源。先说结论：因为核心分析由大模型 API 完成，本地主要消耗的是 CPU、内存和网络带宽，而不是显卡显存。除非你在本地跑开源模型推理，否则显存占用基本可以忽略。

8.1 本地资源占用

执行 Skill 时的本地资源消耗集中在：

• 目录遍历和文件读取：小项目几秒内完成，大项目需要一定时间。
• analyze_imports.py脚本执行：主要是 CPU 和磁盘 IO。
• 编程助手 CLI 本身的进程：内存占用通常在 200MB 到 1GB 之间，与项目和上下文长度有关。

实际占用会因项目大小和工具版本不同而不同，建议通过系统监控工具观察即可。

8.2 大项目处理策略

项目文件过多时，提示词窗口可能装不下所有代码。应对方法：

8.3 如何观察耗时

启动分析后，可以这样观察进程状态：

# 查看当前目录下正在执行的 CLI 进程资源占用 top -o mem

如果 CLI 长时间无响应，可能是因为模型在等待 API 返回，也可能是因为上下文过长导致处理变慢。此时不要盲目重启，先看日志确认卡在哪个阶段。

8.4 降低 API 消耗的思路

调用大模型 API 是按 token 计费的，整个 Skill 流程中消耗最多的是“读取源码文件”这一步。降低消耗的思路：

1. 让 Skill 优先读配置文件和入口文件，而不是所有.py/.js文件。
2. 用辅助脚本先聚合 import 关系，AI 读汇总结果即可。
3. 明确设置max_tokens和合理的上下文窗口。
4. 对大仓库先压缩为文件清单和目录树，再选择性读取。

9. 常见问题与排查方法

这里有一类问题值得单独提醒：如果项目本身是单体应用，内部模块互相依赖严重，AI 生成的架构图会非常复杂。这种情况不是 Skill 的问题，而是系统设计本身需要梳理。架构图的意义就是暴露出这些问题，方便你做拆分决策。

10. 最佳实践与使用建议

10.1 第一次先小步验证

不要上来就分析一个 200 万行的老仓库。先用 10 到 20 个文件的小项目验证 Skill 可用，再逐步扩大到中型项目。每一次扩大范围都观察输出质量和耗时，找到当前模型能处理的边界。

10.2 建立分层出图规范

推荐参考 C4 模型的分层思路：

• Level 1：系统上下文图，展示项目与外部的边界。
• Level 2：容器图，展示应用、数据库、中间件的部署关系。
• Level 3：模块图，展示项目内部核心模块的依赖关系。
• Level 4：类图 / 文件图，只在关键模块中按需生成。

在 SKILL.md 中明确让 AI 先问用户“需要哪个层级”，或者直接生成 Level 1 到 Level 3，避免一次输出过多导致质量下降。

10.3 输出目录与文件管理

建议统一使用docs/architecture/目录，并按名称规范保存：

docs/architecture/ ├── README.md ├── system-overview.md ├── service-dependency.md ├──>