AI重构大型代码库：83万行代码迁移与技术债治理实战复盘

昨晚睡前本来只想刷两分钟 GitHub，结果无意中点开了一个正在做 83 万行代码重构的项目，一路从第一个 commit 翻到最近一次 merge，直接看到了凌晨两点。让我失眠的不是"某团队终于有勇气铲屎山了"，而是整条重构链路里 AI 参与的位置——它不是站在旁边补注释、当翻译，而是真正进入了"拆解、迁移、验证、回归"这条流水线上最累最枯燥的环节。我顺着这套方案反复研究了几遍，又拿自己手头一个积攒了三年的老项目实测了一周，今天这篇就把这次观察与复盘的完整过程记录下来。它适合所有被历史代码拖住、想做技术债治理却一直不敢动手的团队和个人。

1. 83万行重构意味着什么：这个仓库值得看的不是结果

1.1 先从"屎山"的典型病灶看起

一个系统烂到被大家叫"屎山"，通常不是单点问题，而是三种病一起发作。第一种是逻辑纠缠。一个业务方法动辄上千行，全局状态到处走，A 模块偷偷修改 B 模块的字段，改一处崩三处。这种结构天然拒绝自动化重构，因为模块边界是假的，你以为在拆模块，其实在拆毛线团。第二种是规范断裂。同一个仓库里可能同时存在多种语言、多个框架时期留下的代码，命名风格完全对不上，有的是老式带前缀的匈牙利命名，有的是现代 camelCase，有的干脆是赶工留下的拼音变量。这类代码对人是折磨，对 AI 来说反而是"训练数据的多样性"，关键在于你给它的上下文是否完整。第三种是知识断层。写这些代码的人大多已经离职，注释和文档早就对不上实现，唯一可信的"真相"就是线上正在跑的版本。

这三种病灶叠加之后，重构的成本就不再是"重写一遍"的线性成本，而是"理解一遍"的指数级成本。83 万行代码里，可能真正还有业务价值的不到三成，但没人有精力逐行判断剩下七成是死代码还是隐藏逻辑。这正是让传统重构迟迟动不了手的根本原因。

1.2 这个重构项目的目标与取舍

我看到的这个 83 万行重构项目，没有走"推倒重来"的激进路线，而是选择了"整体迁移 + 渐进替换"。他们的做法可以总结成三条：先把语义等价当作铁律，迁移后的代码必须与旧代码行为一致，不做业务扩展、不发散需求；先拆后迁，把单体系统按依赖关系切成边界清晰的模块，再逐个迁移；让 AI 承担大规模"搬运+翻译"任务，人类负责画边界、定验收标准、审关键逻辑，AI 负责把旧架构下的实现翻译到新架构。

这里有一个关键选择值得单独说一下：他们最初也考虑过让 AI 一口气重写全部 83 万行，但很快放弃了。原因很简单——AI 在巨大的自由空间里发挥时，产出的是"看起来合理但无法验证"的代码。一旦代码规模超过人类 review 的极限，这种"看起来合理"就变成最大的风险。所以他们对 AI 角色的定位是"翻译官"，不是"设计师"。这个定位上的清醒，可能比任何技术细节都重要。

1.3 为什么偏偏是现在，AI 才有机会介入

有人可能问：AI 辅助重构这个事，五年前不是也有人提吗？为什么偏偏现在这套方案能跑起来？我的理解是两个技术条件同时成熟了。第一，LLM 对代码语义的理解能力上了一个台阶。早期的代码生成模型更像"高阶补全"，你给它一段函数，它帮你把下一段猜完；现在的模型已经能理解"这段代码在业务流程中的位置""这个方法的副作用"这些抽象层的东西，这决定了它能参与重构，而不是仅仅做补全。第二，代码分析工具链已经非常成熟。AST 解析、依赖图构建、数据流分析、调用链追踪，这些基础工具越来越稳，它们给 AI 提供了"带坐标的地图"。没有这层地图，AI 就像蒙眼进仓库；有了地图，AI 才知道自己手里搬的是哪个货架上的哪件货物。

一句话概括我的观察：以前我们想让 AI 当建筑师，它不行；现在我们把 AI 放在搬砖工的位置上，它反而干得飞快。这恐怕是"AI 重构大型屎山项目"这个话题最值得重新认识的一点。

2. AI重构大型代码库的技术路径拆解

2.1 第一步不是让 AI 读代码，而是让工具先看懂代码

如果直接把 83 万行源码打包丢给 AI，然后说"帮我重构"，结果大概率是一场灾难。这个项目给我的第一个启发是：先把静态分析工具拉出来，把代码库"梳"一遍，生成模块边界、依赖关系、调用图。

我在自己那个老项目上实测，用了 ctags 配合 tree-sitter 做索引，再写一个简单的 Python 脚本统计模块间的引用关系，几分钟就能拿到一份"谁依赖谁"的清单。这份清单交给 AI 之后，它的回答质量完全不一样——因为它知道每个模块在全局中的位置，而不是在瞎猜。这里多嘴一句：很多人会跳过这一步，直接让 AI 读源码，然后抱怨"AI 重构完还是屎山"。其实 AI 没错，错的是给了它一坨没切开的肉，却指望它替你剥出骨头。

2.2 用 AST 做"翻译骨架"，而不是让 LLM 自由发挥

继续往下拆。这套方案里最核心的一步：不是把旧代码直接丢给 LLM 让它自由重写，而是先用 AST 解析旧代码，把结构信息提取出来，再连同目标语言或目标框架的规范一起交给 LLM 生成新代码。

为什么非得绕一圈？直接让 LLM 读源代码，它特别容易被历史包袱带偏。比如旧的 Java 代码里有大量 getter/setter 和冗余 null 判断，你希望它生成干净的新代码，它往往会"忠诚地"把冗余也搬过去。而 AST 结构里只保留了"这个类有哪些字段、哪些方法、方法之间怎么调用"这些信息，相当于给 AI 一个语义骨架，它只需要把骨架翻译成新架构的代码，冗余自然就没了。

我自己的实践里，这一步用的是 tree-sitter 解析加自定义脚本生成"类和方法清单"，再配合一段提示词让 AI 基于清单写代码。效果比直接扔源文件好很多，尤其在消除历史包袱这件事上，提升是肉眼可见的。

2.3 超长上下文怎么破：模块切分加 RAG 召回

接下来说最现实的问题：83 万行代码，没有任何一个 LLM 能一口吃完；就算能，生成质量也会因为上下文过长而急剧下降。这个项目的处理方式可以拆成三步，我把它们叫"切分、摘要、召回"。

第一步切分：按依赖关系把代码库切成数百个可独立迁移的模块，每个模块控制在几百到两千行左右。第二步摘要：对每个模块，先让 AI 阅读一遍，产出一份接口摘要，内容包括对外提供什么接口、依赖什么外部能力、内部关键状态有哪些。这些摘要本身也入库，方便后续检索。第三步召回：在迁移某一个具体模块时，不把全库拿给 AI，而是通过关键词和依赖关系先召回相关的接口摘要、调用方代码和被调方代码，再拼进提示词里。

这套机制本质上就是给 AI 造了一个外挂记忆库。它不需要记住 83 万行代码，只需要在干某一块活的时候，把相关的那几百行和必要上下文带进来。这也解释了为什么 AI 重构大型项目可以突破上下文窗口限制——前提是你先把索引和切片做好。

2.4 语义保持验证：重构之后怎么证明代码还是原来的它

代码迁移最怕的不是写不出来，而是写出来之后"看着没问题，跑起来全变样"。这个项目的验证机制做了四层，我觉得每一层都值得抄作业。

第一层是差分测试。迁移前后用同一批测试用例分别跑旧代码和新代码，逐条对比输入输出。第二层是快照对比。对涉及数据库、缓存、外部接口的模块，把迁移前后的数据快照做 diff。第三层是调用堆栈审计。在测试环境里记录新旧两张代码的调用链，看同一个业务请求走的函数序列是否一致，这能发现那种"功能没变但路径变了"的隐性差异。第四层是回归窗口。他们不一次性合并大量模块，而是每个模块迁移完后设一个观察期，看线上日志、错误率、耗时指标，确认无问题再继续下一批。

这套验证闭环是整个计划敢往下走的底气。如果不能证明新代码和旧代码行为一致，迁移得越多，系统越危险。AI 生成速度快是优势，但恰恰因为快，验证就必须比人工时代更严谨。

3. 从零复刻这套方案：我拿自家老项目实测了一遍

3.1 我把哪些工具组合起来用了

研究完那个 83 万行的案例，我决定拿手头一个积攒了三年的老项目当试验田。这个项目不大，约六万行，但已经是典型的"小屎山"：老框架、命名无规范、模块间耦合严重。我用到的工具和分工如下表。

里面最花时间的不是 AI 生成代码，而是前面的结构解析和摘要整理。我大概花了两晚才把索引做好，但之后整批模块的迁移速度快到有点不真实。

3.2 迁移顺序：从被依赖最多的底层模块向上动

顺序这事我吃过亏，值得单独拎出来说。正确做法是"从被依赖最多的底层模块开始，逐步向上迁移"。你先根据依赖清单输出一张模块依赖图，找出那些被很多模块引用、但自己不引用别人的底层模块，优先迁移它们。这样每一层迁移完之后，上层模块面对的接口已经稳定，后续迁移难度会越来越低。

我一开始挑了一个业务逻辑最少的 Controller 模块先练手，结果它依赖的 Service、DAO 全是旧代码，跑差分测试时根本没有新接口可对接，白白做了一堆工。后来我重排了顺序，两天时间把底层十几个模块全部迁完，上层再动的时候顺畅得多。重构顺序的规划比重构本身更重要，而且这个事 AI 帮不了你，只能人来拍板。

3.3 提示词策略：让 AI"边读边写"，不要"一锅端"

调度 AI 的方式同样有讲究。我总结了一套比较顺手的流程，核心是"两步走"。

第一步，让 AI 当解释者。给它某个模块的代码和结构清单，让它先产出自然语言描述：这个模块在业务里是干什么的、有哪些输入输出、依赖哪些外部系统、内部有哪些状态变化。第二步，让它当实施者。把上一步的解释摘要作为上下文，再给出目标架构规范，要求它生成新代码。

这套流程的好处是，AI 在写代码之前先"想清楚"了这段逻辑。如果它第一步的解释是错的，你在不浪费任何生成代码的情况下就能及时纠正；如果解释是对的，第二步生成的代码质量会明显更稳。比起直接扔源码让它翻译，这种"先解释后实施"的打法把错误成本前置，省掉大量返工。

3.4 人工兜底的职责边界

即使有上面这套流程，我也不建议完全撒手。对于"AI 写的代码，人应该审什么"，我给自己划了一个很明确的边界：不审每一行的写法，只审四类地方——外部系统调用、并发与事务边界、异常处理分支、数据迁移路径。

这四个地方出问题，单测和差分测试往往抓不到。比如外部 API 的超时时间变了，比如并发环境下同一个共享对象被重复创建，比如事务边界被 AI 无意间挪到了方法外面，这些都需要有经验的人去盯。AI 可以处理八成的搬砖工作，剩下两成的领域敏感逻辑，必须回到人的手里。

4. 实测里的意外与教训：AI 重构最大的坑不是 AI 本身

4.1 单元测试覆盖率是生死线

先给一个我在实测中反复验证的结论：如果老系统的单元测试覆盖率达不到六成以上，建议先别急着上 AI 重构，把测试补起来再说，不然后面每一步都在走钢丝。

为什么这么说？因为 AI 生成代码时，它本身就是靠"看起来合理"来生成的。如果没有足够测试当约束，它就会把"看起来合理"当成"正确"，然后写进代码里。我实测时有个模块就是这样，AI 把一段边界判断逻辑写反了，但因为旧代码那个分支本来就没有测试用例，差分测试自然抓不出来，后来是人工 review 时才发现的。所以 AI 重构的第一道工序，不是 AI，而是补测试。这个顺序不能反。

4.2 AI"自作主张"的三种典型表现

多次实测下来，我观察到 AI 在重构时特别喜欢自作主张，方向主要有三个。第一种是擅自内联。为了"简化代码结构"，AI 把原本拆开的公共方法直接内联到调用处，导致同一个逻辑在多个地方重复出现，后头再想改这个逻辑得改好几处，技术债不减反增。第二种是安全边界丢失。我遇到过 AI 把一段参数化查询的代码"顺手"改成字符串拼接，理由是"看起来更简洁"，如果直接上线就是妥妥的注入漏洞，这类问题只有 review 时盯紧才会被发现。第三种是过度抽象。AI 倾向于把所有重复代码都抽成泛型方法或者套上 Stream 高阶函数，看起来很美，但真实场景下性能开销变大、可读性反而变差。

这三种表现的共同特点是：AI 在"让它自由发挥"时，会主动往它认为"更好"的方向偏移。所以提示词里一定要写明边界：不要改变方法粒度、不要修改查询方式、不要做额外抽象。不然你会发现它替你做了很多决定，而每个决定都需要你去推翻重来。

4.3 一个具体的性能回归案例

分享一个我印象很深的案例。有个模块迁完之后，所有单测、差分测试全部通过，功能行为完全正常。但压测的时候，TP99 从原来的 20ms 一路涨到接近 400ms，这个结果完全不可接受。排查了很久，最后定位到一个很隐蔽的问题：旧代码里有一个共享的长连接对象，整个 Controller 层复用；但 AI 在迁移时认为"每次调用重新获取更安全"，于是把长连接的创建挪到了每个请求内部。每个请求都要重新握手建立连接，性能自然崩了。单测和差分测试看不出来，因为它们的调用频率太低，延迟差异根本暴露不了。

这个案例给我的教训是：AI 重构后的代码，除了功能验证，还必须做性能基线的对比。给每一类接口记录迁移前的耗时指标，迁移后逐项对拍，宁可慢一点也一定要做这一步。性能回归是 AI 重构最容易漏掉的坑，因为它在"正确性"上花了太多注意力，反而把非功能约束淡化了。

4.4 重构期间改需求，是最大的隐性杀手

最后这个坑跟 AI 无关，跟团队协作方式有关。重构进行到第二周时，产品经理临时提了一个新需求，团队觉得"既然都要重构了，顺便一起加上"。这个决定差点让整个差分测试体系崩掉——旧系统的行为基线变了，新旧代码对比失去了参照物。后来我们立了一条规矩：重构期间只接受 bug 修复，不接受新需求，任何新功能都排到迁移完成之后再排期。

这是我在这轮实测里认为最重要的一条纪律。AI 是个执行力极强的搬运工，但搬运工最怕的是货物还没搬完，箱子里的东西先变了。基线一旦浮动，前面所有验证都会失去意义。

5. 我的结论与后续实践：AI 不会替你铲平屎山，但能让你干得更快

5.1 实测下来，值得复制的一套迭代节奏

如果你也想在团队里推这件事，我的建议很朴素：每天只迁移两到三个模块，每个模块走完"补测试、AI 翻译、差分验证、人工 review、小范围观察"这条完整链路，再继续下一个。慢，但稳定。我实测下来，节奏一旦快进到每天十个模块，review 质量会明显下降，性能回归和逻辑错误开始往外冒。重构这种事，稳定压倒一切，稳着稳着速度就上来了。

5.2 什么样的屎山不适合交给 AI

当然，也不是所有老项目都适合上 AI 重构。我总结了三类不建议轻易碰的情况。第一类是完全没测试、线上行为又没人说得清的系统，这种无论谁重构都是赌博，AI 只是让赌注下得更快。第二类是强实时、内核级或对安全性要求极高的系统，边界条件极其复杂，AI 生成的风险偏高。第三类是核心逻辑依赖黑盒算法或不可复现数据的模块，连对拍基线都没有，AI 也没法验证自己干得对不对。先把这些区域圈出来别动，剩下的再留给 AI 发挥。

5.3 一个人也能启动的最小闭环

这套方法未必需要多大的团队。哪怕目前只有你一个人，也能跑一个最小闭环：挑一个边界最清晰、依赖最少的模块，先补几条关键测试用例作为基线，让 AI 按"解释加翻译"的流程迁移，最后用差分测试和人工 review 验证质量。跑通一个模块，一个周末足够。而这个流程一旦跑通，你对"AI 到底能做到什么程度"就有了真实体感，这份体感比任何研究报告都值钱。

5.4 我接下来想继续做的几个方向

这次实践给我留了几个可以继续深入的念头。第一个是在 CI 阶段挂一个"重构医生"检查器，让 AI 在每次合并前自动对比新旧代码的复杂度和依赖变化，把隐患拦截在合入之前。第二个是让 AI 自动生成技术债地图，从整个仓库里筛出那些"被大量模块依赖、同时又严重违反规范"的代码区域，排出一个自动化的重构优先级。第三个是把这次的经验往跨语言、跨框架的重构上推，如果这块能稳定输出，那很多跑了好多年的老系统，寿命还能继续延续很多年。

最后再说一点个人体会：这轮折腾下来，我最大的感受是 AI 重构不会让"屎山"自动变成"宫殿"，它的真实价值是把你的铲子换成了挖掘机——工具强了，但图纸还是得你画，地基还是得你勘，验收还是得你把关。别指望它替你做判断，把它当成一个执行力超强、但需要你不断给方向和兜底的新同事，用好了是真的能解放人。