Claude Code 重构项目教程：清理重复代码、优化结构、提高可维护性

Claude Code 很适合辅助项目重构：它能阅读代码结构、发现重复逻辑、解释调用链、生成修改计划，并在确认后编辑文件。但重构和修 Bug 不同，风险更高，因为重构目标通常不是修一个明确错误，而是在不改变行为的前提下优化结构。如果没有计划和测试，AI 很容易把”清理重复”变成”大范围重写”。

本文会用完整流程讲清如何用 Claude Code 清理重复代码、优化模块结构并提高可维护性。还没有完成基础安装的读者，可以先看本站 安装部署教程 和 环境配置教程；想把重构放进团队开发流程，可以继续参考 实战工作流 和 问题排查教程。

摘要

使用 Claude Code 重构项目，推荐按”审计、计划、分批修改、验证、复盘”执行。第一步让 Claude Code 只读分析项目，不要修改文件，输出重复代码、职责混乱、循环依赖、公共接口和测试缺口；第二步要求它给出重构计划，明确目标、范围、禁止事项、文件列表、每批修改顺序和回滚方式；第三步只允许它做最小批次修改，保持外部行为和接口不变；第四步每批修改后检查 git diff，运行测试、lint、构建和关键手动场景；第五步让 Claude Code 总结改动原因、风险和后续建议。重构成功的标准不是代码看起来更短，而是行为稳定、职责更清晰、重复更少、后续维护成本更低。

正文

为什么重构不能一上来就让 AI 改

重构的核心约束是行为不变。Claude Code 可以帮助你分析和修改，但它并不天然知道哪些行为属于历史兼容、哪些重复代码其实是不同业务场景、哪些公共函数被多个模块依赖。因此，重构前必须先审计，再计划，最后分批动手。

如果你直接输入”帮我优化这个项目”，输出很可能过大、过泛，而且难以审查。更好的开局是：只读分析，不要修改文件。

第一步：让 Claude Code 做重构前审计

在项目根目录启动 Claude Code 后，先要求它只读分析项目结构和重复代码。不要让它马上编辑文件。

请先只读分析这个项目，不要修改文件。
目标是评估是否适合重构，并输出：
1. 明显重复的代码片段
2. 职责混乱的模块
3. 可能的循环依赖或过度耦合
4. 公共接口和高风险区域
5. 现有测试覆盖情况
6. 建议的重构优先级

第二步：区分重复代码和必要差异

不是所有相似代码都应该合并。有些代码看起来重复，但分别服务不同业务规则；有些重复是临时兼容旧接口；有些重复是为了隔离风险。让 Claude Code 合并前，必须要求它说明相似点和差异点。

请比较这些相似函数：
1. 它们真正重复的部分是什么
2. 哪些逻辑是业务差异，不能合并
3. 如果抽成公共函数，参数和返回值应该是什么
4. 合并后可能影响哪些调用方
5. 是否值得重构

如果它无法说明差异，只能说”代码重复，建议抽取”，这还不够进入修改阶段。

第三步：先写重构目标

重构目标要具体。不要只写”优化结构”，要写成可验证目标，例如：把三处重复表单校验抽成共享函数；把臃肿组件拆成容器组件和展示组件；把 API 请求封装从页面中移到 service 层；把重复错误处理统一到一个工具函数。

目标越明确，Claude Code 越容易给出小范围计划。

第四步：要求它输出分批计划

重构不要一次做完。让 Claude Code 把计划拆成多个小批次，每一批都能单独验证和回滚。

请给出重构计划，但先不要修改文件。
要求：
1. 每一批只改少量相关文件
2. 保持外部接口和行为不变
3. 每批都说明验证方式
4. 标出高风险文件
5. 说明如何回滚
6. 不要引入新依赖，除非我确认

第五步：设置禁止事项

重构时最重要的不是让 AI 多做，而是明确它不能做什么。常见禁止事项包括：不要修改接口字段、不要改数据库结构、不要引入新依赖、不要删除测试、不要顺手改样式、不要把 Bug 修复和重构混在一起。

本次重构禁止：
- 修改接口协议
- 删除现有测试
- 引入新依赖
- 改动无关样式
- 大范围重命名文件
- 把功能变更混进重构

第六步：先重构低风险重复代码

第一次让 Claude Code 做重构，建议从低风险区域开始，例如纯工具函数、重复校验逻辑、文案映射、类型定义整理、测试辅助函数。不要一开始就重构支付、权限、数据库迁移、核心状态管理等高风险模块。

低风险重构也要保持小步提交。每次只改一类重复，确保 diff 能看懂。

第七步：让 Claude Code 生成最小 diff

确认计划后，要求 Claude Code 只做第一批修改，并解释每个 diff 的原因。

可以开始第一批重构。
只处理重复的表单校验逻辑。
要求：
1. 保持外部行为不变
2. 不要修改接口字段
3. 不要重构无关组件
4. 修改后解释每个文件的 diff
5. 运行相关测试

如果第一批修改过大，立即停止，让它拆小。重构质量和 diff 可审查性直接相关。

第八步：每批修改后检查 diff

Claude Code 修改完成后，必须查看实际差异：

git diff

重点检查：是否改变外部行为，是否删除边界处理，是否把业务差异错误合并，是否把无关文件卷进来，是否引入新的隐式依赖，是否破坏命名一致性。

第九步：运行测试和回归场景

重构不是功能开发，但必须验证功能不变。至少运行相关单元测试、lint、构建命令；如果涉及页面交互或接口流程，还要手动跑关键回归场景。

npm test
npm run lint
npm run build

如果测试不完整，可以让 Claude Code 先补测试，再做重构。没有测试保护的大范围重构，风险非常高。

第十步：把重构知识写进项目记忆

如果这次重构明确了新的模块边界、命名约定或公共函数使用方式，可以把稳定规则写进 CLAUDE.md。这样后续 Claude Code 处理同一项目时，就不会反复走旧路径。

# Refactor Rules
- 表单校验统一放在 src/shared/validation。
- 页面组件不直接拼接 API payload。
- service 层负责请求和响应转换。
- 重构任务必须先给计划，再分批修改。

第十一步：让 Claude Code 输出复盘

每批重构结束后，让 Claude Code 输出复盘，便于提交和后续维护：

请总结本批重构：
1. 清理了哪些重复代码
2. 优化了哪些结构
3. 外部行为是否保持不变
4. 已运行哪些测试
5. 是否还有剩余风险
6. 下一批建议重构什么
7. 建议的 commit message

完整重构提示词模板

下面这段可以直接复制使用：

请帮我评估并执行一次小范围项目重构。
当前阶段先只读分析，不要修改文件。

目标：
【例如：清理重复表单校验逻辑，提高可维护性】

限制：
- 保持外部行为不变
- 不修改接口字段
- 不引入新依赖
- 不删除测试
- 不做无关重构

请先输出：
1. 重复代码或结构问题
2. 是否值得重构
3. 建议修改的文件
4. 分批重构计划
5. 每批验证方式
6. 风险和回滚方式

等我确认后，只执行第一批最小修改。

什么时候不适合用 AI 重构

如果项目没有测试、业务规则没有文档、线上风险很高、核心模块历史债务复杂，建议先让 Claude Code 做只读审计和测试补齐，不要立刻让它重构。重构前的保护网比重构本身更重要。

FAQ

Claude Code 可以直接重构整个项目吗？

不建议。大型重构应该拆成多个小批次，每批都有明确目标、diff 和验证方式。一次性重构整个项目很难审查，也很难回滚。

如何避免 AI 把功能改坏？

明确要求保持外部行为不变，不修改接口字段；每批修改后检查 diff，运行测试和关键回归场景。没有测试时，先补测试再重构。

重复代码一定要抽公共函数吗？

不一定。要先确认重复部分和业务差异。如果相似代码承载不同业务规则，强行合并反而会降低可维护性。

重构时可以让 Claude Code 新增依赖吗？

默认不建议。新增依赖会带来体积、维护、安全和兼容成本。除非理由充分，并且经过人工确认。

重构后应该如何提交代码？

建议按批次提交，每个提交只包含一类重构，并附上验证命令。不要把功能开发、Bug 修复和结构重构混在一个提交里。