用claude code逐步偿还技术债务的具体操作步骤

去年秋天，我接手了一个 Python 电商项目。四年代码、零测试、二十三个模块循环依赖、七位离职工程师留下的注释只有一句“这段代码看不懂，但别删，删了 GMV 会掉”。

我花了两周用 Claude Code 做了一轮系统化债务清理，上线后 P0 故障从每周平均 1.7 次降到零。不是因为它会魔法，而是因为我踩出了一条可复用的操作路径。

这篇文章就是那条路径的完整记录。不泛讲工具命令，只讲如何用 Claude Code 把技术债务一步步从“恐怖老代码”变成“可维护资产”。

一、核心结论：技术债不能用 AI “一把梭”，但可以用 AI “一口口吃”

我从这次重构中学到的东西可以压缩成四句话：

第一，Claude Code 不是重构工具，是重构执行器。 你不能丢给它一整个项目说“帮我重构一下”，它不会拒绝，但大概率会改出逻辑漂移。真正的价值发生在一个很小的粒度上：你给出一个精确的、边界清晰的子任务，它用秒级速度完成。

第二，债务清理的关键步骤不是“改代码”，而是“诊断”和“审验”。 我踩过的最大坑：让 AI 直接改代码，上线后发现一个下单接口的金额计算精度从 Decimal 变成了 float。后来我只让它做两件事：给出现有代码的问题诊断，以及在我指定边界内生成修改建议。所有改动都经过 diff 审查后才合入。

第三，如果一项债务清理动作没有可验证的验收标准，就别开始。 在我的流程里，任何子任务都必须先定义“怎么判断改对了”。没有测试先补测试，补不了测试就定义行为验证 checklist。

第四，人的精力花在“判断”上，AI 的算力花在“执行”上。 这个分工做对了，效率高十倍。做反了，你会花更多时间在修 AI 的 bug 上。

我用这个思路指导了接下来的四步流程：诊断→方案→执行→审查。

二、真实场景：一个没人敢碰的订单服务，藏着多少类债务

在讲操作步骤之前，我先描述一下那个电商项目的典型债务形态，因为不同形态的债务需要不同的处理策略。你对照自己的项目，就能判断哪一步对你们最有用。

订单模块的 OrderService.py，3200 行单文件，核心方法 confirm_order() 长达 480 行。里面发生了这些事情：库存校验、价格计算、优惠券匹配、运费模板、积分抵扣、订单状态机，全写在一起。没有任何单元测试，参数全用 **kwargs 传入，内部变量命名风格混杂了 PEP8 和下划线匈牙利。

这是我当时列出的债务清单：

这和很多老项目的分布规律一致：测试债务和结构债务是金字塔底。 不解决这两层，直接动逻辑就是赌博。所以后面的操作步骤也会按这个优先级展开。

三、常见误区：我在犯了三个错误之后才找到正确姿势

在进入具体操作步骤之前，我想把这三个误区讲透，因为每条都浪费过我至少一整天。

误区一：“让 Claude Code 理解全部项目上下文，才能做出正确重构。”

我最初的做法是把整个项目目录用 /init 加载，然后对话：“请分析这个项目的技术债务并给出重构建议”。Claude Code 确实给了分析，看上去头头是道，但细看会发现它混淆了 OrderService 和 CartService 的职责边界，因为这两个类的调用链很长，AI 在没有明确提示的情况下很难判断业务语义的归属。

教训：上下文不是越大越好。债务清理的最优上下文范围是“一个模块 + 它的直接依赖接口”，别加载整个项目。 这个发现直接决定了后面操作步骤里的“加载策略”。

误区二：“重构就是改代码，直接用 AI 生成新版本替换旧版本。”

我第一次尝试让 Claude Code 直接重写 confirm_order 方法时，它把里面一个不显眼的 round() 调用改成了 Python 内置的四舍五入。原代码用的是 decimal.ROUND_HALF_UP，这个差异导致两笔测试订单的金额少了 0.01 元，在财务对账时才会发现。要不是我们老板恰好是大股东，这种 bug 上线后就是事故。

教训：AI 重构代码，最容易引入的不是语法错误，而是隐式行为的改变。 这些改变需要 diff 审查而不是运行测试来发现。这个经验直接催生了第四步的“差异审查”子流程。

误区三：“旧代码太烂了，没有参考价值，直接让 AI 按现代最佳实践重写。”

有一个运费模板计算方法我本想彻底重写。Claude Code 生成的新版本干净漂亮，逻辑清晰。但上线前我发现它丢失了一个边缘逻辑：当收货地址属于“偏远地区”时，原系统的运费系数比普通地区多一个判断分支，而这个分支的参数来自一个运营后台配置表，不是代码常量。原代码写得很丑陋，但那层丑陋里藏着一个业务规则。

教训：重构的第一原则是“不改变可观测行为”。 AI 帮你变干净的工作，你可以放手让它做。但 AI 帮你“变正确”的工作，你必须自己检查。这个洞察指导了后面“执行”这一步里的安全边界设定。

四、操作步骤第一步：诊断，让 Claude Code 当你的“债务体检医生”

好了，讲完场景和误区，正式进入四步流程。第一步是诊断。

债务诊断在整个流程里占的时间最长，也最值得花时间。因为诊断的精度决定了后面每一步的返工率。 如果这一步模糊，后面的执行就会频繁推翻重来。

4.1 加载项目：不是 /init 就完了

Claude Code 的 /init 命令会扫描项目结构并生成上下文描述。很多人都用，但我发现直接用默认初始化结果去做债务分析会产生两个问题：一是上下文太大导致分析泛化，二是它不了解你的业务重点。

我的做法是分模块加载，每次只加载一个债务清理单元。具体步骤：

1. cd 到你的项目根目录，运行 /init 让 Claude Code 获得项目骨架认知。
2. 明确告诉它本轮的焦点范围。你可以这样说：“现在我只关注 order_service.py 这个文件，以及它直接 import 的模块。请先不要分析项目的其他部分。”
3. 让它生成这个模块的接口清单和调用关系图。

我当时的对话是这样的（还原大意）：

我：/init

Claude Code：（完成初始化，列出了项目结构）

我：“关注 order_service.py，列出它公开给外部的所有方法签名，以及每个方法被哪些模块调用。用表格。”

它输出了一个调用矩阵，我发现 confirm_order() 方法同时被 api/v2/orders.py、admin/order_manage.py 和 tasks/daily_reports.py 三个地方调用。这个信息直接决定了后面的重构边界：我不敢大改它的签名，只能优化内部实现。

4.2 定位债务重灾区：别让它泛泛地“分析问题”

加载完模块后，很多工程师会问：“这个模块有什么问题？”，这个问题太宽，AI 的回答也会很宽，比如“代码太长”“缺少注释”“建议拆分”这种正确但没用的建议。

我的提问方式改了之后，诊断精度大幅提升。用这个句式：

“请只关注以下四个维度，逐项分析这个模块的具体问题：（1）循环依赖；（2）没有单元测试的关键逻辑路径；（3）可变全局状态；（4）异常处理缺失的代码段。每一项都要给出具体的行号和这段代码做什么。”

Claude Code 返回了一份清单，其中关于“可变全局状态”的一项直接找到了 confirm_order 里一个隐式依赖：它读取了一个模块级字典变量 PRICE_RULES，这个变量在另一个文件里被定时任务修改。没错，一个 480 行的方法里用了一个被别的线程改的全局变量，这是我之前根本不知道的。

4.3 生成债务清单并做优先级排序

诊断完成后，让 Claude Code 生成一个结构化的债务清单。关键点：不仅要列出问题，还要让 AI 估算每项修复的“风险-收益比”。

你可以这样说：“根据刚才的分析，按‘修复收益高、引入风险低’的原则，给出建议的处理优先级。每一项包含：问题描述、关联代码行、建议策略、预估的测试工作量。”

它会输出一个排序表。我当时的表里，排第一的不是代码拆分，而是“为 confirm_order() 的价格计算路径补写单元测试”，因为只有先建立安全网，后续拆分才有底气。这个排序和我的直觉不完全一致（我原想先拆分），但事后证明 AI 的建议是对的。

五、操作步骤第二步：方案，把大债务拆成可验证的小手术包

诊断清单有了，接下来不是直接动手改代码。很多人在这跳过了一步，直接让 AI 开改，结果就是频繁回滚。

5.1 任务原子化：从“重构订单模块”变成“只改一个函数”

我这里的核心操作原则是：每个子任务必须在一次对话内完成，且产生的 diff 不超过 200 行。 如果预估超过，就继续拆。

怎么拆？用这个对话模式：

“现在只关注债务清单上的第 2 项：confirm_order() 的价格计算逻辑混在流程控制中。请为我设计一个拆分方案，将价格计算抽取为一个纯函数。要求：不改变任何外部接口，不改变计算结果精度。先不要生成代码，只给出方案。”

它给出了一个方案：抽取 _calculate_order_price() 函数，入参为商品列表、优惠券、积分抵扣额、运费模板版本号，返回 Decimal 类型的最终金额。我审核了方案，确认可行，然后才让它生成代码。

5.2 确定重构顺序：先孤立，再中心

技术债务清理最怕的是改动一个被广泛调用的模块。我让 Claude Code 帮我理清依赖拓扑，然后按“被依赖最少、依赖别人最多”的模块先动手。

这个顺序逻辑是：先重构叶子节点的模块（比如工具类、配置解析类），这些模块改完影响面小，容易验证。等积累了一定数量的重构经验后，再动被大量调用的中心模块。

Claude Code 帮我分析的结果：订单模块的依赖中最适合最先动的是 order_utils.py，这个模块被三个服务调用，但它自己不依赖项目内的业务模块，只依赖标准库。我先用它练手，建立了对 AI 重构速度和质量的第一手体感，后面动 OrderService 时才没有手忙脚乱。

5.3 为每个子任务定义验收标准

这一步是很多人跳过的，但它是我流程里最关键的环节。每个子任务开始前，我必须和 Claude Code 明确：

• 这个改动“做完”的标志是什么？
• 怎么验证改对了？

比如补单元测试这个子任务，验收标准是：“为 confirm_order 的 5 条价格计算路径生成测试，覆盖正常全价、优惠券折扣、积分抵扣、运费叠加、边界零元订单五种场景。每条测试执行 pytest 均通过。”

把验收标准前置定义，有一个意外的好处：它把 Claude Code 从一个“代码生成器”变成了“可验证目标达成器”。AI 在知道验收标准后，代码质量明显提升，因为它会主动在生成代码后提醒你运行测试命令，并且会在测试不通过时基于错误信息自己 debug。有一次它生成了测试，跑失败后自己发现是 mock 对象没模拟配置表返回，主动修正了第二版。

六、操作步骤第三步：执行，让 AI 做 AI 的事，让人做人的事

进入执行环节。这一步的核心是划分职责。

6.1 代码生成：你的人设是指挥官，不是司机

执行阶段我给自己定的角色：决定做什么、审查做得对不对。Claude Code 的角色是：做出来。

具体协作方式：

• 我发出精确指令，包含：要改哪个文件、哪个函数、改成什么、不能改什么。
• Claude Code 生成 diff。
• 我逐段审查 diff。
• 通过后提交。

举一个我实际用过的指令（还原大意）：

“打开 order_service.py，定位 confirm_order 方法的第 227 至 315 行。这段代码处理运费计算逻辑。请将这段逻辑抽取为一个独立方法 _calculate_shipping_fee，参数为 address: dict、items_weight: Decimal、shipping_template_id: int，返回值为 Decimal 类型的运费金额。要求：不改动任何计算逻辑，不改动变量名，纯粹做抽取。生成代码后请用 diff 格式展示改动。”

这条指令的价值在于每一个词都在压缩 AI 的自由发挥空间，从而降低逻辑漂移的风险。

6.2 补测试：AI 最适合干的脏活

技术债务里最枯燥、最耗人力的就是给历史代码补测试。而这恰好是 Claude Code 最擅长的事情。

我的操作经验是：不要让 AI 自己决定测什么，你先告诉它测哪些场景，它负责生成测试代码和 mock 数据。

操作步骤如下：

1. 人与 AI 一起审查目标函数，列出所有 if-else 分支。
2. 人圈定哪些分支是核心业务路径，必须覆盖。
3. AI 为每条路径生成参数化的 pytest 用例。
4. 人审查测试用例的业务逻辑是否正确（不是语法，是测试场景是否覆盖了真实业务）。
5. 运行测试，查看覆盖率报告。

我那个订单模块补了 34 个测试用例，覆盖了 17 条核心路径。整个过程中我写了大约 200 字的指令和审查意见，Claude Code 生成了 1400 行测试代码。如果纯人工写，这大概要花我两个工作日。实际花了两个半小时。

6.3 重构执行：守住“行为不变”红线

当安全网建好之后，才开始动真正的结构重构。我做了三件最重要的事：

1. 保持原接口签名不变。 所有对外暴露的方法，入参和返回值都不动。只优化内部实现。
2. 先抽取，后优化。 第一步把大方法里的代码块原封不动抽成小方法。第二步再对小方法内部做重构（加类型注解、简化逻辑、消除重复）。
3. 每次改动跑全量测试。 这个不用多解释，测试就是安全带。没有测试之前我不让 AI 做任何逻辑改动。

七、操作步骤第四步：审查，这是整个流程里最不 AI 的环节

很多人以为 AI 辅助重构，审查可以省力。完全相反。AI 重构做得越快，审查工作就越重要。 因为 AI 的生产速度远超人类审查速度，如果不专门设计审查流程，代码就变成了“快速生成的屎山”。

7.1 diff 审查：重点关注“逻辑等价性”而非“代码风格”

审查 AI 生成的代码，你不需要挑风格问题（它通常写得比人规矩）。你需要盯的是：语义是否等价。

我的审查习惯是这样的，打开 Claude Code 生成的 diff，逐段问自己三个问题：

• 原代码的这个分支，在新代码里还存在吗？
• 特定输入下，新旧代码的输出是否完全一致？
• 有没有哪个异常处理路径消失了？

有一次我发现 Claude Code 在抽取运费计算方法时，“优化”掉了一个 except KeyError 分支。原代码里如果运费模板查不到，走默认运费为 0 元。AI 认为“这个设计不好，应该抛异常”。我让它恢复了原逻辑，因为 0 元运费是运营团队设置的一个兼容方案，改了会引发业务投诉。

审查的第一原则：原代码的每一个 if-else 分支、每一个 exception 处理，都是“故意”的，除非你有证据证明它是 bug。AI 没有这个认知，你得有这个认知。

7.2 行为验证：不仅仅跑测试，还要做对比回归

测试通过不代表没问题。因为老项目的测试覆盖率往往不完美，即使补了测试，也只能覆盖核心路径。还有一些边缘行为是测试没覆盖到的。

我做了一个额外的验证动作：让 Claude Code 生成一份“行为对比报告”。

操作方法：

“请比对原 confirm_order 方法和重构后的版本，列出所有条件分支的一一对应关系。对于任何一个在原方法中存在、但在新方法中找不到对应实现的分支，请标红。对于新方法中新增的分支，请解释其来源。”

它生成了一份对照表，帮我发现了两个遗漏：一个是对历史订单数据中“无优惠券字段”的兼容处理，另一个是积分抵扣时负数的防御判断。这两个都是崩溃型 bug，但极少触发，测试覆盖不到。

7.3 引入“冷静期”：至少隔一晚再合入

这是我从 Google 的工程实践里学来的方法，移植到 AI 辅助重构流程里意外好用。改完的代码不要当天合入。放一晚，第二天用新的眼光重新看一遍 diff。

我至少三次在冷静期后发现了问题：一次是变量命名虽然规范但容易误解（total_price 和 final_price 的区别不明显），一次是方法虽然抽取了出来但调用时机和原代码差了 3 行，还有一次是发现了测试用例里有个 mock 条件写反了。这些问题如果当天合入，上线后都是定时炸弹。

八、实操案例全回放：一个 480 行函数的完整手术记录

讲完四步流程，这一节我用一张完整的执行时间线给你展示全过程。这是 confirm_order 方法从诊断到合入的 9 小时：

总计：人的时间为 5.5 小时，AI 节省了约 10 小时以上的纯体力劳动时间。 但更重要的是，整个过程中没有引入回归 bug，这比效率数字更关键。

九、常见风险与取舍：不是所有债务都值得现在还

做完整整一轮清理后，我建立了一套判断标准，用来决定“什么债现在还，什么债先放放”。

9.1 立即还的债：高频修改区的代码

如果一个模块每周都被改，那它身上的结构债务就是“高利贷”。我在诊断时发现 order_utils.py 虽然没有被报告太多问题，但它被频繁修改，每次微调都可能碰坏别的东西。这种债的偿还优先级提到了最高。

判断标准：通过 git log 查看过去三个月的提交频率。如果月度改动超过 5 次，立即动手。

9.2 谨慎还的债：极度复杂的业务逻辑

confirm_order 里有一个优惠券叠加计算逻辑，涉及满减、折扣、新人礼包、平台补贴四种优惠的互斥和叠加规则。这段代码虽然丑陋，但它的每一个 if-else 都对应一个业务决策记录（有些可能已经没人记得为什么了）。

对于这种“高业务熵”的代码，我的策略是不主动重构，先补测试锁死行为，然后在有业务专家在场的情况下，一次改一种规则。

9.3 暂时不还的债：即将下线的模块

诊断时发现支付回调处理模块代码质量也非常差，但一看 roadmap，整个支付体系下季度要迁移到第三方。这时候投入精力去重构就是沉没成本。对于这类模块，我的做法是：加上 # DEPRECATED 标签和迁移时间节点，保持现状。

9.4 代价评估：API 调用成本不是问题，人的注意力才是

很多人担心用 Claude Code 清理债务的 API 调用费用。我算了一笔账：

那一轮完整的订单模块重构，Claude Code 的 API 调用总费用大约是 18 美元。而它帮我节省的开发时间按我的时薪折算，大约是 700 美元以上。所以真正的成本不是 API 费用，而是审查 AI 代码所消耗的注意力。 这也是为什么我反复强调审查流程要标准化，你是用一套固定的审查清单来降低每次审查的认知负担，而不是每一次都从头想“这段代码会不会有问题”。

十、建立持续偿债习惯：别让清理变成一次性运动

做完一轮清理就停下来，一年后又回到原样。我给自己和团队定了一套低成本持续动作：

每周一次的“10 分钟体检”：

用 Claude Code 对本周改动的文件做一次快速诊断，命令很简单：“分析本周改动的文件，列出新引入的代码质量问题（圈复杂度增长、无测试覆盖的新逻辑、硬编码配置）。只给清单，不自动改代码。” 这大概花 10 分钟，但能阻止新债务的累积。

代码评审时引入 AI 审查员：

在 PR review 阶段，把 diff 丢给 Claude Code 让它从三个角度分析：逻辑等价性、异常处理完整性、边缘 case 覆盖。人工审查关注架构和业务正确性，AI 审查关注细节和模式匹配。两条线互补。

新人入职第一周就用这套流程：

我把这套四步流程写成了文档，新同事入职后第二天的任务就是“用 Claude Code 为一个历史模块补 5 个测试用例”。目的不是让他们干活，而是让他们在安全的边界内接触老代码，同时建立“先有安全网再动手”的肌肉记忆。

十一、总结：技术债不会消失，但你可以有一套长期低成本消化它的系统

技术债务不是工程问题，是经济问题。你不还它，它就持续收利息，每次改代码多花的时间、每次线上故障的排查成本、每个新人对着旧代码发呆的半个小时。

Claude Code 改变的不是“债务存在”这件事，而是还债的成本结构。以前还一笔债务需要资深工程师一整天的时间，现在只需要一个小时加 2 美元。当还债变成一件低成本的事情，它就从一个“要不要做”的战略决策，变成了一个“顺手做了”的日常习惯。

如果你现在就想开始，我的建议是：不要打开 Clode Code 就直接让它帮你改代码。先花一小时做一次诊断，只诊断不改。拿到那张债务清单，排好优先级，然后一次只解决一项。每一项都走完诊断→方案→执行→审查的完整闭环。

当你完成第一轮清理，看着圈复杂度从 48 掉到 12、测试覆盖率从 0 涨到 87% 的时候，你会理解为什么这套流程值得固化下来。

它不是银弹，但它是一把很稳的手术刀。剩下的工作，是你决定什么时候拿起它。