大规模代码迁移实战：用 Claude Code 的 Agent 与 Subagent 搭建规则手册-平芜编程栈

1. 百万行代码迁移，为什么单靠一个 Agent 会崩

大型项目做跨语言或跨框架迁移，最直观的痛点不是“翻译”本身，而是翻译之后没人能保证行为一致。一个几十万行的 Python 服务要迁到 TypeScript，或者一个 Zig 写的运行时迁到 Rust，代码量摆在那里，人工逐文件改写基本不现实。Claude Code 的 Agent 与 Subagent 机制之所以适合这类场景，是因为它能把“迁移”拆成可并行、可验证、可回滚的任务单元，而不是让一个模型从头到尾硬扛。

我试过把一个小型 Node 项目整体丢给单个 Agent 做框架迁移，结果前 20 个文件还算正常，到第 30 个文件开始出现命名风格漂移、错误处理方式不一致、部分工具函数被重复实现。问题根源在于：单个 Agent 的上下文里没有一份稳定的“规则手册”，它每处理一个新文件都在重新做判断。大规模迁移必须解决三件事——规则统一、任务可拆分、结果可机械验证。这也是 Claude Code 的 Agent 与 Subagent 分工协作的核心价值。

这篇文章面向正在做或准备做跨语言/跨框架迁移的团队，给出一份可复用的迁移规则手册目录骨架、Subagent 任务拆分模板，以及一次小范围迁移的验证步骤与检查清单。你可以把它当成一套可跟做的工程流程，而不是某个模型的评测。

2. TaoToken 前置：把 Claude Code 的模型调用接进来

Claude Code 本身是一个命令行编码工具，它需要能访问 Claude 系列模型。TaoToken 提供的是模型 API 接入能力，你可以把它理解为“让 Claude Code 能稳定调用模型的通道”。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。

接入前你需要先拿到 API Key。打开控制台页面 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在 API Keys 管理里创建一个新 Key，复制保存。注意 Key 只在创建时完整显示一次，丢了就得重建。

拿到 Key 之后，Claude Code 的配置通常通过环境变量注入。下面是一份可复制的配置示例，把ANTHROPIC_BASE_URL指向 TaoToken 的 API 地址，ANTHROPIC_API_KEY填你刚创建的 Key：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的Key"

如果你用的是 Claude Code 的配置文件方式，可以在项目根目录或用户目录下写入对应配置。配置完成后，先做一次最小验证，确认通道可用：

claude --version claude -p "用一句话说明什么是代码迁移"

如果第二条命令能正常返回内容，说明模型调用已经打通。这一步很关键，因为后面所有 Agent 和 Subagent 的调度都依赖这条通道。如果这里报 401 或连接超时，先检查 Key 是否复制完整、Base URL 是否写成了https://taotoken.net/api（不要多加路径）。

对于需要长期跑迁移任务的团队，建议关注 Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合持续性的编码与 Agent 调度场景。模型对话能力可以在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 查看，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。

3. 迁移规则手册的目录骨架

规则手册是整个迁移流程的“宪法”。它的作用是：当两个 Agent 面对同一个转换问题时，必须给出同一个答案。只要存在两种合理答案，就应该提前定死，写进手册。

下面是一份可直接落地的目录骨架，适用于保留原架构的迁移（比如 Zig 到 Rust、Python 到 TypeScript）：

# 迁移规则手册 v1 ## 1. 语言映射总则 ### 1.1 类型系统对应表 ### 1.2 错误处理与异常模型 ### 1.3 内存/资源管理约定 ### 1.4 命名与目录结构约定 ## 2. 惯用写法替换 ### 2.1 循环与迭代 ### 2.2 集合与容器 ### 2.3 字符串与编码 ### 2.4 并发与异步 ## 3. 差距清单（无法直接转换项） ### 3.1 运行时隐含行为 ### 3.2 动态类型/反射相关 ### 3.3 平台相关 API ## 4. 禁止事项 ### 4.1 不允许的临时绕过 ### 4.2 TODO 标记规范 ## 5. 验证与验收 ### 5.1 编译检查 ### 5.2 测试套件 ### 5.3 行为 diff 规则

差距清单是手册里最容易被忽略、但最关键的部分。源语言里有些知识藏在运行时行为、动态类型或内存管理方式中，目标语言要求你显式写出来。比如 Zig 里调用方需要手动释放内存，Rust 里所有权转移后自动释放，这类差异必须逐条记录，供实现 Agent 查询。

一个实用的判断标准：只要两个 Agent 对同一个转换可能给出不同答案，就写进手册。手册不是一次写完的，它会在压力测试和批量迁移中不断回写。

4. Subagent 任务拆分模板

Subagent 的价值在于“上下文隔离”。每个 Subagent 只负责一个明确的迁移单元，不共享彼此的中间状态，这样可以避免错误在 Agent 之间传染。下面是一份任务拆分模板，你可以直接套用：

## Subagent 任务卡 - 任务 ID: port-<模块名>-<批次号> - 输入文件: src/<模块>/<文件列表> - 目标文件: dst/<模块>/<文件列表> - 依赖前置: <必须先完成的模块> - 适用规则: 手册第 1.2、2.3 节 - 差距条目: gap-007, gap-012 - 验收命令: <编译命令> && <测试命令> - 失败处理: 标记 TODO(port): <原因>，不阻塞其他单元 - 审查要求: 两个独立上下文审查 Agent，冲突时第三人裁决

拆分粒度建议按“文件或小模块”为单位，不要按函数拆，太碎会导致调度开销超过收益；也不要按整个子系统拆，太大则单次失败成本高。一个批次控制在 10 到 30 个文件比较合适。

任务队列最好由脚本自动维护，而不是手工维护。脚本通过检查目标文件是否存在来判断哪些单元已完成，再把剩余文件划分成新批次。这样迁移流程可以随时暂停和恢复，Agent 中断后也能从已有进度继续。

# 伪代码：根据磁盘状态生成待迁移批次 for f in $(find src -name "*.zig"); do target="dst/${f#src/}" target="${target%.zig}.rs" if [ ! -f "$target" ]; then echo "$f" fi done | split -l 20 - batch_

5. 一次小范围迁移的验证步骤

在正式批量迁移前，必须先做一次小范围压力测试。这一步生成的代码不保留，它的唯一任务是暴露规则和流程中的问题。

第一步，选 3 个有代表性的文件，覆盖简单、中等、复杂三种情况。第二步，让第一个 Agent 严格按规则手册翻译，让第二个 Agent 以“资深目标语言工程师”的方式独立翻译同样的文件。第三步，让第三个 Agent 对比两份结果，根据 diff 补充规则手册。

# 启动双翻译对比 claude -p "按规则手册翻译 src/a.zig 到 dst/a.rs，只输出代码" claude -p "以资深 Rust 工程师身份翻译 src/a.zig，只输出代码" claude -p "对比两份实现，列出差异并指出规则手册缺失项"

如果两份实现差异集中在某几类问题上，说明规则手册在这些点上不够明确。把差异回写进手册，再重新跑一轮。只有当双翻译结果高度收敛，才说明规则足够稳定，可以扩展到全量文件。

验证检查清单：

编译是否通过，错误是否可归类
原有测试套件是否全部运行
新旧实现的输出 diff 是否为空
错误码、退出码是否一致
是否存在未标记的 TODO
是否有 Agent 绕过了规则手册

6. 批量迁移与编译验证循环

进入批量阶段后，流程基本固定：实现、独立审查、修复。高吞吐的实现任务可以交给较小模型，审查和规则修改交给更强模型。每个迁移单元由两个上下文独立的审查 Agent 检查，意见冲突时交给第三个 Agent 裁决。

编译验证要遵循“廉价检查高频运行，昂贵检查集中处理”的原则。TypeScript 编译只要几秒，可以在每个单元内运行；Rust 工作区编译要几分钟，统一留到批次结束后进行。

# 批次编译并生成错误队列 cargo build --workspace 2> build_errors.log grep -E "^error" build_errors.log | sort | uniq -c | sort -rn

如果错误队列里出现大量重复错误，说明迁移流程本身有问题，而不是单个文件的问题。这时候应该停下来修改规则手册，重新生成受影响的批次，而不是围绕错误代码逐个打补丁。

行为一致性验证是最后一道关。每个失败测试分配给一个修复 Agent，由它同时检查新旧实现，定位差异并提交补丁，再由对抗式审查 Agent 复核。构建操作建议串行执行，避免多个 Agent 重复构建相互干扰。

7. 本篇常见错排查

报错一：401 Unauthorized。通常是 API Key 没配好。检查ANTHROPIC_API_KEY是否完整，是否有多余空格。重新在控制台创建一个 Key 再试。

报错二：连接超时或 DNS 失败。检查ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api，不要多加/v1之类的路径。网络环境本身要能正常访问该地址。

报错三：Agent 输出风格漂移。说明规则手册覆盖不足。把漂移的案例回写进手册，重新跑压力测试，不要直接进入批量阶段。

报错四：编译错误大量重复。不要逐个修。先归类根因，如果是规则问题就改手册，如果是依赖顺序问题就调整依赖图，然后重新生成批次。

报错五：测试通过但行为不一致。说明验收体系不够严。补充输出 diff、退出码、文件变化对比，确保测试能识别真实差异。

报错六：任务队列卡住不推进。检查脚本判断“完成”的条件是否过于严格，比如目标文件存在但内容为空也被算作完成。建议加上文件非空和编译通过双重判断。

8. 把迁移变成可重复的工程流程

大规模迁移真正难的从来不是写代码，而是让每一轮生成的结果都可验证、可回滚、可修正。规则手册统一实现边界，依赖图安排执行顺序，差距清单记录例外，任务队列和独立审查负责推进与校验。人类判断集中在前期——划定边界、设计验收体系、识别系统性偏差；Agent 承担大规模重复性的实现和修复。

如果你准备开始，建议先从一个小模块跑通完整流程：配置好 TaoToken 通道，写好规则手册骨架，用双翻译对比做压力测试，再进入批量迁移。接入相关的 Key 和文档在 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 和接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ；需要长期跑 Agent 调度的话，Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 更合适；想先验证模型对话效果，可以从模型对话 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 入手。Claude Code 相关的接入细节可以参考 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 里的说明。