老仓库现代化重构工作流

老仓库现代化重构工作流

是什么

老仓库现代化重构工作流是一套面向遗留代码库的渐进式 AI 辅助重构方法论，覆盖从代码理解、模块拆分、单 PR 执行、批量机械变更到最终审查的全流程。核心理念是”AI 出方案 + AI 出 diff + 人决定合入”——把理解旧代码这种机械但高脑力消耗的工作交给 AI，把判断架构方向保留给人类。

这套工作流针对 5 万行以上的中型遗留仓库设计，假设代码库有以下特征：

• 缺乏完整文档，作者已离职
• 测试覆盖率不足（< 30%）
• 存在大量重复/冗余代码（import 混乱、命名不一致、模块间耦合高）
• 单个模块可独立重构，不需要全量重写

准备工作

前置条件

工具安装确认

• Claude（Anthropic）：claude CLI 已配置 API key，支持 100 万 token 上下文
• Cursor：安装 Composer 插件，确认 diff-only 模式可用
• CodeLlama（本地）：ollama run codellama:34b 可调用，无额外 API 费用
• Claude Code（Anthropic）：claude code CLI 已安装，有 SWE-Bench Verified 75%+ 能力

安全底线

1. 每步可回滚：每个原子 PR 单独分支，合入前确认可以单独 revert
2. 测试先行：目标模块如果没有测试，先生成 characterization test（记录当前行为），再开始重构
3. 不要相信 AI 说没问题：合入前必须跑一次完整测试 + 人工 smoke test

核心流程

阶段 1：理解（占 20% 时间）

这一步只用 Claude，因为它是当前少数能稳定吃下整个中型仓库（10-20 万行）的模型之一。不要急着改代码，先确认你和 AI 对仓库的理解一致。

具体操作：

1. git ls-files | xargs cat 把全部源码塞进 Claude 的一条提示
2. 让 Claude 产出三份输出：
   • 模块依赖图（text-based Mermaid 或 ASCII）
   • 高复杂度文件 Top 20（基于 cyclomatic complexity 估算）
   • 重构优先级排序（低风险高收益 → 高风险低收益）
3. 根据输出制定原子 PR 拆分计划（8-12 个可独立合入的 PR）

阶段 2：执行（占 60% 时间）

按”原子 PR”节奏推进。每个 PR 的约束：

• 单次 diff ≤ 500 行（超限需进一步拆分）
• 独立通过 CI 测试
• 有明确验收标准（以阶段 1 的 checklist 为准）

执行路径：

• 复杂多文件变更 → Cursor Composer 的 diff-only 模式（逐 hunk 确认）
• 重复机械变更（import 迁移、命名统一、API 路由重命名）→ CodeLlama 本地批量替换
• 单文件简单重构 → Claude Code 内联编辑

CodeLlama 批量批改组合命令：

# 示例：统一 import 路径
rg 'from old-pattern' --files-with-matches | xargs -I{} sh -c 'ollama run codellama:34b "Replace all old-pattern imports with new-pattern in file {}"'

阶段 3：验收（占 20% 时间）

Claude Code 跑最终 review，人工合入。这一步必须保留人为闸门——重构最大的风险不是代码丑，而是行为变更被偷偷引入。

验收 checklist：

1. Claude Code 输出”风险清单 + 建议手动复查的代码段”
2. 针对风险清单逐条人工确认
3. 运行完整 CI + 人工 smoke test
4. 只有全部通过后才合入主干

踩坑记录

P1：Claude 大仓库上下文溢出

100 万 token 上下文在极端情况下仍可能溢出（如 monorepo 包含大量二进制/生成文件）。解决方案：用 .claudeignore 排除 node_modules/、dist/、build/、*.lock 等非源码文件。

P2：Cursor Composer 一次性修改过多文件

Composer 在处理 10+ 文件的批量修改时可能出现 diff 顺序错误。解决方案：每个原子 PR 严格控制在 5 个文件以内，超过则拆分为子步骤。

P3：CodeLlama 本地批改质量不稳定

本地模型（34B）在复杂重构场景下可能产生不完整的替换或误改。解决方案：

1. 仅用于机械性、模式固定的替换
2. 每次替换后先 diff 再提交
3. 替换后的文件必须通过 lint + test

P4：原始模块无测试覆盖面

目标模块如果没有测试，AI 重构引入行为变更的风险大幅上升。解决方案：先用 Cursor 或 Claude 生成 characterization test（记录 old code 的实际输入输出），作为后续重构的安全网。

P5：合入后 CI 红但本地绿

AI 工具可能在修复冲突时引入微妙的差异（换行符、编码、文件权限）。解决方案：每个 PR 合入前再跑一次 CI，不要在本地绿后就直接合入。

FAQ

Q：这套工作流适合多大代码库？

最适合 5-50 万行的中型仓库。小于 5 万行直接用 Claude Code 全量处理更快；大于 50 万行需要先拆分子仓库或独立服务。

Q：一定要 4 个工具全用吗？

不是。核心路径是 Claude（理解）→ Cursor（执行）→ 人工合入。CodeLlama 是可选优化项（降低 API 成本），Claude Code 是可选增强项（提升审查质量）。

Q：CodeLlama 34B 能跑在什么硬件上？

34B 量化版（Q4_K_M）需要约 20GB VRAM，建议 RTX 4090 24GB 或 M2 Ultra 64GB。8GB 以下显存的设备建议换用 CodeLlama 7B 或直接用 API。

Q：评估一个仓库能否用这套工作流需要多久？

1 天。用 Claude 走完整仓库分析，产出模块依赖图和 Top 20 高复杂度文件，当天就能判断是否可行。

Q：AI 重构后代码风格不一致怎么办？

在 Cursor 中使用 .cursorrules 定义项目代码规范，每个 PR 合入后跑一次 ESLint + Prettier（或其他 formatter），确保全局风格统一。

参考资料

• 用 AI 现代化遗留代码：2026 重构指南 —— AI 辅助遗留系统现代化的四阶段框架：代码考古→特征测试→绞杀榕实施→验证。
• AI 代码重构：用 AI 辅助现代化你的代码库 —— AI 重构的安全实践、增量变更策略与常见陷阱避坑指南。
• 加速遗留代码重构的 AI 工具：Copilot、Claude 与 Cursor —— 三种主流 AI 工具在遗留重构场景中的优劣对比与组合策略。
• AI 驱动的遗留代码现代化与迁移 —— 企业级 AI 辅助遗留系统迁移的方法论、安全考量与 ROI 分析。