前阵子接手一个几乎没文档的老系统。代码能跑测试能过可当我想弄明白订单模块到底依赖哪些基础服务、哪些内部接口还在被别的系统调用时只能一头扎进源码里翻。最尴尬的是我憋了半天画出来一张架构图拿给当年的开发同事看对方扫了一眼说“这个服务其实已经下线了你图里画的是上一代的。”文档和现实脱节到这种程度比没有文档还让人头疼。后来我开始认真对待“AI辅助软件架构图生成”这条路不是让AI随便画一张漂亮的拓扑图交差而是让AI先读代码、抽依赖、产出结构化描述再由人审核校正用脚本渲染成图。半年下来我手上几个项目的架构文档质量明显上了一个台阶新同学看文档能直接上手评审会上也不会再因为“图里画的和实际跑的对不上”被反复挑战。这篇就把这套方法的完整思路、提示词设计步骤和踩坑过程整理出来给同样被架构文档折磨的人一个参考。1. 一张架构图的信息含量为什么文档质量卡在画图上1.1 架构图不是“画”出来的是“理”出来的很多人以为架构图难难在“画”其实恰恰相反。画图工具谁都会用拖几个框、拉几条线半小时就能弄出一张像模像样的图。真正的难点在“理”——理清楚系统里到底有哪些模块、模块之间谁调用谁、数据往哪个方向流、哪些是核心链路、哪些是边缘能力。我见过太多团队的做法是这样某个项目上线时负责人口头描述一遍系统大致的样子然后让一个不太了解全局的同事根据 PPT 里的画风“美化”出一张架构图。图是好看但里面至少三分之一的信息是拍脑袋补的。等到系统迭代几轮新的微服务拆出来了旧的定时任务下线了这张图却没人维护自然就成了挂在 Wiki 上的“历史文物”。文档质量差的根子就在这里架构图的内容没有和真实代码建立对应关系画图的人凭记忆改图的人凭感觉。AI能在这里发挥作用不是因为AI会画画而是因为AI擅长从大量文本里抽取实体和关系正好对口“读代码、理依赖”这件事。1.2 分层视角从调用关系到部署拓扑要把架构讲清楚至少得能回答下面这几类问题系统有哪些独立部署的进程或服务服务之间有调用关系吗是同步接口还是异步消息数据存储用了几类谁在读写外部依赖有多少走的是内网网关还是公网API前端的页面能触达哪些后端能力中间有没有经过网关或鉴权也就是说架构图信息含量高低取决于它能不能把“逻辑架构”“部署架构”“数据流向”这几个视角一下子讲明白。单张图画得再精美如果只画了几个框和几条连线没有说明层次和方向阅读者还是得去翻代码才能确认细节。我之前习惯用白板先画一遍再誊到文档工具里但每次誊完都觉得少点东西——要么漏了某个旁路依赖要么把某个已经被网关屏蔽的老接口画成了当前路径。这类问题恰好是 AI 辅助架构图生成最有价值的地方可以让模型基于代码分析结果去补全关系而不是靠人的记忆去补。1.3 文档质量的三个可量化维度怎么判断一张架构图的质量好坏我后来归纳了三个维度每次评审都用它们打分维度说明低质量的典型表现完整性核心服务、外部依赖、数据存储是否齐全画了三层实际上有五层漏了消息队列准确性图中的关系是否与代码实际行为一致把“HTTP调用”画成“RPC调用”指向已下线服务可维护性改一处业务逻辑后图能否低成本同步更新每次更新要人工重画一遍耗时一下午这三个维度里准确性和完整性靠传统的人工方式很难长期保持尤其是项目超过一年后人事变动、代码腐化、技术栈调整都会让图迅速失真。AI辅助生成的意义就是把这几个维度的成本大幅降下来让“维护架构图”不再是一个靠自觉才能完成的任务。2. AI辅助生成的整体流水线从代码到架构图2.1 第一步让AI先“读”代码而不是直接画图我踩过的一个很大的误区是一开始就丢给AI一句“帮我画这个项目的架构图”。AI没有看过项目代码单凭这个指令只能生成一张放之四海皆准的模板图看起来专业实际等于没画。正确做法是先做“代码信息预处理”把项目的目录结构、核心模块的关键代码片段、接口定义、配置文件等资源整理成文本摘要再交给AI。不必把整个代码库灌进去那样既占用上下文窗口也会让AI把注意力放到无关的框架细节上。我通常会把下面这些信息喂给模型README 里写明的系统职责如果有项目根目录的模块划分比如packages/、services/、modules/下有哪些目录每个服务的入口文件、路由配置文件对外暴露的接口文档或 OpenAPI 风格的路由列表数据库建表语句的表名清单消息队列的 topic 名称和消费组名称有了这些AI才算“读过”这个项目的骨架而不是凭空发挥。实际操作中我会写一个小脚本把上述信息抓取合并成一个纯文本文件然后分段交给模型分析而不是一次性全塞进去。2.2 第二步输出结构化描述而非图片这里有个关键决策不要直接让AI生成图片先让它输出结构化的文本描述。为什么因为图片是一次性的改起来麻烦而且难以追溯。结构化文本则相当于中间产物既能被人类看懂又能被脚本解析渲染成图。后续如果系统变了只需对应修改文本里的一行依赖关系重新跑一遍渲染脚本整张图就更新了。我使用的描述格式很简单核心就是“组件”和“依赖关系”两种元素service: user-service layer: application depends_on: - order-service - payment-service - redis-cache service: order-service layer: application depends_on: - inventory-service - mysql-main api-gateway: layer: gateway depends_on: - user-service - order-service格式里的depends_on表示“依赖”方向清晰。AI在生成时我明确要求组件命名必须与代码里的模块名保持一致不能自己发挥改叫“用户服务”“订单服务”这类口语化名称。这种方式的另一个好处是方便追溯我可以让AI在每条依赖关系后面标注“依据”比如“来自 user-service 里的RestTemplate调用”方便后续人工作坊验证。2.3 第三步用脚本把结构化描述渲染成图拿到结构化描述后渲染成图这件事就可以完全交给脚本不用再让任何人都拖一遍框。我用的是自写的一个简单解析脚本大致逻辑是def parse_arch_text(text): services [] current None for line in text.strip().splitlines(): if line.startswith(service:): current {name: line.split(:, 1)[1].strip(), deps: []} services.append(current) elif line.startswith(depends_on:) or line.startswith( -): if current is not None: dep line.strip().lstrip(-).strip() if dep: current[deps].append(dep) return services def build_graph(services): edges [] for svc in services: for dep in svc[deps]: edges.append((svc[name], dep)) return edges然后把解析出来的节点和边交给绘图引擎生成 SVG 或 PNG。节点按layer分组相同层放在同一行或同一列有依赖关系的两个节点之间画一条带箭头的线。脚本跑完还能顺带统计一下“每个服务被多少上层服务依赖”用来识别核心节点。这套流程跑通后更新架构图的时间从“画一下午”缩短到“改几行文本、跑一下脚本”文档质量自然不会再像以前那样快速腐烂。3. 提示词与工作流设计的几个关键决策3.1 为什么要分步走而不是一次生成让AI在一个任务里同时完成“读代码、抽依赖、分层、画图”四件事效果通常很差。模型很容易在一路输出里迷失前面的分析结论到后面就被遗忘了或者为了“完成整张图”而强行把不存在的依赖补上。所以我坚持让AI分步执行第一步只分析代码结构输出模块清单。第二步根据模块清单识别依赖关系输出依赖文本。第三步做层级划分把模块归入网关层、应用层、领域层、基础设施层。第四步由人工审核依赖文本确认无误后再交给渲染脚本。每步单独控制我可以随时介入纠正某一步的偏差。比如AI把数据库配置项当成业务服务时我在第二步结束就能发现并纠正不会一路错到最后。3.2 约束格式给AI一个“填空模板”AI生成内容时如果要求不够细产出就会很散。我的做法是给一个严格的“输出模板”让模型只往里面填空不要自由发挥写小作文。我常用的提示词模板大致长这样你是一名资深软件架构师。下面是我整理的某项目模块清单请根据这些信息生成 系统依赖关系的结构化描述。 输出要求 1. 只输出结构化文本不要输出任何解释、引言或总结。 2. 组件名称必须与模块清单里的名称完全一致。 3. 依赖关系方向用 depends_on 表示A depends_on B 表示 A 依赖 B。 4. 忽略通用基础库日志库、工具库、ORM框架之间的内部依赖。 5. 将每个组件标记为以下 layer 之一gateway、application、domain、infrastructure。 模块清单 [此处填入项目模块清单]模板的价值在于降低AI的“发挥空间”把它的任务收敛成一次“翻译加归类”。我在多个项目里验证过加了模板后输出格式的稳定程度明显提升偶尔还需要微调但不再需要大改。3.3 引入人工质检AI画的图必须能追溯到代码AI产生的内容再专业也不能直接进文档。这是我在项目里坚持的一条铁律任何AI生成的依赖关系都必须能追溯到代码依据。这个“可追溯性”就是质量保障的最后一环。具体操作上我会要求AI在每条依赖后面用一行简短的“依据说明”例如user-service depends_on order-service 依据: user-server/src/main/java 下 OrderClient.java 调用 order-service 的 /api/order人工审核时只需要抽样检查这些依据是否真实存在。如果AI无法给出依据而是说“根据经验用户服务通常需要订单服务”这条依赖就会被标记为“存疑”必须由人确认后再保留。这套机制下来AI生成的初稿仍然只是“半成品”但相比以前从零画图人的工作量已经大幅减轻而且最终的准确性是有根据的不是靠记忆赌运气。4. 落地过程中的真实踩坑记录4.1 信息过载AI把底层库调用也画进去了第一批测试图跑出来时我差点被图上的节点数量吓到。AI把框架内部的调度逻辑、ORM 的底层连接池、缓存的客户端SDK全都当成了一级组件画进架构图整张图密密麻麻根本没法看。问题出在“项目模块清单”本身太粗没有区分业务代码和基础设施依赖。后来我在前置脚本里增加了一个“排除列表”先把通用基础库的包名过滤掉再让AI分析。同时提示词里也明确说明“只关注业务模块之间的直接依赖不展开框架内部机制。”过滤后再生成节点数从六十多个降到了二十几个信息密度一下就有了。4.2 抽象层级混乱把配置项当成了服务另一次离谱的输出是AI把“配置文件里的数据库地址”“网关路由的一个路径前缀”都当成独立服务节点。大概是模型从文本里识别出太多“看起来像组件”的词却没有理解它们其实只是某个服务的属性。这次教训让我意识到在给AI的信息里必须显式区分“服务”和“配置”。我在模块清单里增加了一列“类型”标明每个条目是服务、数据库、MQ还是配置项提示词里也加了规则“只有能独立部署或独立运行的进程才作为服务节点其余一律不进入依赖图。”这一步让抽象层级问题基本绝迹。4.3 过期代码的干扰AI被死代码带偏老系统里总有那么一堆没人敢删、实际也不再被调用的“祖传代码”。AI根据这些代码分析会把早已不存在的依赖关系画进图里。我最初没意识到这个问题直到我在审核时发现图中有一个“短信推送服务”而据我所知这个服务三年前就已经下架了。后来的处理办法是分两步走。第一步先用静态扫描工具把项目里“没有任何引用”的类和接口标记出来作为“疑似死代码”清单第二步把这个清单传给AI并且明确要求它优先分析有活跃调用的路径忽略清单里标记的内容。这并不能百分百保证AI不犯错但漏网的死代码比例大幅下降人工抽查的负担也减轻了。4.4 同义词风暴同一个模块多个叫法AI没有维护“命名一致性”的意识。在我喂给它的材料里同一套服务在代码目录里叫member-center在配置里叫membership在数据库表里叫t_memberAI初稿里三套叫法混着出导致渲染出来的图里出现了三个看起来不同、实际指同一个东西的节点。这个问题的解法是给AI配一张“术语映射表”提前声明这些名称属于同一个实体member-center ≡ membership ≡ t_member 统一命名为 member-centerAI只要看到其中任意一个名字就统一输出成member-center。从那以后我零散的做法变成了一套固定流程每次生成前都先花十分钟梳理术语表看似多了一步实际省了后面大量返工。踩坑现象根因解决办法节点爆炸、图面拥堵没有区分业务依赖和底层库依赖前置脚本过滤基础库提示词限定“只看业务直接依赖”配置项被当服务模型分不清进程与配置模块清单加“类型”列只允许独立进程成为节点死代码污染依赖关系老系统存在未下线代码先静态扫描标记死代码再让AI忽略同一模块多个叫法不同配置文件里名称不一致维护术语映射表强制统一输出5. 实测效果与后续扩展5.1 三张图的对比人工草稿、AI初稿、人机协作终稿为了验证这套流程到底有没有价值我在同一个项目上做过一次直接对比。结果是三个版本放在一起后差距一眼就能看出来。对比维度人工草稿AI初稿人机协作终稿耗时约半天脚本加模型分析约1小时AI产出后再人工审核约2小时完整性漏掉了2个异步消费者完整枚举出所有消费者完整且逐个确认过准确性2处依赖方向标反3处依赖方向待核实全部标注了代码依据可维护性改一处要重画重新跑AI分析即可文本化描述改一行重渲染可读性布局美观但层级不清层级清晰但偶有冗余节点分层清楚节点数量适中AI初稿虽然还不完美但它最大的价值是“兜住了底线”——不会再因为人的记忆盲区把某个服务整个漏掉。人机协作终稿才是真正能放上评审会的版本信息完整、可追溯、也经得起追问。5.2 这套流水线适合什么场景试了大半年后我的判断是这套方案的价值并不是均匀的它最擅长下面这几类场景老系统考古项目组变动大、文档缺失代码本身是唯一真相AI辅助可以从代码里把依赖关系“掘”出来。新人入职培训材料一张图配合代码位置标注新人上手速度比翻几千行代码快得多。评审前的快照每次做架构评审前重新跑一遍流水线生成一次性版本至少保证图没有明显过期。架构演进前的现状基线在说“要重构”之前先弄清楚当前系统到底长什么样省得方案评审时鸡同鸭讲。但也有一些场景不适合项目代码极少、逻辑完全在脑内、或者系统还在纸面设计阶段没有落地代码时AI能拿到的信息太少生成的图只能当参考不如直接在白板上讨论来得高效。5.3 还可以往哪些方向延伸目前这套流水线在我这里已经稳定运行了几个月。再往后我想做的扩展有三个一是把“术语映射表”的维护也半自动化每周跑一次代码扫描自动发现新增的命名并提醒我确认二是把依赖描述文件接入自动构建流水线代码合并后自动生成一版差异清单告诉我哪条依赖关系发生了变化三是让AI基于不同批次的结构化描述自动输出一段“架构演进说明”当系统里新增了某个核心依赖时它能写清楚这轮改动影响了哪些链路。这些方向能不能全部落地还不确定但至少有了一版可信的架构描述作为基础后面想做自动化就顺理成章。聊回最终的体会AI辅助生成架构图这件事真正改变的不是“画图”这个动作而是整个工作流——把依赖抽取从“人的记忆”变成“基于代码的分析”把维护成本从“每次重画”降到“改文本重渲染”。模型的能力还在快速迭代但流程设计始终比模型本身更重要。只要你的流程里留出人工审核的环节、约束好输出格式、坚持依赖可追溯哪怕模型不那么聪明产出的文档质量也不会差到哪里去。最后再分享一个实用小技巧所有喂给AI的材料我都会顺手保留一份命名规范和术语表在项目仓库里它不仅是给AI用的提示词素材更是新同事了解系统边界的捷径。一次整理长期受益。