一、为什么选择 Claude Code 重构遗留系统
本节交代文章背景与写作动机，帮助读者判断这篇内容是否适合自己。
- 遗留系统的典型困境：文档缺失、依赖陈旧、测试覆盖率低、无人敢改的"祖传代码"。
- 传统重构方式的瓶颈：人工阅读成本高、改动风险大、重构周期长、知识传递困难。
- Claude Code 的定位：面向项目级代码理解与修改的 AI 编程助手，擅长跨文件检索、批量改造与上下文推理。
- 本文目标读者与预期收益：适合有一定工程经验、正在维护存量系统的开发者与团队负责人。
二、重构前的准备：让 AI 真正读懂你的项目
本节说明在动手改代码之前，如何为 Claude Code 建立可靠的项目上下文。
2.1 项目摸底与结构梳理
- 用 Claude Code 快速生成模块清单、调用关系与依赖图谱。
- 识别核心链路与高风险区域，划定重构边界。
- 输出一份"系统现状说明"，作为后续重构的基线文档。
2.2 建立项目级上下文文件
- 编写 CLAUDE.md：约定技术栈、目录规范、编码风格与禁止事项。
- 沉淀领域术语表，减少 AI 对业务概念的误判。
- 明确"哪些代码可以改、哪些必须保持原样"的红线。
2.3 补齐安全网：测试与可回滚机制
- 优先为待重构模块补充特征测试（Characterization Test）。
- 建立分支策略与灰度发布方案，确保每次改动可回滚。
- 约定"先补测试、再改代码"的协作纪律。
三、重构策略：小步快跑而非推倒重来
本节给出可落地的重构节奏与优先级判断方法。
- 绞杀者模式（Strangler Fig）：新逻辑并行生长，逐步替换旧实现。
- 按风险与收益排序：先做低风险高收益的清理，再攻坚核心模块。
- 单次改动范围控制：一次只做一类改动，便于审查与回滚。
- 重构与需求开发分离：避免在同一提交中混合两类变更。
四、实战场景一：代码清理与规范化
本节用具体场景演示 Claude Code 在低风险改造中的价值。
- 统一命名规范、消除重复代码、拆分超长函数。
- 替换已废弃 API 与过时依赖，处理版本升级带来的兼容问题。
- 批量补充注释与类型声明，提升代码可读性。
- 提示词示例：如何描述"只做格式化、不改变行为"的约束。
五、实战场景二：模块拆分与架构演进
本节聚焦结构性改造，说明如何借助 AI 完成跨文件的架构调整。
- 识别耦合点，抽取公共能力为独立模块。
- 将单体逻辑按领域边界拆分，逐步引入清晰的分层结构。
- 处理跨模块调用的迁移与兼容层设计。
- 用 Claude Code 生成迁移清单与影响面分析。
六、实战场景三：技术栈升级与迁移
本节以典型升级路径为例，展示 AI 辅助迁移的完整流程。
- 依赖版本升级：从影响分析到逐文件改造。
- 语言或框架迁移：如何分批推进、如何验证等价性。
- 数据库与接口变更：数据迁移脚本与兼容策略。
- 迁移过程中的回归验证与问题定位方法。
七、质量保障：让 AI 的改动可验证、可信任
本节回答"如何确保 AI 改的代码是对的"这一核心疑问。
- 代码审查要点：关注行为变更而非格式差异。
- 自动化验证：单元测试、集成测试与静态检查的组合使用。
- 差异对比与人工复核的协作流程。
- 常见 AI 改动陷阱：过度重构、隐式行为变化、遗漏边界条件。
八、团队协作与工程规范
本节讨论如何把个人实践升级为团队可复用的工作方式。
- 统一提示词模板与任务拆解规范。
- 提交信息、分支命名与变更记录的约定。
- 知识沉淀：把重构经验反哺到项目文档与上下文文件。
- 权限与安全边界：敏感代码、生产配置的处理原则。
九、常见问题与避坑指南
本节汇总实践中最容易踩的坑，给出可操作的应对建议。
- AI 对业务语义理解偏差时如何纠正。
- 大仓库上下文超限时的分而治之策略。
- 改动范围失控时的止损方法。
- 何时应当放弃 AI 辅助、回归人工处理。
十、总结与延伸阅读
本节收束全文，给出可执行的行动清单与进一步学习方向。
- 重构路线图回顾：从摸底、补测试到分场景改造。
- 给读者的三条起步建议。
- 推荐阅读：重构方法论经典著作与 Claude Code 官方文档。