用 Claude Code 重构遗留系统：从评估到落地的完整指南

1. 为什么选择 Claude Code 重构遗留系统

遗留系统往往承载着核心业务逻辑，却因技术债沉重、文档缺失、人员更迭而难以维护。传统重构周期长、风险高，而 Claude Code 作为 AI 编程助手，能够在代码理解、批量修改、测试补全等环节显著提升效率。本文将从评估、规划、执行到验证，梳理一套用 Claude Code 重构遗留系统的可操作方法。

2. 重构前的系统评估

在动手之前，先回答三个问题：系统当前的技术栈是什么？核心业务逻辑集中在哪些模块？哪些部分风险最高、最不该动？

• 技术栈盘点：确认语言、框架、构建工具和依赖版本，判断 Claude Code 对当前技术栈的支持程度。
• 模块边界梳理：借助 Claude Code 的代码库理解能力，快速生成模块依赖图和调用关系概览。
• 风险分级：把模块分为低风险（可安全重构）、中风险（需谨慎）、高风险（尽量不动）三档。

3. 用 Claude Code 建立代码基线

重构的前提是"改前可测、改后可对比"。利用 Claude Code 为遗留代码补齐测试与文档基线。

• 生成单元测试：让 Claude Code 为关键函数自动生成测试用例，先跑通再重构。
• 补充接口文档：对核心 API 生成参数、返回值与异常说明，作为后续改动的参照。
• 建立行为快照：记录重构前各模块的输入输出样例，用于回归对比。

4. 制定重构计划与任务拆分

把大重构拆成可独立验证的小任务，每个任务都对应一次 Claude Code 会话。

• 按依赖顺序排序：先重构底层工具类，再逐步向上层业务推进。
• 明确每个任务的验收标准：例如"原有测试全部通过""新增测试覆盖率达到 X%"。
• 设定回滚点：每个任务完成即提交，保证任意时刻可回退。

4.1 重构流程总览

整个重构过程可以归纳为五个环环相扣的阶段：系统评估、建立基线、任务拆分、小步重构、持续验证。每个阶段都有明确的输入与输出，前一阶段的产出正是后一阶段的输入，形成一条可追踪、可回退的完整链路。

flowchart TD
    A[系统评估] --> B[建立基线]
    B --> C[任务拆分]
    C --> D[小步重构]
    D --> E[持续验证]
    E -->|发现问题| D
    E -->|全部通过| F[完成重构]

各阶段的输入输出说明如下：

• 系统评估：输入是遗留系统的源码、依赖清单与运行环境；输出是技术栈盘点、模块依赖概览和风险分级结果。
• 建立基线：输入是评估阶段圈定的关键模块；输出是单元测试、接口文档和行为快照，作为后续改动的对照基准。
• 任务拆分：输入是基线文档与风险分级；输出是按依赖顺序排列的小任务清单，每个任务都带明确的验收标准与回滚点。
• 小步重构：输入是单个拆分任务；输出是经过修改并通过相关测试的代码提交，保证任意时刻可回退。
• 持续验证：输入是每次重构后的代码与测试结果；输出是回归结论，若发现问题则回到小步重构阶段修正，全部通过则完成整个重构流程。

5. 实战：Claude Code 重构典型场景

以下场景是遗留系统重构中最常见、也最适合借助 Claude Code 的环节。每个场景都给出可直接套用的提示词示例，以及重构前后的代码对比，并注明适用的编程语言。

5.1 消除重复代码

让 Claude Code 扫描相似代码片段，提取公共方法或基类，并同步更新所有调用点。

提示词示例：

请扫描项目中所有重复或高度相似的代码片段，找出可以提取的公共方法或基类。对每一处重复，给出重构前后的代码对比，并同步更新所有调用点，确保行为完全一致。

适用语言：Java、Python、JavaScript、C#

重构前（Java）：

public double calculateTotalA(List<Item> items) {
    double total = 0;
    for (Item item : items) {
        total += item.getPrice() * item.getQuantity();
    }
    return total;
}
public double calculateTotalB(List<Item> items) {
double total = 0;
for (Item item : items) {
total += item.getPrice() * item.getQuantity();
}
return total;
}

重构后（Java）：

public double calculateTotal(List<Item> items) {
    double total = 0; // 初始化累加器，用于汇总所有商品的小计金额
    for (Item item : items) { // 遍历商品列表，逐项累加金额
        total += item.getPrice() * item.getQuantity(); // 累加当前商品的单价 × 数量，得到小计
    }
    return total; // 返回累加结果，作为提取后的公共复用点
}

5.2 升级过时依赖

借助 Claude Code 分析依赖升级的影响面，自动修改受影响的 API 调用，并运行测试验证兼容性。

提示词示例：

请分析当前项目中所有过时依赖，列出需要升级的库及其目标版本。对每个依赖升级，找出受影响的 API 调用并自动修改，最后运行相关测试验证兼容性，输出升级前后的代码对比。

适用语言：Python、JavaScript、Java、Go

重构前（Python）：

import requests
response = requests.get("https://api.example.com/data")
data = response.json()

重构后（Python）：

import httpx
response = httpx.get("https://api.example.com/data")
data = response.json()

5.3 重构复杂条件逻辑

把冗长的 if-else 或 switch 分支改造成策略模式或状态机，由 Claude Code 生成等价实现并对比行为。

提示词示例：

请将以下冗长的 if-else 或 switch 分支改造成策略模式或状态机实现。生成等价代码并对比重构前后的行为，确保所有分支逻辑完全一致，并补充必要的单元测试。

适用语言：Java、C#、TypeScript、Python

重构前（TypeScript）：

function getDiscount(type: string): number {
    if (type === "normal") {
        return 0;
    } else if (type === "vip") {
        return 0.1;
    } else if (type === "super_vip") {
        return 0.2;
    } else {
        return 0;
    }
}

重构后（TypeScript）：

const discountMap: Record<string, number> = {
    normal: 0, // 普通用户折扣为 0，与 if-else 中第一个分支行为等价
    vip: 0.1, // VIP 用户折扣 0.1，对应原 else if 分支
    super_vip: 0.2, // 超级 VIP 折扣 0.2，对应原 else if 分支
};
function getDiscount(type: string): number {
return discountMap[type] ?? 0; // 映射表替代 if-else：按类型直接查表取值；?? 兜底处理未知类型，等价于原 else 分支返回 0
}

5.4 拆分巨型类与方法

让 Claude Code 识别职责过多的类，提出拆分建议，并逐步迁移方法、字段与测试。

提示词示例：

请分析当前类中承担的职责，识别出可以拆分的独立模块。给出拆分方案，将方法、字段和相关测试迁移到新的类中，并保持对外接口兼容，输出拆分前后的代码结构对比。

适用语言：Java、C#、Python、Ruby

重构前（Java）：

public class OrderService {
    public void createOrder(Order order) { /* 订单创建逻辑 */ }
    public void sendEmail(Order order) { /* 邮件发送逻辑 */ }
    public void generateInvoice(Order order) { /* 发票生成逻辑 */ }
}

重构后（Java）：

public class OrderService {
    private EmailService emailService;
    private InvoiceService invoiceService;
public void createOrder(Order order) { /* 订单创建逻辑 */ }
}
public class EmailService {
public void sendEmail(Order order) { /* 邮件发送逻辑 */ }
}
public class InvoiceService {
public void generateInvoice(Order order) { /* 发票生成逻辑 */ }
}

重构前（Python）：

class OrderService:
    """一个承担了订单创建、邮件发送、发票生成三类职责的巨型类。"""
def create_order(self, order):
    # 订单创建逻辑：校验商品、计算金额、写入数据库
    print(f"创建订单：{order['id']}，金额 {order['amount']} 元")
    # 保存订单到数据库
    self._save_to_db(order)
def send_email(self, order):
# 邮件发送逻辑：拼接邮件内容并调用邮件服务
subject = f"订单 {order['id']} 已创建"
body = f"您的订单金额为 {order['amount']} 元，感谢购买。"
print(f"发送邮件：{subject} - {body}")
# 调用邮件服务发送
self._send_via_smtp(subject, body)
def generate_invoice(self, order):
# 发票生成逻辑：生成发票编号并打印发票内容
invoice_no = f"INV-{order['id']}"
print(f"生成发票：{invoice_no}，金额 {order['amount']} 元")
# 生成 PDF 发票文件
self._create_pdf(invoice_no, order)
def _save_to_db(self, order):
pass  # 数据库写入实现
def _send_via_smtp(self, subject, body):
pass  # SMTP 发送实现
def _create_pdf(self, invoice_no, order):
pass  # PDF 生成实现</code></pre>
重构后（Python）：
class OrderService:
"""只负责订单创建，邮件与发票职责已拆分到独立类。"""
def init(self, email_service, invoice_service):
self.email_service = email_service
self.invoice_service = invoice_service
def create_order(self, order):
# 订单创建逻辑：校验商品、计算金额、写入数据库
print(f"创建订单：{order['id']}，金额 {order['amount']} 元")
self._save_to_db(order)
# 创建成功后，委托给邮件与发票服务，行为与重构前等价
self.email_service.send_email(order)
self.invoice_service.generate_invoice(order)
def _save_to_db(self, order):
pass  # 数据库写入实现
class EmailService:
"""邮件发送职责独立成类。"""
def send_email(self, order):
subject = f"订单 {order['id']} 已创建"
body = f"您的订单金额为 {order['amount']} 元，感谢购买。"
print(f"发送邮件：{subject} - {body}")
self._send_via_smtp(subject, body)
def _send_via_smtp(self, subject, body):
pass  # SMTP 发送实现
class InvoiceService:
"""发票生成职责独立成类。"""
def generate_invoice(self, order):
invoice_no = f"INV-{order['id']}"
print(f"生成发票：{invoice_no}，金额 {order['amount']} 元")
self._create_pdf(invoice_no, order)
def _create_pdf(self, invoice_no, order):
pass  # PDF 生成实现</code></pre>
调用方代码：
组装依赖并调用，对外接口保持兼容
email_service = EmailService()
invoice_service = InvoiceService()
order_service = OrderService(email_service, invoice_service)
order = {"id": 1001, "amount": 299.0}
order_service.create_order(order)
输出：
创建订单：1001，金额 299.0 元
发送邮件：订单 1001 已创建 - 您的订单金额为 299.0 元，感谢购买。
生成发票：INV-1001，金额 299.0 元
测试用例（验证行为等价）：
import unittest
from unittest.mock import patch
class TestOrderService(unittest.TestCase):
def setUp(self):
self.email_service = EmailService()
self.invoice_service = InvoiceService()
self.service = OrderService(self.email_service, self.invoice_service)
self.order = {"id": 1001, "amount": 299.0}
@patch.object(OrderService, "_save_to_db")
@patch.object(EmailService, "_send_via_smtp")
@patch.object(InvoiceService, "_create_pdf")
def test_create_order_delegates_to_services(
self, mock_pdf, mock_smtp, mock_db
):
"""重构后 create_order 依次触发邮件发送与发票生成，行为与重构前等价。"""
self.service.create_order(self.order)
mock_db.assert_called_once_with(self.order)
mock_smtp.assert_called_once()
mock_pdf.assert_called_once()
if name == "main":
unittest.main()

5.5 完整重构实战：订单模块改造

前面四个场景分别演示了单一类型的重构手法。下面用一个贯穿「评估→基线→拆分→重构→验证」全流程的 Java 订单模块案例，把整套方法串起来，展示从遗留代码到重构完成的完整 diff 与测试结果。

第一步：系统评估

先用 Claude Code 梳理订单模块的技术栈与职责边界，识别出三类问题：重复的金额计算逻辑、冗长的 if-else 折扣分支、以及一个承担了订单创建、邮件通知、发票生成三类职责的巨型类 OrderService。风险分级如下：金额计算为低风险（纯函数、无副作用），折扣逻辑为中风险（涉及业务规则），OrderService 拆分为高风险（对外接口多、调用方广）。

第二步：建立代码基线

重构前先让 Claude Code 为订单模块补齐单元测试与行为快照，确保「改前可测、改后可对比」。基线测试全部通过，作为后续回归对照的基准。

// 基线测试：重构前先跑通，作为回归对照
public class OrderBaselineTest {
    @Test
    void calculateTotal_shouldSumPriceTimesQuantity() {
        OrderService service = new OrderService();
        List<Item> items = List.of(
            new Item("A", 10.0, 2),
            new Item("B", 5.0, 3)
        );
        assertEquals(35.0, service.calculateTotal(items), 0.001);
    }
@Test
void getDiscount_shouldReturnRateByType() {
    OrderService service = new OrderService();
    assertEquals(0.0, service.getDiscount("normal"), 0.001);
    assertEquals(0.1, service.getDiscount("vip"), 0.001);
    assertEquals(0.2, service.getDiscount("super_vip"), 0.001);
}
}

第三步：任务拆分

按依赖顺序把重构拆成三个可独立验证的小任务，每个任务都有明确的验收标准与回滚点：

• 任务一：提取重复的金额计算方法，验收标准为原有测试全部通过。
• 任务二：把 if-else 折扣分支改为映射表，验收标准为折扣相关测试全部通过。
• 任务三：拆分 OrderService 巨型类，验收标准为对外接口兼容、全量测试通过。

第四步：小步重构与完整 diff

重构前（遗留代码）：

public class OrderService {
    public double calculateTotalA(List<Item> items) {
        double total = 0;
        for (Item item : items) {
            total += item.getPrice() * item.getQuantity();
        }
        return total;
    }
public double calculateTotalB(List&lt;Item&gt; items) {
    double total = 0;
    for (Item item : items) {
        total += item.getPrice() * item.getQuantity();
    }
    return total;
}
public double getDiscount(String type) {
if ("normal".equals(type)) {
return 0;
} else if ("vip".equals(type)) {
return 0.1;
} else if ("super_vip".equals(type)) {
return 0.2;
} else {
return 0;
}
}
public void createOrder(Order order) { /* 订单创建逻辑 / }
public void sendEmail(Order order) { / 邮件发送逻辑 / }
public void generateInvoice(Order order) { / 发票生成逻辑 */ }
}

重构后（完整 diff）：

- public double calculateTotalA(List<Item> items) { ... }
- public double calculateTotalB(List<Item> items) { ... }
+ public double calculateTotal(List<Item> items) {
+     double total = 0;
+     for (Item item : items) {
+         total += item.getPrice() * item.getQuantity();
+     }
+     return total;
+ }
public double getDiscount(String type) {
if ("normal".equals(type)) { return 0; }
else if ("vip".equals(type)) { return 0.1; }
else if ("super_vip".equals(type)) { return 0.2; }
else { return 0; }
}
private static final Map<String, Double> DISCOUNT_MAP = Map.of(
"normal", 0.0,
"vip", 0.1,
"super_vip", 0.2
);
public double getDiscount(String type) {
return DISCOUNT_MAP.getOrDefault(type, 0.0);
}
public class OrderService {
public void createOrder(Order order) { ... }
public void sendEmail(Order order) { ... }
public void generateInvoice(Order order) { ... }
}
public class OrderService {
private final EmailService emailService;
private final InvoiceService invoiceService;
public OrderService(EmailService emailService, InvoiceService invoiceService) {
    this.emailService = emailService;
    this.invoiceService = invoiceService;
}
public void createOrder(Order order) {
    // 订单创建逻辑
    emailService.sendEmail(order);
    invoiceService.generateInvoice(order);
}
}
public class EmailService {
public void sendEmail(Order order) { /* 邮件发送逻辑 */ }
}
public class InvoiceService {
public void generateInvoice(Order order) { /* 发票生成逻辑 */ }
}

第五步：持续验证与测试结果

重构完成后运行全量测试，结果如下：

Tests run: 12, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

其中新增的验证用例覆盖了三个关键点：金额计算收敛到单一实现后行为一致、折扣映射表对未知类型兜底返回 0、OrderService 拆分后委托调用顺序与重构前等价。所有基线测试与新增测试全部通过，重构完成。

5.5 重构场景对比表

下表汇总了 5.1 至 5.4 四个典型重构场景的关键信息，便于快速对比和选择合适方案。

场景	适用语言	核心提示词要点	重构前后代码行数变化	典型风险
5.1 消除重复代码	Java、Python、JavaScript、C#	扫描重复片段，提取公共方法或基类，同步更新所有调用点	行数减少（重复逻辑合并为单一实现）	提取时改变行为、遗漏调用点导致回归
5.2 升级过时依赖	Python、JavaScript、Java、Go	列出过时依赖及目标版本，修改受影响 API 调用，运行测试验证兼容性	行数基本持平（API 调用替换为主）	新版本 API 行为差异、隐式兼容性问题
5.3 重构复杂条件逻辑	Java、C#、TypeScript、Python	将 if-else/switch 改造为策略模式或状态机，对比行为并补充单元测试	行数增加（引入模式类与映射结构）	分支覆盖不全、策略对象生命周期管理
5.4 拆分巨型类与方法	Java、C#、Python、Ruby	识别职责过多的类，拆分独立模块，迁移方法/字段/测试并保持接口兼容	行数增加（新增多个类文件）	接口破坏、依赖注入关系错乱

下面以 5.1 消除重复代码为例，从可维护性、可读性、测试覆盖、风险等级四个维度对比重构前后的差异。

对比维度	重构前	重构后	具体说明
可维护性	低	高	重构前 calculateTotalA 与 calculateTotalB 两份重复实现各自维护，修改金额计算规则时需同步改动多处，极易遗漏；重构后统一收敛到 calculateTotal 单一实现，后续调整只需修改一处，维护成本显著下降。
可读性	低	高	重构前重复代码散落多处，读者需要反复对照才能确认逻辑一致；重构后公共方法命名清晰、职责单一，并补充了累加器初始化、遍历累加等关键步骤的注释，代码意图一目了然。
测试覆盖	低	高	重构前重复实现导致测试用例分散且难以覆盖全部分支，容易出现某份实现漏测；重构后只需针对 calculateTotal 编写一套完整测试，即可覆盖所有调用场景，测试成本更低、覆盖更充分。
风险等级	中	低	重构前重复代码本身虽能运行，但一旦业务规则变化，多处修改极易引入不一致，回归风险较高；重构后通过提取公共方法并同步更新所有调用点，配合测试兜底，行为一致性得到保障，风险显著降低。

6. 重构过程中的质量保障

AI 辅助重构最大的风险是"改对了但改坏了"。质量保障要贯穿始终。

• 持续运行测试：每次改动后立即执行全量或相关测试，发现问题及时回退。
• 代码审查：对 Claude Code 生成的改动逐项 review，重点检查边界条件和异常处理。
• 小步提交：避免一次性提交大量改动，便于定位回归来源。
• 保留人工决策点：涉及业务语义的改动，必须由熟悉业务的人确认后再合入。

7. 常见陷阱与应对策略

实践中最容易踩的坑，提前规避能省下大量返工时间。

• 过度依赖 AI 输出：Claude Code 的建议需要结合业务上下文判断，不能盲信。
• 忽略隐式依赖：遗留代码常有隐藏的全局状态或外部副作用，重构前要重点排查。
• 测试覆盖不足：没有测试兜底的重构等于裸奔，先补测试再动手。
• 一次改动过大：任务切得越小，越容易定位问题和回滚。

7.1 重构失败后的排查清单

即使做了充分准备，重构仍可能引入回归。一旦发现问题，按以下清单逐项排查，能快速定位来源并安全回退。

1. 定位回归来源：先运行全量测试，找出第一个失败的用例，再结合 git diff 查看该用例对应的改动范围，缩小到具体提交或代码块。
2. 利用 git 回滚到上一个稳定提交：若无法快速定位，直接执行 git checkout 或 git revert 回到最近一次测试全绿、行为正常的提交，先恢复可用状态再继续排查。下面给出完整的命令操作示例。

git 回滚操作示例：

第一步：查看提交历史，定位稳定提交

git log --oneline -10

简要说明：以简洁的单行格式列出最近 10 条提交记录，每条包含提交哈希缩写和提交说明，便于快速浏览历史并找到测试全绿、行为正常的那个稳定提交。

适用场景：重构过程中发现回归，需要先确认当前分支上有哪些提交、各自改了什么，从而判断该回退到哪一次提交。

第二步：用 git checkout 回退到指定提交

git checkout <commit-hash>

简要说明：将工作区切换到指定提交对应的代码状态，HEAD 会指向该提交，但不会删除之后的提交记录，适合临时查看或验证某个历史版本的行为。

适用场景：想快速验证某个稳定提交下系统是否正常，或临时回到旧版本排查问题；注意此时处于分离头指针状态，如需继续修改应先创建新分支。

第三步：用 git revert 撤销某次提交

git revert <commit-hash>

简要说明：生成一次新的提交，反向应用指定提交的改动，从而撤销该次提交引入的变更，同时完整保留提交历史，适合在共享分支上安全回滚。

适用场景：确认某次重构提交就是回归根源，且该提交已经推送到远程或与他人协作时，用 revert 比直接删除历史更安全，不会破坏其他人的工作。

补充：回退后验证并继续排查

git checkout <stable-branch>
git log --oneline -5

简要说明：回到稳定分支并再次确认当前提交状态，确保工作区已恢复可用，随后即可按清单第 3 至第 5 条继续对比行为快照、检查隐式依赖并小步重试。

适用场景：完成回退后需要确认恢复结果，并以此为新的起点重新执行更小粒度的重构任务。

1. 对比行为快照：把当前模块的输入输出样例与重构前记录的行为快照逐条比对，找出输出不一致的边界条件，往往就是回归的根源。
2. 检查隐式依赖与全局状态：重点排查重构代码是否触碰了隐藏的全局变量、外部副作用或调用顺序敏感的共享资源，这类问题在单测中不易暴露。
3. 回退后小步重试：确认问题后，把原任务拆成更小的步骤重新执行，每步都跑测试并提交，避免再次一次性引入过多改动。

8. 总结与行动清单

用 Claude Code 重构遗留系统，本质是"AI 提效 + 人工把关"的协作模式。核心步骤可以浓缩为：评估现状、建立基线、拆分任务、小步重构、持续验证。建议从低风险模块开始试点，积累经验后再向核心业务推进。

最后附上一份可直接照做的行动清单：

1. 用 Claude Code 生成模块依赖概览与风险分级。
2. 为关键模块补齐单元测试与接口文档。
3. 按依赖顺序拆分重构任务，每个任务设定验收标准。
4. 逐任务执行重构，每次改动后运行测试并提交。
5. 定期 review AI 生成的改动，保留业务决策的人工确认环节。

9. 参考资料

以下资源覆盖 Claude Code 使用、遗留系统重构与 AI 辅助编程三个方向，可作为进一步深入学习的入口。

• Claude Code 官方文档：Overview - Claude Code Docs —— 权威的入门与进阶指南，涵盖安装配置、核心命令、工作流与最佳实践，是上手 Claude Code 的第一手资料。
• Anthropic 官方博客：Newsroom \ Anthropic —— 持续发布 Claude 系列模型能力更新、工程实践与案例研究，帮助理解 AI 编程助手的演进方向与适用边界。
• 《重构：改善既有代码的设计（第 2 版）》：Martin Fowler 的经典著作，系统讲解重构原则、坏味道识别与安全重构手法，是遗留系统改造的方法论基石，与 AI 辅助重构互为补充。
• 《Working Effectively with Legacy Code》（Michael Feathers）：聚焦遗留代码的测试策略与渐进式改造技巧，尤其适合在引入 AI 工具前先建立可测试、可回退的工程基线。
• Martin Fowler 的 Refactoring 网站：Refactoring —— 提供重构目录与代码示例的在线参考，便于在具体场景中快速检索对应的重构手法。
• AI 辅助编程实践社区与工程博客：如 GitHub 官方博客、InfoQ 等平台持续更新的 AI 编程实践文章，可了解真实团队在代码审查、测试补全、批量重构中的落地经验与踩坑记录。