Claude Code反向工程整个软件系统的架构

AI能帮你“反向工程”整个软件系统的架构？ 这个真实案例，就发生在一位资深架构师身上——他用 Claude Code 一天之内，把一个复杂电商系统的端到端流程“扒”得明明白白！这不仅让AI能更精准地协助排查线上问题，还让新入职的同事秒懂系统全貌。

先简单介绍一下这位大神——尼克·坦（Nick Tune），他是《架构现代化》（Architecture Modernization）一书的作者，长期深耕领域驱动设计（DDD）、组织架构设计和持续交付。他不仅是技术布道者，更是实战派，经常在 Medium 上分享如何用现代工具解决遗留系统难题。他这次的实验，不是纸上谈兵，而是基于真实工作场景，用 AI 工具解决“没人搞得懂的复杂系统”这一老大难问题。

想象一下：你的公司有几十个微服务，每个团队维护自己的代码库，订单、支付、库存、物流各自为政。客户一投诉，你根本不知道问题出在哪一环。传统做法是翻代码、看日志、问人，效率极低。而 AI 虽然聪明，但如果只给它一个仓库的代码，它也“看不见森林”。尼克意识到：必须让 AI 理解整个端到端业务流程，才能真正帮上忙。

于是，他决定用 Claude Code 来“逆向绘制”系统架构图——不是画静态的框框连线，而是动态的、可执行的、包含所有 API、事件、数据库操作的完整流程图。

尼克没有直接扔代码给 AI，而是先写了一份轻量级需求文档，明确告诉 Claude Code 要做什么。核心目标就一条：从用户点击“下单”开始，一路追踪到物流事件发布结束，把每个环节都串起来。具体要求包括：

- 记录 UI 触发的页面路径  
- 标注 BFF（后端前置层）接口地址和所属仓库  
- 列出所有下游服务调用  
- 标记数据库读写操作  
- 记录发布的事件（比如 order.placed）  
- 找出事件的消费者  
- 标注触发的工作流（如 syncOrders）

他还特别强调：不要花里胡哨的架构图，只要能被 AI 和人同时理解的 Mermaid 流程图，而且必须按仓库划分“泳道”，每个步骤只能是 API 调用、领域方法、数据库操作、事件发布等八种标准类型之一。

这份需求文档长这样（节选）：

#AI 架构分析任务说明

##目标
映射出本应用参与的所有端到端流程，包括：
- 从 UI 触发的动作
- 到 BFF 的调用
- 到后端 API 的调用
- 或由事件触发的异步流程

##要求
每个流程必须包含：
1. 触发页面的 URL 路径
2. BFF 接口路径及所在仓库
3. 下游服务调用路径
4. 数据库交互操作
5. 产生的事件（全名，如 private.orders.order.created）
6. 事件消费者（如可识别）
7. 触发的工作流（如 synchronizeOrder）

##信息来源
- <code>/docs/architecture</code>：领域概念说明
- 各 API 项目的 <code>openapi.json</code>：接口清单
- 领域实体的方法：如 <code>Order.place()</code>

一个订单流程可能涉及五个仓库：前端、订单服务、支付服务、库存服务、物流服务。Claude 默认只能看当前目录，但尼克通过配置权限，让它能访问本地所有代码目录，甚至调用 GitHub 客户端搜索远程仓库。他还贴心地告诉 AI：“去 /docs/architecture 找领域概念，去每个 API 项目的 openapi.json 里找接口清单”——这相当于给 AI 一张藏宝图，让它知道去哪儿挖关键信息。

权限配置如下（.claude/settings.local.json）：

{
  "permissions": {
    "allow": [
      "Read(/Users/nicktune/code/)"
    ]
  }
}

这样，Claude 就能自由穿梭于所有本地代码仓库，甚至调用 gh 命令行工具搜索远程仓库。

第一个流程花了整整两小时。一开始 Claude 画的是垂直序列图，好看但太细，方法调用堆成山，根本没法读。尼克果断叫停，改成横向泳道图：每个服务一个泳道，流程从左到右推进，清晰直观。他还反复纠正 AI：别写“调用某个内部函数”，要写“POST /api/payments/authorize”这种真实接口；别漏掉事件消费者；别忽略工作流里的隐藏步骤。

最终，他们定下标准：每个流程单独一个文件夹，包含 README.md（完整说明）和 diagram.mermaid（纯语法流程图），绝不分散内容。

Mermaid 图必须严格遵守以下规则（节选自需求文档）：

###diagram.mermaid 要求

关键规则：
1. 文件格式：纯 Mermaid 语法，以 .mermaid 为扩展名
   - 无 Markdown 头部
   - 无代码块包裹（不要 mermaid）
   - 直接以 flowchart LR 开头

2. 使用泳道格式：flowchart LR
   - 每个仓库是一个水平泳道（subgraph）
   - 流程从左到右
   - 泳道标签用 emoji 突出（如 order-api）

3. 合法步骤类型（只能是以下之一）：
   - HTTP 接口：POST /api/orders
   - 聚合方法：Order.create()
   - 数据库操作：[(Database: INSERT orders)]
   - 事件发布：Publish: private.orders.order.created
   - 工作流触发：⚙️ Workflow: syncOrders
   - Lambda 调用：Lambda: payment-handler-lambda
   - UI 动作：User clicks "Place Order"

有了模板，后续流程就快了。每个新流程只需 15 分钟左右，尼克边做其他事边等结果。他还会让 AI 先列出所有可能的流程，再逐个验证：“这个 API 真的没被任何流程覆盖吗？”“这个事件真的只有这两个消费者？”有时候，AI 还真能通过 GitHub 搜索，发现本地没有的仓库里的隐藏消费者！

他还不断更新需求文档，加入新规则。例如：

规则：追踪工作流到最终事件

问题：漏掉事件，因为没读工作流实现文件  
规则：遇到工作流时，必须：
1. 找到 .asl.json 文件（AWS Step Functions 定义）
2. 通读整个工作流
3. 记录所有发布的事件

示例：
- 原以为 syncOrder 以 order.synced 结束
- 读 syncOrder.asl.json 后发现实际以 legacy.order.updated 结束
- 该事件对后续流程至关重要

尼克挑了一个复杂的客服工单，让 Claude 分析。这次，他加了一条指令：“先去 /docs/architecture/flows 里找相关流程”。结果，AI 立刻定位到“订单上传与历史同步”流程，准确列出预期行为：应该并行处理四个域、发布哪个事件、最终状态是什么。接着，它还主动提出要查事件日志，对比“实际发生”和“应该发生”的差异。

这不再是简单的日志分析，而是像资深工程师一样推理系统行为！尼克感慨：以前要花几小时翻代码的事，现在 AI 几分钟就能给出结构化分析。

尼克坦承：AI 会犯错，甚至编造不存在的事件或调用。他曾发现一个关键事件被漏掉，因为 AI 没读工作流定义文件（.asl.json）。于是他追加规则：“遇到工作流，必须读完整定义，找出所有发布的事件”。他还建议：定期用确定性工具（如 ts-morph）重建架构图，或在 CI 流程中加入自动校验，甚至每季度全量重生成一次。

尼克认为，靠 AI 逆向解析终究是“补救”。未来，平台工程的核心任务，应该是让系统天生就能“自描述”——你只要按平台规范写代码，架构图、依赖关系、事件流就自动产生。像 Event Catalog 这类工具，正在朝这个方向走。对于没有历史包袱的创业公司，这简直是 AI 时代的超级杠杆。

为了让读者更直观，尼克让 Claude 生成了一个匿名化的“下单-支付-履约”流程示例。它包含：

- 7 个关键事件：从 private.orders.order.created 到 shipping.shipment-created  
- 5 个服务仓库：前端、订单、支付、库存、物流  
- 完整的失败处理：支付失败或库存不足时，自动取消订单并通知用户  
- 数据库操作明细：orders 表插入、inventory_reservations 表更新等  
- 外部集成：Stripe 支付网关、FedEx/UPS 物流 API  

- 接手遗留系统的新人：不用再靠“口口相传”理解业务  
- 跨团队协作者：快速搞清自己的改动会影响哪些下游  
- SRE/技术支持：结合架构图和日志，精准定位故障根因  
- 架构治理团队：自动发现未文档化的隐式依赖  

尼克的实验告诉我们：AI 不是万能的，但当你给它清晰的上下文和结构化规则，它就能成为你大脑的“外挂”。与其担心被取代，不如学会如何“指挥”AI，让它帮你搞定那些枯燥、复杂、跨系统的脏活累活。未来的软件工程师，拼的不是写代码速度，而是设计认知框架的能力。