← Back to all guides

用 Claude 搭建代码迁移工具：从解析到批量重写

为什么用 Claude 做代码迁移，而不是只靠脚本

真正的代码迁移很少是简单替换函数名，更多是跨文件依赖、接口签名变化、测试断言更新和框架习惯迁移。Claude 的优势在于它能理解“意图”和“约束”同时存在的场景：你可以让它把 Python 服务迁到 TypeScript，把老旧 ORM 调用迁到新版本 SDK，或者把同步逻辑改成异步实现，同时尽量保持原始业务语义不变。

经验上，迁移工具不要追求一次性生成完整仓库，而是拆成可控的流水线：先识别，再重写，再验证，最后应用补丁。这样你才能把 AI 的不确定性限制在最小范围内。

第一步：先构建“迁移清单”，不要直接喂整仓库

最实用的做法是先用静态分析生成一个 manifest。它至少包含文件路径、导出符号、依赖项、测试文件和风险等级。你可以先用轻量模型做分类，再把高价值模块交给 Claude 主模型处理。

• 按符号切块：以类、函数、模块为单位，而不是按固定 token 数硬切。
• 保留上下文窗口：把调用方、被调用方和相关类型定义一起传给模型。
• 标记不可改区域：例如公共 API、协议字段、数据库迁移脚本名称等。

这一步做得好，后面的改写质量会明显提升，因为模型不再猜测项目结构，而是在清晰边界内工作。

第二步：提示词要像“变换规范”，不是“请帮我改一下”

高质量迁移提示词的核心是约束。你要明确告诉 Claude：目标语言、允许修改的范围、输出格式、失败条件，以及必须保持不变的行为。最推荐的输出格式是统一 diff 或结构化 JSON，方便自动应用和回滚。

• 明确目标：例如“将 Node 18 代码迁移到 Node 22，并替换已弃用的 SDK 调用”。
• 要求最小改动：优先保留命名和目录结构，只改必要部分。
• 强制自检：要求模型列出可能破坏测试的点，但不要把解释混进补丁里。

如果你让模型“直接重写文件”，它很容易引入风格漂移；如果你要求“只输出可应用的 diff”，工程上就更稳定。

第三步：把 AST、检索和补丁应用结合起来

先进的迁移工具不会只依赖提示词，而是把 AST 解析和检索增强一起用。比如你先解析出函数签名、导入列表和类型引用，再把相关代码片段拼成上下文。对于大型仓库，建议采用“先检索再生成”的策略：先找出最相关的 3 到 5 个片段，再让 Claude 处理。

一个很实用的技巧是把复杂迁移拆成两轮：第一轮让模型输出迁移计划和风险点；第二轮只根据计划生成补丁。这样可以减少幻觉，也便于在 CI 里做自动拦截。

第四步：自动验收比“看起来对”更重要

迁移工具是否靠谱，不取决于它能写多少代码，而取决于它能否在失败时快速自我修正。建议你把以下校验串成固定流程：

• 单测：优先跑受影响模块的测试，再跑全量测试。
• 类型检查：TypeScript、mypy、go test、javac 都应纳入流程。
• 静态检查：lint、格式化、死代码和导入顺序。
• 失败回传：把编译错误和测试日志原样喂回 Claude，让它只修补失败点。

低温度参数也很关键。迁移阶段建议把采样随机性压低，优先稳定输出；只有在生成修复方案时才允许稍微放宽。

用 59API 把成本压下来，同时保持原生质量

做迁移工具时，调用量通常很大：分类、检索、重写、修复、复核，都会消耗 token。这里很适合用 59API 作为 Claude 的低成本 API 中继。它提供按量计费、价格友好的调用方式，而且接入方式很直接，基础地址就是 https://api.59api.com。更重要的是，它使用原生官方质量模型，没有降级，兼容 Claude Code、Codex 以及任意 OpenAI SDK，所以你可以几乎不改代码就把现有脚本接进去。

我的建议是：Haiku 用于文件筛选和摘要，Sonnet 用于大多数重写任务，Opus 只留给高风险、强推理的核心模块。这样既能控制预算，又能保持迁移质量。如果你已经在规划一个真实的迁移项目，可以先注册 59API 试跑一个小仓库，再决定是否扩大规模；它还有推荐返利，对长期跑批量任务也很友好。

真正好用的代码迁移工具，不是“替你写代码”，而是把分析、生成、验证和回滚做成一条可靠流水线。Claude 很适合承担生成和修复环节，而 59API 则让这套流水线在成本上更可持续。