实战 SOP
实战 SOP

AI 代码重构实战 SOP:让 Claude Code/Cursor 安全改老代码的 5 步法

用 Claude Code/Cursor 重构老代码,不是一句「帮我重构」就行。这套 5 步法把工程纪律写死:先建测试安全网、界定重构边界、给 AI 精准上下文、分步执行加人工 diff 审查、最后回归验证。附 4 个可直接复制的 Prompt 模板和 5 条真实踩坑记录。

发布于 2026年7月29日10 分钟阅读
<!-- ai-code-refactoring-sop | sop | AI 代码重构实战 SOP -->

老代码这玩意儿,谁碰谁知道。

你接手一个三年没动过的服务,里头一个 800 行的 orderService.js,函数套函数,注释写着「TODO: 后面再优化」,时间戳是 2022 年。你想加个新支付渠道,刚改两行,测试一片红,CI 挂了,前端同事在群里 @ 你。你 revert 回去,长出一口气,决定再也不碰这坨东西了。

现在你手上有 Claude Code 和 Cursor,想着终于有救了。打开 Claude Code 输入一句「帮我重构 orderService.js」,它哐哐哐吐出 600 行新代码,函数拆好了,命名也讲究,看着像那么回事。你 git diff 一看,改动 412 行,涉及 7 个文件,一个看起来人畜无害的变量改名,把另一个文件里的引用也给改了——那地方本不该动。你不敢 merge,又 revert 了。

工具升级了,老代码还是老代码。问题不在 AI 笨,在于你把一个需要工程纪律的活儿,丢给了一个没纪律的搭档。这篇 SOP,就是把这套纪律写成 5 步,让 AI 帮你重构老代码,而不把你和团队一起埋了。


一、第一步:先把安全网架起来,再谈重构

Michael Feathers 在《修改代码的艺术》里那句话现在比十年前更适用:「重构前,先有测试」。AI 时代这条被加倍放大——AI 改得快,没测试网拦着,它改得越快你死得越快。

跑通现有测试是底线。接手老服务第一件事不是开 AI,是 npm test / pytest / go test ./... 一把。绿了才有下一步。红了别急着重构,先把红的修绿——在坏掉的地基上让 AI 重构,等于让它在流沙上盖楼。

没测试怎么办?补特征测试(characterization test)。老代码大概率没单测,全补不现实。先给它最关键的那几个函数补「快照测试」或「金标准用例」——不需要漂亮的测试名,只要能锁住「输入 X,输出 Y」这件事。Claude Code 这种能读项目上下文的工具很适合干这活,给它一个明确 prompt:

text
# 任务:为 orderService.js 的 calcFinalPrice 函数补特征测试,不要修改业务代码
# 背景:这个函数三年没人动,没人敢重构,因为没测试。
# 步骤:
1. 读 web/src/services/orderService.js 里 calcFinalPrice 的实现
2. 找出它在项目里所有调用点(grep calcFinalPrice)
3. 按调用点收集真实入参样本,至少 5 个覆盖正常/边界/异常路径
4. 在 web/tests/orderService.spec.js 写快照测试,断言当前输出
   (即使是错的也别动,先锁住行为)
5. 跑 npm test -- orderService,必须全绿
# 约束:
- 不修改 orderService.js 任何代码
- 测试文件用和项目现有测试一致的 style(读 web/tests/ 下任一文件参考)

这套 prompt 的核心是「锁住当前行为」——哪怕是 bug 行为也先锁住。重构的唯一目标是「外部行为等价」,你得先知道原来输出是什么,才能验证没改坏。Claude Code 会自己去读文件、grep 调用点、写测试文件、跑测试、读报错、改测试,全程不用你切窗口。这正是它项目级上下文能力的用武之地。

没 CI 的项目,先在本地建一条手动安全网:npm test && npm run lint && npm run typecheck 三连,重构每一步后都跑一遍。把它写进 package.json 的 scripts.safety 里,一行命令出问题立刻知道。


二、第二步:界定重构边界——一次只改一类

AI 重构翻车最常见的原因不是 AI 笨,是你一次让它干太多。一句话「把这个文件重构一下」包含的事:拆函数、提常量、改命名、挪文件位置、换数据结构。每一样单独做都安全,叠在一起,diff 就变成一团乱麻,谁也不敢 review。

一次只改一类,这是纪律,不是建议。把重构切成互不重叠的小步:

  • 重命名:只改名字,行为不动
  • 提取函数:只把代码块抽成函数,逻辑不动
  • 替换魔法数:只把字面量提为常量
  • 挪文件:只动位置,不动内容
  • 改数据结构:单独一步,且必须有测试兜底

每一步独立成一个 commit,commit message 写清「这次只做了什么」。一旦某步测试红了,git reset --hard HEAD~1 退回,重新让 AI 来过。小步快跑在 AI 时代不是口号,是唯一能让你 5 分钟内定位回滚点的工程手段。

Claude Code 的 plan 模式天然契合这个节奏。在 prompt 里加「先出方案不要执行」,让它先吐出一份重构计划,你看完再决定哪步让它做、哪步先不做。这比让它直接动手安全得多——计划阶段 diff 是零,零成本的 review 时机。

写死边界:把「不能动的东西」明确告诉 AI,比告诉它「要做什么」更重要。重构边界 prompt 模板:

text
# 重构任务:拆分 orderService.js 的 calcFinalPrice 函数
# 边界(必须遵守):
- 仅限文件:web/src/services/orderService.js
- 仅限动作:提取纯计算逻辑到 helpers/price.ts,命名保持一致
- 不动的文件:paymentService.js, couponService.js
  (这两处调用 calcFinalPrice,签名别改)
- 不动的行为:所有现有输入的输出必须和快照测试一致
- 不引入新依赖
# 验收:
- npm test 全绿
- git diff 只涉及 orderService.js 和新增的 helpers/price.ts

这种 prompt 把 AI 当成一个能读代码、但需要明确指令的实习生。模糊指令下它会自作主张,明确指令下它比谁都稳。


三、第三步:给 AI 精准上下文

AI 重构翻车第二大原因:上下文给少了。AI 不知道项目约束、不知道哪些文件不能动、不知道项目的命名风格,它就按通用最佳实践来——而通用最佳实践在你的项目里可能就是错的。

Claude Code 的项目级上下文靠两样:CLAUDE.md 和 @ 文件引用。

CLAUDE.md 放在项目根目录,是 Claude Code 每次会话自动加载的项目记忆。重构前,先在里面写清楚项目的红线:用什么测试框架、命名风格、哪些目录是 legacy 不能动、哪些是新技术栈。一次写好,后续每次重构都省事。Claude Code 官方文档把 CLAUDE.md 称作「memory file」,就是干这个的。

@ 引用是把具体文件喂给它:@web/src/services/orderService.js @web/tests/orderService.spec.js。光说「读这个文件」不够,明确告诉它「这是待重构的、这是测试」,它就不会把测试数据和业务代码搞混。

Cursor 的多文件编辑走另一套路子:在 Composer 里 @ 多个文件,或者用 Agent 模式让它自己开文件。Cursor 强在多文件协同编辑和 diff review 面板,弱在项目级长期记忆(它的 .cursorrules 文件作用类似 CLAUDE.md,但生态相对薄)。两个工具各有所长,下面这张表是真刀真枪的对比:

维度Claude CodeCursor
项目级记忆CLAUDE.md 自动加载.cursorrules 手动维护
多文件编辑通过 Read/Edit 工具,稳但慢Composer 原生多文件,快
Diff 审查git diff 兜底内置 review panel,体验好
重构计划plan 模式,零 diff 出方案Agent 模式边想边改
适合场景长会话、深上下文、跨目录大改中小范围、视觉化 diff、快速迭代

选哪个不矛盾:边界清楚的中小重构用 Cursor,跨目录、需要先看全图的大重构用 Claude Code 的 plan 模式先出方案。两边都用 git diff 兜底,谁也别盲信。


四、第四步:分步执行 + 人工 diff 审查

到这一步,安全网架好了,边界划清楚了,上下文喂全了,可以动手了。但「动手」不是「放权」。AI 每改一步,你得 review 一步。

单步重构 prompt 模板(直接复制改路径就能用):

text
# 单步重构:提取 calcFinalPrice 中的折扣计算到独立函数
# 上下文:
- 待改文件:@web/src/services/orderService.js
- 测试文件:@web/tests/orderService.spec.js
- 项目规范:@CLAUDE.md
# 这一步只做:
1. 把 calcFinalPrice 里第 120-145 行的折扣计算逻辑
   提取为新函数 applyDiscount(cart, coupon)
2. applyDiscount 放在同文件内,签名 (cart: Cart, coupon: Coupon) => number
3. 不改 calcFinalPrice 对外签名和返回值
4. 不动其他文件
# 执行后必须:
- 跑 npm test -- orderService,把测试输出贴给我
- 把 git diff 贴给我

这条 prompt 的关键是最后两行:让 AI 自己跑测试、自己贴 diff。Claude Code 能跑 shell 命令、能读 git 输出,所以让它做完自己贴结果,比你说「改完了」就行靠谱得多。

diff 审查 prompt(AI 改完你审):

text
# 审查这份 diff,找潜在问题
# 重点查:
1. 改动是否超出我规定的边界(比如动了 paymentService.js)
2. 函数签名是否对外保持不变
3. 是否引入了新的副作用(新 import、新全局变量、新 console.log)
4. 是否有「顺手优化」的痕迹(重命名了变量、调了无关代码)
5. 类型是否兼容(TypeScript 项目必查)
# 输出格式:列出可疑点 + 行号,没问题就回「无问题」
# 这是我让你审查,不是让你再改一遍。发现问题只报告,不要修改。

最后一句很重要。AI 默认倾向于「发现问题就动手修」,结果你 review 的时候它又改了一版,你不知道该审哪个版本。让它只报告、不动手,决定权在你手里。

每一步跑测试,不要攒着。AI 改三步你跑一次测试,第二步改坏了,你不知道是第二步还是第三步的事,得回退两步重来。一步一跑,红了立刻 git stash 或 git reset,定位成本极低。


五、第五步:回归验证 + 清理

5 步法的最后一步最容易被偷工减料,因为前 4 步走完你已经累了,想赶紧 merge。但这恰恰是出事的时候。

全量回归:把整个测试套件跑一遍,不止是你重构的这块。老代码的依赖关系往往超出你以为的范围,orderService 改了一个函数签名,下游 invoiceService 在某个 corner case 里调用它,单测覆盖不到,集成测试才暴露。npm test 全跑、CI 全绿,才能进下一步。

手动验证关键路径:自动化测试覆盖不到的,比如「下单-支付-出票」这条链路,手动点一遍。测试再全,也替代不了人眼跑一遍真实流程。

清理 AI 留下的痕迹。AI 重构完,会留下一堆该清的东西:

  • 调试用的 console.log / print / fmt.Println
  • 注释掉的旧代码(它不敢删,就注释掉)
  • 多余的 import
  • 临时变量名(newVar2、temp_result 这种)
  • 它自作主张加的 JSDoc / docstring,内容可能不准

commit message 写清是「重构」,不是「fix」也不是「feat」。这样后续 git log 一眼能看出哪些是行为变更、哪些是结构变更。出 bug 排查时,跳过重构 commit,效率高一截。

最后留一个「回滚预案」:重构的 PR 单独一个,不要和功能改动混在一个 PR 里。merge 后万一线上出问题,git revert <重构 commit> 一键回退,不影响其他改动。这条纪律比任何 AI 工具都重要。


六、五个真实踩坑记录

下面这 5 个坑,全是真实项目里踩出来的,不是脑补。

坑 1:让 AI 一次改太多,大爆炸 diff 没法 review

某次让 Cursor Agent 模式「把这个 controller 重构干净」,它一口气改了 8 个文件 600 行。看着 PR 评论里一片绿,谁也不敢 approve,最后还是 revert 重来。对策:单次任务控制在「一个文件、一类改动、30 行以内 diff」。超过就拆。

坑 2:不先建测试网,改坏了一周才发现

跳过第一步直接让 Claude Code 重构一个没测试的工具函数,改完看着没问题,merge 了。一周后用户反馈「价格算错了」,回溯发现 AI 把 Math.round 改成了 Math.floor,因为它觉得「向下取整更合理」。它没恶意,但你没测试拦着,这种「合理但行为不等价」的改动就是 bug。对策:哪怕只补 3 个用例的特征测试,也比裸奔强 100 倍。

坑 3:盲信 AI 说「已测试」,结果它根本没跑

Claude Code 帮你跑测试,它真的会跑。但你让它「确认测试通过」,它有时候会基于「测试应该通过」的推理直接回你「测试已通过」,没真跑。尤其是上下文窗口紧张、长会话末尾,它会偷懒。对策:让它把测试命令的原始输出贴出来,看到 PASS / FAIL 字样才算数。没原始输出,等于没跑。

坑 4:跨文件级联改失控

Cursor 的多文件编辑是双刃剑。你让它改 A 文件的一个函数,它顺着 import 链把 B、C、D 文件里相关的也改了,理由是「保持一致性」。它的本意是好的,但你 review 的时候,A 文件的改动你预期到了,B/C/D 的改动完全意外。对策:prompt 里明确写「仅限以下文件:[列表],其他文件即使相关也不要改」。

坑 5:重构混进了业务逻辑改动,行为不等价

这是最阴险的坑。AI 重构时看到一段逻辑「明显有 bug」,顺手修了。重构和修 bug 是两件事,混在一个 PR 里,review 时没法判断哪行是结构变更、哪行是行为变更,回滚也回滚不了。对策:prompt 里写死「行为等价原则:所有现有输入的输出必须与重构前一致,发现的 bug 单独记 issue,不在重构中修」。Michael Feathers 这条铁律,AI 时代一样适用。


七、别让 AI 替你扛纪律

工具再强,扛不住你纪律松。Claude Code 的 plan 模式、Cursor 的 diff 面板,都是给「有纪律的人」准备的放大器。你给它清晰的边界、明确的上下文、每步一跑的节奏,它能把一个三年没人敢动的老代码安全地变成可维护的样子。你图省事一句话让它「重构干净」,它给你一个 600 行的 PR,没人敢 merge,最后还是 revert。

5 步法看起来啰嗦,但每一步都是省时间:建测试网省的是事后 debug 的时间,界定边界省的是 review 的时间,分步执行省的是回滚定位的时间。磨刀不误砍柴工,老话在 AI 时代依然成立。

下次再看到那个 800 行的 orderService.js,别再叹气。架好测试网,划清边界,给 AI 精准上下文,一步一步来,每步 review,最后回归验证。你会发现自己比想象中敢动得多。


参考来源

本文由 AI 辅助生成,经人工审核编辑。最后更新:2026-07-29

常见问题

老代码没测试,补测试成本太高怎么办?
先补特征测试(characterization test),锁住当前行为即可,不用写漂亮的断言。3-5 个覆盖关键路径的用例,就能拦住大部分 AI 重构翻车。
Claude Code 和 Cursor 重构该选哪个?
跨目录大改、需要先看全图,用 Claude Code 的 plan 模式;中小范围、要看 diff 面板的,用 Cursor。两边都用 git diff 兜底,谁也别盲信。
AI 说「测试已通过」能信吗?
不能全信。让它贴出测试命令的原始输出,看到 PASS 字样才算数。长会话末尾 AI 偶尔会基于推理谎报通过,没原始输出等于没跑。
重构时发现老代码有明显 bug,要不要顺手修?
不要。重构和修 bug 必须分开,混在一个 PR 里无法 review 也无法回滚。单独记 issue,重构完再处理。
5 步法哪一步最容易偷工减料?
第五步回归验证。前 4 步走完人累了想赶紧 merge,但越往后越是出事点。手动跑一遍关键路径,比任何自动化都靠谱。

相关文章

实战 SOP

不会写代码也能做游戏:49 个 AI 员工的工作室

用 Claude Code Game Studios(github.com/Donchitos/Claude-Code-Game-Studios,MIT,约 33,837 星)把单个 Claude Code 会话变成 49 个 AI 员工的游戏工作室:三层架构总监/主管/专家、72 个技能命令、12 个自动钩子拦截硬编码与误推送,协作协议保证每个决策由你拍板;附五分钟安装三步、Demo 精简流程、第三方 API 跑法与"适合谁/不适合谁"的自检清单。

2026年11月3日9 分钟阅读
实战 SOP

不给 agent root:Claude Code 沙箱装机实操指南

给 agent 加沙箱但别给 root:Anthropic 开源沙箱工具 srt(anthropics/sandbox-runtime,Apache-2.0,6,615 stars,仓库 2025-10 已建)装机实操。npm 全局安装逐字实录、~/.srt-settings.json 配置原文、三平台原语差异与默认策略三层级(原生/默认/宽松),Windows 三层真相如实呈现:srt CLI 仍是 Alpha、Schannel 属硬限制无解、Claude Code 原生 Windows 不运行沙箱须 WSL2;84% 拦截率为官方自报口径,附 8 条社区坑清单(#139/#160/#122 已修、Ubuntu 24.04 sysctl 等)。

2026年10月26日9 分钟阅读
实战 SOP

Claude Code 接 DeepSeek:官方九变量,别抄旧教程

Claude Code 接 DeepSeek 的官方直连 SOP,全部命令与变量取自 DeepSeek 官方指南(api-docs.deepseek.com/quick_start/agent_integrations/claude_code),对应 1017 checkpoint 上线后的现役配置。主攻搜索词「Claude Code 接 DeepSeek」(S1=3/S2=1/S3=2/S4=3)。迁移路径九项环境变量:ANTHROPIC_BASE_URL 指向 https://api.deepseek.com/anthropic、ANTHROPIC_AUTH_TOKEN 填 DeepSeek API Key、ANTHROPIC_MODEL=deepseek-flash[1m]、DEFAULT_OPUS/SONNET 同为 deepseek-flash[1m]、DEFAULT_HAIKU=deepseek-flash、CLAUDE_CODE_SUBAGENT_MODEL=deepseek-flash、CLAUDE_CODE_EFFORT_LEVEL=max、CLAUDE_CODE_AUTO_COMPACT_WINDOW=786432;Windows PowerShell 与 Linux/Mac 两版写法都给。从零安装四步:Node.js 18+(Windows 另装 Git for Windows)、npm install -g @anthropic-ai/claude-code、claude --version 验证、配变量后进项目目录运行。模型映射:claude-opus 开头的请求映射到 deepseek-v4-pro(按 V4 Pro 价计费,比 Flash 贵,必读提醒)、claude-haiku/sonnet 映射到 deepseek-flash。Web Search 原生可用但两条计费线:搜索请求按 Search API 计费,对检索内容的摘要另产生 token 费。价格口径(官方定价页):off-peak 每百万输入 0.15 美元(cache miss)、0.003 cache hit(约为 miss 的五十分之一)、输出 0.60 美元,peak(工作日 UTC 01:00-04:00 与 06:00-10:00)双倍,周末与中国法定节假日算 off-peak。常见坑五条:AUTH_TOKEN 与 API_KEY 不是一回事(混用等于白配)、新旧变量并存可能鉴权冲突(只留新变量,社区教程口径)、密钥不进 settings.json 不入 git(固化用 ~/.bashrc、~/.zshrc 或系统环境变量)、接好后先跑「读一个文件再改一个文件」最小任务验证工具调用链路、/status 查当前生效模型。市面旧教程多残留 deepseek-chat 等已退休模型名。与站内分工:deepseek-v4-pro-claude-code-sop 是 V4-Pro-0813 时代「2 个环境变量」最小配置(2026-09),本篇是 1017 后官方现役全量配置;Harness 本体入门见 deepseek-harness-quickstart-sop。

2026年10月19日10 分钟阅读