claude-code-migration-kit

用途

Claude Code Migration Kit 是一个用于在 Claude Code 中运行大规模、整体性语言迁移的结构化框架。它面向“结构保持型迁移”（structure-preserving migration）：架构保持不变、换用新语言、整个代码库跨语言迁移、旧语言代码被删除。

它的核心准则是：你不去修代码——你去修产生代码的流程。（You don't fix the code — you fix the process that produced the code.）

主要能力

提供 8 个按顺序排列的提示词（从可行性评估到 post-parity），用于有条理地推进迁移
生成依赖图，用于排列翻译工作的顺序
创建规则手册（rulebook），一次性决定所有翻译问题
实现对抗式审查（每个单元由实施者 + 2 名审查者 + 修复者参与）
使用并行代理工作流，并设有明确的签核门禁（sign-off gates）
通过与原始代码库进行对照测试（parity testing）来验证

使用方式

安装

# 在正在迁移的仓库内部或相邻处克隆
git clone https://github.com/anthropics/code-migration-kit-with-claude-code ./migration-kit

# 作为 Claude Code 技能安装（可选）
cp -r migration-kit/skill ~/.claude/skills/code-migration

# 将操作手册复制到目标仓库
cp migration-kit/CLAUDE.md ./CLAUDE.md

# 创建迁移工作区
mkdir -p migration

六步流程

第 0 步：可行性评估。 始终从这里开始。填入占位符后粘贴 prompts/00-feasibility.md。可行性提示会产出：保留 vs. 迁移的论证、结构保持 vs. 重设计的建议、验证成本估算、为你的仓库定制的六步草稿、go/no-go 结论。若选择重设计而非结构保持：规则手册变为设计文档；bakeoff 步骤失效（改用对抗式设计评审 + 一次性完整运行）；工作单元是模块/子系统，而非文件；行为匹配仍然不变。

第 0b 步：裁判设置（关键）。 在第 1 步之前你需要一个裁判。如果你的测试套件导入了将随旧语言一起消失的内部实现，运行 prompts/00b-judge-setup.md。裁判必须：针对原始代码验证通过（零失败）、针对故意破坏的代码验证通过（能捕获刻意注入的 bug）、在整个迁移过程中持续运行、与语言无关（不导入源语言内部实现）。

第 1 步：创建依赖图与规则。 三份并行产物：依赖图、规则手册、缺口清单。依赖图脚本示例：

python migration-kit/scripts/depmap_python.py ./src > migration/depmap.json
node migration-kit/scripts/depmap_js.mjs ./src > migration/depmap.json
python migration-kit/scripts/depmap_c_headers.py ./include > migration/depmap.json

规则手册用 prompts/01-create-rulebook.md 起草，决定每种源构造如何翻译为目标语言、命名约定、错误处理模式、内存管理、每个翻译单元的测试方法。元规则：如果两个代理可能给出不同答案，就写进规则手册。 缺口清单使用 prompts/02-gap-inventory.md，生成 migration/inventory.tsv。之后生成清单：

python migration-kit/scripts/make_manifest.py migration/depmap.json > migration/manifest.tsv

第 2 步：压力测试规则。 在任何 fan-out 之前运行 prompts/03-stress-test.md。Bakeoff：两个翻译器在各自上下文中，一个遵循规则手册，一个不知道它存在，差异检查器把每个差异变成对某条规则的裁定，修正案排队等待人工批准，绝不自行应用。Pilot：严格按第 3 步的方式运行生产流水线，挑选 3-5 个棘手文件，按对规则的服从度而非输出质量评分。在此 pilot 之前安装 .claude/settings.json。settings.json 必须在第 2 步 pilot 前存在，并持续活跃到第 4 步。

第 3 步：翻译全部内容。 安装队列运行器：

chmod +x migration-kit/scripts/queue_runner.mjs

用 prompts/04-translation-kickoff.md 启动。每个文件依次：实施者翻译 → 对抗审查者 1（检查规则遵从）→ 对抗审查者 2（检查某类错误）→ 修复者 → 写入 migration/translated/<target_path>。此时不要运行编译器。队列运行器会自动处理续跑：

node migration-kit/scripts/queue_runner.mjs \
  --manifest migration/manifest.tsv \
  --output migration/translated \
  --rulebook migration/RULEBOOK.md

第 4 步：编译。 用 prompts/05-survey-build.md 运行一次 survey build。构建守护进程监视 migration/translated/，变更时重跑构建，输出编号错误文件。修复者在无编译器访问权限下工作，按依赖顺序修复，直到构建干净。如果目标语言类型检查很便宜（TypeScript、Go），此步骤可并入第 3 步。

第 5 步：运行它。 从 hello world 开始，再到最小端到端命令，最后是冒烟测试。

第 6 步：匹配行为。 由第 0b 步的裁判决定门禁。若测试命中公共接口（CLI/API），对新代码运行新测试，再对旧代码运行原始套件以分类失败：回归/继承/环境。若使用对照 harness，则分别对旧、新运行并 diff。完成门禁：每个对照测试通过；原始套件在原始代码上重跑零继承失败；两个计数都记录在最终报告中。之后用 prompts/06-post-parity.md 清理延迟标记（BUG(port)、TODO(port)、PERF(port)）。

配置

设置文件 .claude/settings.json 示例：

{
  "deny_operations": {
    "test_execution": true,
    "build_commands": true,
    "file_operations_outside_workspace": true
  },
  "migration": {
    "workspace": "migration/translated",
    "rulebook": "migration/RULEBOOK.md",
    "manifest": "migration/manifest.tsv"
  }
}

时间线：第 2 步 pilot 前安装；持续活跃至第 4 步；第 6 步修复循环重新启用测试禁止；若第 4 步并入第 3 步，移除类型检查禁止。

资料还包含完整的 Python → Rust 迁移示例（原 Python 解析器、规则手册条目、翻译后的 Rust 代码）、常见模式（可续跑工作流、签核门禁、对抗式审查、依赖图用法）以及故障排查章节。

适用场景

需要整体性、结构保持的语言迁移（同一架构，新语言，旧代码删除）
希望用结构化提示词、依赖映射和对抗式审查来降低迁移风险
希望以对照测试作为完成门禁的项目

限制

资料明确指出以下情况不适用本套件：

增量迁移（JavaScript → TypeScript）：目标语言是超集，逐文件采用即可
全新重写：没有现有代码库可供保留结构
小型代码库（资料在“<”处截断，未提供完整阈值）

若可行性提示给出“不要迁移”的结论，这是有效结果，可选方案包括：保留当前语言、增量采用（TypeScript 超集模式）、完全重写。本套件专为整体、结构保持的迁移而设，若不属于此场景，投入产出比不成立。

此外，资料中部分内容（如小型代码库的完整判定标准、官方文本）暂未提供。

技能介绍

用途

主要能力

使用方式

安装

六步流程

配置

适用场景

限制