1. 为什么我敢把遗留系统交给 Claude Code先说结论AI 写新代码早就不是什么新鲜事真正的分水岭是——它能不能在你不熟悉的、又老又乱的代码库里不出错地把活干完。Claude Code 给我的感觉是它把理解上下文这件事做到了可以信任的程度而重构遗留系统恰好就是上下文理解能力的极致考验。我在一家传统企业里接手过一个跑了好几年的订单管理系统。技术栈是 .NET Framework 3.5 Web Forms数据库是 SQL Server 2008代码里混杂着三层架构、存储过程、内嵌 SQL、还有少量 ASPX 页面里的业务逻辑。最致命的是没有单元测试连集成测试都几乎没有。这种系统你不可能推倒重写只能一点一点地拆、一点一点地迁。过去我处理这类项目的办法是自己画架构图、做依赖分析、手工找调用链一周下来可能连一个模块都理不清。Claude Code 改变的不是重构这个动作本身而是前置分析阶段的工作方式它可以快速扫完整个代码库帮你画出模块依赖、找出循环引用、定位什么代码真正在跑、什么代码已经死了。要说明的是Claude Code 不是一个图形界面里的聊天机器人它是一个跑在终端里的命令行工具。你在项目目录里启动它它可以直接读写文件、执行命令、运行测试、搜索代码然后基于这些真实反馈去修改代码。这意味着它和把代码粘给 AI 让它给你解释是完全不同的工作模式——它能在你的项目里实际干活而不是隔着一层对话框空谈。这篇文章就是一份实战记录。我会从环境准备、重构策略、具体操作、失败教训这几个方面完整复盘我是怎么用一个命令行 AI 工具把一个遗留系统逐步理顺的。如果你手里也有一个不敢动、又不得不动的老系统这篇文章应该能帮你少走不少弯路。后半部分我还会针对能用什么模型这类常见疑问给出我的配置建议这部分其实是整个方案能否落地的关键之一。2. 重构之前先让 Claude Code 摸清家底2.1 用代码库扫描代替人工阅读接手遗留系统第一步永远是搞清楚现状而不是开始改代码。这个项目我在阅读阶段就花了两周而 Claude Code 进入之后这个周期被压缩到了一天。我做的第一件事是在项目根目录启动 Claude Code让它做一次全库扫描。指令大概是这样的claude进入交互界面后我给出指令请扫描当前仓库识别出所有项目文件和工程文件梳理整个解决方案的模块结构并标记出你认为是核心技术债务的问题区域。它会自动列出项目的组成、各层之间的引用、哪些项目是入口、哪些是类库然后生成一份结构报告。这份报告的价值在于它帮你建立了一张地图而地图这种东西恰恰是遗留系统最缺的。接下来是更进一步的操作。我给它的任务是分析这个项目里哪些类和文件被多次引用哪些是无人引用的文件分别列出 Top 20。然后再列出所有循环依赖的项目引用和类引用。这个操作的输出让我非常惊讶。我原来用了两周才勉强画出的模块依赖图它在一个小时内就给出了一份带具体文件路径、引用关系的清单。虽然里面有不少误报但作为第一版地图完全够用了。注意Claude Code 对大型代码库的处理是有上限的。如果你的仓库非常大建议先用rg --files或find生成文件清单然后让它在核心目录上做扫描而不是一次全仓扫描。实际经验是100 万行左右的仓库直接扫描问题不大更大的仓库需要分模块处理。2.2 建立重构前的基线防线在没有测试的遗留系统里做重构就像在没有护栏的悬崖边开车。所以在让 Claude Code 动手改代码之前我必须先建一条安全防线。这一步我的做法是引入快照测试。简单说就是把某个模块的输入和输出记录成固定用例重构完成后跑一遍如果结果和重构前一致说明行为没有被破坏。Claude Code 在这里能派上两个用场一是帮我自动生成这些测试用例的骨架二是帮我判断哪些函数可以安全地生成快照测试。我的做法是让 Claude Code 扫描领域层的核心类和方法然后对它说请为这些核心方法生成调用示例。读取数据库中真实存在的记录作为输入样本为每个方法生成一个最小化的调用测试。不要断言业务逻辑只断言返回结果的类型和关键字段存在。这类操作生成的测试虽然不算严格意义上的单元测试但它提供了一个非常重要的东西回归基线。重构过程中只要这些测试不过就说明代码行为变了立刻停下来检查。另一个很实用的功能是让 Claude Code 对比重构前后方法的调用签名变化。遗留系统重构里最常见的翻车方式是你觉得我只是提取了一个方法结果它的行为和你想象的不一样。原因往往是隐藏的副作用比如方法内部修改了静态变量、改了 Session 状态、或者是访问了某个外部服务。Claude Code 在分析这类隐藏副作用时比我凭经验猜要可靠得多。我给它的指令是分析这些方法的副作用标记所有修改了外部状态静态属性、数据库写入、文件输出、会话变量的地方。这些副作用必须在重构时保持原样。它会输出一张副作用清单这些内容在你重构时就是一张红榜时刻提醒你别动它们。2.3 挑出可以碰和不能碰的代码摸清家底之后我让 Claude Code 帮我做了第三件事给代码做安全分级。分级的原则我参考了 Michael Feathers 在《修改代码的艺术》里的思路再结合这个项目的实际情况A 级可以碰有测试覆盖、没有外部依赖、纯逻辑类。B 级小心碰有测试但没有完全覆盖或依赖外部服务但可以 mock。C 级别碰没有测试、有数据库读写、有静态状态修改、被很多地方引用的核心类。我让 Claude Code 扫描全部类然后分类输出。它的评估标准来自我给它的描述将项目中的所有类按照 A、B、C 三级分类A 级是无副作用、无外部依赖的方法B 级是有外部依赖但可以通过参数注入改进的方法C 级是修改全局状态、直接操作数据库或 Session 的方法。输出分类结果并列出理由。这个分类结果成了我整个重构计划的项目排期表。我只会让它在 A 级和 B 级代码上做重构C 级代码只做包裹wrap就是往里套一层接口而不是直接改内部逻辑。这个过程有点像做手术前给病人分诊——你不能一上来就给最危重的病人开刀而是要先挑那些基础状况好、风险低的部位练手。重构遗留系统也是一样从一个 A 级模块的提取和迁移开始积累信心和验证流程然后再逐步深入。3. 三个核心操作拆解、提取、迁移3.1 从大方法里提取业务规则在遗留系统里最典型的代码坏味道就是上帝方法——一个方法几百行甚至上千行里面什么都有。我让 Claude Code 做的事是把这个大方法拆成若干小方法然后把其中的业务规则单独提取出来。这里要说一个非常关键的技巧不要直接让 Claude Code 重写这个方法让它先做机械拆分。机械拆分的意思是保持每行代码几乎不变只是改变缩进和调用位置。这样做的目的是拆分之后的行为和原来完全一致不会引入新的逻辑错误。等拆分完成你再在此基础上做逻辑整理。我给它类似这样的指令这个方法是典型的上帝方法请按以下顺序拆分1. 保持方法签名不变2. 按注释或逻辑块拆分为多个私有方法3. 每个私有方法只做一件事名字直接描述行为4. 拆分过程中不要修改任何业务逻辑5. 拆分完成后请列出每个方法的职责和大致行数。它很快给了我一个新版本并且标注了每个方法的功能说明。让我惊讶的是它不只是机械地断行它还会主动识别重复的逻辑块并建议合并。这种半机械半智能的感觉正是我需要的——它比纯机械工具如 ReSharper更灵活比纯手写更高效。3.2 用接口隔离脏代码而不是直接清理遗留系统里最麻烦的代码不是写得乱的代码而是和数据库、外部服务紧密耦合的代码。这部分代码你直接清理大概率会把业务逻辑和基础设施一起拆散最后得到一个看起来更干净但实际上跑不起来的结果。我的方案是先用接口隔离再逐步替换实现。具体做法是让 Claude Code 识别出所有直接访问数据库的类和方法然后为这些数据库访问类创建接口接口方法签名与现有公共方法一致。然后修改依赖方让它们依赖接口而不是具体类。不要修改接口内部实现。这一步做下来整个数据访问层的耦合就被切断了一部分。以后更换数据库实现或者替换为新的 ORM就只需要提供一个新的实现类而不需要改动任何业务层代码。这个过程的收益是巨大的。它让一个传统三层架构里的数据访问层一夜之间变成了可以替换的可插拔组件。而这一切都是在没有重构实现细节的前提下完成的。说白了我只是先给这些脏代码穿了一件隔离服真正清理内部是后面的事。3.3 小步迁移一次只搬一段代码重构最有挑战的部分不是技术而是心理压力。每次看到几百行代码在一夜之间被改得面目全非你很难说服自己这是安全的。所以我对 Claude Code 的策略一直是小步快跑一次只迁移一个模块。我实际设定的流程是这样的选定一个 A 级类安全等级最高。让 Claude Code 生成这个类的快照测试。用 Claude Code 将它的实现复制到新的项目或命名空间。在新的实现上做重构拆分方法、提取规则、清理命名。跑测试对比新旧结果。通过后删除旧实现保留新实现。Claude Code 在这种搬移局部重构的任务上特别顺手。它不需要你给它精确到每个文件的指令你只需要定义目标状态它会自己规划路径。例如我给它下达过这样的任务将 ShippingCalculator 类从旧命名空间迁移到新命名为 BusinessLogic.Calculator 的命名空间。迁移过程中1. 保持所有公共方法签名不变2. 将内部的switch-case替换为策略类3. 新增方法需要保留原有日志输出格式4. 迁移后运行现有测试确保全部通过。它会自己找到需要迁移的文件创建新的命名空间修改引用替换逻辑然后运行测试。我在旁边只需要盯着测试结果。这套流程往复多次之后我整理出了一个很重要的工作习惯一次对话只做一类重构操作做完就停绝不贪多。既然提到测试我一直用的是 Claude Code 原生集成的测试工具。执行前它会自动检测项目用的测试框架然后通过命令行跑测试。你也可以在提示词里直接要求运行项目的测试套件并汇报失败项它确实会如实照做失败信息也列得很清楚省去了我自己敲命令的步骤。4. 真实踩坑过程一次失败的自动重构与复盘4.1 事故现场它把 try-catch 逻辑改丢了如果你以为上面的流程每次都能顺利跑通那就太天真了。我这里真实翻过一次车。当时我让 Claude Code 重构一个订单状态转换的方法。它本身的逻辑是try块里做状态切换catch块里记录异常并返回失败状态。结果它重构完之后把catch里的返回值从失败改成了抛异常并且去掉了日志记录。测试立刻暴露出异常但问题是这个错误非常隐蔽——因为我的快照测试只覆盖了正常路径没有覆盖异常路径。Claude Code 本身不会自动补全测试异常分支它只会忠实执行你给的任务。这个 bug 过了两天才被一个线上问题逼出来运维日志里显示大量订单状态更新失败老用户那边已经炸了。这件事给我提了个醒**AI 重构最大的风险不是 AI 笨而是你给的验收标准不够严。**你如果用保持行为一致这种模糊描述它会自由发挥。你必须明确告诉它catch 块必须返回 Failure 状态同时写入日志它才会真的守住这条线。从那以后我所有重构指令都会自带一句固定后缀重构后所有 public 方法的行为必须完全一致包括异常路径并运行全部测试验证。4.2 排查链路从测试失败到定位根因出问题之后完整的排查流程大概是这样走的对你自己排查这类问题应该也有参考价值。第一步是看测试输出。Claude Code 执行测试后会把失败信息直接贴在对话里我一眼看出某个订单状态相关的测试挂了。第二步我让它查询相关测试文件定位断言了哪些行为。第三步我让它在本地项目里全文搜索这个方法的副作用点。第四步我发现它把 catch 块的返回语句改成了throw同时在错误日志里新增了一个不该有的异常堆栈。第五步我回看它的重构过程它确实早就提示过修改了这个方法的行为但我当时只关注了正常路径直接点了接受。整个过程中最值得反思的其实不是 AI 的错误而是我的审查粒度。在快速产出带来的兴奋感中我跳过了 diff review 环节这是不可原谅的。后来我给自己立了个规矩任何 AI 改动的代码我在 merge 之前必须完整看一遍 diff不做盲信。同时我会在提示词里明确要求如果本次修改涉及异常处理逻辑先在回答中说明再给出代码否则严格保持与原逻辑一致。4.3 从这次翻车中总结出来的三条铁律事故之后我建立起一套防错机制现在分享三条最核心的第一条快照测试一定要覆盖异常路径。只测正常路径的测试在 AI 面前等于摆设。它太容易把出错时返回失败结果改成出错时抛出异常然后测试还全绿。你必须专门为异常路径写测试而且要在重构之前写。第二条每一批重构只做一类操作。你让 AI 同时做方法提取 命名清理 策略模式替换 数据库层隔离它大概率会引入交互式 bug。它的优势在于单线任务的深度处理而不是多线程并发修改。分批处理每批验证虽然慢但安全。第三条diff review 不可省略。很多AI 重构翻车的案例追溯源头几乎都是负责审查的人类偷懒。Claude Code 的方案再好最终签字的是你。重构遗留系统的过程里你的角色不应该是AI 的操作员而应该是一个拿着放大镜的审计员。提示如果你发现 Claude Code 在一次重构里改动了超过预期范围的内容直接让它回滚到改前状态然后缩小范围重新操作。我大多数时候都这么做几乎每一次都能避免不必要的风险扩散。这也算是出了问题优先止血的一种操作习惯。5. 让 Claude Code 真正适配自己的项目模型、规则与团队协作5.1 模型选择与成本控制很多人以为 Claude Code 只能用 Anthropic 的官方模型其实不是。它本身是一个支持多种模型接入的终端工具配置方式是在命令行里指定或修改对应的模型映射配置。你可以按需接 Anthropic 模型、云厂商的模型接口也可以换成开源的本地模型。就我的使用体验来看如果你手里项目代码量比较大、上下文要求高官方模型在 Long Context 场景下最好用尤其适合让 AI 通读整个解决方案再下手的重构场景。不过代价是成本上升尤其是你频繁让它在大型代码库上做全库扫描的时候。如果你只是做小型模块重构或者不想依赖云端接口可以考虑配置本地模型 API。改造逻辑简单、上下文需求低的场景本地模型完全够用。当然接入本地模型的前提是你的环境里有可用的模型服务操作方式和配在线模型差不多指向你本地的服务地址就行。下面这个表是我自己总结的选型参考场景模型类型推荐原因大型代码库全库扫描长上下文的高性能大模型能一次读入更多文件依赖关系模块级小步重构标准大模型或本地大模型上下文开销低成本可控生成单元测试骨架任意模型任务模式固定对推理能力要求不高大型代码库内做多轮交互排查长上下文优先减少中途上下文清洗带来的信息丢失具体到费用我建议你给每个重构任务设定一个最高预算。Claude Code 的输出消耗与任务复杂度直接相关全库扫描和深度推理的任务花费会显著高于单文件修改。所以实践上我会把通读全局的任务放在分批处理里一次只让 AI 专注一个模块而不是反复发起全库级别的高成本请求——这样既省预算也减少因为上下文过大带来的不稳定。提示在团队场景里如果一个任务要 AI 修改超过 10 个文件我会主动把它拆成 3-4 个批次。这既是为了控制模型输出的稳定性也是为了避免一次改动太大后 replication 困难、review 难做。多批次沟通下来总成本反而更低。5.2 用项目规则文件约束 AI 的行为重构进行到中期我发现 Claude Code 偶尔会自由发挥生成一些和团队规范不一致的代码。它毕竟不是一个了解你们团队编码习惯的工程师。解决办法是给它立规矩。Claude Code 支持项目级的规则定义文件。我通常会在项目根目录下加一个规则文件把团队编码规范的核心条款写进去。比如本项目禁止使用 var 关键字除非无法推导类型。所有方法必须有 XML 注释。数据库访问必须走仓储层禁止在业务层直接调用 DbContext。异常处理不得吞没异常必须保留原始异常信息。这个文件一旦存在Claude Code 在生成代码的时候就会自动遵守这些规则。效果非常明显从那以后它生成的代码基本不需要再专门花时间调整代码风格。你可以把它看作给 AI 的一个项目章程它要在这个章程的约束下办事否则算越权。整个重构从混乱到有序的过程本质上也是在不断往这个章程里补充我们迭代中发现的坑和禁忌。5.3 Claude Code 与团队协作的边界最后聊聊团队协作。这部分可能直接关系到你的重构方案能不能在团队里落地所以单独拿出来说。一开始我们团队是禁止使用 Claude Code 改代码的原因和大多数团队一样担心引入不理解的变更。但实验跑了几周之后团队的态度发生了转变。原因是 Claude Code 产出的代码质量稳定、注释完整、测试也一并生成了code review 的成本反而比传统开发方式低。团队协作里我用 Claude Code 的方式是每个成员在自己的分支上使用 Claude Code不直接在主分支上让它做修改。AI 生成的所有代码必须走正常的 pull request 流程。PR 描述里必须标注AI 参与修改的部分方便 reviewer 重点审查。凡是涉及数据库结构、接口签名、权限模型变更的任务一律禁用 Claude Code必须人工评审后手动修改。这套规则运行下来Claude Code 的产出和团队的信任度都提升了很多。后来我们还引入了另一种 Agent 工具配合进行代码审查但核心流程没变。6. 重构完成之后如何让系统不再退化6.1 架构边界在重构中形成的守护模式重构不是终点而是新病情的起点。很多重构完的项目半年之后又回到了原来的混乱状态——新需求不断叠加架构重新腐烂。我在这段时间里总结出最有效的一招把架构规则写进 AI 的规则库中让它在生成新代码时自动遵守。比如我重构完成后在规则文件里加了一条新代码必须依赖接口不得直接依赖具体实现类。领域层不得引用任何基础设施层类型。所有外部调用必须通过应用服务层。这意味着后续任何开发者用 Claude Code 写新功能时生成的代码天然符合架构边界。相当于你用 AI 实现了架构守护——它不再只是帮你重构一次而是在持续帮整个团队守住架构的底线。6.2 从代码重构到知识沉淀另一件我觉得比代码重构本身更有价值的事是 Claude Code 帮我把项目里那些口口相传的知识固化成了文档。在重构过程中我让它随时记录这个模块为什么这样设计这个类为什么不能改成枚举这个数据表为什么要冗余这份数据。最后它帮我整理出了一份反映真实业务逻辑的架构说明文档。这比我过去靠采访老员工、翻邮件记录来整理知识的方式高效得多。这份文档我现在每次培训新人都直接给效果远好于让他们自己翻代码。所以我的建议是你在重构时一定要让 Claude Code顺便写注释和文档而不仅仅是改代码。如果你做完重构留下来的只有新代码没有新认知那你的重构只完成了一半。这句话算是我几个月实操下来最大的体会。6.3 这轮重构结束后我的真实体会回到最开始的问题。为什么我敢把遗留系统交给 Claude Code因为经过这轮完整项目之后我得到的结论是真正让我放心的不是 Claude Code 有多强而是我在使用它的过程中形成了一套完整的约束、验证、审查机制。它不是因为万能而安全而是因为好用而被纳入了我的防御性开发体系。重构遗留系统不是一个技术问题而是一个勇气问题。你需要的不是一把能一刀切掉所有问题的快刀而是一个能帮你慢慢理清线头的助手。Claude Code 天然是后者——它耐心、细致、不抱怨、也不会被历史包袱吓到。但我必须再一次提醒它是一种工具不是一个可以完全托付的工程师。你的经验、你的判断、你对业务的理解才是整个迁移过程中唯一不可替代的部分。最后分享一个小技巧如果你刚开始试的时候发现 Claude Code 给出的重构方案不够好别急着否定它。试着把问题再拆小一点把边界条件再补充一些把验收标准再写清楚一点。多数情况下问题出在我们的指令不够精确而不是工具不够聪明。这和带一个新人其实是一个道理。