Skip to main content
← All posts
作者：Sagasu
AI辅助开发文档驱动遗留代码

#002-文档驱动项目-让 AI 帮你理解遗留代码

——从“看不懂”到“看明白”的实战指南

封面：AI 帮你理解遗留代码

系列导读：这是《老项目如何引入文档驱动》系列的第 2 篇。上一篇我们聊了为什么老项目需要文档驱动，这一篇开始动手——如何用 AI 快速理解那些“看不懂”的遗留代码。

周五下午的噩梦（续）

还记得上一篇提到的场景吗？

周五下午 5 点，产品经理突然说：“支付功能要支持花呗分期，下周上线。”

你打开代码，支付模块有 15,000 行代码，核心处理逻辑分散在 8 个文件里，上次改这块的人已经离职了。

你打开代码，支付模块有 15,000 行代码，核心处理逻辑分散在 8 个文件里，上次改这块的人已经离职了。

传统做法是什么？

花一整个周末，对着代码一行行看，画流程图，猜测每个方法的作用。运气好的话，周一早上能大概搞明白；运气不好，可能还是云里雾里。

但现在，你有了 AI。

能不能让 AI 帮你快速理解这堆代码？

答案是：能，但有前提。

这篇文章就是告诉你：如何用 AI 理解遗留代码，以及——更重要的——如何避开 AI 的坑。

一、传统方法 vs AI 辅助：一个真实对比

传统方法 vs AI 辅助对比

让我们用一个真实案例来对比。

传统方法：小李的周末

小李是我们团队的一名高级工程师，负责维护一个运行了 3 年的电商平台的支付模块。

任务：理解支付回调处理逻辑，为新增花呗分期做准备。

第 1 天（周六）:

  • 上午：找到入口方法 handlePaymentCallback()，发现它调用了 6 个其他方法

  • 中午：画了一张流程图，但还有 3 个分支逻辑不确定

  • 下午：翻 Git 历史，看了 50 次提交记录，找到一些线索

  • 晚上：问了之前的同事，但他也记不太清了

第 2 天（周日）:

  • 上午：继续看代码，发现有个隐藏的状态转换

  • 下午：运行了几个测试用例，验证自己的理解

  • 晚上：终于搞明白了主流程，但边界情况还不太清楚

总耗时：约 12 小时

结果：理解了主流程，但细节还有疑问

AI 辅助方法：小王的周末

小王是团队的另一名工程师，也接到了类似的任务。

但他决定先让 AI 帮忙理解代码。

  • 上午 10 点：把核心的 3 个文件（约 2000 行）复制到 AI 对话框，明确告诉 AI 要分析支付回调流程

  • 上午 11 点：AI 生成了一份流程图和关键方法说明

  • 中午：发现 AI 理解有偏差，重新提问并补充上下文

  • 下午：基于 AI 的分析，快速验证了主流程

  • 晚上：补充了 AI 遗漏的 2 个异常分支

第 1 天（周六）:

  • 上午 10 点：把核心的 3 个文件（约 2000 行）复制到 AI 对话框，明确告诉 AI 要分析支付回调流程

  • 上午 11 点：AI 生成了一份流程图和关键方法说明

  • 中午：发现 AI 理解有偏差，重新提问并补充上下文

  • 下午：基于 AI 的分析，快速验证了主流程

  • 晚上：补充了 AI 遗漏的 2 个异常分支

第 2 天（周日）:

  • 上午：整理 AI 的分析结果，写成文档

  • 下午：和小李对比理解，发现了 1 个小李也没注意到的细节

  • 晚上：跑测试验证，确认理解正确

总耗时：约 6 小时

结果：理解了主流程，还发现了一个潜在 bug

差异在哪里？

不是说 AI 更聪明，而是：AI 帮你完成了“机械性”的理解工作。

AI 擅长的：

  • 快速识别代码结构（类、方法、依赖关系）

  • 生成流程图和调用链

  • 总结方法的作用

  • 识别常见模式（状态机、重试逻辑等）

AI 不擅长的：

  • 理解业务规则（为什么这样设计？）

  • 识别隐含的依赖（数据库状态、外部服务）

  • 发现边界情况和异常处理的遗漏

  • 判断代码的“合理性”

所以，小王节省的 6 小时，主要是 AI 帮他完成了“读代码”的机械工作，他自己专注于“理解业务”和“验证逻辑”。

这就是 AI 的价值：不是替代你，而是加速你。

二、实战：如何用 AI 分析遗留代码

好，理论够了。我们来动手。

还是那个支付模块，15000 行代码，3 年历史，多人维护。

目标：理解支付回调处理的完整流程。

第一步：准备上下文

你不能直接把 15000 行代码扔给 AI，它会懵。

你需要先“聚焦”:

  1. 找到入口方法（比如 handlePaymentCallback())

  2. 列出这个方法调用的所有相关类和方法

  3. 准备相关的配置文件（如果有状态定义）

示例：

我找到了 3 个核心文件：

  • PaymentCallbackHandler.java （主处理逻辑）

  • PaymentStateMachine.java （状态转换）

  • PaymentGatewayClient.java （外部调用）

还有 1 个配置文件：

  • payment-state-config.yml （状态定义）

为什么要这样准备？

因为 AI 需要“完整的上下文”才能理解逻辑。如果只给它一个方法，它只能猜测。

第二步：设计你的提问

不要问 AI:“这段代码是干什么的？”

这是最糟糕的提问方式，因为你会得到一个笼统的、可能错误的回答。

好的提问方式：

（你可以用 Claude、GPT-4、Cursor 等工具，选择代码窗口足够大的）

我有一个支付回调处理的代码,包含 3 个文件:
- PaymentCallbackHandler.java (主处理逻辑)
- PaymentStateMachine.java (状态转换)
- PaymentGatewayClient.java (外部调用)

请帮我分析:
1. 支付回调的主流程是什么?(从接收回调到更新订单状态)
2. 涉及哪些状态转换?
3. 有哪些异常处理分支?
4. 是否有重试逻辑?如何实现的?

请用流程图和文字说明结合的方式回答。

为什么这样问？

  • ✅ 明确了分析范围

  • ✅ 给出了具体的问题

  • ✅ 要求输出格式（流程图 + 文字）

  • ✅ 聚焦于“流程”而不是“实现细节”

第三步：验证 AI 的理解

（你可以用 Claude、GPT-4、Cursor 等工具，选择代码窗口足够大的）

AI 给了你一份分析结果。

不要直接相信！

你需要验证：

验证方法 1：跑一遍代码

最直接的方式：运行测试用例，或者手动触发一次回调，看实际流程是否和 AI 描述的一致。

验证方法 2：检查边界情况

AI 通常能识别主流程，但容易遗漏边界情况。

你需要手动检查：

  • 如果回调超时会怎样？

  • 如果支付网关返回错误码会怎样？

  • 如果同一个回调被调用两次会怎样？（幂等性）

验证方法 3：问资深同事

如果团队里有熟悉这块代码的人，拿 AI 的分析结果和他对比。

通常你会发现：

  • AI 理解对了 70-80% 的主流程

  • 但遗漏了 1-2 个关键的业务规则

  • 或者误解了某个状态的含义

让我给你看一个真实例子。

案例：

让我给你看一个真实例子。

我让 AI 分析支付回调处理逻辑，它给出了这样一个流程：

1. 接收回调 → 2. 验证签名 → 3. 查询订单 → 4. 更新状态 → 5. 返回成功

看起来没问题。

但我跑了一遍测试，发现：实际流程中还有一个“锁订单”的步骤，在第 3 步和第 4 步之间。

AI 没识别出来，因为这个逻辑藏在数据库事务里，代码层面不明显。

这就是为什么验证很重要。

第四步：补充 AI 遗漏的部分

发现 AI 的遗漏后，你需要手动补充。

不要责怪 AI，它已经帮你节省了 80% 的时间。剩下的 20%，是你的价值所在。

补充的内容通常包括：

  • 隐藏的业务规则（AI 无法从代码推断）

  • 数据库层面的逻辑（AI 看不到 SQL）

  • 外部依赖的行为（AI 不知道第三方接口的特性）

  • 历史演进的原因（为什么这样设计？AI 不知道）

案例继续：

我补充了“锁订单”这个步骤，并标注了原因：

为什么要锁订单？

因为支付回调可能重复发送，如果不加锁，可能导致重复扣款。

这是 2 年前的一次生产事故后加上的，当时支付宝回调失败重试，导致用户被扣了两次钱。

这些信息，AI 无法从代码中推断，需要你补充。

第五步：整理成文档

最后，把 AI 的分析结果和你的补充整理成文档。

不要写成“代码注释”，而是写成“理解文档”:

## 支付回调处理流程

### 主流程

1. 接收回调(来自支付网关)
2. 验证签名(防止伪造)
3. 查询订单(从数据库获取当前状态)
4. **锁订单**(防止重复处理,这是关键!)
5. 更新状态(根据回调结果)
6. 释放锁
7. 返回成功响应

### 关键点

**为什么要锁订单?**

2 年前的一次生产事故:支付宝回调失败重试,导致用户被扣了两次钱。
所以加了分布式锁(Redis 实现),确保同一个订单只能被处理一次。

**状态转换规则**

- CREATED → PAYING (用户点击支付)
- PAYING → PAID (回调成功)
- PAYING → FAILED (回调失败)
- PAID → REFUNDING (用户申请退款)

### 异常处理

- 签名验证失败 → 记录日志,返回 400
- 订单不存在 → 记录日志,返回 404
- 加锁失败 → 重试 3 次,仍失败则返回 500
- 状态更新失败 → 回滚事务,返回 500

这份文档，既有 AI 帮你理解的流程，也有你补充的关键信息。

3 个月后，当你或别人再看这段代码时，这份文档就是救命稻草。

三、AI 的局限：你必须知道的坑

AI 的局限：必须知道的坑

说了这么多 AI 的好处，现在我们来聊聊 AI 的坑。

这些坑，我都踩过。

坑 1:AI 会“编造”逻辑

AI 最大的问题是：它会基于“常见模式”推断，而不是基于“实际代码”。

案例：

我问 AI:“这个支付模块有重试逻辑吗？”

AI 回答：“有的，支付失败后会自动重试 3 次，间隔 5 秒。”

听起来很合理，对吧？

但我检查代码后发现：根本没有重试逻辑！

AI 是基于“支付系统通常有重试”这个常识推断的，而不是看代码。

教训：永远不要完全相信 AI 的第一次回答。

坑 2:AI 理解不了“隐含的依赖”

AI 只能看到代码，看不到运行时的依赖。

案例：

支付模块的状态更新，依赖于一个外部的“风控服务”。

如果风控服务返回“高风险”，支付会被冻结，状态不会更新为 PAID。

但这个逻辑是在另一个微服务里，AI 看不到。

所以 AI 的流程图里，没有这个分支。

教训：对于分布式系统，AI 只能理解单个服务的逻辑，跨服务的依赖需要你手动补充。

坑 3:AI 不知道“为什么”

AI 能告诉你“是什么”，但不能告诉你“为什么这样设计”。

案例：

支付模块有个奇怪的逻辑：如果用户在支付过程中点击了“取消”，订单状态不会立即变成 CANCELLED，而是变成 PENDING_CANCEL，然后由定时任务在 5 分钟后真正取消。

AI 能识别这个流程，但不知道为什么。

我问了原来的开发者才知道：这是为了处理“用户点了取消但支付宝已经扣款”的极端情况。

5 分钟的缓冲期，是为了等支付宝的异步回调。

教训：AI 无法推断历史演进和设计决策，这些需要你挖掘和记录。

坑 4:AI 对复杂状态机的理解容易出错

如果代码里有复杂的状态转换（比如支付有 8 种状态，20 种转换路径）,AI 很容易遗漏或搞错。

案例：

我让 AI 分析支付状态机，它给出了 6 种状态，15 种转换。

但我运行代码后发现：实际有 8 种状态，22 种转换。

AI 遗漏了 2 种状态（PENDING_CANCEL 和 PARTIAL_REFUND），以及 7 种转换路径。

教训：对于状态机，AI 的分析只能作为起点，你需要运行代码、查数据库、看日志，才能确认完整的状态转换。

四、人类验证：AI 给出的答案，你得这样检查

人类验证：仔细检查 AI 的分析

AI 不是银弹，它只是工具。

最关键的，是你的验证。

验证清单

1. 运行代码，确认主流程

不要只看 AI 的分析，实际跑一遍代码。

  • 写个测试用例，模拟支付回调

  • 打日志，看实际的执行路径

  • 检查数据库，看状态变化

2. 检查状态转换，补充遗漏的路径

对于状态机，不要只看代码，还要：

  • 查数据库中的状态字段，看是否有 AI 遗漏的状态

  • 看日志，找异常情况下的状态转换

  • 问原开发者或资深同事

3. 添加边界条件和异常场景

AI 通常只理解主流程，边界情况需要你补充：

  • 如果外部服务超时会怎样？

  • 如果同一个请求被调用两次会怎样？（幂等性）

  • 如果数据库更新失败会怎样？

4. 标注关键的业务规则和设计决策

AI 不知道“为什么”，你需要补充：

  • 为什么这里要加锁？

  • 为什么这个状态要延迟 5 分钟？

  • 为什么这里要重试 3 次而不是 5 次？

5. 补充性能和安全相关的注意事项

AI 看不到非功能性需求，你需要补充：

  • 这个接口的 QPS 是多少？

  • 有没有限流？

  • 敏感信息有没有加密？

验证的时间成本

你可能会问：验证这么多，会不会反而更慢？

不会。

传统方法：12 小时理解代码

AI 辅助方法：

  • AI 分析：0.5 小时

  • 你验证和补充：3 小时

  • 整理文档：2 小时

  • 总计：5.5 小时

节省了约 6 小时，效率提升 50%。

更重要的是，AI 帮你完成了最枯燥的“读代码”工作，你可以把精力放在“理解业务”和“发现问题”上。

五、独立开发者的特殊场景：AI 是你的“记忆助手”

前面主要讲了团队场景，现在我们聊聊独立开发者。

如果你是独立开发者，同时维护 3-5 个项目，AI 对你的价值更大。

场景：3 个月后回到老项目

你 3 个月前做了一个客户的管理系统，最近客户要加新功能。

你打开代码，看着自己 3 个月前写的 UserService.java，懵了。

传统做法：

花半天到一天时间，重新理解代码，回忆当时的设计思路。

AI 辅助做法：

你在 3 个月前，用 AI 生成了一份项目概览和核心模块说明。

现在，你只需要花 10 分钟看一遍文档，就能快速进入状态。

关键是：你要在“还记得”的时候，用 AI 帮你生成文档。

独立开发者的 AI 使用建议

1. 每次完成一个模块，用 AI 生成概览

不用写详细文档，只需要生成：

  • 这个模块是干什么的？

  • 核心流程是什么？

  • 关键的设计决策是什么？

2. 记录“为什么”，而不是“是什么”

3 个月后，你不会忘记“这个方法是干什么的”，但你会忘记“为什么这样实现”。

所以，重点记录：

  • 为什么选择这个方案而不是那个？

  • 为什么这里要特殊处理？

  • 有哪些坑不能踩？

3. 建立个人文档模板，跨项目复用

不用每次都从头开始，建立一套模板：

  • 项目概览模板

  • 核心模块说明模板

  • 常见问题记录模板

每次新项目，直接套用。

4. 每次切换项目时，花 10 分钟更新关键变更

不用每次都更新文档，只在关键变更时更新：

  • 添加了新功能

  • 重构了核心逻辑

  • 修复了重要 bug

时间投入：每个项目每周 < 30 分钟

收益：上下文切换成本从 1-2 天缩短到 5-10 分钟

总结：AI 是工具，不是银弹

写到这里，我想强调一点：AI 不是万能的。

它能帮你：

  • ✅ 快速理解代码结构

  • ✅ 生成流程图和调用链

  • ✅ 识别常见模式

  • ✅ 节省 50-80% 的“读代码”时间

但它不能：

  • ❌ 理解业务规则和设计决策

  • ❌ 发现所有的边界情况

  • ❌ 替代你的验证和思考

  • ❌ 保证 100% 的准确性

所以，正确的姿势是：

  1. 用 AI 快速生成初步的理解

  2. 你来验证、补充、完善

  3. 整理成文档，供未来参考

AI 是加速器，不是替代品。

它帮你完成机械性的工作，让你有更多时间思考真正重要的问题：

  • 这段代码合理吗？

  • 能不能更好？

  • 有没有潜在的风险？

这才是你的价值所在。

下一篇，我们会聊：如何基于 AI 的分析，写出第一份真正有用的文档。

不是“摆设文档”，而是真正能帮你理解代码、指导开发的文档。

小练习：

找一段你看不懂的遗留代码（不超过 500 行），试着用 AI 分析一遍。

然后用本文提到的验证方法检查，看 AI 对了多少，错了多少。

你会发现：AI 能对 70-80%，但剩下的 20-30% 才是关键。