架构图这个事平时看着简单真动手画起来特别烦。尤其是拿到一个不熟悉的项目或者刚接手一套微服务代码你想理清楚服务之间怎么调用、模块怎么划分、数据流向哪靠人肉读代码再拖框连线一个下午基本就没了。最近我试了一种新玩法给 AI 配一个处理代码架构图的 Skill让它自己读代码、自己梳理模块关系、直接输出架构图。实测下来对于中小型项目和中大型项目的模块梳理这个思路能把画图时间从半天压缩到十几分钟。这篇文章就围绕“AI 读代码生成架构图”这件事把 Skill 的结构、运行条件、实际步骤、参数配置和踩坑点完整拆一遍。先说结论这个 Skill 不是简单的“把代码丢给 AI 然后让它画张图”而是通过一套规则文件让 AI 按固定流程去扫描目录、分析依赖、抽取模块职责最后用统一的图表格式输出。它解决的核心问题不是“画图”而是“理解代码结构”。画图工具遍地都是真正卡住人的是代码阅读和结构梳理。如果你经常需要给项目写文档、做技术方案、给团队讲架构或者刚接手不熟悉的代码仓库这个方案值得试试。1. 为什么画架构图这件事卡点从来不在“画”而在“读”很多人第一反应是画架构图不是有 draw.io、ProcessOn、Visio 吗拖拖框框不就行了工具确实很多但问题不在于工具而在于画图之前你必须先知道“要画什么”。1.1 手动画图的三个真实痛点第一读代码成本高。一个模块几十个文件类之间的继承、接口实现、依赖注入、配置项关联靠肉眼扫很难短时间建立完整的结构认知。第二结构容易过时。代码改了图没更新过两周再看图跟实际代码对不上图就变成了废图。第三批量梳理时人很容易漏。画完服务 A 和 B 的调用关系可能漏掉通过消息队列解耦的那条链路画出来的架构图看着完整其实关键路径缺失。这些痛点单靠画图软件解决不了。真正需要的是先把代码结构读出来再落到图上。以前这个工作只能靠人现在可以让 AI 代劳。1.2 Skill 到底改变了什么Skill 在 AI 编程工具里是一种可复用的能力包。常见的做法是用一个 markdown 文件定义使用规则再配合脚本、数据文件、示例内容让 AI 在特定场景下按照你预设的流程工作。放到架构图这个场景里Skill 要完成的事情不是“拿现有文字描述生成图”而是拿到代码仓库路径。扫描目录结构了解项目全貌。读取关键文件识别模块边界。分析模块之间的调用和依赖关系。按固定格式输出架构图代码。这其实是把“架构师梳理项目”的流程标准化了。AI 负责干活你负责检查结果。我把这套思路整理成 Skill 文件后在几个不同规模的项目上都试过效果很稳定。2. 一个能用的架构图 Skill拆开看就四件套很多人以为 Skill 就是写一段提示词让 AI 去执行实际不是。成熟的 Skill 应该有固定的目录结构、明确的规则文件、可执行的辅助脚本以及输出格式约束。四样东西缺一个结果都会不稳定。2.1 SKILL.md 才是真正的入口文件这个文件是整个 Skill 的核心。AI 加载 Skill 时优先读它所以里面要写清楚这个 Skill 解决什么问题、适合分析哪些代码仓库、工作流程分几步、输出格式是什么、遇到看不懂的代码怎么办。我当时写的 SKILL.md 里重点强调了几个约束必须先列出项目根目录结构再决定从哪些文件入手。不要直接打开所有文件先读构建文件、入口文件、路由文件、配置目录。输出必须使用 Mermaid 格式同时给一份模块解释说明。每个模块要标注职责、关键文件列表、对外依赖。遇到无法判断的依赖关系不要瞎猜要标记为待确认。这些约束非常关键。没有约束的 AI 经常会漏掉关键依赖或者编造不存在的模块名。有了 SKILL.mdAI 的行为就变成了一条固定流水线。2.2 用脚本补齐 AI 读不到的信息AI 在分析代码时有一个天生的盲区它在一次对话里能读取的文件数量有限。如果项目文件很多AI 不可能每个文件都打开看一遍。这时候就需要一个辅助脚本先把整个项目的文件列表、目录层级、文件大小、语言类型统计出来作为 AI 的“项目地图”。我一般在 Skill 里放一个 Python 脚本运行之后输出类似这样的结构:# 示例扫描项目目录并生成结构清单 import os import json from collections import defaultdict def scan_project(root_dir, max_depth4, excludeNone): exclude exclude or {node_modules, .git, dist, build, __pycache__, .venv, venv, .idea} tree defaultdict(list) for dirpath, dirnames, filenames in os.walk(root_dir): depth dirpath.replace(root_dir, ).count(os.sep) if depth max_depth: continue dirnames[:] [d for d in dirnames if d not in exclude] rel_dir os.path.relpath(dirpath, root_dir) tree[rel_dir] [f for f in filenames if not f.startswith(.)] return tree if __name__ __main__: import sys root sys.argv[1] if len(sys.argv) 1 else . result scan_project(root) for directory in sorted(result.keys()): files result[directory] if files: print(f{directory}/) for f in files: print(f ├── {f})这个脚本不复杂但它能给 AI 提供一次扫描就能覆盖整个项目的信息。AI 拿到这个结构清单后就能判断先读哪个入口文件、哪些目录可以跳过、哪些模块可能是核心依赖。2.3 输出格式要先定死如果让 AI 自由发挥每次输出的格式可能都不一样。这次是 Mermaid下次就变成 PlantUML或者干脆输出一段 Json 描述。所以 Skill 里必须强制规定最终输出结构。我会在 SKILL.md 里规定统一输出三部分输出部分内容要求格式Mermaid 代码块必须包含顶层图、模块关系、核心依赖线mermaid 代码块模块清单每个模块的职责、关键文件、主要对外依赖表格待确认项无法确定的关系、疑似失效的依赖、需要人确认的部分列表这样 AI 输出的结果既是图也是文档。给人看图给文档留排查线索。3. 在 Claude Code 或 Cursor 里把 Skill 跑起来Skill 的落地方式取决于你用的客户端。不同工具对 Skill 的目录约定和加载方式不完全一样但核心思路一致把 Skill 文件放到指定目录然后在对话里通过名称触发。3.1 先确认客户端支持自定义 Skill目前主流 AI 编程工具基本都支持自定义规则或技能文件只是叫法不同。有些叫 Skill有些叫 Rules还有些叫 Commands。我实测使用较多的是 Claude Code 和 Cursor两者都能通过配置文件加载自定义规则。如果你用的是其他工具先看文档里有没有类似“Agent Skills”“Custom Commands”的入口。目录结构一般这样放~/.claude/skills/ └── code-visualizer/ ├── SKILL.md └── scripts/ └── scan_project.pyCursor 里则可能放在.cursor/skills或者通过.cursor/rules加载。没有固定标准要以你用的工具版本为准。我建议先在官方文档里查清楚目录约定再开始省得后面排查“为什么 Skill 没生效”的问题。3.2 建一个最小可用版本别一上来就堆功能我第一次做架构图 Skill 时想得很复杂塞了一大堆规则和脚本进去结果 AI 加载后行为反而混乱。后来我学到一个原则先做最小可用版本。最小版本只需要三样东西# 技能名称代码架构图生成 # 触发词使用架构图、分析项目结构 # 工作步骤 1. 先运行 scan_project.py 获取项目文件清单。 2. 根据清单选择入口文件和关键配置文件。 3. 读取文件内容识别模块和依赖。 4. 按输出模板生成 Mermaid 图和模块表格。再加上一个最简单的扫描脚本。先在一个只有十来个文件的 Demo 项目上跑通确认 AI 能按流程走。跑通之后再逐步加复杂规则比如“指定忽略目录”“限制分析深度”“输出架构决策记录”等。3.3 单项目跑通后再验证批量场景很多时候大家习惯一上来就压测直接把一个几百个文件的微服务仓库丢给 AI 分析。结果不是超时就是漏模块。我建议按顺序来先用一个单模块项目验证 Skill 是否被正确加载。确认输出格式是否正确Mermaid 能否正常渲染。再加一个中等规模项目验证模块拆分逻辑。最后才上微服务项目并配合目录深度限制和文件排除规则。这里有一个容易忽略的细节AI 的上下文窗口有限分析大项目时必须让脚本先过滤掉不重要的目录和文件比如测试代码、构建产物、第三方依赖目录。如果不过滤AI 的大部分“注意力”会被无关文件消耗掉真正重要的架构信息反而读不完整。注意不要一上来就把整个仓库直接丢给 AI 读。先让扫描脚本输出文件清单再在提示词里指定“先读 pom.xml / package.json / main.go / manage.py 这类入口文件”效率会高很多。4. 从小项目到微服务目录控制、模块抽取和依赖过滤Skill 在小项目上跑通容易但到了微服务项目问题就会暴露出来服务数量多、依赖链路长、有些服务之间还通过消息队列异步通信。这时候如果还用同一套规则很可能画出来一张巨复杂的图连作者自己都看不懂。4.1 先做模块级架构图再做全局架构图我的处理方式是把分析拆成两层。第一层是模块级让 AI 分析单个服务或单个核心模块输出这个模块内部的类关系、接口、关键流程。第二层是全局级分析各个服务之间的调用关系、数据依赖和部署边界。Skill 里必须让 AI 在输出全局架构图之前先输出模块级架构图。如果 AI 直接尝试生成一张全项目大图很容易缺漏信息。可以这样要求分析步骤 1. 先识别根目录下的模块或服务清单。 2. 逐个模块分析其对外暴露的接口和核心依赖。 3. 先输出模块级 Mermaid 图。 4. 再基于模块清单输出全局 Mermaid 图。这样做的好处是后续你发现某张图有问题只需要替换对应模块的分析结果不需要重跑整个项目。而且多模块项目里模块级图往往比全局图更有实际价值。4.2 依赖爆炸时必须设置过滤规则当项目依赖特别多时比如一个 Java Spring Cloud 项目里有几十个服务服务之间的依赖关系会有几百条。全部画出来图就变成一团乱麻。所以在 Skill 里要加依赖过滤规则。常用做法是设置依赖阈值和忽略列表依赖过滤规则 - 只保留业务模块之间的依赖忽略对第三方中间件Redis、Kafka、MySQL的依赖线。 - 如果某个模块被超过 20 个模块依赖只显示其名称和职责不画入边。 - 消息队列依赖统一用虚线标记并单独列出 Topic 名称。 - 被过滤的依赖要记录到“待确认项”中方便人工检查。这样输出的图既保留了核心结构又不会因为次要依赖太多而失去可读性。说白了架构图的价值在于“帮助理解”不在于“展示所有细节”。4.3 批量分析时日志和输出命名要提前规划如果你要用 Skill 分析多个项目或者分析同一个微服务仓库中的所有模块不要只生成一张大图就结束。建议让 AI 按模块分别输出图片代码并存到独立文件。我一般这样组织输出目录output/ ├── module-01-order-service.md ├── module-02-user-service.md ├── module-03-payment-service.md └── global-architecture.md每个文件只包含一个模块的架构图和说明。这样方便后续单独更新某一模块也方便在文档系统里分别引入。如果所有内容都堆在一个文件里后续维护非常痛苦。同时如果任务比较长AI 中途可能因为上下文到达上限而出错。这时候不要直接重跑先看已经输出的部分是完整的再针对缺失模块单独续跑。5. 输出不是终点架构图也要有验收标准AI 生成的架构图不是出来就能直接用。我见过 AI 在分析时把模块名写错、把某个依赖方向画反、把根本不存在的中间件加进去。所以每次生成后都要按固定维度验收。5.1 四个维度检查架构图质量检查维度判断标准发现问题的处理方式模块完整性核心业务模块是否全部出现逐个对照代码目录确认是否有遗漏依赖正确性调用方向是否跟代码一致抽重点依赖文件人工核对命名准确性模块名、文件名是否真实存在用代码搜索功能验证明可读性图上是否有超过 30 条交叉线要求 AI 增加模块分组或过滤规则我第一次测的时候AI 把 “gateway-service” 写成了 “api-gateway”虽然功能相似但项目里真实名字不对直接放文档里就误导人。后来我在 SKILL.md 里加了一条强制规则模块名必须跟代码目录名完全一致不能改写、不能翻译。这个问题就解决了。5.2 常见渲染问题和排查顺序Mermaid 图有时渲染不出来或者预览报错。一般先别急着怪 AI先看代码块语法是不是有问题。我遇到过的情况有几种Mermaid 中模块名包含特殊字符比如括号、斜杠、中文标点导致节点解析失败。图太大超过预览器渲染限制。依赖线重复有环状引用导致渲染异常。排查顺序我建议这样先看 Mermaid 语法是否校验通过再确认模块名是否用了不允许的特殊字符最后看图是否太大需要拆分。大部分问题不是 AI 没读懂代码而是输出格式对渲染器不友好。排查时优先检查模块名中是否有特殊字符。把模块名统一改成“字母数字连字符”的格式能解决大部分 Mermaid 渲染问题。6. 哪些项目适合无脑用哪些项目要谨慎Skill 不是银弹。测试下来不同类型项目的效果差异挺大这里给一个适用范围参考。6.1 适合用 Skill 的项目类型中小型单体项目几百个文件以内模块边界清楚AI 读取后容易理解成功率高。微服务项目的模块梳理重点分析服务模块之间的调用关系比人工梳理效率高很多。技术文档更新给老项目补架构图省去人工读代码的耗时。新成员入职培训快速生成项目整体结构图帮助新人建立全局认知。技术方案评审输出模块依赖图用于评审会上讨论耦合点和优化方向。6.2 需要谨慎的项目类型超大仓库几万个文件即使有过滤脚本AI 也很难保证覆盖全面建议拆分后再分析。前端组件级项目如果图太细画到组件层会非常杂乱更适合用类型关系图代替架构图。多语言混合项目某些语言之间的跨语言调用关系AI 不一定能准确识别需要人工复核。强动态类型语言项目比如 Python 技术栈中大量使用装饰器、动态导入、依赖注入框架AI 分析时容易出现误判。6.3 没有 Skill 功能时怎么办如果你的工具不支持自定义 Skill也不用放弃这个思路。核心逻辑完全可以复刻成普通规则文件或者项目文档。在项目根目录放一份ARCHITECTURE_PROMPT.md里面写好分析步骤、输入范围、输出模板然后每次让 AI 读这个文件并执行。效果略逊于真正的 Skill但对大多数项目也够用。关键在于你要把“怎么分析代码、怎么判断模块边界、怎么输出图”这套规则固化下来而不是每次重新描述需求。固化成文件以后不管用哪个工具都能复用这套规则。7. 我踩过的几个坑和建议优先做的事最后分享一下我在实际使用中遇到的最多的几个问题以及我现在的处理习惯。7.1 最容易踩的坑第一个坑是让 AI 自由发挥。不写死规则AI 输出的图经常“看起来合理细看不对”。比如漏掉一个模块的对外接口或者把日志组件当成核心业务模块画进架构图里。所以我现在特别强调让 SKILL.md 里写清楚“哪些目录必须忽略哪些文件必须读取”。第二个坑是上下文长度不够。分析大型项目时AI 可能读到一半就丢了前面的信息导致后面的判断不连贯。应对方法是缩小分析范围严格控制输入文件数。第三个坑是输出格式不可复用。如果 AI 生成的是图片而不是 Mermaid 或 PlantUML 代码那你后续就没法修改和维护。我一般要求 AI 总是输出可编辑的图代码而不是一张静态图。第四个坑是忽略人工复核。AI 读代码的能力再强也做不到百分百准确。尤其涉及业务语义的部分比如某个服务的职责边界AI 很容易理解偏差。所以生成结果后一定要让熟悉业务的人过一遍模块清单。7.2 我现在推荐的落地方案如果你今天就想试我的建议是先找一个你完全熟悉的项目按照这个思路做一个最小 Skill 文件。在项目里跑通一次对照你自己的认知检查 AI 输出的准确性。确认没问题之后再用到你不熟悉的项目上。不要一开始就追求“全自动”。这个方案的实际价值是帮你把重复梳理工作降到最低而不是替代人的判断。我曾经花了一个下午手动给一个十几模块的服务端项目画架构图后来改成这个 Skill 思路再梳理类似项目时大部分时间都花在“检查”而不是“梳理”上。对于需要频繁给项目写文档、做方案的人来说这已经能省下大量重复劳动了。
AI读代码生成架构图：用Skill把画图时间从半天压缩到十几分钟
架构图这个事平时看着简单真动手画起来特别烦。尤其是拿到一个不熟悉的项目或者刚接手一套微服务代码你想理清楚服务之间怎么调用、模块怎么划分、数据流向哪靠人肉读代码再拖框连线一个下午基本就没了。最近我试了一种新玩法给 AI 配一个处理代码架构图的 Skill让它自己读代码、自己梳理模块关系、直接输出架构图。实测下来对于中小型项目和中大型项目的模块梳理这个思路能把画图时间从半天压缩到十几分钟。这篇文章就围绕“AI 读代码生成架构图”这件事把 Skill 的结构、运行条件、实际步骤、参数配置和踩坑点完整拆一遍。先说结论这个 Skill 不是简单的“把代码丢给 AI 然后让它画张图”而是通过一套规则文件让 AI 按固定流程去扫描目录、分析依赖、抽取模块职责最后用统一的图表格式输出。它解决的核心问题不是“画图”而是“理解代码结构”。画图工具遍地都是真正卡住人的是代码阅读和结构梳理。如果你经常需要给项目写文档、做技术方案、给团队讲架构或者刚接手不熟悉的代码仓库这个方案值得试试。1. 为什么画架构图这件事卡点从来不在“画”而在“读”很多人第一反应是画架构图不是有 draw.io、ProcessOn、Visio 吗拖拖框框不就行了工具确实很多但问题不在于工具而在于画图之前你必须先知道“要画什么”。1.1 手动画图的三个真实痛点第一读代码成本高。一个模块几十个文件类之间的继承、接口实现、依赖注入、配置项关联靠肉眼扫很难短时间建立完整的结构认知。第二结构容易过时。代码改了图没更新过两周再看图跟实际代码对不上图就变成了废图。第三批量梳理时人很容易漏。画完服务 A 和 B 的调用关系可能漏掉通过消息队列解耦的那条链路画出来的架构图看着完整其实关键路径缺失。这些痛点单靠画图软件解决不了。真正需要的是先把代码结构读出来再落到图上。以前这个工作只能靠人现在可以让 AI 代劳。1.2 Skill 到底改变了什么Skill 在 AI 编程工具里是一种可复用的能力包。常见的做法是用一个 markdown 文件定义使用规则再配合脚本、数据文件、示例内容让 AI 在特定场景下按照你预设的流程工作。放到架构图这个场景里Skill 要完成的事情不是“拿现有文字描述生成图”而是拿到代码仓库路径。扫描目录结构了解项目全貌。读取关键文件识别模块边界。分析模块之间的调用和依赖关系。按固定格式输出架构图代码。这其实是把“架构师梳理项目”的流程标准化了。AI 负责干活你负责检查结果。我把这套思路整理成 Skill 文件后在几个不同规模的项目上都试过效果很稳定。2. 一个能用的架构图 Skill拆开看就四件套很多人以为 Skill 就是写一段提示词让 AI 去执行实际不是。成熟的 Skill 应该有固定的目录结构、明确的规则文件、可执行的辅助脚本以及输出格式约束。四样东西缺一个结果都会不稳定。2.1 SKILL.md 才是真正的入口文件这个文件是整个 Skill 的核心。AI 加载 Skill 时优先读它所以里面要写清楚这个 Skill 解决什么问题、适合分析哪些代码仓库、工作流程分几步、输出格式是什么、遇到看不懂的代码怎么办。我当时写的 SKILL.md 里重点强调了几个约束必须先列出项目根目录结构再决定从哪些文件入手。不要直接打开所有文件先读构建文件、入口文件、路由文件、配置目录。输出必须使用 Mermaid 格式同时给一份模块解释说明。每个模块要标注职责、关键文件列表、对外依赖。遇到无法判断的依赖关系不要瞎猜要标记为待确认。这些约束非常关键。没有约束的 AI 经常会漏掉关键依赖或者编造不存在的模块名。有了 SKILL.mdAI 的行为就变成了一条固定流水线。2.2 用脚本补齐 AI 读不到的信息AI 在分析代码时有一个天生的盲区它在一次对话里能读取的文件数量有限。如果项目文件很多AI 不可能每个文件都打开看一遍。这时候就需要一个辅助脚本先把整个项目的文件列表、目录层级、文件大小、语言类型统计出来作为 AI 的“项目地图”。我一般在 Skill 里放一个 Python 脚本运行之后输出类似这样的结构:# 示例扫描项目目录并生成结构清单 import os import json from collections import defaultdict def scan_project(root_dir, max_depth4, excludeNone): exclude exclude or {node_modules, .git, dist, build, __pycache__, .venv, venv, .idea} tree defaultdict(list) for dirpath, dirnames, filenames in os.walk(root_dir): depth dirpath.replace(root_dir, ).count(os.sep) if depth max_depth: continue dirnames[:] [d for d in dirnames if d not in exclude] rel_dir os.path.relpath(dirpath, root_dir) tree[rel_dir] [f for f in filenames if not f.startswith(.)] return tree if __name__ __main__: import sys root sys.argv[1] if len(sys.argv) 1 else . result scan_project(root) for directory in sorted(result.keys()): files result[directory] if files: print(f{directory}/) for f in files: print(f ├── {f})这个脚本不复杂但它能给 AI 提供一次扫描就能覆盖整个项目的信息。AI 拿到这个结构清单后就能判断先读哪个入口文件、哪些目录可以跳过、哪些模块可能是核心依赖。2.3 输出格式要先定死如果让 AI 自由发挥每次输出的格式可能都不一样。这次是 Mermaid下次就变成 PlantUML或者干脆输出一段 Json 描述。所以 Skill 里必须强制规定最终输出结构。我会在 SKILL.md 里规定统一输出三部分输出部分内容要求格式Mermaid 代码块必须包含顶层图、模块关系、核心依赖线mermaid 代码块模块清单每个模块的职责、关键文件、主要对外依赖表格待确认项无法确定的关系、疑似失效的依赖、需要人确认的部分列表这样 AI 输出的结果既是图也是文档。给人看图给文档留排查线索。3. 在 Claude Code 或 Cursor 里把 Skill 跑起来Skill 的落地方式取决于你用的客户端。不同工具对 Skill 的目录约定和加载方式不完全一样但核心思路一致把 Skill 文件放到指定目录然后在对话里通过名称触发。3.1 先确认客户端支持自定义 Skill目前主流 AI 编程工具基本都支持自定义规则或技能文件只是叫法不同。有些叫 Skill有些叫 Rules还有些叫 Commands。我实测使用较多的是 Claude Code 和 Cursor两者都能通过配置文件加载自定义规则。如果你用的是其他工具先看文档里有没有类似“Agent Skills”“Custom Commands”的入口。目录结构一般这样放~/.claude/skills/ └── code-visualizer/ ├── SKILL.md └── scripts/ └── scan_project.pyCursor 里则可能放在.cursor/skills或者通过.cursor/rules加载。没有固定标准要以你用的工具版本为准。我建议先在官方文档里查清楚目录约定再开始省得后面排查“为什么 Skill 没生效”的问题。3.2 建一个最小可用版本别一上来就堆功能我第一次做架构图 Skill 时想得很复杂塞了一大堆规则和脚本进去结果 AI 加载后行为反而混乱。后来我学到一个原则先做最小可用版本。最小版本只需要三样东西# 技能名称代码架构图生成 # 触发词使用架构图、分析项目结构 # 工作步骤 1. 先运行 scan_project.py 获取项目文件清单。 2. 根据清单选择入口文件和关键配置文件。 3. 读取文件内容识别模块和依赖。 4. 按输出模板生成 Mermaid 图和模块表格。再加上一个最简单的扫描脚本。先在一个只有十来个文件的 Demo 项目上跑通确认 AI 能按流程走。跑通之后再逐步加复杂规则比如“指定忽略目录”“限制分析深度”“输出架构决策记录”等。3.3 单项目跑通后再验证批量场景很多时候大家习惯一上来就压测直接把一个几百个文件的微服务仓库丢给 AI 分析。结果不是超时就是漏模块。我建议按顺序来先用一个单模块项目验证 Skill 是否被正确加载。确认输出格式是否正确Mermaid 能否正常渲染。再加一个中等规模项目验证模块拆分逻辑。最后才上微服务项目并配合目录深度限制和文件排除规则。这里有一个容易忽略的细节AI 的上下文窗口有限分析大项目时必须让脚本先过滤掉不重要的目录和文件比如测试代码、构建产物、第三方依赖目录。如果不过滤AI 的大部分“注意力”会被无关文件消耗掉真正重要的架构信息反而读不完整。注意不要一上来就把整个仓库直接丢给 AI 读。先让扫描脚本输出文件清单再在提示词里指定“先读 pom.xml / package.json / main.go / manage.py 这类入口文件”效率会高很多。4. 从小项目到微服务目录控制、模块抽取和依赖过滤Skill 在小项目上跑通容易但到了微服务项目问题就会暴露出来服务数量多、依赖链路长、有些服务之间还通过消息队列异步通信。这时候如果还用同一套规则很可能画出来一张巨复杂的图连作者自己都看不懂。4.1 先做模块级架构图再做全局架构图我的处理方式是把分析拆成两层。第一层是模块级让 AI 分析单个服务或单个核心模块输出这个模块内部的类关系、接口、关键流程。第二层是全局级分析各个服务之间的调用关系、数据依赖和部署边界。Skill 里必须让 AI 在输出全局架构图之前先输出模块级架构图。如果 AI 直接尝试生成一张全项目大图很容易缺漏信息。可以这样要求分析步骤 1. 先识别根目录下的模块或服务清单。 2. 逐个模块分析其对外暴露的接口和核心依赖。 3. 先输出模块级 Mermaid 图。 4. 再基于模块清单输出全局 Mermaid 图。这样做的好处是后续你发现某张图有问题只需要替换对应模块的分析结果不需要重跑整个项目。而且多模块项目里模块级图往往比全局图更有实际价值。4.2 依赖爆炸时必须设置过滤规则当项目依赖特别多时比如一个 Java Spring Cloud 项目里有几十个服务服务之间的依赖关系会有几百条。全部画出来图就变成一团乱麻。所以在 Skill 里要加依赖过滤规则。常用做法是设置依赖阈值和忽略列表依赖过滤规则 - 只保留业务模块之间的依赖忽略对第三方中间件Redis、Kafka、MySQL的依赖线。 - 如果某个模块被超过 20 个模块依赖只显示其名称和职责不画入边。 - 消息队列依赖统一用虚线标记并单独列出 Topic 名称。 - 被过滤的依赖要记录到“待确认项”中方便人工检查。这样输出的图既保留了核心结构又不会因为次要依赖太多而失去可读性。说白了架构图的价值在于“帮助理解”不在于“展示所有细节”。4.3 批量分析时日志和输出命名要提前规划如果你要用 Skill 分析多个项目或者分析同一个微服务仓库中的所有模块不要只生成一张大图就结束。建议让 AI 按模块分别输出图片代码并存到独立文件。我一般这样组织输出目录output/ ├── module-01-order-service.md ├── module-02-user-service.md ├── module-03-payment-service.md └── global-architecture.md每个文件只包含一个模块的架构图和说明。这样方便后续单独更新某一模块也方便在文档系统里分别引入。如果所有内容都堆在一个文件里后续维护非常痛苦。同时如果任务比较长AI 中途可能因为上下文到达上限而出错。这时候不要直接重跑先看已经输出的部分是完整的再针对缺失模块单独续跑。5. 输出不是终点架构图也要有验收标准AI 生成的架构图不是出来就能直接用。我见过 AI 在分析时把模块名写错、把某个依赖方向画反、把根本不存在的中间件加进去。所以每次生成后都要按固定维度验收。5.1 四个维度检查架构图质量检查维度判断标准发现问题的处理方式模块完整性核心业务模块是否全部出现逐个对照代码目录确认是否有遗漏依赖正确性调用方向是否跟代码一致抽重点依赖文件人工核对命名准确性模块名、文件名是否真实存在用代码搜索功能验证明可读性图上是否有超过 30 条交叉线要求 AI 增加模块分组或过滤规则我第一次测的时候AI 把 “gateway-service” 写成了 “api-gateway”虽然功能相似但项目里真实名字不对直接放文档里就误导人。后来我在 SKILL.md 里加了一条强制规则模块名必须跟代码目录名完全一致不能改写、不能翻译。这个问题就解决了。5.2 常见渲染问题和排查顺序Mermaid 图有时渲染不出来或者预览报错。一般先别急着怪 AI先看代码块语法是不是有问题。我遇到过的情况有几种Mermaid 中模块名包含特殊字符比如括号、斜杠、中文标点导致节点解析失败。图太大超过预览器渲染限制。依赖线重复有环状引用导致渲染异常。排查顺序我建议这样先看 Mermaid 语法是否校验通过再确认模块名是否用了不允许的特殊字符最后看图是否太大需要拆分。大部分问题不是 AI 没读懂代码而是输出格式对渲染器不友好。排查时优先检查模块名中是否有特殊字符。把模块名统一改成“字母数字连字符”的格式能解决大部分 Mermaid 渲染问题。6. 哪些项目适合无脑用哪些项目要谨慎Skill 不是银弹。测试下来不同类型项目的效果差异挺大这里给一个适用范围参考。6.1 适合用 Skill 的项目类型中小型单体项目几百个文件以内模块边界清楚AI 读取后容易理解成功率高。微服务项目的模块梳理重点分析服务模块之间的调用关系比人工梳理效率高很多。技术文档更新给老项目补架构图省去人工读代码的耗时。新成员入职培训快速生成项目整体结构图帮助新人建立全局认知。技术方案评审输出模块依赖图用于评审会上讨论耦合点和优化方向。6.2 需要谨慎的项目类型超大仓库几万个文件即使有过滤脚本AI 也很难保证覆盖全面建议拆分后再分析。前端组件级项目如果图太细画到组件层会非常杂乱更适合用类型关系图代替架构图。多语言混合项目某些语言之间的跨语言调用关系AI 不一定能准确识别需要人工复核。强动态类型语言项目比如 Python 技术栈中大量使用装饰器、动态导入、依赖注入框架AI 分析时容易出现误判。6.3 没有 Skill 功能时怎么办如果你的工具不支持自定义 Skill也不用放弃这个思路。核心逻辑完全可以复刻成普通规则文件或者项目文档。在项目根目录放一份ARCHITECTURE_PROMPT.md里面写好分析步骤、输入范围、输出模板然后每次让 AI 读这个文件并执行。效果略逊于真正的 Skill但对大多数项目也够用。关键在于你要把“怎么分析代码、怎么判断模块边界、怎么输出图”这套规则固化下来而不是每次重新描述需求。固化成文件以后不管用哪个工具都能复用这套规则。7. 我踩过的几个坑和建议优先做的事最后分享一下我在实际使用中遇到的最多的几个问题以及我现在的处理习惯。7.1 最容易踩的坑第一个坑是让 AI 自由发挥。不写死规则AI 输出的图经常“看起来合理细看不对”。比如漏掉一个模块的对外接口或者把日志组件当成核心业务模块画进架构图里。所以我现在特别强调让 SKILL.md 里写清楚“哪些目录必须忽略哪些文件必须读取”。第二个坑是上下文长度不够。分析大型项目时AI 可能读到一半就丢了前面的信息导致后面的判断不连贯。应对方法是缩小分析范围严格控制输入文件数。第三个坑是输出格式不可复用。如果 AI 生成的是图片而不是 Mermaid 或 PlantUML 代码那你后续就没法修改和维护。我一般要求 AI 总是输出可编辑的图代码而不是一张静态图。第四个坑是忽略人工复核。AI 读代码的能力再强也做不到百分百准确。尤其涉及业务语义的部分比如某个服务的职责边界AI 很容易理解偏差。所以生成结果后一定要让熟悉业务的人过一遍模块清单。7.2 我现在推荐的落地方案如果你今天就想试我的建议是先找一个你完全熟悉的项目按照这个思路做一个最小 Skill 文件。在项目里跑通一次对照你自己的认知检查 AI 输出的准确性。确认没问题之后再用到你不熟悉的项目上。不要一开始就追求“全自动”。这个方案的实际价值是帮你把重复梳理工作降到最低而不是替代人的判断。我曾经花了一个下午手动给一个十几模块的服务端项目画架构图后来改成这个 Skill 思路再梳理类似项目时大部分时间都花在“检查”而不是“梳理”上。对于需要频繁给项目写文档、做方案的人来说这已经能省下大量重复劳动了。
