一、引言：遗留系统的困境与 AI 协作的新可能
- 遗留系统的典型痛点：文档缺失、技术栈陈旧、耦合严重、无人敢改
- 传统重构方式的成本与风险：周期长、回归难、知识断层
- 为什么选择 Claude Code：代码库级理解、多文件编辑、可脚本化的工作流
- 本文要解决的问题与读者收益
二、重构前的准备：让 AI 先读懂你的系统
- 环境搭建：Claude Code 安装、项目根目录初始化、权限与安全边界配置
- 建立项目上下文：CLAUDE.md 编写要点（架构说明、编码规范、禁止事项）
- 代码库摸底：用 Claude Code 生成模块依赖图与调用链梳理
- 产出物沉淀：自动生成架构文档、接口清单、数据流说明
- 风险清单：识别高风险模块，划定重构优先级
三、重构策略制定：人机分工的边界
- 三种重构路径对比：绞杀者模式、渐进式改造、局部重写
- 哪些任务适合交给 Claude Code：样板代码迁移、接口适配、测试补全、文档生成
- 哪些任务必须人工把关：领域逻辑判定、数据一致性、性能关键路径
- 制定分阶段计划：以可交付、可回滚为原则拆分任务
四、实战一：代码理解与依赖梳理
- 场景说明：一个缺乏文档的老旧单体服务
- 用自然语言提问定位核心业务入口
- 批量分析模块耦合度，输出重构建议清单
- 生成可视化依赖关系（Mermaid 图表示例）
- 实践要点：提问粒度、上下文控制、结果校验
五、实战二：渐进式代码迁移与改造
- 场景说明：将旧版数据访问层迁移到新框架
- 先让 Claude Code 输出迁移方案，人工确认后再执行
- 小步提交：单文件改造 + 即时验证的循环
- 处理跨文件引用与接口兼容问题
- 代码示例：改造前后的对比片段
- 实践要点：控制单次改动范围，避免大爆炸式重写
六、实战三：用测试为重构兜底
- 为遗留代码补测试的难点与突破口
- 让 Claude Code 基于现有实现反向生成单元测试
- 生成契约测试，保障接口行为不变
- 测试覆盖率提升的渐进策略
- 实践要点：AI 生成的测试必须人工审查断言合理性
七、实战四：文档与知识资产同步重建
- 自动生成模块说明、接口文档与部署手册
- 把重构决策记录成 ADR（架构决策记录）
- 让 CLAUDE.md 随项目演进持续更新
- 实践要点：文档与代码同源维护，避免再次腐化
八、常见坑与应对经验
- 上下文超限导致理解偏差：如何拆分任务与提供精准上下文
- AI 生成的代码"看起来对但跑不通"：验证闭环的重要性
- 过度信任导致的隐性回归：Code Review 与自动化测试的双重防线
- 敏感代码与数据安全：权限控制与脱敏处理
- 团队协作中的规范统一：提示词与工作流标准化
九、效果评估与度量
- 重构效率指标：改造耗时、代码量变化、缺陷率
- 质量指标：测试覆盖率、圈复杂度、重复代码率
- 团队指标：新人上手时间、文档完备度
- 如何用数据说明 AI 协作的真实价值
十、总结与展望
- 核心结论：AI 是加速器，不是替代品
- 可复用的重构工作流清单
- 对团队工程文化的长期影响
- 后续可探索方向：CI 集成、自动化重构流水线