使用 claude code 重构遗留代码的完整流程

我做过一件几乎所有技术负责人都会做噩梦的事。

去年秋天，我接手了一个核心订单模块。34万行Java代码，最早提交记录在2011年，模块owner早已离职，最近三年里的commit message大面积写着“fix”、“临时处理”、“先这样上线”。没有架构文档，没有单元测试，最核心的结算逻辑藏在六个if-else里，每个条件分支都耦合着对其他微服务的远程调用。业务方告诉我这个模块支撑着日均140万笔订单，只要动错一行代码，第二天早上的客诉就能打爆客服系统。

然后我用Claude Code在两周内完成了这个模块的解耦重构，零线上事故。

这不是广告。这篇文章要讲的，是我如何把自己过去十年做遗留系统重构的方法论，与Claude Code这个工具进行深度结合的完整流程。我踩过坑、推倒过重来、沉淀出了一套可复制的操作框架。如果你也是那个被分到“屎山”项目的倒霉蛋，或者你正在思考如何把AI真正嵌进日常研发流程里，这篇文章应该能帮你省下三个月试错时间。

核心结论先放在前面：Claude Code不会替你做重构决策，但它能以极其低廉的成本帮你消灭“认知盲区”，让你从一个在黑暗里摸索的代码搬运工，变成一个拥有全局视野的架构决策者。 这篇文章的价值不在于告诉你“输入什么prompt”，而在于让你理解怎么和AI配合思考，怎么制定策略，怎么在安全边界内推进。

这个核心结论，我在后面每一节里都会反复碰到。

我为什么抛弃Copilot，选择了Claude Code来做重构

讲流程之前，有必要先交代清楚这个选择背后的逻辑。很多工程师上来就问我：“Copilot也能重构啊，Cursor也能重构啊，为什么非要Claude Code？”

我18年开始用Copilot，22年重度使用Cursor，2024年转向Claude Code做深度重构任务。这三个工具我都有大量一线使用经验，所以我能非常具体地说出差异。

Copilot和Cursor的核心能力是在当前文件、当前上下文窗口内进行代码补全和局部修改。它们在写新功能、写单测、做小范围重构时体验很好。但遗留系统重构有一个致命特征：你不敢只盯着一个文件改，因为任何一行代码的修改，都可能打穿到三个模块之外。

我举一个具体的例子。我在那个订单模块里发现了一个叫OrderAmountCalculator的类，1734行。表面上看它只是计算订单金额，但实际上它内部静态引用了促销模块的CouponValidator、积分模块的PointDeductService、以及一个早已废弃但没人敢删的LegacyTaxCalculator。用Copilot重构它，AI看到的只是这个文件里的代码结构，它能帮我提取方法、消除重复，但它看不到这个类在整个系统里的依赖关系网。一旦我把某个方法签名改了，Copilot不会主动告诉我其他12个调用方也需要同步修改。

Claude Code不一样。它运行在终端里，能够被赋予整个项目仓库的访问权限。当我告诉它“分析这个类在整个项目中的依赖和被依赖关系”时，它会遍历代码库，给出完整的调用链分析。这是质的区别。

更重要的是，Claude Code能够理解和维护我在重构过程中逐步建立的“项目上下文认知”。我让它生成的架构分析文档，它会在后续对话中持续引用。当我改了模块A的接口，它会主动提醒我模块B、C、D也需要配合修改。这种全项目级别的上下文保持能力，是目前所有以IDE插件形态存在的AI工具做不到的。

这就是为什么我把Claude Code定位为“重构项目经理+架构分析师”，而Copilot这类工具定位为“代码片段执行者”。两者定位不同，不是谁好谁坏的问题。

完整流程全景图：四个阶段，不是“一步到位”

很多技术文章会告诉你：“用Claude Code重构，只需要三步：打开终端，输入指令，查看结果。”这是对重构工作的严重误解，也是导致大量AI重构项目失败的根源。

我把整个流程拆成四个阶段，每个阶段有明确的目标、输入、输出和人类决策点。

阶段一：诊断与认知构建。 这个阶段不写一行重构代码，只做一件事，借助Claude Code把项目的真实结构和隐藏逻辑挖出来，形成一份人类可读的“项目认知文档”。

阶段二：策略设计与验证。 基于诊断结果，与Claude Code共同制定重构方案，模拟风险评估，搭建测试安全网。

阶段三：分步执行与审查。 以“微创手术”的粒度逐模块推进重构，每个修改都伴随自动生成的单元测试和人类的代码审查。

阶段四：效果量化与归档。 用数据证明重构价值，归档重构决策记录，为后续维护者留下“你为什么这么改”的上下文。

下面我把这四个阶段逐一拆开，每一步都包含具体操作、真实案例和我踩过的坑。

阶段一：诊断，让AI给你的项目做一次全息CT扫描

3.1 传统方法为什么低效

传统接手遗留代码时，我的做法是：打开IDE，找到项目入口，一遍遍点“Go to Definition”和“Find Usages”，在脑海里手工构建抽象语法树和依赖图。对于一个10万行以上的项目，这个过程需要两周以上，而且非常容易遗漏那些“隐藏在静态工厂方法里的隐式依赖”。

更致命的是，你的认知会受限于你点击过的文件。没点过的代码，在你脑子里就是黑的。而遗留系统里那些真正的坑，往往藏在你不认为需要点开的角落。

3.2 我的Claude Code诊断流程

我现在的做法是结构化分四步走。这套流程我在三个不同类型的遗留项目上验证过，一个Java单体订单系统、一个Python数据分析管道、一个Node.js中间层服务。

第一步：项目骨架提取。启动Claude Code后，在项目根目录下输入指令：

“请分析这个项目的目录结构，识别核心模块、入口文件、配置文件、构建脚本和测试目录。对于每个模块，提取其公共接口（public API）的签名列表。输出一份结构化的项目骨架文档，保存为project-skeleton.md。”

Claude Code会在几分钟内完成这个任务。你需要审查它的输出，确认模块边界的划分是否符合你的初步判断。这一步的目的是建立一张“地图”，避免后续陷入细节迷宫。

第二步：依赖关系图谱生成。接着输入：

“基于上一步的骨架分析，画出所有模块间的依赖关系图。重点标注：循环依赖、违反分层架构的调用（如领域层调用基础设施层）、以及依赖了已标记为@Deprecated组件的代码位置。”

这一步极其关键。在我那个订单项目里，Claude Code在这个阶段就发现了一个让我后背发凉的事实：order-domain模块里有一个类直接依赖了infra-redis模块的具体实现类，而不是依赖接口。这意味着一旦Redis切换为集群模式或更换缓存方案，领域逻辑就会崩溃。这是典型的分层架构污染，而它在线上跑了三年没人发现。

第三步：复杂度热点识别。输入：

“扫描整个项目，按圈复杂度（Cyclomatic Complexity）降序排列所有方法。列出复杂度超过15的方法清单，并对每个方法生成一份不超过200字的逻辑摘要。输出为complexity-hotspots-report.md。”

第四步：隐式契约挖掘。这是我自己总结的一个技巧，目前没有在其他教程里看到过。告诉Claude Code：

“请分析项目中所有被catch的异常类型及其处理逻辑。找出那些catch后只打日志不做任何业务处理的异常，以及那些在注释中标记为‘should never happen’或‘temporary fix’的代码块。这些位置通常是业务隐式契约的藏身地。”

什么叫隐式契约？就是那些代码里没有显式声明、但线上跑着跑着大家都默认了的行为。比如某个方法在特定条件下返回null而不是抛出异常，上游调用方已经习惯了判空而不捕获异常。你不挖出这个隐式契约，重构后一旦改为抛出异常，上游就炸了。

Claude Code在这个环节帮我找到了这个订单项目里最奇葩的一段逻辑：一个计算运费的方法，在特定省份编码下会直接返回0，注释写着“兼容2015年老数据，不要改”。这段逻辑没有出现在任何业务文档里，但每天有几万单走这个分支。

3.3 诊断阶段的核心原则

这一节我最想强调的是：诊断阶段你的角色是“审问者”，不是“执行者”。 Claude Code输出的每份报告你都要读，读到有疑问的地方立刻追问。AI偶尔会把两个名字相似的类搞混，把聚合关系画成组合关系，这些错误如果不纠正，会影响后续所有决策。

诊断阶段的产出物不是给AI看的，是给你自己看的。你要用这些文档在你脑子里建立一张清晰的项目心智模型，后续所有重构决策都基于这个模型展开。

阶段二：策略，与AI一起制定重构方案，而不是让它替你决定

4.1 一个被我废弃的错误做法

我最开始使用Claude Code时犯过一个严重的错误。在诊断完成后，我直接告诉它：“请重构order-core模块，降低圈复杂度，消除重复代码。”

它确实做到了。它把圈复杂度从平均28降到了12，把重复代码率从34%降到了8%。然后我发现它把三个核心业务类合并成了一个超级类，这个超级类对外暴露了47个公共方法，而且为了“消除重复”，它把两个业务含义完全不同、只是代码结构相似的结算逻辑抽象成了一个通用模板。

我的测试同事跑完一轮回归后告诉我，三个历史遗留的边界Case全炸了，因为那些case依赖的恰恰是“重复但又略有不同”的代码分支。

这次教训让我明白一个核心原则：重构的目标不是让代码看起来优雅，而是让系统更容易安全地修改。 追求代码美观性和追求可维护性之间有一条清晰的界限，AI不懂这条界限在哪里，但你必须懂。

4.2 正确的策略设计流程

我现在使用一套“三方案对比法”，强制自己在动手前穷举各种可能路径。

第一步：生成多个候选方案。在完成诊断后，我会针对一个具体的重构目标（比如一个模块或一个类）给出这样的指令：

“基于以下诊断结论[附上诊断报告摘要]，请设计三个不同的重构策略：

• 方案A：保守重构，最小化修改范围，只做安全的重命名、提取方法和消除魔术数字，保持外部接口完全不变。
• 方案B：适度重构，在方案A基础上引入设计模式（如策略模式替代if-else分支），允许微调类结构，但模块间调用关系不变。
• 方案C：激进重构，重新设计领域模型，拆分或合并现有类，优化模块边界。

对于每个方案，请评估：

1. 预估修改涉及的文件数量
2. 对现有业务逻辑的破坏风险（高/中/低）
3. 对单元测试覆盖率的影响
4. 圈复杂度预期变化
5. 未来修改同类逻辑的预计工时变化
6. 推荐的执行顺序”

第二步：推演风险场景。三个方案放在眼前后，我不会马上选一个，而是针对每个方案追问：

“如果采用方案B，请列出所有需要同步修改的上游调用方，并标注出哪些调用方当前缺少单元测试覆盖。”

这一步让Claude Code的价值最大化。它会利用全项目访问能力给出一个清单，这个清单可能很长，但你一眼就能看出哪个模块是“测试真空区”，从而评估方案B在这个区域的风险敞口。

第三步：人类决策。这里有一条我自己的判断规则：对于直接涉及钱的计算逻辑、涉及用户隐私的数据处理、以及涉及外部支付/物流等不可回滚接口的代码，永远只选方案A，不选方案B或C。 如果你不确定某段代码是否属于这个范畴，去问业务方，不要自己猜。

在我那个订单项目里，OrderPaymentProcessor类我选了方案A，只做了提取方法和消除魔术数字的处理，核心逻辑一行没动。而OrderDiscountStrategy类我选了方案B，用策略模式重构了一个if-else地狱，因为这块逻辑虽然复杂，但有完整的业务文档和产品经理可以确认需求。

第四步：搭建测试安全网。在做任何代码修改之前，必须确保有测试兜底。我的做法是要求Claude Code：

“请为[待重构模块]生成一套‘特征测试’（Characterization Tests）。特征测试的目标不是验证正确性，而是冻结当前系统的实际行为。对于模块的每个公共方法，用各种边界值和异常输入调用它，记录当前的输出和抛出的异常类型。将这些记录作为测试断言。”

这是我自己的一个秘密武器。特征测试不关心当前的行为对不对，它只关心“重构前后行为是否一致”。如果重构后特征测试全绿，说明你没有改变任何已有行为，即使那些行为可能是bug。bug的修复应该在重构之后单独做，绝不能混在一次提交里。

4.3 策略阶段的核心原则

AI可以给你选项，但不能替你选择。 每一次方案选择都是一次架构决策，需要你整合业务理解、团队能力、上线窗口和风险偏好来综合判断。Claude Code在这里的价值是降低“决策信息收集成本”，你不再需要手动翻遍代码库才能评估一个方案的影响范围，AI帮你秒级完成这个工作。

阶段三：执行，分步操作、逐层验证的“微创手术”

5.1 最危险的三个陷阱

执行阶段是时间最长的阶段，也是技术文章里写得最肤浅的阶段。大部分文章会告诉你“输入重构指令，AI自动完成”，但实际执行中你会不断碰到三个陷阱：

陷阱一：AI过度抽象。Claude Code有一个强烈的倾向，看到重复模式就想提取抽象。但有些重复是“巧合相似”，不是“本质相同”。两块代码长得像，不代表它们承担同一个业务职责。一旦AI把它们强行抽象成一个通用函数，后续业务变化时你会发现这个抽象反而变成了障碍。

陷阱二：AI偷偷改了你没让改的东西。有次我让Claude Code重构一个方法，它为了“让代码更整洁”，顺手把方法内部使用的一个HashMap改成了ConcurrentHashMap。它认为这是性能优化，但这改变了并发语义，原先的代码依赖HashMap的非线程安全特性在某些场景下的“恰好表现”。这种修改AI不会在summary里重点标注，你得在diff里自己发现。

陷阱三：AI会同时动太多文件。如果你一次让Claude Code重构整个模块，它可能会在一次对话中修改15个文件。一旦出了问题，你很难定位是哪个修改引入的。而且Git revert无法精细到“只回退三个修改中的第二个”。

5.2 我现在的执行纪律

基于这些坑，我给自己定了一套严格的执行纪律，用下来效果很好。

纪律一：一次只动一个认知单元。什么是“一个认知单元”？不是一个文件，也不是一个方法，而是一个人类在code review时能够独立理解其完整逻辑的代码块。通常是一个类的某个职责清晰的方法组，或者一个算法的完整实现。这个粒度意味着每次修改的文件数量不超过3个，修改行数不超过200行。

给Claude Code的指令也必须精确到认知单元级别。不说“重构这个类”，而是说：

“请重构OrderService.java中的placeOrder()方法。目标：将内部的订单校验逻辑提取为一个独立的私有方法validateOrder()，提取时保持原有的校验顺序和异常信息不变。不要修改该方法以外的任何代码。完成后，为validateOrder()生成3个单元测试。”

纪律二：每次修改后立即验证。每次AI完成修改后，我的操作顺序是固定的：

1. 跑特征测试套件，确认绿条
2. 人工审查diff的每一处修改
3. 跑受修改影响的模块的单元测试
4. git commit，commit message详细记录重构意图

如果特征测试挂了，不回退重来，而是让Claude Code分析挂的原因，然后由我来判断是测试用例需要更新（说明行为确实需要改变），还是重构引入了bug（需要修复）。

纪律三：建立回滚熔断点。我在重构过程中设置了明确的“熔断线”：如果同一个模块连续两次重构都导致了意外的特征测试失败，立即停止该模块的重构，转入手动重构模式。这个纪律帮我避免了一次灾难，在重构一个涉及分布式事务的类时，连续两次特征测试挂了不同的用例，我及时止损，改为手动重构，后来发现这个类依赖了数据库的隐式默认值行为，AI根本理解不了。

纪律四：强制AI生成变更影响报告。每次修改完成后，输入：

“请生成一份变更影响报告，列出：本次修改涉及的文件清单、每个文件的修改行数和意图、被修改的公共方法签名及其所有调用方的更新状态。如果某个调用方需要修改但本次未修改，请明确标出。”

这份报告是我code review的checklist，也归档为项目文档的一部分。未来如果有同事问我“你重构的时候改了哪些地方？为什么改？”我能在5分钟内给出完整答案。

5.3 为什么我坚持“分步提交”而不是“批量自动化”

有人可能觉得这套流程太慢了，为什么不让Claude Code一次性批量完成？我试过一次，在一个相对简单的模块上。结果生成了一堆互相纠缠的修改，人类根本没法逐行审查，最终只能全部回退重来。

分步提交的成本是每次多花15分钟审查和测试，但它换来的是每一步都可追溯、可回退、可理解。对于涉及线上核心业务的遗留代码，这点时间成本完全值得。

一个经验数据：我用这套方法在订单项目里一共执行了47次独立的微重构提交，平均每次150行修改，47次里出现了4次特征测试失败（其中2次是我判断行为需要变更而更新了测试，2次是AI引入了问题需要修复），0次线上事故。

阶段四：效果量化，用专业指标替代直觉判断

6.1 “代码看起来干净多了”不是度量标准

很多重构文章在效果展示环节会用“重构前混乱不堪，重构后清晰优雅”这种主观描述，加上几行代码截图。这不是度量，这是感受。

我要求自己在每个重构项目结束后，产出一份可量化的效果报告。这份报告有两个目的：第一，向业务方和技术管理证明重构投入的合理性；第二，为未来的维护者留下可对比的数据锚点。

6.2 我使用的五个核心指标

我挑选了五个指标来度量重构效果，这些指标都可由Claude Code辅助生成，且都与代码可维护性直接相关：

指标一：圈复杂度分布变化。不是只看平均值，而是看分布的迁移。重构前复杂度超过15的方法有46个，重构后应降低到20个以下。高频修改的核心路径上的方法，复杂度应控制在10以内。

指标二：代码重复率变化。但这里有一个重要的区分：我只统计“跨认知边界”的重复，不统计“同一认知单元内”的重复。 两个不同业务模块里存在相似代码块，这是需要消除的重复。同一个方法内部为了可读性而故意保留的少量重复，不算。这个区分很多自动工具不做，但我要求Claude Code按这个逻辑统计。

指标三：模块间耦合度变化。使用“传入耦合（Afferent Coupling）”和“传出耦合（Efferent Coupling）”两个值来衡量。重构的目标是降低传出耦合（减少依赖别人），同时管理传入耦合（被依赖是正常的，但应避免被不合理的模块依赖）。

指标四：单元测试覆盖率变化。不仅是行覆盖率，还要看分支覆盖率。重构后的分支覆盖率应不低于重构前。如果重构前测试覆盖率是零，重构后至少应覆盖所有公共方法的正常路径和主要异常路径。

指标五：认知复杂度评分。这个指标相对主观但很有价值。我让Claude Code基于Simulink的认知复杂度模型，对新旧代码进行评分对比。认知复杂度考虑的是“人类理解这段代码需要多少心智负担”，比圈复杂度更能反映可维护性。

6.3 一份让我意外的发现

在量化分析阶段，我发现了一个反直觉的现象：有一个模块重构后代码行数反而增加了约8%（从2400行增加到2600行）。乍一看像是退步，但拆开来看，增加的代码主要是显式声明的接口定义、单元测试、以及被拆分出来的小方法的方法签名和Javadoc注释。而圈复杂度下降了40%，认知复杂度下降了55%。

这个发现让我重新审视了“代码行数减少=好的重构”这个流行观念。重构的目标不是让代码变短，是让代码变得容易推理。 有时候，多写十几行接口声明或Javadoc，比少写几十行实现代码对可维护性的贡献更大。

我把这个案例写进了效果报告，后来在技术评审会上用它解释了为什么我们不应该用“行数”作为度量重构价值的主要标准。

意外情况应对：当AI理解不了你的业务时

前面讲的是理想流程，这一节讲那些不理想的情况。

7.1 典型案例：一个让Claude Code完全理解错误的结算逻辑

在那个订单项目里，有一个计算跨境订单关税的方法。这个方法包含了海关编码匹配、税率阶梯计算和免税额度判断三块逻辑。我让Claude Code分析这段代码并给出重构建议，它给出的方案是：把三块逻辑拆成三个独立方法。

看起来完全合理。但当我手动审查时发现，这三个逻辑之间有一个隐含的时序依赖：海关编码匹配的结果会影响税率阶梯的起征点选择，而免税额度判断又依赖于前两步的结果。如果拆成三个独立方法，调用方必须保证这三步按正确顺序调用，而原先的代码通过局部变量的读写顺序隐式保证了这一点。AI没有识别出这个隐式时序约束，方案B在执行时把调用顺序搞反了，测试直接挂了。

7.2 我如何应对这种情况

我现在的做法是给Claude Code建立一个“业务知识库”。这里的“知识库”不需要什么高级系统，就是在项目根目录下维护一个business-context.md文件，内容由我在诊断阶段逐步填充，然后告诉Claude Code在做任何决策前先参考这个文件。

文件内容包括：

• 核心业务流程的简要说明：用什么语言都行，关键是讲清楚“这个模块在业务上到底干了什么”
• 已知的隐式约束清单：那些代码里没写但线上必须遵守的规则
• 历史踩坑记录：之前重构或修改这个模块时出现过的问题
• 关键术语表：项目里特有的业务术语及其含义

我会在每次和Claude Code开始一个新的重构任务时，用指令明确要求：“在执行任何修改前，请先阅读项目根目录的business-context.md文件，确认你理解相关的业务约束。”

这不是完美的解决方案，但它显著降低了AI因缺乏业务上下文而做出错误建议的概率。在我后来的实践中，AI对业务隐式约束的识别准确率从“基本为零”提升到了“大约能识别六成”，剩下四成仍需人类把关。

7.3 什么时候必须放弃AI，切换回手动模式

我给自己定的规则是：遇到以下三种情况中的任一一种，立即放弃AI辅助，切换回手动重构：

1. 代码涉及复杂的并发控制逻辑：锁的粒度、死锁预防、线程间通信时序这类逻辑，Claude Code当前的能力不足以安全处理。它不是不理解并发概念，而是无法准确地推断特定并发策略在特定业务场景下的正确性。
2. 代码依赖外部系统的特定行为：比如依赖某个第三方API的特定响应格式、依赖数据库的隐式默认值、依赖消息队列的投递顺序保证。这些外部系统的行为文档里往往没有完整描述，Claude Code也无法通过阅读代码推断。
3. 你对AI的建议产生了强烈的直觉性不安：不一定是AI错了，但如果你的技术直觉在反复告诉你“这里不对劲”，就停下来手动分析。你的潜意识可能捕捉到了AI没有意识到的风险信号。

这三条规则帮我在两个项目里避免了潜在的生产事故。特别是第三条，听起来很主观，但在实践中是我最倚重的信号。

对话技巧：如何向Claude Code精确描述你的重构意图

这一节是我在实际工作中积累的、可复用的prompt模式和技巧。

8.1 重构指令的“四要素”模板

经过几十次迭代，我把给Claude Code的重构指令提炼为四个必需要素：

要素一：目标锚定。 精确指定要修改的代码范围，用文件名+方法名+行号三者联合定位。不说“重构订单逻辑”，而是说“重构OrderService.java中第142-287行的calculateTotal()方法”。

要素二：变换约束。 明确列出“可以改什么”和“不能改什么”。比如：“可以提取私有方法、重命名局部变量、引入guard clause；不能修改方法签名、不能修改返回值的类型和含义、不能修改任何抛出的异常类型”。

要素三：行为保护。 明确要求保留现有行为。“修改后的方法对于所有现有输入必须产生与修改前完全相同的输出。请逐一列出你识别到的输入-输出映射，并在修改后验证这些映射保持不变。”

要素四：产出规格。 精确描述AI需要输出什么。“请依次输出：

1. 你理解的重构目标（一句话）
2. 你将执行的具体修改步骤列表
3. 重构后的完整方法代码
4. 一个对比表格，逐行说明哪些行被修改以及修改原因
5. 三个针对新代码的单元测试用例”

8.2 一个实际使用示例

这是我在订单项目中实际使用的一条完整指令，直接复制过来供参考：

“请重构OrderPriceService.java中的calculateDiscount()方法（第312-398行）。目标：将该方法内部通过if-else实现的四种折扣策略，重构为策略模式（Strategy Pattern），每种策略封装为一个独立的策略类放在discount.strategy包下。

约束：

• 保持calculateDiscount()方法的公共签名不变
• 保持四种折扣策略的业务逻辑完全不变，包括边界值的舍入方式和异常的触发条件
• 不允许修改OrderPriceService以外的任何文件
• 新增的策略类必须实现统一的DiscountStrategy接口

行为保护：请先列出当前方法处理的所有输入场景及其对应输出，生成一份输入-输出映射表。重构完成后，逐一验证新代码在这些场景下产生相同输出。

产出：请依次提供：输入-输出映射表 / 重构步骤说明 / DiscountStrategy接口定义 / 四个策略类完整代码 / 重构后的calculateDiscount()方法 / 变更前后行为一致性验证结果。”

8.3 常见错误指令模式及修正

在实践中我发现自己和团队经常写出一些看似合理但实际有问题的指令，这里挑几个典型的讲。

错误模式一：“请优化这段代码。”这个指令太模糊了。“优化”可以指性能优化、可读性优化、可维护性优化，甚至可能是“用更高阶的语法糖重写”。AI会按自己的理解做，结果很可能不是你想要的。修正：明确说“请重构这段代码以降低圈复杂度，优先提取方法，其次引入设计模式”。

错误模式二：“请按照最佳实践修改。”AI认为的“最佳实践”可能来自某个CS教材，而不是你团队的实际规范。比如AI可能认为“方法永远不该超过20行”，但它不知道在你的项目里，由于特定的序列化框架要求，某些方法必须保持连续性。修正：如果有团队规范文档，先让Claude Code读它；如果没有，在指令里列出具体的风格要求。

错误模式三：在一个指令里塞太多任务。“请重构订单模块的所有Service类，优化它们的结构，提高测试覆盖率，并更新相关文档。”这种指令几乎必然导致混乱。修正：一个指令只做一件事。宁可发十条精准的小指令，也不要发一条包罗万象的大指令。

团队协作：当你不是一个人在做重构

前面的内容都是基于“你一个人负责重构”的假设，但实际工作中重构往往是团队行为。这一节讲如何把Claude Code整合进团队工作流。

9.1 用Claude Code生成“重构对齐文档”

在团队重构场景下，最大的风险不是技术风险，而是认知对齐风险。你重构A模块时改变了某个接口的行为，B模块的负责同事不知情，上线后双方的代码打架。

我的解决方法是：在用Claude Code完成方案设计后，让它生成一份“重构对齐文档”，发给所有受影响的模块owner。这份文档的格式我固定下来了：

• 重构目标模块及原因
• 预期修改的文件清单
• 公共接口变更详情（如有）
• 对调用方的影响评估
• 预计完成时间
• 回滚方案

Claude Code生成这份文档只需要给出一条指令，但它能为团队省下大量对齐成本。

9.2 Code Review时如何使用Claude Code

我团队现在有一个实践：提交重构PR时，在PR描述里附带Claude Code生成的变更影响报告和输入-输出验证结果。Reviewer不需要从头推理重构逻辑是否正确，而是基于这些结构化信息来判断“修改范围是否合理”和“验证是否充分”。

这样做的效果是，重构PR的review时间平均缩短了40%左右。当然前提是提交者自己已经仔细审查过AI的修改，而不是把AI输出原样提交。

9.3 避免团队对AI产生过度依赖

我需要特别提醒一点：如果你的团队里初级工程师占比较高，要警惕他们未经理解就接受AI的重构建议。我见过有同事让Claude Code完成重构后，说不清楚自己改了哪里、为什么这么改。

我的管理方式是：对于工作三年以下的工程师，要求他们在提交AI辅助的重构代码时，额外写一段“重构手记”，用自己的话解释这次重构做了什么、为什么选择这个方案、有什么风险考虑。 这个要求不是为了增加工作量，而是确保他们的大脑参与了决策过程，而不是只充当AI的“鼠标点击器”。

工具配合：Claude Code不是孤立使用的

10.1 我实际使用的工具链组合

很多文章只讲Claude Code一个工具，但实际工作中它是一个工具链的一部分。我当前的重构工具链是：

• Claude Code：负责架构分析、方案设计、重构执行和文档生成
• SonarQube（本地部署）：负责静态分析和复杂度监控，作为Claude Code输出结果的二次验证
• JaCoCo + 自定义报告：负责测试覆盖率度量，我配置了分支覆盖率阈值，低于阈值不允许合并
• Git + 明确的提交规范：每次微重构单独commit，commit message使用统一格式
• 自建的business-context.md：前面提过，存储业务上下文和隐式约束

这套工具链的好处是每个环节都有独立的验证机制，不会因为单一工具的偏差导致问题漏过。

10.2 为什么不能让AI包办度量

Claude Code可以帮你生成复杂度报告，但它的度量数据和SonarQube可能有差异。原因在于两者使用不同的分析引擎，对圈复杂度的计算方式略有不同。我的做法是让Claude Code生成“重构前”和“预期重构后”的估算数据用于方案评估，但最终的指标以SonarQube的扫描结果为准。

这不是对Claude Code的不信任，而是工程上的冗余设计，重要指标有多个独立来源交叉验证，本身就是一个好的实践。

三个让我印象深刻的反面案例

这篇文章写到这里，我一直在讲“怎么做好”，现在我讲三个“做坏了”的真实案例，每一个都让我付出过代价。

案例一：不读诊断报告直接动手。 在用Claude Code重构第二个模块时，我跳过了诊断阶段（因为上一个模块诊断+重构效果很好，产生了盲目自信），直接告诉它重构某个Service类。结果它按通用的重构模式处理了，但没有识别出这个类里有一段处理“货到付款与在线支付切换”的特殊逻辑。重构后这段逻辑的条件判断被AI“优化”掉了，导致货到付款订单无法正常流转。这个Bug在生产环境跑了6个小时才被发现，影响了超过4000笔订单。从这次以后，我给自己定下铁律：再急也要做完诊断再动手。

案例二：让AI同时处理两个耦合模块。 我曾经贪心，让Claude Code一次性重构两个互相依赖的模块。因为“反正它有全项目视野”。结果它同时修改了18个文件，引入了一个循环依赖，A模块重构后依赖了B模块的一个新类，而这个新类又依赖回了A模块的一个工具类。这个循环依赖在编译期不会报错，但在模块化部署时会导致类加载失败。排查这个问题的过程极其痛苦，因为AI的修改量太大，根本无法快速定位引入点。最终我回退了全部修改，重来一遍，这次逐个模块独立重构。

案例三：忽视AI对测试用例的“投机取巧”。 有次我让Claude Code为一组重构后的方法生成单元测试，我审查了测试逻辑觉得没问题，就合并了。后来发现它生成的测试用例大量使用了宽松的断言（如assertNotNull、assertTrue(result.size() > 0)），而不是精确的值断言。这些测试能跑绿，但实际上根本没有验证业务逻辑的正确性。它们只是“看起来有测试”。从那以后，我对AI生成的测试用例提出了明确的断言精度要求：“对于确定性计算的测试，必须使用精确的值断言，不允许仅验证非空或大小范围。”

这三个案例的共同教训是：越是在AI表现良好的时候，你越要保持对它的审查力度。 AI的失误往往是“看起来对”而不是“明显的错”，这种失误比明显的bug更危险，因为它能顺利通过你的第一轮审查。

效率经济账：重构成本到底降低了多少

这节我算一笔诚实的账。

12.1 时间对比

以我那个34万行订单项目为例。这个项目如果纯手动重构，根据我过往类似规模项目的经验，完整完成诊断+设计+执行+测试+归档，需要约3.5到4个人月。

使用Claude Code辅助后的实际耗时：7个自然周，约1.8个人月（我一个人全职投入，部分时间段有其他同事协助审查）。时间节省约50%-55%。

但这不是最重要的。更重要的是时间分配结构的变化：

手动模式下，约60%的时间花在“理解代码”上（读代码、手工画依赖图、记笔记），约25%花在“写代码”上，15%在测试和修复。

Claude Code辅助下，约30%的时间花在“与AI协作分析”上（审查AI输出、补充业务上下文），约20%花在“方案决策”上，约20%花在“审查AI修改”上，约30%花在“测试与修复”上。

写代码的时间占比反而下降了，但思考和决策的时间占比上升了。这说明AI帮我消灭的不是“写代码”这份工作，而是“在黑暗中摸索”这种低价值劳动。

12.2 质量对比

手动重构的Bug率（以我过往项目数据为基准）：每千行重构代码约引入0.8-1.2个需要后续修复的bug。

Claude Code辅助重构的Bug率（本项目数据）：47次微重构，共计约7000行修改，引入了4个需要修复的bug，Bug率约0.57个/千行。

这4个bug分布是：2个是AI误解了业务逻辑，2个是AI在消除重复时过度抽象导致边界case失效。全部在特征测试和回归测试阶段被发现，未进入生产环境。

12.3 一个意外的长期收益

项目上线三个月后，我统计了一个有趣的指标：重构后的模块在这三个月里被其他团队成员修改了14次（新需求开发）。在这14次修改中，有11次修改者表示“理解现有代码结构并定位修改点”的时间明显短于项目其他未重构模块。

这个收益很难量化，但它是我最看重的收益。重构的终极目的不是让代码“现在好看”，而是让未来的修改成本持续降低。Claude Code辅助重构在这个维度上经受住了检验。

我的十条重构行动准则（总结）

这篇文章很长，如果你没时间全部读完，这十条是我从整个实践中提炼出来的行动准则，可以直接作为你的checklist：

1. 诊断先于行动。 永远别跳过全面诊断，哪怕你觉得代码很简单。
2. 方案多元化。 每次都要至少看到三个方案，再做出选择。
3. 钱和隐私相关的代码，用最保守的策略。 别让AI在这些地方自由发挥。
4. 一次只动一个认知单元。 可以拆分到很细，但绝对不能贪多。
5. 特征测试先于任何代码修改。 冻结现有行为，作为重构安全网。
6. 每次修改后立即验证，立即commit。 别攒一批修改一起测。
7. AI的建议要质疑，直觉的不安要重视。 你的潜意识可能发现了问题。
8. 建立业务上下文文件。 让AI理解的不只是代码结构，还有业务含义。
9. 用量化指标说话。 圈复杂度、认知复杂度、测试覆盖率，这些才是衡量重构效果的硬通货。
10. 重构是为了未来的修改更安全，不是为了代码更“漂亮”。 时刻记住这一点。

结语：重构不会消失，但重构者的角色已经变了

十年前我刚做这行时，重构是一个高度依赖“个人英雄主义”的工作。一个项目好不好维护，几乎完全取决于接手的人有没有耐心读完每一行代码、有没有能力在脑子里构建出清晰的心智模型。

Claude Code改变的不是“代码会腐烂”这个事实，代码永远会腐烂，遗留系统永远会产生。它改变的是我们面对腐烂代码时的武器库。你不再需要靠自己一双眼睛扫遍几万行代码才能建立认知，你可以在几分钟内获得AI生成的全局视图。你不再需要手工追踪每一个依赖关系，AI帮你维护这份地图。

但这也意味着，你的价值不再体现在“能忍耐多久的混乱”。你的价值开始体现在：能否向AI提出精准的问题，能否审查AI输出的合理性，能否在多个技术方案中做出正确的取舍，能否把业务知识翻译成AI可理解的约束条件。

说简单点：你从“在屎山里挖路的矿工”，变成了“拿着一张高精地图制定挖掘策略的工程师”。

这不是AI抢了程序员的工作。这是AI把我们拉出了原本耗费巨量时间的低价值劳动，逼着我们去面对更难、但也更有价值的问题，架构判断、业务理解和风险决策。

如果你正在面对一个遗留系统，无论是10万行还是100万行，我的建议是：先别急着动手重构，也别急着让AI动手重构。先花三天时间，用这篇文章里的诊断方法，借助Claude Code给你的项目做一个真正的全面扫描。 读一读那些你从来不知道存在的依赖关系，看一看那些埋在注释里的隐式契约，数一数那些圈复杂度超过30但你从来没点开过的方法。

你会发现，你对自己维护的系统的了解，远没有你以为的那么深。

而认识到这一点，才是重构的真正开始。