Claude Code Migration Kit: Templates for Large-Scale Language Migrations

What the Kit Is and Who It Is For

Large codebase language migrations with AI agents tend to fail in predictable ways: agents make inconsistent decisions across thousands of files, the rulebook is implicit, and verification is deferred until the end when it is too late to fix systematic errors. The Claude Code Migration Kit provides the scaffolding to avoid these failures: a six-step process with explicit gates, a shared rulebook, a dependency ordering script, and prompts that direct Claude Code agents rather than leaving decisions implicit.

The kit defaults to structure-preserving migrations, which the README defines as moving to a new language while keeping the same architecture and data structures. The README is specific about scope: this is the case where the process is mechanical enough to template. If you are redesigning while migrating, the README recommends reading the "If you're redesigning" section first, because parts of the kit change and one step becomes invalid for that scenario.

The primary audience is engineering teams running migrations measured in thousands to millions of lines. The README references Bun's 1M+ line Zig-to-Rust port as an example of a real migration the process was validated against.

The Six-Step Migration Process

The kit structures migration work into six gates. Each gate produces evidence and exits. Moving to the next gate requires your sign-off, not the agent's. The design is explicit about this: stopping is free because every queue is defined by what exists on disk, and resuming is a re-invocation.

Step 1 creates three artifacts in parallel: a dependency map (a deterministic script ordering which units to translate first, and finding cycles at both file and package granularity), a gap inventory (a flat table of every site where the target language demands something the source language let you leave implicit, such as ownership, lifetimes, nullability, or interface contracts), and the rulebook (every translation decision that could go two ways, decided once). The meta-rule for the rulebook: if two agents could answer differently, it goes in the rulebook.

Step 2 stress-tests the rulebook against real code before any fan-out. A bakeoff runs two translators in separate contexts: one follows the rules, one does not know they exist. Every difference becomes a verdict on a specific rule. A pilot then runs the production pipeline on a handful of the hardest files.

Step 3 fans out the translation across all units. An implementer plus two adversarial reviewers and a fixer per unit. The compiler waits until Step 4.

Step 4 runs one survey build, grading all output. The error list becomes a machine queue sliced by module. Fixers work without compiler access in this step.

Step 5 is a smoke test: Hello World first, then the cheapest end-to-end proof before the expensive test suite.

Step 6 runs the inherited test suite or a parity referee built against the old code.

The Kit's Files and How to Use Them

The kit is cloned inside or adjacent to the repository being migrated:

git clone <kit> ./migration-kit

The `CLAUDE.md` file from the kit is copied or `@`-imported into the target repository's `CLAUDE.md` before any other step. It is the operating manual that every Claude Code session reads. The optional skill installation:

cp -r migration-kit/skill ~/.claude/skills/code-migration

The feasibility prompt is the starting point:

# open Claude Code in the target repo and paste:
prompts/00-feasibility.md

The output is a read-only report: the case for migrating, three committed decisions (structure-preserving or redesign, what verification costs, whether tests survive), a sketch of the six steps for your repo, and a verdict. The README states that "Don't migrate" is a valid outcome and nothing else in the kit matters until that report says go.

The `templates/settings.json` must be copied to the target repo's `.claude/settings.json` before Step 3 begins. Prompts 03 and 04 check for it and stop without it.

The Rulebook and the Gap Inventory

The rulebook (`templates/RULEBOOK.md`) is the most important artifact. It is copied to `migration/RULEBOOK.md` in the target repository and contains every decision that translators could make two different ways, resolved once. Drafting it happens in a conversation with Claude; then agents survey the codebase for facts (how many struct fields, how many uses of a pattern tree-wide), and adversarial reviewers audit it for one mistake class each.

The README gives a concrete example of why the rulebook matters: Bun's actual migration prompt was a 576-line rulebook in PORTING.md plus a one-sentence kickoff. The template generalizes this pattern.

The gap inventory (`templates/inventory.tsv`) is a flat table of every site where the target language demands explicit handling of something the source language allowed implicitly. Implementers grep it during translation; it is not meant to be read top to bottom. The dependency map scripts in `scripts/depmap_*.py` and `scripts/depmap_*.mjs` produce the dependency ordering used in Step 1. The README notes a specific failure mode: Bun's file-level dependency graph was clean but the package-level graph had cycles that produced approximately 16,000 compile errors.

Limitations and Maintenance Status

The README is direct about scope: this kit handles structure-preserving migrations. Redesigns during migration invalidate part of the process. It also does not handle migrations of infrastructure, schemas, or APIs as distinct categories from code.

The judge requirement in Step 5 and Step 6 is a real constraint. The README states: "No judge, no exit condition." If the existing test suite imports internals that die with the old language, the `prompts/00b-judge-setup.md` prompt builds a portable parity harness. But building a parity harness is non-trivial work that the kit templates but does not automate.

The README states explicitly: "This repo is a companion to the blog post and is not actively maintained. Issues and PRs are not monitored." The last push was on 2026-07-08. There are no GitHub releases.

A comparable alternative is manually adapting the Bun PORTING.md approach for your own migration, using Claude Code without the kit's scaffolding. The kit's advantage over that approach is the structured six-step framework with explicit gates, the adversarial review step, and the validated settings.json permission structure that prevents agents from reaching outside the translation scope. The license field in the GitHub repository shows NOASSERTION, which means the license terms are unclear and should be checked before use in a commercial context.

Editorial conclusion

The migration kit is most useful to engineering teams that have already decided to migrate a large codebase from one language to another and want a proven process structure rather than starting from scratch. The six-step framework covers feasibility, rule creation, stress testing, fan-out translation, compilation, and behavior verification, with gate-based checkpoints between each. It is explicitly not useful for concurrent redesigns: the README states that if you are redesigning while migrating, parts of the kit change and one part becomes invalid. Run the feasibility prompt first, in your own repository, before deciding whether to proceed: "Don't migrate" is a documented valid outcome. The kit has no license statement (the GitHub license field shows NOASSERTION) and the README states it is not actively maintained as of the last push on 2026-07-08.

Frequently asked questions

Official sources

1. anthropics/code-migration-kit-with-claude-code on GitHub
2. Issues
3. README