接手过遗留系统的同学应该都有这种体验代码能跑但没人敢碰每次加需求都像做心脏手术改动一行日志都要把整个调用链翻一遍。我以前处理这类问题的方式是“硬着头皮手动重构”直到我尝试把 Claude Code 引入重构流程整个过程发生了质变——它不仅能读代码、改代码还能和我讨论重构方案把原来需要两周的模块梳理压缩到两天。这篇内容不是理论科普而是我一整套可复用的实战方法怎么让 AI 先看懂你的遗留系统、怎么把大模块拆成 AI 能处理的小任务、怎么防止 AI 在旧代码上“自由发挥”改坏行为。适合正在维护老项目的开发者、想引入 AI 辅助开发但不知道从哪下手的团队也适合准备用 Claude Code 做代码重构但还没摸清边界的人。我会把背后原理、具体命令、提示词模板、翻车场景全部摊开讲。1. 别急着让 AI 动手重构成留系统的三个前置动作很多人拿到 Claude Code 第一反应是把整个项目丢给它说“帮我重构”然后坐等奇迹。这个思路大概率会翻车。遗留系统之所以叫遗留系统是因为它积累了十几年的业务规则、隐式约定和“删了就会炸”的神秘代码。AI 再强也需要你先帮它搭建一个能“理解”这个系统的基础。1.1 先让 AI“体检”而不是直接“开刀”我第一次实操时先没用重构指令而是让 Claude Code 做代码库扫描命令很简单claude -p 阅读当前仓库的代码结构输出一份技术债报告包括模块划分、循环依赖、重复代码集中区域、明显违反分层架构的地方。不要修改任何文件。这一步的目的不是拿到一个完美的报告而是让 AI 在改动代码之前先建立全局认知。原始仓库里如果连 README 都没有AI 就只能靠猜而猜测在遗留系统里往往是灾难的开始。我会把这份报告保存下来作为后续所有重构决策的基线。跑完扫描之后我个人习惯是再追问一轮让 AI 列出它觉得“最需要重构但风险最低”的模块并说清楚理由。这一步能帮你判断 AI 对系统的理解是否靠谱——如果它选出的模块明显是核心链路说明它还没吃透业务边界你需要在上下文里补充模块职责说明。1.2 画清楚模块边界AI 最怕“一团乱麻式”的上下文遗留系统最常见的特征是模块边界模糊Service 层互相调用Utils 类里什么都有全局变量到处传。这种情况下AI 拿到整个仓库的上下文反而会迷失方向。我的做法是在项目根目录建一个CLAUDE.md文件把系统架构浓缩进去。比如# 订单系统架构说明 ## 模块边界 - order-service订单创建、状态流转、取消逻辑依赖 customer-service 和 payment-service - payment-service支付渠道适配状态回调严禁反向调用 order-service - customer-service客户信息与等级计算被 order-service 依赖 ## 高风险区域 - OrderStateMachine 类包含订单全部状态流转改动必须同步更新状态变更日志 - LegacyPriceCalculator遗留价格计算器存在多种促销叠加逻辑不要试图统一算法 ## 编码约束 - 新代码禁止使用静态全局变量 - 对外接口必须保持兼容不允许修改方法签名这个文件会被 Claude Code 自动读取成为所有后续对话的默认上下文。它相当于给 AI 画了一张“地图”AI 才知道哪些地方可以动、哪些地方只能绕行。1.3 建立“行为基线”没有测试就先补测试哪怕只补一层冒烟重构最大的风险不是代码改错而是改错了还发现不了。旧系统往往没有单元测试所以我补测试的策略是“关键路径 冒烟覆盖”优先给以下代码补订单状态流转相关的状态机逻辑价格计算、优惠叠加这类“算错一分钱都是事故”的函数对外 API 的入参出参转换层定时任务、消息队列消费者这类“跑起来才出错”的入口不需要做得很完美哪怕只是把输入输出用断言固定下来也能在重构后充当安全网。Claude Code 可以帮你生成测试骨架你负责补充业务断言。这里我通常用这个提示词claude -p 针对当前模块的 OrderService 和 PriceCalculator生成一组基于真实业务场景的单元测试骨架使用 JUnit 5测试数据用具体的硬编码值不要用 mock 框架。为什么不用 mock因为遗留代码通常耦合严重mock 会让测试失去意义直接用真实对象跑更容易暴露隐藏依赖。2. 环境搭建与模型接入Claude Code 跑起来的完整记录聊完了方法论进入实操环境。Claude Code 本质上是一个运行在终端里的 AI 编程代理你可以用自然语言指挥它读写文件、执行命令、运行测试。它不只是补全代码而是可以执行多步任务比如“找到所有调用旧接口的地方逐个替换成新接口然后跑测试”。2.1 安装两条路选适合你的安装 Claude Code 最常用的方式是通过 npmnpm install -g anthropic-ai/claude-code安装后直接在终端输入claude就能进入交互模式或者用claude -p 指令做一次性非交互调用。如果你不想用命令行新版本也提供了桌面客户端本质上一样只是多了个图形界面。还有很多人直接把 Claude Code 接进 VSCode 使用配置方式也不复杂通过插件市场搜索 Claude Code 相关扩展即可这样你可以在编辑器里直接框选代码片段让 AI 处理而不需要切换终端窗口。从我实际使用感受来说终端版更适合大范围重构VSCode 插件更适合局部修改和代码解释两者互补。2.2 模型接入官方 Claude 模型以及 DeepSeek 等第三方兼容方案Claude Code 默认走 Anthropic 官方 API首次启动时需要登录授权。但不同开发者的网络环境不一样如果你发现claude启动后一直卡在连接阶段不必死磕可以先确认终端的网络连通性是否正常。另外不少开发者会把它配置为接入 DeepSeek 等其他模型做法是通过环境变量指定兼容接口export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_API_KEY你的API密钥设置完之后再运行claude它就会走对应的第三方模型。我之前在某个老项目上试过用 DeepSeek 跑重构任务推理能力完全够用在一些中文命名规范的理解上甚至更贴合团队习惯。需要提醒的是任何第三方接入都要先看官方文档确认兼容性而且不要在生产环境乱试。2.3 Skill 与 Workflows让 AI 拥有“团队规范”Claude Code 支持 Skills 机制你可以在项目里放一份skills目录为 AI 定义可复用的技能。举个例子我们团队要求所有重构后的方法必须有日志和参数校验我会写成# skill: refactor-with-guard ## 描述 重构Java方法时自动补充参数校验、日志输出、异常包装。 ## 执行步骤 1. 识别方法入口参数 2. 添加 null 校验与非法值校验 3. 保留原方法签名方法体内新增结构化日志 4. 异常统一包装为 BizException配置好后对话中提到“按团队规范重构”AI 就会自动应用这个技能。这是把个人经验沉淀成组织能力的好方式也是 Claude Code 用得越久越顺手的关键。3. 第一次重构实战把一个 2000 行的“上帝类”拆干净做好前置准备后我拿一个真实案例演示整个重构链路。这个案例是一个老订单模块里的OrderService2000 多行混杂了订单创建、价格计算、库存扣减、状态流转、消息通知甚至还有一段优惠券校验。我准备把它拆成订单、价格、库存、通知四个子模块同时保持对外接口完全不变。3.1 上下文构建给 AI 喂“精华”而不是“全文”虽然 Claude Code 有长上下文能力但直接把 2000 行代码全部塞进去效果不一定好。我的做法是先用命令提取关键信息claude -p 读取 OrderService.java列出它调用的所有外部依赖其他类的public方法、它被谁调用、内部的私有方法的职责聚类。输出格式依赖清单、调用方清单、私有方法分组。不要改代码。拿到结果后我会把“依赖清单”和“调用方清单”作为上下文基础然后让 AI 设计拆分方案而不是直接让它拆。因为拆分方案涉及业务判断AI 容易分得太机械把强耦合的逻辑硬拆开反而增加后续维护成本。方案确认后的提示词是这样claude -p 基于以下拆分方案重构 OrderService 1. OrderCoreService订单创建、状态流转 2. PriceCalculationService价格与优惠计算 3. StockDeductionService库存扣减 4. NotificationService消息通知 要求 - 保持 OrderService 对外方法签名完全不变 - 新类放在 com.example.order.domain 包下 - 每个新类生成对应单元测试骨架 - 不要修改任何其他文件这一步用了几个关键约束“对外方法签名不变”限制了行为变化“不要修改任何其他文件”避免了 AI 顺手把调用方也改了导致 diff 爆炸。3.2 迁移过程一次性完成 vs 分批进行实际操作中我极少让 AI 一次性完成整个迁移而是按数据流拆分步骤先把内部私有方法按职责迁到新类OrderService改为调用新类的方法跑一遍既有测试确认行为没变再把新类支持扩展到完整业务逻辑重复跑测试最后做调用方清理确认没有绕过OrderService直接使用被拆分的内部状态每一步之间都进行一次编译和测试。这相当于把一个大重构拆成多个小重构每个步骤都是可回滚的。我踩过的坑是让 AI 一次性拆完结果编译错误几十个并且因为改动面太大AI 自己也搞不清哪里出了问题最后我只能手动回溯。分批执行时Claude Code 的记忆能力帮了大忙。它可以记住你上一个步骤做了什么、为什么这样做后续指令只需要说“继续”即可。我用的是claude --continue这个方式来续接会话效果等同于我一个人全程盯着代码库。3.3 验证闭环重构完不是结束是开始代码拆分完成后真正的工作才开始。我一般安排四层验证验证层级方法目的编译检查全量编译保证语法和引用完整单测回归新增/既有单元测试验证核心算法行为接口契约检查API diff 对比工具确认对外签名未变链路验证本地启动跑核心业务场景模拟真实调用链路Claude Code 在验证环节同样能发挥作用claude -p 检查当前代码库中是否还有对 OrderService 内部私有方法或已迁移类内部状态的直接访问输出警告列表。这种“查漏”指令在拆分后的代码里特别有价值能把遗留的越权访问揪出来。4. AI 在旧代码上翻车的四个高频场景我的排查链路AI 重构不是一路开绿灯。我在多次实践中总结出四个高频翻车点每个都经历过完整的问题排查这里把思路和复盘过程分享出来帮大家少走弯路。4.1 幻觉式补全AI 自己“编造”了不存在的 API第一次用 Claude Code 重构一个老支付模块时AI 在迁移代码时引用了一个名为PaymentTransactionManager的类但实际上整个项目里根本没有这个类。它可能是根据语义拼出来的“合理名字”编译直接报错。排查过程我打开编译错误日志发现错误集中在某个包下然后让 Claude Code 自己解释这段代码的引用来源它承认是基于上下文推断而非真实存在。解决办法是回到代码库搜索真实类名修正引用同时在后续提示词里加强约束“所有引用的类名、方法名、变量名必须以现有代码为准禁止创造不存在的标识符。”这个坑的本质是AI 的“语义合理性”和“代码正确性”是两回事。你不能让 AI 在重构过程中同时负责“设计新类名”和“保持编译通过”除非你把允许新类名的范围缩小到“专用于新拆分的类”。4.2 行为过度封装把遗留逻辑“美化”成不符合原意的样子第二次踩坑更隐蔽。我让 AI 重构一个促销价格计算函数原本的代码是叠加折扣时保留中间小数最后再四舍五入。AI 觉得这不够优雅改成每一步都保留两位小数表面上代码更规范实际计算出的价格和老系统不一致差了一分钱。排查过程先跑价格相关的单元测试发现有断言失败。对比新旧逻辑定位到小数精度差异。修复方式不是让 AI 去更新算法而是让 AI 严格对照旧函数的输入输出逐行复刻算法逻辑把“保持行为一致”作为最高优先级。这是非常重要的一个认知AI 有强烈的“优化冲动”但重构遗留系统的第一原则是行为不变优化是后续的事。你必须在提示词里反反复复强调“保持原逻辑不要优化算法”。4.3 上下文不够AI 只看局部方案偏掉有一个订单状态机重构的案例AI 只读了我指定的状态机类文件没有看调用方的代码结果把状态枚举重命名了所有调用方全部编译失败更麻烦的是会话历史里 AI 已经把这个重命名当作是“已完成的事实”后面再问它它会把错误方案作为基准继续推进。排查过程我发现编译错误波及面太广立刻中断会话用claude -p 搜索所有引用 OrderState 枚举的地方拿到真实影响面然后在新的会话里重新构建上下文把“订单状态枚举是全局共享禁止重命名只能内部调整流转逻辑”写进CLAUDE.md后续才没有再犯。这个案例给我的启示是AI 的上下文是对话级的不是项目级的。它在一次会话里看到的文件有限你必须主动告诉它哪些文件属于受影响范围否则它会基于不完整的信息做全局决策。4.4 验证缺失AI 认为“没报错就成功了”不等于行为没变还有一次是 AI 改完代码后告诉我“重构完成测试通过”但我打开测试报告发现测试覆盖率低得可怜它只跑了它自己生成的那几个测试原有的核心测试根本没执行。它没有主动运行完整测试集的习惯或者说它在“自我报告”时只关注了自己接触到的部分。排查过程我在提示词里增加了强制验证步骤claude -p 重构完成后执行以下验证并输出完整日志1) 全量编译2) 运行 /src/test 下所有测试类3) 对比 git diff 中被改动的公共接口签名。强制要求它输出验证日志你才能判断它是否真的验证了。不要轻信“看起来成功了”的结论要看它实际跑出了什么结果。5. 让 Claude Code 越用越懂你的工程化技巧经历了前面几个翻车场景后我逐渐摸索出一套让 AI 从“偶尔聪明”变成“稳定可靠”的方法。核心思路是把团队规范、模块边界、历史约定全部固化下来让 AI 每次开工前都能读到而不是靠每一次对话里临时解释。5.1 CLAUDE.md 的正确写法写“边界”而不写“风格”很多人把CLAUDE.md写成代码风格指南比如“缩进用两个空格”“函数命名用驼峰”。这些当然有用但对遗留系统重构来说更重要是写清“不能碰的东西”。我推荐的模板结构是# 项目概览核心业务是什么 # 模块边界与依赖方向谁可以依赖谁 # 高风险区域哪些代码动之前必须慎重 # 重构约束对外签名不可变、行为必须保持一致 # 常用命令怎么编译、怎么跑测试其中“重构约束”是最容易被忽略也最有价值的。它让 AI 在思考重构方案时先过一遍“边界检查”而不是只从代码结构出发追求完美设计。5.2 把提示词模板沉淀成团队资产不要每次重构都临时想提示词。我会把高频任务做成可复用模板放在项目文档或 skills 目录里。比如模块拆分模板任务拆分 {模块名} 步骤 1. 梳理当前模块职责清单 2. 识别强弱依赖关系 3. 输出拆分方案新类名职责调用关系 4. 用户确认方案后再动手 5. 分批迁移每批编译测试 约束 - 对外接口签名不变 - 禁止引入新依赖库 - 保持原行为不做算法优化行为对比模板对比 {函数名} 重构前后的行为差异 1. 列出输入参数的所有边界情况 2. 对每种情况分别描述重构前后输出 3. 如有差异指出差异原因并修复这些模板看起来简单但实际用起来能极大减少反复沟通的成本。AI 第一次按模板做事可能还需要你补细节第二次就会自动按模板执行。5.3 多轮会话接续让 AI 不“失忆”Claude Code 支持会话管理和续接我的习惯是同一个重构模块始终用同一组会话文件不要中途开新会话。中途开新会话会导致 AI 丢失之前的所有上下文它会重新“理解”代码库甚至给出和之前相反的方案。我用claude --continue来继续上次会话或者列出历史会话找回当时的上下文。这在大规模重构中特别重要因为一个模块的重构周期可能横跨几天AI 需要记住它自己之前的决策逻辑否则就会出现前后矛盾。5.4 和本地模型结合私有仓库场景下的重构思路有些团队的代码没法传到外部 API这时可以考虑把 Claude Code 类的工作流和本地模型结合。虽然本地模型的推理能力相对弱一些但用于“找重复代码”“生成测试骨架”“做代码解释”这类辅助任务还是够用的。核心重构仍然建议用能力更强的模型来把关。我曾经在一台内网开发机上试过用本地模型跑代码分析任务效果比预期好的是它能快速生成“方法级调用关系图文本”比人工翻阅快得多。瓶颈在于复杂逻辑推理一旦涉及跨模块方案设计本地模型给的方案会比较浅需要人工修正。6. 哪些重构适合 AI哪些不适合我的判断标准任何工具都有边界。用 Claude Code 做了大量重构之后我形成了一套自己的判断标准不一定适用所有人但至少能帮你在开始之前做一个初步的风险评估。6.1 适合 AI 重构的场景职责拆分上帝类拆分、超大方法拆小方法AI 很擅长识别“不同功能块的边界”重复代码抽取找重复代码并提取公共方法AI 比人眼快一个量级统一调用方式比如把一堆直接 new 对象的地方改成工厂方法AI 能批量完成代码迁移从旧框架 API 迁到新框架 APIAI 能按映射关系批量替换测试骨架生成虽然断言还要人补但骨架和分支覆盖分析是 AI 的强项这些场景的共性是目标明确、边界清晰、行为可以验证。AI 的容错空间大即使第一版不完美人工 review 的成本也低。6.2 不适合 AI 重构的场景核心业务规则模糊的代码连团队自己都说不清“为什么这里要这样判断”AI 更不可能搞懂强行重构等于重写业务性能敏感的核心链路AI 对算法和数据结构优化的理解有限容易“优化”出更差的实现依赖大量隐式约定的代码比如“这个全局变量在启动时由外部注入”“这个枚举顺序对应数据库存储值”如果这些约定没写进文档AI 无从知晓大规模跨模块改动比如要改数据库表结构、改消息协议格式涉及多个系统联动的不适合让 AI 一把梭判断标准可以浓缩成一句话如果改动可以“从代码层面验证对错”AI 能帮上大忙如果只能靠“业务人员确认对错”就不要让 AI 动手。6.3 落地节奏渐进式引入而不是“大爆炸式”重构最后一点经验是节奏问题。我见过不止一个团队想用 AI 一次性把遗留系统整个翻新结果和 AI 一起陷入混乱最后回滚代码。更稳的做法是选一个影响面可控的模块做试点跑通全流程——梳理、拆解、迁移、验证、复盘——建立团队的信心和 AI 的操作规范再逐步扩大范围。我在试点阶段会特意选一个“中等规模、业务价值高、风险可控”的模块既能让团队看到实际收益又能暴露出 AI 操作的典型问题。踩完试点期的坑之后再大面积铺开会顺畅得多。我个人的体会是Claude Code 不会替你解决遗留系统的所有问题但它能把你从“不敢动代码”的泥潭里拉出来让你有勇气和工具去推进重构。真正重要的是你能否把业务边界和行为约束清晰地转交给它以及你是否愿意在它翻车的时候耐心排查而不是立刻否定整个工作流。只要这两点做好了AI 重构带来的效率提升是实打实的。