最近很多团队开始用 Claude Code、Codex 这类 AI 编程助手处理代码库分析任务但实际用下来发现一个问题让 AI 总结代码逻辑、列依赖关系还行一旦要“画架构图”就变成它输出一堆描述你还是得手动拖框、连线、调布局。这次我们来看一种新的解决思路——通过 Skill 机制让 AI 边读代码边出图直接把结果落在 Mermaid、Draw.io、PlantUML 这类架构图文件里。先给结论这个方案的核心不是某个现成的“画图软件”而是一套给 AI Agent 用的“技能包”设计思路。你可以把它理解成给 Claude Code / Codex / Cursor 等编程助手装上一个“架构师外挂”它会先扫描项目目录、识别模块依赖、生成调用关系再按你指定的图类型输出架构图文档。整体运行不依赖高配 GPU普通开发机即可适合本地代码库、微服务项目、单体应用改造前的结构梳理。本文会完整演示Skill 是什么、如何设计一个自动读代码并出架构图的 Skill、怎么在本地装上跑通、如何拿真实项目验证效果以及批量处理多个仓库的方法。如果你正在做老项目迁移、新同学 onboarding、代码评审前的模块梳理这篇文章可以直接收藏。1. 核心能力速览能力项说明项目类型AI Agent Skill 设计方案结合代码解析与架构图生成适用工具Claude Code、Codex CLI、Cursor 等支持 Skill 机制的编程助手主要功能自动扫描代码目录、分析模块依赖、生成架构图文档输出格式Mermaid、PlantUML、Draw.io.drawio / .xml、Markdown 说明数据输入本地代码仓库、项目根目录、指定源码目录硬件门槛普通开发机即可无需独立显卡大项目建议 16G 以上内存依赖环境Node.js 18 或 Python 3.9Git编程助手 CLI启动方式在 Agent 对话中触发 Skill或通过 CLI 批量调用API 能力取决于所使用的编程助手是否开放 API / CLI 模式批量任务可以通过脚本循环处理多个仓库目录适合场景代码结构梳理、架构评审、文档生成、微服务依赖分析从规格能看到这个方向不再依赖“人手一个画图软件”而是把“读代码—分析关系—出图—改图”全部交给 Agent 完成。你只需要定义清楚要什么粒度的图、什么格式、输出到哪个目录。2. 适用场景与使用边界Skill 自动画架构图最适合下面几类情况老项目接手不知道十几个模块之间怎么调用的让 AI 先扫一遍生成模块依赖图。微服务改造Service 数量多、调用关系复杂先生成服务级架构图再决定拆分方向。代码评审评审前让 AI 生成本次改动涉及模块的架构影响图方便讨论。技术文档建设架构图直接以 Mermaid / Draw.io 文件落到 docs 目录后续可持续维护。新成员 onboarding通过自动生成的架构说明快速了解项目全貌。需要注意使用边界。Skill 自动生成的架构图更适合“模块级”“服务级”“文件目录级”的宏观展示不适合逐行代码级别的调用可视化因为提示词窗口和模型理解能力都有限。另外一个实际问题如果项目里有大量自动生成代码、第三方依赖、加密混淆业务逻辑AI 的分析结果可能出现偏差架构图需要人工校核后使用。合规方面也要重视。这个方案会读取本地代码并发送给编程助手的大模型接口处理涉及公司私有代码、未公开商业项目、敏感业务逻辑时必须先确认使用的模型服务是否符合内部数据安全规范。生成包含业务块的架构图、文档时同样要注意数据脱敏和访问控制。3. 环境准备与前置条件开始之前先准备一套最小环境。以下版本要求按常见实践给出实际以你本机工具版本为准。3.1 基础环境清单组件推荐配置说明操作系统macOS / Linux / Windows WSL2三个平台都能跑Windows 建议用 WSL2 避免路径问题Node.js18 或更高Claude Code、Codex CLI 等工具链依赖Python3.9 或更高部分脚本和代码解析工具使用Git2.3 以上拉取工具、读 Git 历史辅助分析编程助手 CLIClaude Code / Codex CLI / Cursor CLI需要支持 Skill 机制或自定义指令加载可选Mermaid CLI、draw.io CLI用于把 Mermaid 导出成 PNG / SVG3.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.pySKILL.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_dirsNone): 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, encodingutf-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}, filesys.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 Codecd /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 成功与失败判断环节成功标准常见失败原因Skill 触发对话中出现“使用 Skill”的系统提示目录放错、CLI 版本不支持目录扫描返回真实项目结构权限不足、路径错误依赖分析与静态扫描结果一致大型项目内容超出上下文窗口图生成Markdown / XML 文件可正常打开Mermaid 语法错误、标签不闭合图渲染图形布局符合预期节点过多导致布局混乱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/checkoutv4 - uses: actions/setup-nodev4 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 botexample.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 21抓取日志后可以快速发现哪个项目失败、失败在哪个环节。批量任务不是越多越好每轮建议先处理 3 到 5 个项目确认输出质量稳定后再扩大范围。8. 资源占用与性能观察很多人关心这个方案跑起来吃多少资源。先说结论因为核心分析由大模型 API 完成本地主要消耗的是 CPU、内存和网络带宽而不是显卡显存。除非你在本地跑开源模型推理否则显存占用基本可以忽略。8.1 本地资源占用执行 Skill 时的本地资源消耗集中在目录遍历和文件读取小项目几秒内完成大项目需要一定时间。analyze_imports.py脚本执行主要是 CPU 和磁盘 IO。编程助手 CLI 本身的进程内存占用通常在 200MB 到 1GB 之间与项目和上下文长度有关。实际占用会因项目大小和工具版本不同而不同建议通过系统监控工具观察即可。8.2 大项目处理策略项目文件过多时提示词窗口可能装不下所有代码。应对方法策略说明缩小分析范围先分析核心模块目录再分析外围模块先跑辅助脚本用本地脚本生成依赖汇总再让 AI 看图分层出图先出系统级 L1 图再展开服务级 L3 图排除生成代码把 build、dist、generated 目录排除掉拆分子项目微服务仓库按服务逐个分析8.3 如何观察耗时启动分析后可以这样观察进程状态# 查看当前目录下正在执行的 CLI 进程资源占用 top -o mem如果 CLI 长时间无响应可能是因为模型在等待 API 返回也可能是因为上下文过长导致处理变慢。此时不要盲目重启先看日志确认卡在哪个阶段。8.4 降低 API 消耗的思路调用大模型 API 是按 token 计费的整个 Skill 流程中消耗最多的是“读取源码文件”这一步。降低消耗的思路让 Skill 优先读配置文件和入口文件而不是所有.py/.js文件。用辅助脚本先聚合 import 关系AI 读汇总结果即可。明确设置max_tokens和合理的上下文窗口。对大仓库先压缩为文件清单和目录树再选择性读取。9. 常见问题与排查方法问题现象可能原因排查方式解决方案触发 Skill 后 AI 没有按流程执行Skill 目录未生效或命名不对检查~/.claude/skills/下目录名和 SKILL.md 头信息把目录名改成 kebab-case确认name字段与目录一致扫描时把 node_modules 也分析了SKILL.md 缺少排除规则或规则描述不明确查看 AI 实际读取的文件列表在指令中补充更明确的忽略目录清单生成的 Mermaid 图渲染报错Mermaid 语法不完整或节点 ID 冲突将代码粘贴到 mermaid.live 测试让 AI 重新生成并限定“只能使用基础 graph TD 语法”大项目分析中途截断上下文窗口超限查看 CLI 日志中的 token 使用量缩小目录范围先跑辅助脚本再生成图Draw.io 文件打不开XML 标签不闭合或格式错误用文本编辑器确认根节点是否存在要求 AI 输出后先自检 XML 格式输出架构图看不见调用关系项目是动态语言或使用了大量反射检查是否有静态 import 之外的调用结合 README 和运行时日志补充标注“人工确认”API 调用失败认证过期或网络问题检查 CLI 登录状态和网络连通性重新登录或切换到兼容的网络环境批量任务某个仓库卡住仓库过大或存在异常文件查看对应的日志输出为该仓库单独设置超时时间并跳过生成的图过于复杂模块数量多且依赖关系混乱检查节点数量和连线数量拆分服务级 / 模块级增加聚合层级这里有一类问题值得单独提醒如果项目本身是单体应用内部模块互相依赖严重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 ├──> Skill机制让AI自动读代码生成架构图，代码分析到可视化一步到位
最近很多团队开始用 Claude Code、Codex 这类 AI 编程助手处理代码库分析任务但实际用下来发现一个问题让 AI 总结代码逻辑、列依赖关系还行一旦要“画架构图”就变成它输出一堆描述你还是得手动拖框、连线、调布局。这次我们来看一种新的解决思路——通过 Skill 机制让 AI 边读代码边出图直接把结果落在 Mermaid、Draw.io、PlantUML 这类架构图文件里。先给结论这个方案的核心不是某个现成的“画图软件”而是一套给 AI Agent 用的“技能包”设计思路。你可以把它理解成给 Claude Code / Codex / Cursor 等编程助手装上一个“架构师外挂”它会先扫描项目目录、识别模块依赖、生成调用关系再按你指定的图类型输出架构图文档。整体运行不依赖高配 GPU普通开发机即可适合本地代码库、微服务项目、单体应用改造前的结构梳理。本文会完整演示Skill 是什么、如何设计一个自动读代码并出架构图的 Skill、怎么在本地装上跑通、如何拿真实项目验证效果以及批量处理多个仓库的方法。如果你正在做老项目迁移、新同学 onboarding、代码评审前的模块梳理这篇文章可以直接收藏。1. 核心能力速览能力项说明项目类型AI Agent Skill 设计方案结合代码解析与架构图生成适用工具Claude Code、Codex CLI、Cursor 等支持 Skill 机制的编程助手主要功能自动扫描代码目录、分析模块依赖、生成架构图文档输出格式Mermaid、PlantUML、Draw.io.drawio / .xml、Markdown 说明数据输入本地代码仓库、项目根目录、指定源码目录硬件门槛普通开发机即可无需独立显卡大项目建议 16G 以上内存依赖环境Node.js 18 或 Python 3.9Git编程助手 CLI启动方式在 Agent 对话中触发 Skill或通过 CLI 批量调用API 能力取决于所使用的编程助手是否开放 API / CLI 模式批量任务可以通过脚本循环处理多个仓库目录适合场景代码结构梳理、架构评审、文档生成、微服务依赖分析从规格能看到这个方向不再依赖“人手一个画图软件”而是把“读代码—分析关系—出图—改图”全部交给 Agent 完成。你只需要定义清楚要什么粒度的图、什么格式、输出到哪个目录。2. 适用场景与使用边界Skill 自动画架构图最适合下面几类情况老项目接手不知道十几个模块之间怎么调用的让 AI 先扫一遍生成模块依赖图。微服务改造Service 数量多、调用关系复杂先生成服务级架构图再决定拆分方向。代码评审评审前让 AI 生成本次改动涉及模块的架构影响图方便讨论。技术文档建设架构图直接以 Mermaid / Draw.io 文件落到 docs 目录后续可持续维护。新成员 onboarding通过自动生成的架构说明快速了解项目全貌。需要注意使用边界。Skill 自动生成的架构图更适合“模块级”“服务级”“文件目录级”的宏观展示不适合逐行代码级别的调用可视化因为提示词窗口和模型理解能力都有限。另外一个实际问题如果项目里有大量自动生成代码、第三方依赖、加密混淆业务逻辑AI 的分析结果可能出现偏差架构图需要人工校核后使用。合规方面也要重视。这个方案会读取本地代码并发送给编程助手的大模型接口处理涉及公司私有代码、未公开商业项目、敏感业务逻辑时必须先确认使用的模型服务是否符合内部数据安全规范。生成包含业务块的架构图、文档时同样要注意数据脱敏和访问控制。3. 环境准备与前置条件开始之前先准备一套最小环境。以下版本要求按常见实践给出实际以你本机工具版本为准。3.1 基础环境清单组件推荐配置说明操作系统macOS / Linux / Windows WSL2三个平台都能跑Windows 建议用 WSL2 避免路径问题Node.js18 或更高Claude Code、Codex CLI 等工具链依赖Python3.9 或更高部分脚本和代码解析工具使用Git2.3 以上拉取工具、读 Git 历史辅助分析编程助手 CLIClaude Code / Codex CLI / Cursor CLI需要支持 Skill 机制或自定义指令加载可选Mermaid CLI、draw.io CLI用于把 Mermaid 导出成 PNG / SVG3.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.pySKILL.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_dirsNone): 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, encodingutf-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}, filesys.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 Codecd /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 成功与失败判断环节成功标准常见失败原因Skill 触发对话中出现“使用 Skill”的系统提示目录放错、CLI 版本不支持目录扫描返回真实项目结构权限不足、路径错误依赖分析与静态扫描结果一致大型项目内容超出上下文窗口图生成Markdown / XML 文件可正常打开Mermaid 语法错误、标签不闭合图渲染图形布局符合预期节点过多导致布局混乱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/checkoutv4 - uses: actions/setup-nodev4 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 botexample.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 21抓取日志后可以快速发现哪个项目失败、失败在哪个环节。批量任务不是越多越好每轮建议先处理 3 到 5 个项目确认输出质量稳定后再扩大范围。8. 资源占用与性能观察很多人关心这个方案跑起来吃多少资源。先说结论因为核心分析由大模型 API 完成本地主要消耗的是 CPU、内存和网络带宽而不是显卡显存。除非你在本地跑开源模型推理否则显存占用基本可以忽略。8.1 本地资源占用执行 Skill 时的本地资源消耗集中在目录遍历和文件读取小项目几秒内完成大项目需要一定时间。analyze_imports.py脚本执行主要是 CPU 和磁盘 IO。编程助手 CLI 本身的进程内存占用通常在 200MB 到 1GB 之间与项目和上下文长度有关。实际占用会因项目大小和工具版本不同而不同建议通过系统监控工具观察即可。8.2 大项目处理策略项目文件过多时提示词窗口可能装不下所有代码。应对方法策略说明缩小分析范围先分析核心模块目录再分析外围模块先跑辅助脚本用本地脚本生成依赖汇总再让 AI 看图分层出图先出系统级 L1 图再展开服务级 L3 图排除生成代码把 build、dist、generated 目录排除掉拆分子项目微服务仓库按服务逐个分析8.3 如何观察耗时启动分析后可以这样观察进程状态# 查看当前目录下正在执行的 CLI 进程资源占用 top -o mem如果 CLI 长时间无响应可能是因为模型在等待 API 返回也可能是因为上下文过长导致处理变慢。此时不要盲目重启先看日志确认卡在哪个阶段。8.4 降低 API 消耗的思路调用大模型 API 是按 token 计费的整个 Skill 流程中消耗最多的是“读取源码文件”这一步。降低消耗的思路让 Skill 优先读配置文件和入口文件而不是所有.py/.js文件。用辅助脚本先聚合 import 关系AI 读汇总结果即可。明确设置max_tokens和合理的上下文窗口。对大仓库先压缩为文件清单和目录树再选择性读取。9. 常见问题与排查方法问题现象可能原因排查方式解决方案触发 Skill 后 AI 没有按流程执行Skill 目录未生效或命名不对检查~/.claude/skills/下目录名和 SKILL.md 头信息把目录名改成 kebab-case确认name字段与目录一致扫描时把 node_modules 也分析了SKILL.md 缺少排除规则或规则描述不明确查看 AI 实际读取的文件列表在指令中补充更明确的忽略目录清单生成的 Mermaid 图渲染报错Mermaid 语法不完整或节点 ID 冲突将代码粘贴到 mermaid.live 测试让 AI 重新生成并限定“只能使用基础 graph TD 语法”大项目分析中途截断上下文窗口超限查看 CLI 日志中的 token 使用量缩小目录范围先跑辅助脚本再生成图Draw.io 文件打不开XML 标签不闭合或格式错误用文本编辑器确认根节点是否存在要求 AI 输出后先自检 XML 格式输出架构图看不见调用关系项目是动态语言或使用了大量反射检查是否有静态 import 之外的调用结合 README 和运行时日志补充标注“人工确认”API 调用失败认证过期或网络问题检查 CLI 登录状态和网络连通性重新登录或切换到兼容的网络环境批量任务某个仓库卡住仓库过大或存在异常文件查看对应的日志输出为该仓库单独设置超时时间并跳过生成的图过于复杂模块数量多且依赖关系混乱检查节点数量和连线数量拆分服务级 / 模块级增加聚合层级这里有一类问题值得单独提醒如果项目本身是单体应用内部模块互相依赖严重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 ├──>