Anthropic 如何用 Claude Code 做大规模代码迁移
🎯 一句话
迁移先建立规则手册、依赖图与行为验证,再拆成可定位失败、可恢复的小批次。切分依据是依赖和接口,并非所有任务都应按单文件提交。
本页先解决:迁移单元怎样切分,才能验证并恢复?
Claude 博客资料库 · ClaudeCode实践
迁移单元怎样切分,才能验证并恢复?
案例中的速度要与消耗、测试覆盖和上线后回归一起看,不能只保留完成时间。
读完可以:按依赖与接口切分迁移任务,并区分编译通过、冒烟和行为对齐。
切分依赖,再接验证闸门
- 定义迁移单元规则手册、依赖图和缺口清单先建立
- 样本压力测试试验翻译方式,只保留修订后的规则
- 并行翻译按依赖与接口划分可协作的批次
- 编译与冒烟先发现基本构建和运行问题
- 行为对齐再检查迁移前后的行为差异
失败回到对应单元与规则;编译通过还没有证明行为保持一致。
📄 来自 Claude 官方博客
- 原文标题
- How Anthropic Runs Large-Scale Code Migrations with Claude Code(Anthropic 如何用 Claude Code 做大规模代码迁移)
- 原文链接
- https://claude.com/blog/ai-code-migration
- 作者
- Anthropic(Claude 博客)
- 发布日期
- 2026-07-16
⚠️ 本页是原文的中文结构化整理笔记(保留架构、数据、案例、结论),并非逐字翻译。版本、参数与案例数字属于原文所示条件,不是本资料库的实测结果;产品状态与接口以实施时官方文档为准。
代码迁移(把生产代码库转换到新语言)已从「多年、百万美元级」的项目变成「数周可完成」的工作。核心洞察是:
「你要修的不是代码,而是产出代码的那个流程(循环)。」
案例中的速度要与消耗、测试覆盖和上线后回归一起看,不能只保留完成时间。
两个真实案例
Bun 迁移(Zig → Rust)
- 规模: 一百万行代码,不到两周
- 质量: 合并前 100% 通过既有测试套件;合并后出现 19 个回归,均已修复
- 消耗: 59 亿输入 token、6.9 亿输出 token,约 $165,000
- 收益: Linux/Windows 二进制体积减少 19%;基准测试中内存占用从 6,745 MB 降到 609 MB;性能提升 2-5%
- 已在生产部署;代码中约 4% 是 unsafe 块(多为 C/C++ 边界的指针操作)
内部 Python → TypeScript 项目
- 规模: 16.5 万行,一个周末
- 配置: 12 个子 Agent、8 道阶段闸门、3 轮对抗式审查
- 收益: 编译时间从约 30 分钟降到每平台约 2 秒;二进制启动快 6 倍;退役了一条独立的部署流水线
并行单元来自依赖与接口;规则手册、样本压力测试和验证闸门共同决定如何切分。
六步迁移架构
第 1 步:打地基(三条并行工作流)
- 规则手册(Rulebook): 记录两种语言间的翻译政策——惯用法、类型、架构决策
- 依赖图(Dependency Map): 用脚本识别文件关系,据此切分可并行的工作流
- 缺口清单(Gap Inventory): 编目那些需要重构而非直译的架构差异(如 Rust 的所有权模型 vs Zig 的手动分配)
第 2 步:压力测试
在代表性样本上用不同翻译方式跑小规模迁移。Bun 的作者在这一阶段抓出了两个影响 1,448 个文件的关键问题。产出全部丢弃,只保留精化后的规则。
第 3 步:并行翻译
- 跨批次部署实现者 Agent,高并发工作用较小模型(Sonnet)
- 未解决的项用
// TODO(port):注释标记 - 用双重对抗式审查者;分歧升级给仲裁者
- 发现模式时更新规则手册,而不是逐个修文件
第 4-6 步:编译 → 冒烟测试 → 行为对齐
- 编译: 全工作区跑编译器,并行修错并配对抗式审查
- 冒烟测试: 自动化测试找崩溃,按根因分组做系统性修复
- 行为对齐: 对新旧两套代码库跑完整测试套件;用构建守护进程串行化昂贵的重建操作
- 没有测试套件时的替代方案: 建对等性测试台(parity harness)对比真实场景,或让 Claude 自主设计并通宵运行端到端测试
经济账解释为什么值得迁移,工程实践解释怎样限制失败的影响范围。
为什么 AI 改变了迁移的经济账
- 工作天然可并行: 数千个独立文件单元支持并发执行
- 规格明确: 原代码库本身就是参考规格
- 验证客观: 测试套件提供无需人工仲裁的基准真值
- 工作队列自动生成: 编译错误和测试失败自动填充待办队列
- 模式可检测: 系统性问题在审查循环中浮现,防止悄然偏移
六条关键实践
- 把人力前置到规则手册和压力测试上;后续阶段基本是「烧队列」
- 关注失败的模式而非单个失败——人的注意力应该放在模式上
- 设计 token 高效的循环: 最大的模型留给审查者和写规则,实现工作用小模型
- 让工作队列机械化: 输出文件存在可作为队列进度信号;语义完成仍须编译、行为对齐和回归验证,恢复还需保留原件与检查点
- 坚持对抗式审查——长任务中它值那个 token 成本
- 别照搬本文: 每次迁移都不同,先和 Claude 一起做针对性规划
结论
语言迁移不再需要「关乎存亡」的理由来立项——长期存在的瓶颈或维护负担现在就足以证明投资合理。通过把迁移围绕系统性验证循环(而非人工代码审查)来组织,并策略性地搭配不同档位的模型,历史上需要「多年工程」的项目可以压缩到几周,迁移的算术从根本上变了。
✅ 检查点
- 大规模代码迁移该怎么切分任务?
- 为什么「一次性全改完」是错的?
- 迁移任务里人应该负责什么?
👀 答案
- ⭐ 按「可独立验证 + 可独立回滚」切,通常是单个文件或单个模块。每个单元走完整闭环:改 → 跑测试 → 通过就提交,不通过就回滚重试。
- 因为错误会累积且无法定位。500 个文件一起改完再跑测试,挂了 30 个用例,你无法知道是哪些改动引起的,只能整体回滚重来。⭐ 而小单元提交时,小批次能缩小排查范围;跨模块依赖仍可能导致交互性失败。
- ⭐ 人负责①定义迁移规则和边界情况 ②建立验证手段 ③处理模型报上来的例外。也就是「定规则 + 建尺子 + 处理异常」,而不是逐个 review 每处改动——那样规模上不去,也失去了自动化的意义。
本节回顾
先记住这几件事
- 迁移单元要能独立验证、定位失败与恢复。
- 先确定迁移规则和边界案例,再批量推进。
- 每批检查产物及保留项,异常回到明确的人工处理入口。