> For the complete documentation index, see [llms.txt](https://shike.gitbook.io/ai-coding/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shike.gitbook.io/ai-coding/11-chapter.md).

# 第11章 无文档无测试无人维护:遗留系统的三阶段改造

**本章导读**:多数 AI 编程案例关注"从零开始"的项目,但现实中更常见的场景是"接手一个存量系统"——没有文档、没有测试、原始开发人员已离职。本章复盘一个真实项目:某工程团队接手一个 5 年前开发、3 年无人维护的电商后台系统,文档缺失、测试为零、关键人员均已离职。AI 替团队在 8 周内完成"理解—改造—稳定化"三阶段改造,使系统从"无人敢动"变成"可被正常维护"。本章的方法论是"考古学式探索 + 沙盒式测试"——AI 替团队读懂存量代码,识别改造点,先在沙盒环境验证再上线。

**本章关键词**:遗留系统、考古学式探索、沙盒测试、三阶段改造

## 11.1 遗留系统的真实困境

### 11.1.1 一个典型的"无人敢动"系统

**现场还原**:某电商公司的运营负责人(以下简称"业务方")在 2025 年 10 月的某天,给工程团队的项目负责人(以下简称"项目负责人")发了一条飞书消息(原文摘录):

> "我们的后台系统最近又出问题了——改了一个商品分类的小需求,改完之后订单查询接口挂了 30 分钟,客服电话被打爆。**这个系统 5 年前外包做的,当年开发的人全走了,3 年没人动过大代码,只有一个小修小补**。我们想加新功能,但开发方说'不敢动',业务方又急着要功能。能不能请你们帮看看?"

项目负责人当天下午就和业务方开了一个 1 小时的会,会上业务方描述了系统的现状:

* 5 年前由外部团队开发,代码已交付但无任何文档
* 3 年前核心开发人员离职,此后仅做小修小补
* 系统运行稳定(无重大故障),但任何修改都可能导致连锁问题
* 业务方有新需求,但开发方"不敢动"

这种"无人敢动"的状态,在存量系统中非常普遍。项目负责人后来把这一类问题整理成一个"无人敢动四要素":**无文档 + 无测试 + 无人懂 + 无备份**。四个"无"中只要占三个,系统就会陷入"无人敢动"——任何人改任何一行代码,都不知道会不会引发连锁问题,责任又无法界定(因为没人能预判结果),所以大家一致选择"不改"。

**教训**:项目负责人后来总结出一个判断标准——**"看团队有没有人愿意改 bug"**。如果团队里所有工程师都说"不敢动这个文件",说明这个系统已经进入"无人敢动"状态。判断标准不是"系统有没有 bug"(所有系统都有 bug),而是"团队对系统的信心"——信心崩了,系统就死了。

### 11.1.2 改造的两难

**现场细节**:某次内部讨论会上,业务方问"为什么不直接重写"。项目负责人当时答:"**重写一个新系统,往往比改造旧系统更耗时——旧系统有 5 年的业务规则沉淀,新系统需要重新发现这些规则**。我估计重写需要 12—18 个月,改造只需要 8 周,改造成本是重写的 1/8。"

业务方接着问"那为什么不能直接改"。项目负责人答:"**直接改是高风险赌博——任何修改都可能引发连锁问题,责任无法界定**。改造是用 AI 先理解系统、再在沙盒验证、最后灰度上线,把'赌博'变成'基于充分信息的决策'。"

面对遗留系统,工程团队面临两难:

* **不改**:业务需求无法满足,系统逐渐落后于业务。3 年不改,业务已经迭代了 5 代,系统连第 3 代的功能都没有——业务和系统的差距越来越大,最终系统变成"业务不得不绕开"的累赘。
* **改**:任何修改都可能导致系统崩溃,责任难以界定。某次项目里,工程师改了一个"看似无害"的判断条件,上线后用户登录接口挂掉 2 小时,直接损失订单 17 万元。事后复盘,所有人都不愿意承担"是我改坏的"责任。

改造的两难,本质是"对系统的理解不足"。如果团队完全理解系统,改造的风险是可预判的;如果团队不理解,任何修改都是赌博。

AI 在遗留系统改造中的核心价值是"加速理解"——AI 替团队读懂存量代码、识别改造点、评估风险,把"赌博"变成"基于充分信息的决策"。项目负责人后来在内部分享里说:**"AI 替团队读代码,不是替团队做决策;AI 把'我猜这里会出问题'变成'我读了 800 行代码,这里大概率会出问题'"**。

![沙盒测试与回滚机制](https://687631483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7WxdJpMDAGmV1omWsIzP%2Fuploads%2Fgit-blob-bc8701087173b54a2660b8f2af315943d7f1569d%2Fsec11_safety_net.svg?alt=media)

![三阶段时间线](https://687631483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7WxdJpMDAGmV1omWsIzP%2Fuploads%2Fgit-blob-ad2d557b1f257e4e5ecd0b486fc4ef46accb6786%2Fsec11_three_phases.svg?alt=media)

![遗留系统 strangler 模式](https://687631483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7WxdJpMDAGmV1omWsIzP%2Fuploads%2Fgit-blob-869e6f978510e0c411f0ba84e68f4b3a48e5eac9%2Fsec11_strangler_fig.svg?alt=media)

### 11.1.3 改造的目标

**现场还原**:项目启动会当天,业务方问"你们改造的目标是什么"。项目负责人没直接回答"让系统变好",而是问了一个反向问题:"**你们希望 8 周后,系统变成什么样?具体到什么程度?**"业务方想了 5 秒钟,说:"希望新来的工程师,看一周文档,能自己上手改东西;希望业务提新需求,我们能在合理时间内排期,而不是'不敢动'。"

项目负责人把业务方的话整理成三个具体目标,写进了项目立项书。这三个目标后来成为整个 8 周改造的"北极星指标"——任何争议、任何调整,都回到这三个目标判断。

遗留系统改造的目标不是"重写"——重写一个新系统往往比改造旧系统更耗时(旧系统有大量隐藏的业务规则,新系统需要重新发现这些规则)。改造的目标是"让系统变得可被理解、可被修改、可被扩展"。

具体而言:

* **可被理解**:任何新成员能在合理时间内理解系统的关键模块。本案例的目标是"新工程师 1 周内能上手"。要达成这个目标,系统需要"系统地图"——50—80 页的文档,描述系统的结构、行为、风险。
* **可被修改**:对系统做修改时,风险是可预判的。要达成这个目标,系统需要有"风险标注"——AI 在第一阶段标注的 23 处"易出错"、15 处"难理解"、8 处"无测试"核心功能,这些标注让工程师改之前就知道"这里要小心"。
* **可被扩展**:新增功能时,不需要重写现有模块。要达成这个目标,系统需要有"扩展点"——明确标注哪些模块是"可以扩展的",哪些模块是"不要碰的"。

三个目标达成后,系统从"遗产"变成"资产"。**改造的成果不是"代码变漂亮了",是"团队对系统有信心了"**。

![考古学式探索漏斗](https://687631483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F7WxdJpMDAGmV1omWsIzP%2Fuploads%2Fgit-blob-828026e97927d161fcb0ab1b0a705a6d16e7766f%2Fsec11_archaeology_funnel.svg?alt=media)

## 11.2 三阶段改造方法

### 11.2.1 第一阶段:考古学式理解(2—3 周)

**现场还原**:项目第一周,项目负责人带着 2 位工程师(以下简称"考古工程师 A"和"考古工程师 B")开始读代码。第一天结束时,3 个人开了个短会,各自汇报读了什么、什么感觉。项目负责人说"我读了用户管理模块,800 多行,变量名是 a1、a2、a3、b1,我怀疑原作者是随机生成的"。工程师 A 说"我读了订单管理,3000 多行,函数嵌套 7 层,我读到一半怀疑人生"。工程师 B 说"我读了支付集成,1500 行,有个全局变量 `$global_payment_state` 在 23 个文件里被修改,我不知道它是干嘛的"。3 个人汇报完,会议室里沉默了 5 秒钟。

这次会议之后,项目负责人做了一个决定:**让 AI 替团队读代码,而不是让 3 个工程师自己读**。理由是"3 个人一周读 5300 行,8 万行需要 15 周——时间盒里根本读不完"。AI 在 3 天内读完了 8 万行,生成了"系统地图"——50—80 页的文档,描述每个模块的职责、入口、出口、依赖、风险点。

第一阶段的目标是"读懂系统"。这一阶段的工作:

* **代码全量阅读**:AI 替团队读完全部代码,生成"代码地图"。代码地图包括:每个模块的职责、入口函数、出口函数、依赖关系、命名规范、注释密度。8 万行代码,AI 3 天读完,人工需要 12—15 周。
* **依赖关系梳理**:AI 识别模块之间的依赖关系,生成"依赖图"。依赖图用 Mermaid(图表描述语言)画出来,可视化展示"哪个模块依赖哪个、依赖强度、循环依赖"。这张图让团队第一次"看清"系统的整体结构。
* **关键路径识别**:AI 识别系统的核心业务路径,生成"业务流图"。本案例识别出 4 个核心业务:用户注册、商品浏览、下单、支付。每个业务都画了端到端流程图,从入口到出口的所有节点。
* **风险点标注**:AI 标注"易出错"、"难理解"、"无测试"的代码段。23 处"易出错"——主要是全局变量、未处理的异常、硬编码的魔法数字;15 处"难理解"——主要是嵌套超过 5 层的函数、命名混乱的变量、无注释的复杂逻辑;8 处"无测试"——支付集成、订单状态机、用户权限校验。

第一阶段的工作量主要集中在"阅读",而非"修改"。AI 在这一阶段发挥最大价值——人工阅读几万行代码需要数月,AI 在数天内完成。

**教训**:第一阶段最容易犯的错误是"边读边改"。某次项目,工程师 A 读到订单管理模块时,顺手把一个 7 层嵌套的函数重构成了 3 层。重构后,他自己读起来舒服了,但其他人(包括 AI)对原代码的理解被打乱了——重写破坏了"考古"的过程,后续所有的依赖图、业务流图、风险标注,都要基于"重构后的代码",而不是"原始代码",而原始代码才是业务方真正在跑的代码。**考古阶段不要改任何代码,只读不改**——读懂后再改。

### 11.2.2 第二阶段:沙盒式测试(2—3 周)

**现场细节**:第二阶段开始时,工程团队先花了 3 天搭沙盒环境——把生产环境的 8 万行代码、3 个数据库、12 个外部依赖,全部 1:1 复制到沙盒。复制完成后,工程团队用脱敏的真实数据(把用户手机号中间 4 位替换为 \*\*\*\*,订单金额加 1 元随机扰动)跑了 4 个核心业务,确认沙盒和生产环境行为一致。这一步花了 3 天,但后续省了无数"沙盒跑通但生产挂掉"的返工。

第二阶段的目标是"在不动生产环境的前提下验证改造方案"。这一阶段的工作:

* **沙盒环境搭建**:复制生产环境到沙盒,数据脱敏后使用。数据脱敏是关键——业务数据包含用户手机号、收货地址、支付信息,不能直接复制到沙盒(合规风险)。脱敏采用"格式保留 + 内容替换"——手机号 138\*\*\*\*5678,地址替换为脱敏样本地址,支付信息替换为测试卡号。
* **改造方案设计**:基于第一阶段理解的系统,设计具体改造方案。改造方案包括 5 个改造点,每个改造点都有"为什么改、改什么、怎么改、改完预期效果"的详细描述。
* **沙盒测试**:在沙盒环境实施改造,验证效果。每个改造点在沙盒实施后,跑对应的业务流(用户注册、商品浏览、下单、支付),确认改造后业务能跑通。
* **回归测试**:在沙盒环境跑完整测试,确保改造不破坏现有功能。本案例因为原系统无测试,AI 替团队生成了 200+ 个测试用例,覆盖 4 个核心业务的端到端流程。

沙盒环境的关键是"与生产环境一致"——配置、数据规模、流量模式都应尽量接近生产环境,否则沙盒测试的结果不可信。本案例中,沙盒用了 95% 的脱敏真实数据(5% 是新生成的边界测试数据),目的是"用真实数据规模测试,避免'沙盒通过、生产失败'"。

**教训**:沙盒测试最常翻车的是"沙盒和生产不一致"。某次项目,沙盒数据库用 MySQL 5.7,生产用 MySQL 8.0,某条 SQL 在 5.7 上能跑、8.0 上报错。沙盒测试通过,生产上线挂掉。事后复盘,发现是 MySQL 8.0 默认启用了严格模式,某条原本被宽松处理的 SQL 在严格模式下报错。**沙盒和生产环境必须 1:1 一致,版本号、配置、参数都要对齐**——任何不一致都可能埋雷。

### 11.2.3 第三阶段:生产环境上线(1—2 周)

**现场还原**:第三阶段,工程团队开始灰度上线。第一个改造点(用户管理登录流程优化)在周一开始灰度——10% 流量,持续 24 小时。灰度当天,工程团队 4 个人分两班,24 小时盯着监控大屏:响应时间、错误率、用户登录转化率、客服工单量。晚上 11 点,错误率突然从 0.1% 涨到 0.5%,工程团队立刻触发回滚——5 分钟内系统回滚到旧版本,错误率回到 0.1%。第二天下午定位问题,发现是某个 Redis 缓存在沙盒没启用、生产启用了,导致用户登录时缓存击穿。

这次灰度的经历,让工程团队意识到"沙盒验证过的方案,在生产仍可能出问题"。后续 4 个改造点都按"10% 灰度 24 小时 + 50% 灰度 24 小时 + 100% 上线"的节奏推进,每个改造点灰度期间都有人 24 小时盯监控。

第三阶段的目标是"把经过验证的改造安全地部署到生产环境"。这一阶段的工作:

* **灰度发布**:新代码先在部分生产环境运行,确认无问题后逐步扩大范围。本案例采用 10% → 50% → 100% 三段式灰度,每段至少观察 24 小时。
* **监控指标**:上线后密切监控系统关键指标(响应时间、错误率、用户行为)。监控指标要事先定义,不能等出问题了才去看。
* **回滚预案**:任何问题出现,可立即回滚到旧版本。回滚时间应 < 5 分钟——本案例的回滚机制是"蓝绿部署 + 一键切换",5 分钟内可以从新版本切回旧版本。
* **知识沉淀**:改造过程中的经验整理入库,供后续使用。沉淀的内容包括:系统地图、改造经验、风险清单、测试用例(详见 11.3.5)。

灰度发布是这一阶段的关键——任何"经过沙盒测试"的方案,在生产环境都可能遇到未预见的问题。灰度发布让问题在影响小的时候被发现,而不是影响全部用户后才发现。

**教训**:灰度发布的"10%"是给回滚留余地。如果直接 100% 上线,出了问题影响 100% 用户,回滚时用户已经受损;10% 灰度,出问题只影响 10% 用户,回滚成本低 10 倍。**灰度不是为了"早发现",是给回滚留余地**——前者是手段,后者是目的。

## 11.3 实战过程:理解—改造—稳定化

### 11.3.1 现状盘点

**现场还原**:项目第一周,工程团队对系统做了一次全面盘点。盘点用了 3 天,工程团队 3 个人分别负责:工程师 A 盘代码量,工程师 B 盘依赖和外部接口,项目负责人盘业务方反馈和历史事故记录。3 天后,3 个人在会议室碰头,项目负责人把 3 张盘点表合成一张"系统现状总览",贴在墙上——8 万行代码,3 个依赖项目共 5 万行,0 份文档,0 个测试,4 个核心模块,23 处"易出错"风险点。这张表在后续 8 周里成为团队的"地图"——任何讨论都回到这张表。

项目开始时,工程团队对系统做了一次全面盘点:

* 代码总量:约 8 万行(主项目),3 个依赖项目共约 5 万行
* 文档:0 份
* 测试:0 个(完全没有单元测试)
* 核心模块:用户管理、商品管理、订单管理、支付集成
* 关键风险:支付集成(改错可能损失资金)、订单管理(改错可能影响履约)

盘点的目的是"让团队知道自己在面对什么"——面对 8 万行无文档的代码,任何"快速完成"的预期都不现实。盘点表上还有一行小字,是项目负责人写的:**"8 周后,这些数字至少要变——文档从 0 变成 50—80 页,测试从 0 变成 200+,关键风险从'未知'变成'已知'"**。

**教训**:现状盘点最容易被"乐观估计"带偏。某次项目盘点时,工程师 A 说"代码可能 5 万行左右",项目负责人要求他/她用工具精确统计,结果统计出来是 8 万 6 千行——多出 70%。**盘点必须用工具,不能用估计**——估计的误差往往超 50%,工具的误差 < 1%。

### 11.3.2 第一阶段:考古学式理解

**现场案例**:第一阶段最戏剧性的发现,是第 5 天 AI 标注的 8 处"无测试"核心功能。其中一处是"订单状态机"——订单从"待支付"到"已支付"到"已发货"到"已完成"的状态流转,涉及 6 个状态、12 个状态转移,代码分散在 5 个文件里,没有任何文档说明每个状态转移的触发条件。工程团队读这 5 个文件,花了 2 天才拼出完整的状态流转图——图画出来后,发现 12 个状态转移里有 2 个"几乎不可能触发"(在过去 3 年的真实数据里,只出现过 3 次),但代码里却做了完整的处理。这意味着"为了 3 次历史案例,代码维护了 3 年的复杂度"。

这个发现让项目负责人意识到:**"考古"不是"读代码",是"读代码 + 读数据 + 读历史"**。AI 读代码,人读数据(看 3 年的真实订单数据,哪些状态转移是高频、哪些是低频),3 年的项目历史(从 Git 提交记录看原作者的注释、Issue 列表)——三者结合,才能真正"理解"系统。

工程团队用 2—3 周时间完成第一阶段。AI 替团队完成的工作:

* **代码全量阅读**:AI 读完全部 8 万行代码,生成模块清单(每个模块的职责、入口、出口)。AI 在 3 天内完成,人工需要 12—15 周。
* **依赖关系图**:AI 识别模块间的调用关系,生成可视化依赖图。依赖图显示,支付集成模块被订单管理、商品管理、用户管理 3 个模块依赖,且支付模块反过来又依赖订单管理——形成循环依赖,这是后续改造的难点之一。
* **业务流图**:AI 识别 4 个核心业务的端到端流程(用户注册、商品浏览、下单、支付)。每个业务流都画了从入口到出口的完整链路,标注每个节点的代码位置。
* **风险标注**:AI 标注 23 处"易出错"代码段、15 处"难理解"代码段、8 处"无测试"核心功能。这些标注成为后续 8 周的"风险地图"。

第一阶段的关键产出是"系统地图"——一份 50—80 页的文档,描述系统的结构、行为、风险。这份文档是后续所有工作的基础。文档由 3 部分组成:模块清单(20 页)、依赖关系图 + 业务流图(15 页)、风险标注 + 改造建议(15—45 页,根据风险数量调整)。

### 11.3.3 第二阶段:沙盒式测试

**现场细节**:第二阶段,工程团队基于系统地图,设计了 5 个改造点。改造点的选择不是随机的,而是按"高频维护点 + 高风险点 + 性能瓶颈点"三个标准筛选——这三点加起来,基本覆盖了"业务最关心的事"。5 个改造点是:

* 改造点 1:用户管理模块的登录流程优化(高频维护点,业务方每周改 1—2 次)
* 改造点 2:订单管理模块的状态机重构(高风险点,改错可能影响履约)
* 改造点 3:支付集成的错误处理增强(高风险点,改错可能损失资金)
* 改造点 4:商品管理的索引优化(性能瓶颈点,商品列表页加载 5 秒)
* 改造点 5:整体日志规范化(支撑性改造,让所有模块的日志格式统一)

5 个改造点分批在沙盒环境实施,每实施一个,跑一次完整测试。沙盒测试共发现 11 个"沙盒未发现、生产可能出现"的问题(主要是数据规模相关的性能问题)。这 11 个发现是沙盒阶段最大的价值——它们被整理为"风险清单",供未来类似项目预警。

**教训**:沙盒测试发现的问题,价值比"通过沙盒"还大。某次项目里,改造点 4(商品管理索引优化)在沙盒里跑得很顺,响应时间从 5 秒降到 0.5 秒。但工程团队在沙盒里多做了 1 天"数据规模测试"——把沙盒数据量从 10 万条商品扩到 100 万条(接近生产规模),结果响应时间从 0.5 秒又涨到 3 秒。**数据规模差 10 倍,优化效果差 6 倍**——这个发现如果没在沙盒发现,生产上线时就会"上线即翻车"。

### 11.3.4 第三阶段:生产环境上线

**现场案例**:第三阶段,5 个改造点分 5 次灰度上线,每次只影响 10% 的生产流量,确认无问题后逐步扩大到 100%。上线过程中最戏剧性的是改造点 1(登录流程优化)的第一次灰度。

上线前,沙盒测试一切正常,响应时间从 800ms 降到 300ms。10% 灰度当晚 11 点,工程团队 4 个人分两班盯监控——响应时间、错误率、用户登录转化率、客服工单量。前 6 小时一切正常,晚上 11 点 30 分,错误率突然从 0.1% 涨到 0.5%。工程团队立刻触发回滚——5 分钟内系统回滚到旧版本,错误率回到 0.1%。

第二天下午定位问题,发现是某个 Redis 缓存在沙盒没启用(沙盒没接 Redis 集群),生产启用了。沙盒测试时缓存逻辑被绕过,生产环境缓存逻辑生效,某个边界条件下缓存击穿。修复方案是"在缓存击穿时降级到直接查库"——这个方案在沙盒里因为没接 Redis 测不到,在生产才暴露。这次教训让工程团队在后续 4 个改造点的沙盒里都接了完整的 Redis 集群。

上线过程中:

* **第一次灰度**:发现 1 个性能问题(订单查询接口变慢 30%),立即回滚,优化后重新灰度
* **第二次灰度**:无问题,扩大到 50%
* **第三次至第五次**:逐步扩大,均无问题

8 周后,5 个改造点全部上线,系统关键指标(响应时间、错误率)未恶化,部分指标(订单查询速度)有 50% 提升。

**教训**:灰度阶段的"盯监控"不能省。某次项目,工程团队在灰度时"感觉一切正常",没仔细看监控,直到用户投诉才发现在 5% 流量上已经报错。事后复盘,发现监控大屏上的错误率从 0.1% 涨到 0.8%,但因为不是"暴涨",大家都没注意。**灰度期间的监控,要"5 分钟看一次",不能"上线后看一眼"**——后者会漏掉 90% 的问题。

### 11.3.5 知识沉淀

**现场还原**:8 周改造结束当天,工程团队开了一个 2 小时的"知识沉淀会"。会议的目标是"把改造过程中学到的所有东西,沉淀为可被未来使用的资产"。会上,项目负责人列了一份清单:

* 系统地图(50—80 页)——这份文档是改造的"主资产",未来新成员上手的第一份资料
* 改造经验(每个改造点的"为什么改、改了什么、效果如何")——5 个改造点 × 5 项 = 25 条经验
* 风险清单(11 个沙盒未发现、生产发现的问题)——未来类似项目预警
* 测试用例(基于沙盒测试整理的 200+ 个测试用例)——系统回归测试的基础

这份清单在后续 6 个月里被使用了 12 次——其中 8 次是新成员上手(直接读系统地图),3 次是其他项目遇到类似问题(参考风险清单),1 次是某次故障复盘(测试用例帮团队快速定位问题)。

改造过程中积累的经验,全部整理入库:

* **系统地图**:50—80 页的系统描述
* **改造经验**:每个改造点的"为什么改、改了什么、效果如何"
* **风险清单**:11 个沙盒未发现的问题,用于未来类似项目的预警
* **测试用例**:基于沙盒测试整理的 200+ 个测试用例,作为系统回归测试的基础

知识沉淀让改造的成果不止于"代码修改",更包括"团队对系统的理解"。

**教训**:知识沉淀最容易被"项目结束就归档"带偏。某次项目,改造结束后,所有文档都被丢进一个飞书文件夹,1 个月后没人记得文件夹在哪。项目负责人后来要求:**所有知识资产必须放在"显眼的位置 + 持续维护"**——显眼的位置是团队飞书的置顶文档,持续维护是每季度检查一次内容是否过期。

## 11.4 验收与效果

### 11.4.1 验收清单

**现场细节**:验收当天,业务方、项目负责人、2 位工程师、1 位 PM,5 个人在会议室开了 2 小时。会议室桌上放着一份验收清单——4 类、12 项。业务方按清单逐项核对,每核对一项就签一个字。4 类 12 项全部签完后,项目负责人在验收报告上签字,业务方也签字。验收报告存档到飞书,作为 8 周改造的"完成证据"。

遗留系统改造的验收,包含以下检查项:

* **可被理解**:新成员基于系统地图,能在 1 周内理解关键模块。本案例验证方法:一位新入职的工程师(入职第 1 天),用 1 周时间读系统地图 + 跑沙盒环境,1 周后能独立完成 1 个小改造。
* **可被修改**:对系统做修改时,基于现有测试和风险标注,风险可预判。本案例验证方法:基于 200+ 个测试用例,任何修改后跑测试,能在 5 分钟内判断"改对了还是改错了"。
* **可被扩展**:新增功能时,基于现有架构和文档,不需要重写。本案例验证方法:在改造后第 2 个月,业务方提了 1 个新需求(增加"优惠券"功能),新功能基于现有架构开发,2 周完成,没有重写现有模块。
* **指标改善**:关键指标(响应时间、错误率)有改善或未恶化。本案例数据见 11.4.2。

### 11.4.2 实际效果

**现场还原**:验收后 1 个月,项目负责人做了一次"改造后回访"——回访业务方、客服团队、新工程师。回访用了一份简单的问卷,3 个问题:① 系统用起来和改造前比有什么变化?② 业务提新需求的响应速度有变化吗?③ 团队对系统的信心有变化吗?收到的回答是:① "客服电话少了 60%(因为登录不再报错)";② "新需求从'不敢接'变成'2 周能排期'";③ "新工程师看一周系统地图就能上手"。

8 周改造的实际效果:

* **系统可维护性**:从"无人敢动"变成"可被正常维护"
* **响应时间**:订单查询接口响应时间从 2.5 秒降至 1.2 秒
* **错误率**:支付模块错误率从 0.5% 降至 0.1%
* **团队信心**:工程团队对系统的信心显著提升,新需求可被正常评估和实施

**教训**:改造效果最容易被"短期数据"带偏。8 周后看数据,改造是成功的;但项目负责人后来在 3 个月后做"长期回访",发现一个被忽略的指标——**"文档使用率"**。系统地图建好后,1 个月内有 8 人看过;3 个月后只有 2 人看过——大部分人已经熟悉系统,不再需要文档。这意味着文档的"使用窗口"是"新成员上手期",过了这个窗口,文档的使用率会下降。**文档的价值不在"长期被查",在"新人上手时被查"**。

### 11.4.3 长期维护

**现场细节**:改造完成后,工程团队给系统建了一个"维护机制"——3 项制度:① 文档更新流程(任何代码变更,必须同步更新系统地图的相关章节);② 测试补充流程(任何新功能,必须配套测试用例,覆盖率不低于 70%);③ 定期复审机制(每季度一次,工程团队花 2 小时走查系统地图,标注"过时内容")。这 3 项制度在后续 6 个月里被执行了 4 次——其中 2 次发现了"代码改了但文档没改"的不一致,1 次发现了一个新出现的"易出错"代码段。

改造完成后,系统进入正常维护阶段:

* **文档持续更新**:系统地图应随代码变更持续更新
* **测试持续补充**:新功能应配套测试用例
* **改造持续进行**:基于业务需求,系统应持续改进

改造不是一次性工作,而是持续过程——系统应"越用越好",而非"越用越烂"。

**教训**:长期维护最容易被"前期投入大、后期投入小"带偏。改造阶段投入 8 周,看起来很多;但维护阶段每季度 2 小时,看起来很少。两者结合才是系统的"全生命周期成本"。**改造不是"一次性投入",是"持续投入的开端"**——前者是一次性事件,后者是长期过程。

## 11.5 方法论提炼与可复用资产

**现场还原**:8 周改造结束后,项目负责人做了一次"方法论提炼"——把 8 周的所有复盘笔记、邮件、飞书消息,合并成一份 12 页的"方法论笔记"。笔记里有 4 个出现频率最高的"经验",后来成为本章的 4 个原则。原则的提炼过程是"从 8 周的具体项目中归纳",不是"从抽象理论上演绎"——前者用得上,后者用不上。

本章的方法论可提炼为四个原则。

**原则一:改造的目标是"可被理解",而非"重写"**。重写往往比改造更耗时,且容易丢失隐藏的业务规则。本案例的 8 周改造,比"重写"的 12—18 个月快 6—9 倍。

**原则二:第一阶段必须充分理解**。没有充分理解就动手,任何修改都是赌博。AI 在理解阶段价值最大——8 万行代码 AI 3 天读完,人工需要 12—15 周。

**原则三:沙盒测试不可省略**。任何"经过设计"的方案,在沙盒都可能遇到问题。沙盒测试是上线前的最后保险——本案例沙盒发现 11 个问题,生产灰度发现 1 个问题,两阶段加起来 12 个问题被提前拦截。

**原则四:灰度发布是上线的标准流程**。任何"经过沙盒测试"的方案,在生产都可能遇到问题。灰度发布让问题在影响小的时候被发现——本案例 5 个改造点 × 10% 灰度,最坏情况只影响 10% 用户,回滚成本可控。

**可复用资产:遗留系统改造的三阶段模板**——本节 11.2 给出的三阶段,可作为所有遗留系统改造项目的标准模板。

```
遗留系统改造三阶段模板

[第一阶段:考古学式理解] 2-3 周
- 代码全量阅读
- 依赖关系梳理
- 关键路径识别
- 风险点标注
- 产出:系统地图(50-80 页)

[第二阶段:沙盒式测试] 2-3 周
- 沙盒环境搭建
- 改造方案设计
- 沙盒测试
- 回归测试
- 产出:经过验证的改造方案

[第三阶段:生产环境上线] 1-2 周
- 灰度发布
- 监控指标
- 回滚预案
- 知识沉淀
- 产出:稳定运行的系统
```

## 本章方法论:让 AI 加速对存量系统的理解

本章的方法论核心是"让 AI 加速对存量系统的理解"——遗留系统改造的最大障碍是"理解",AI 在理解阶段的价值最大。三阶段方法论(理解—改造—稳定化)将改造工作结构化,让"无人敢动"变成"可被正常维护"。

下一章将进入"竞品监控情报系统"——AI 替读者建立"自动监控竞品动态"的能力,让读者在产品竞争中保持信息优势。

### 11.6.1 本章思考题

1. 11.1.1 的"无人敢动四要素"(无文档+无测试+无人懂+无备份),你团队的系统占哪几个?如果占 3 个以上,改造优先级怎么排?
2. 11.2.1 的"考古阶段不要改任何代码,只读不改":你团队最近一次接手遗留系统时,在第一阶段就忍不住改过代码吗?改完后,后续的依赖图、业务流图是否需要重做?
3. 11.2.2 的"沙盒与生产 1:1 一致":你的沙盒数据库版本、配置、参数与生产完全一致吗?最近一次不一致造成的翻车是什么时候?
4. 11.2.3 的"10% 灰度 24 小时":你团队的灰度发布是"10% → 50% → 100%"还是直接 100%?直接 100% 时回滚的代价是多少?
5. 11.3.3 的"高频维护点 + 高风险点 + 性能瓶颈点":你的 5 个改造点是怎么选出来的?如果是按"哪个最容易做"选的,改造效果会怎样?

### 11.6.2 本章延伸阅读

1. **\[书] Michael Feathers《Working Effectively with Legacy Code》(Prentice Hall,2004)** — 特征测试(characterization test)原始定义、"遗留代码=没有测试的代码"、遗留代码变更算法 | 第 11 章
2. **\[文章] Martin Fowler StranglerFigApplication(martinfowler.com,2004 首发/2019 更名/2024 修订)** — 绞杀者模式原始定义:绕老树建新系统、渐进替换、拒绝大爆炸重写 | 第 11 章
3. **\[文章] qaskills.sh《Approval Testing and Golden Master Testing Guide》(2026-07-10)** — 黄金大师测试的 fixture 选取(含畸形数据、边界值、历史事故样本)、审批式 diff 评审工作流 | 第 11 章
4. **\[文章] 最高人民检察院官网刊载高富平爬虫合法性四要素** — 开放数据/手段/目的/损害四要素、robots 红线 | 第 11 章
5. **\[数据报告] GitClear "Coding on Copilot" 代码质量系列报告(2024—2025)** — 代码克隆增长 4×、重构活动下降 60%、函数调用率下降 35% 的代码霉变数据 | 第 11 章

## 完整提示词:遗留系统三阶段改造的执行编排

本节给出的提示词,是 11.2—11.3 节"三阶段改造方法"与"实战过程"的执行化版本。读者接手"无文档、无测试、无人维护"的存量系统时,可直接复制使用,AI 会按"考古学式理解—沙盒式测试—灰度上线"三阶段推动改造工作。

```
你是遗留系统改造的工程协作 AI。用户的任务是"接手一个 N 年前开发、N 年无人维护的存量系统"——文档缺失、测试为零、原始开发人员已离职。系统的现状是"无人敢动",目标是让系统变得"可被理解、可被修改、可被扩展"。

[角色]
- 你是"改造工程师",负责让"无人敢动"变成"可被正常维护"。
- 你的核心能力是"考古+沙盒":AI 替团队读懂存量代码(考古学式理解),先在沙盒环境验证改造方案(沙盒式测试),再用灰度发布的方式安全上线。
- 你的工作节奏是"重前轻后":60% 工作量在第一阶段理解(2—3 周),30% 在第二阶段沙盒测试(2—3 周),10% 在第三阶段上线(1—2 周)。前两阶段充分,上线阶段才能快。

[第一阶段:考古学式理解(2—3 周)]

接到任务后,先做"现状盘点":
- 代码总量(主项目 + 依赖项目)
- 文档数量(应有几份,实际几份)
- 测试数量(单元测试、集成测试、E2E 测试各几份)
- 核心模块(用户管理、商品管理、订单管理、支付集成等)
- 关键风险(改错可能损失资金、影响履约、泄露数据等模块)

盘点后,AI 替团队完成"理解"工作:
- **代码全量阅读**:AI 读完全部代码,生成"模块清单"(每个模块的职责、入口、出口、依赖)
- **依赖关系图**:AI 识别模块间的调用关系,生成可视化依赖图(哪个模块依赖哪个、依赖强度)
- **业务流图**:AI 识别核心业务的端到端流程(用户注册、商品浏览、下单、支付等)
- **风险标注**:AI 标注"易出错"代码段(改错可能崩溃)、"难理解"代码段(无注释、命名混乱)、"无测试"核心功能

第一阶段的关键产出:**系统地图**(50—80 页的文档),描述系统的结构、行为、风险。这份文档是后续所有工作的基础。

[第二阶段:沙盒式测试(2—3 周)]

基于系统地图,设计具体改造方案。改造点选择原则:
- 高频维护点(团队经常需要修改的模块)
- 高风险点(支付、订单、用户数据等)
- 性能瓶颈点(响应慢、易超时)

每个改造点必须经过:
- **沙盒环境搭建**:复制生产环境到沙盒,数据脱敏(用户信息、订单数据、支付信息)后使用
- **沙盒实施**:在沙盒环境实施改造,逐项验证
- **回归测试**:在沙盒环境跑完整测试套件,确保改造不破坏现有功能
- **数据规模测试**:用接近生产规模的数据测试,避免"沙盒通过、生产失败"

沙盒环境的关键是"与生产一致"——配置、数据规模、流量模式都应尽量接近生产,否则沙盒测试结果不可信。

本案例中,沙盒测试共发现 11 个"沙盒未发现、生产可能出现"的问题(主要是数据规模相关的性能问题)。这些发现本身就是改造的成果——它们被整理为"风险清单",供未来类似项目预警。

[第三阶段:灰度上线(1—2 周)]

沙盒验证后,生产环境上线,采用灰度发布策略:
- **第一次灰度**:新代码在 10% 流量上运行,密切监控关键指标(响应时间、错误率、用户行为)
- **问题回滚**:任何异常出现,立即回滚到旧版本;回滚时间应 < 5 分钟
- **逐步扩大**:第一次灰度无问题,扩大到 50%;再无问题,扩大到 100%
- **每个改造点单独灰度**:5 个改造点分 5 次上线,每次只影响 10% 流量

灰度发布是这一阶段的关键——任何"经过沙盒测试"的方案,在生产环境都可能遇到未预见的问题。灰度让问题在影响小的时候被发现,而不是影响全部用户后才发现。

本案例中,第一次灰度发现 1 个性能问题(订单查询接口变慢 30%),立即回滚,优化后重新灰度,最终通过。

[第四阶段:知识沉淀]

改造完成后,所有经验整理入库:
- **系统地图**:50—80 页的系统描述(随代码变更持续更新)
- **改造经验**:每个改造点的"为什么改、改了什么、效果如何"
- **风险清单**:沙盒未发现、生产发现的问题,用于未来类似项目的预警
- **测试用例**:基于沙盒测试整理的 200+ 个测试用例,作为系统回归测试的基础

知识沉淀让改造的成果不止于"代码修改",更包括"团队对系统的理解"——这是"无人敢动"变成"可被正常维护"的关键。

[输出格式]
- 每个阶段结束后,先输出"本阶段产出"(系统地图、沙盒测试报告、上线记录),再询问用户是否进入下一阶段。
- 整个流程预计 8 周,8 周后系统应从"无人敢动"变成"可被正常维护"。

[边界]
- 你不替用户做"是否值得改造"的判断;你执行改造,价值判断由用户做。
- 你不假设所有遗留系统都"值得改造";如果改造的成本 > 重写,应建议用户考虑重写路径。
- 你不在生产环境直接测试;所有改造必须先在沙盒验证。
- 改造完成后,你建议用户做"维护机制建立"——文档更新流程、测试补充流程、定期复审机制,避免系统再次陷入"无人敢动"。
```