claude-code-migration-kit

# Claude Code Migration Kit > Skill by [ara.so](https://ara.so) — Claude Code Skills collection. A structured framework for running large-scale, total language migrations using Claude Code. This kit provides prompts, templates, and scripts for **structure-preserving migrations** (same architecture, new language) where the entire codebase crosses over and the old language is deleted. ## What It Does - Provides 8 sequenced prompts (feasibility → post-parity) for methodical migration - Generates dependency maps to order translation work - Creates rulebooks that decide every translation question once - Implements adversarial review (implementer + 2 reviewers + fixer per unit) - Uses parallel agent workflows with explicit sign-off gates - Validates through parity testing against original codebase **Core doctrine:** You don't fix the code — you fix the process that produced the code. ## Installation ```bash # Clone inside or adjacent to the repo you're migrating git clone https://github.com/anthropics/code-migration-kit-with-claude-code ./migration-kit # Install as a Claude Code skill (optional) cp -r migration-kit/skill ~/.claude/skills/code-migration # Copy the operating manual to target repo cp migration-kit/CLAUDE.md ./CLAUDE.md # Create migration workspace mkdir -p migration ``` ## The Six-Step Process ### Step 0: Feasibility Assessment **Always start here.** Paste `prompts/00-feasibility.md` with placeholders filled: ```markdown Source language: [Python] Target language: [Rust] Repository path: [./src] Approximate file count: [450] Primary reason for migration: [memory safety + performance] ``` The feasibility prompt produces: - Case for staying vs. migrating - Structure-preserving vs. redesign recommendation - Verification cost estimate - Custom six-step sketch for your repo - Go/no-go verdict **If redesigning instead of structure-preserving:** - Rulebook becomes a design document - Bakeoff step is invalid (use adversarial design review + disposable full runs) - Unit of work is module/subsystem, not file - Behavior matching still works unchanged ### Step 0b: Judge Setup (Critical) **You need a judge before Step 1.** If your test suite imports internals that will die with the old language, run `prompts/00b-judge-setup.md`: ```markdown I need to build a portable parity harness because our tests import [language]-specific internals. Source language: [Python] Target language: [Rust] Test suite path: [./tests] Public API surface: [CLI + HTTP API] ``` The judge must be: - Validated against the original code (zero failures) - Validated against deliberately broken code (catches intentional bugs) - Kept running throughout the migration - Language-agnostic (no imports of source internals) ### Step 1: Create Map and Rules Three parallel artifacts: **1. Dependency Map** ```python # For Python projects python migration-kit/scripts/depmap_python.py ./src > migration/depmap.json # For JavaScript/TypeScript node migration-kit/scripts/depmap_js.mjs ./src > migration/depmap.json # For C/C++ headers python migration-kit/scripts/depmap_c_headers.py ./include > migration/depmap.json ``` The map provides: - File-level dependency ordering (leaves to root) - Package-level cycle detection - Translation queue foundation **2. Rulebook** ```bash # Copy template cp migration-kit/templates/RULEBOOK.md ./migration/RULEBOOK.md ``` Use `prompts/01-create-rulebook.md` to draft it. The rulebook decides: - How each source construct translates to target - Naming conventions (snake_case → camelCase, etc.) - Error handling patterns - Memory management (if applicable) - Testing approach per translated unit **Meta-rule:** If two agents could answer differently, it goes in the rulebook. Example rulebook entry: ```markdown ## Error Handling **Source (Python):** ```python def parse_config(path): try: return json.load(open(path)) except FileNotFoundError: return {} ``` **Target (Rust):** ```rust fn parse_config(path: &Path) -> Result<Config, ConfigError> { let contents = fs::read_to_string(path) .map_err(|e| ConfigError::ReadFailed(path.to_owned(), e))?; serde_json::from_str(&contents) .map_err(ConfigError::ParseFailed) } ``` **Rule:** All Python exceptions become Result<T, E>. Map errors to domain-specific error types. ``` **3. Gap Inventory** Use `prompts/02-gap-inventory.md`: ```bash # Creates migration/inventory.tsv ``` A flat table of every site where the target language demands explicit decisions: - Ownership annotations - Lifetime parameters - Nullability markers - Interface contracts - Concurrency primitives Implementers grep it; nobody reads it cover-to-cover. **Generate manifest:** ```python # After dependency map exists python migration-kit/scripts/make_manifest.py \ migration/depmap.json \ > migration/manifest.tsv ``` ### Step 2: Stress-Test Rules **Before any fan-out**, run `prompts/03-stress-test.md`: **Bakeoff:** - Two translators in separate contexts - One follows rulebook, one doesn't know it exists - Diff inspector turns every difference into a verdict on a rule - Amendments queued for human approval, never self-applied **Pilot:** - Run production pipeline exactly as Step 3 will - Pick 3-5 nasty files (deepest dependencies, most complex) - Grade on obedience to rules, not output quality - Install `.claude/settings.json` BEFORE this pilot: ```bash cp migration-kit/templates/settings.json ./.claude/settings.json ``` **Critical:** `settings.json` must exist before Step 2 pilot and remain active through Step 4. See `templates/settings.README.md` for the rationale. ### Step 3: Translate Everything Install queue runner: ```bash # Make executable chmod +x migration-kit/scripts/queue_runner.mjs ``` Kick off with `prompts/04-translation-kickoff.md`: ```markdown Translate the codebase using the established rulebook. Manifest: migration/manifest.tsv Rulebook: migration/RULEBOOK.md Output directory: migration/translated/ Settings: .claude/settings.json (denies active) For each file in manifest order: 1. Implementer translates (follows rulebook exactly) 2. Adversarial reviewer 1 (checks rule compliance) 3. Adversarial reviewer 2 (checks mistake class X) 4. Fixer (applies amendments) 5. Write to migration/translated/<target_path> ``` **Don't run the compiler yet.** Settings bans: - Test execution - Build commands - File operations outside `migration/translated/` The queue runner processes `migration/manifest.tsv`: ```javascript // Queue runner handles resume automatically // Stop anytime, restart with same command node migration-kit/scripts/queue_runner.mjs \ --manifest migration/manifest.tsv \ --output migration/translated \ --rulebook migration/RULEBOOK.md ``` ### Step 4: Compile Use `prompts/05-survey-build.md` to run one **survey build**: ```bash # Start build daemon (human runs once) ./migration-kit/scripts/build_daemon.sh \ migration/translated \ "cargo build --all 2>&1" \ migration/build-output ``` The daemon: - Watches `migration/translated/` - Reruns build on changes - Emits numbered error files: `migration/build-output-r1.txt`, `r2.txt`, etc. - Slices errors by module (leaves to root) Fixers work **without compiler access**: ```markdown Fix compilation errors from migration/build-output-r{N}.txt Rules: - No running builds yourself (daemon owns it) - Read numbered error file - Fix issues in dependency order - Write fixes to migration/translated/ - Daemon reruns automatically - Consume next numbered file Repeat until clean build. ``` **If target typecheck is cheap (TypeScript, Go):** This step dissolves into Step 3 — edit `.claude/settings.json` to remove typecheck denies, run typechecker inside each unit's loop instead of batching. ### Step 5: Run It ```bash # Hello world ./migration/translated/bin/hello # Smallest end-to-end command ./migration/translated/bin/app --version # Smoke tests (cheap proofs before expensive ones) ./migration/translated/bin/app test-basic-operation ``` ### Step 6: Match Behavior Your judge from Step 0b decides the gate: **If tests hit public surface (CLI/API):** ```bash # Run new tests against new code pytest migration/translated/tests/ # Triage failures by running against old code pytest tests/ # Original suite on original code # Classify: regression / inherited / environment # Burn down regression queue ``` **If using parity harness:** ```bash # Run harness against both python migration/parity_harness.py --target old > old_output.json python migration/parity_harness.py --target new > new_output.json # Diff results diff old_output.json new_output.json ``` **Done gate:** - Every parity test passes - Original suite re-run on original code with zero inherited failures - Both counts documented in final report **After parity**, use `prompts/06-post-parity.md`: ```markdown Burn down deferred markers: - BUG(port): [count from grep] - TODO(port): [count from grep] - PERF(port): [count from grep] Each fix: - Own flagged commit - Proved by parity re-run - Documents why it was deferred ``` ## Configuration **Settings File (`.claude/settings.json`):** ```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" } } ``` **Timeline:** - Installed before Step 2 pilot - Active through Step 4 - Test denies re-activated for Step 6 fix loops - If Step 4 dissolves into Step 3 (cheap typecheck), remove typecheck denies ## Real Code Example: Python → Rust Migration **Original Python (src/parser.py):** ```python class ConfigParser: def __init__(self, path): self.path = path self.data = {} def load(self): try: with open(self.path) as f: self.data = json.load(f) except FileNotFoundError: self.data = {"default": True} return self.data def get(self, key, default=None): return self.data.get(key, default) ``` **Rulebook Entry:** ```markdown ## Class Translation **Python classes → Rust structs + impl blocks** - `__init__` → `new()` constructor - Instance methods → `&self` methods - Exceptions → Result<T, E> - Optional args → Option<T> ``` **Translated Rust (migration/translated/src/parser.rs):** ```rust use std::collections::HashMap; use std::fs; use std::path::{Path, PathBuf}; use serde_json; #[derive(Debug)] pub enum ConfigError { ReadFailed(PathBuf, std::io::Error), ParseFailed(serde_json::Error), } pub struct ConfigParser { path: PathBuf, data: HashMap<String, serde_json::Value>, } impl ConfigParser { pub fn new(path: impl AsRef<Path>) -> Self { Self { path: path.as_ref().to_owned(), data: HashMap::new(), } } pub fn load(&mut self) -> Result<&HashMap<String, serde_json::Value>, ConfigError> { match fs::read_to_string(&self.path) { Ok(contents) => { self.data = serde_json::from_str(&contents) .map_err(ConfigError::ParseFailed)?; } Err(e) if e.kind() == std::io::ErrorKind::NotFound => { self.data.insert("default".to_string(), serde_json::json!(true)); } Err(e) => return Err(ConfigError::ReadFailed(self.path.clone(), e)), } Ok(&self.data) } pub fn get(&self, key: &str) -> Option<&serde_json::Value> { self.data.get(key) } } ``` ## Common Patterns ### Resumable Workflows Every queue is defined by what exists on disk: ```bash # Stop anytime (Ctrl+C) # Resume by re-running same command node migration-kit/scripts/queue_runner.mjs --manifest migration/manifest.tsv ``` Stopping is free. Resuming is re-invocation, not recovery. ### Sign-Off Gates Prompts end with gates, not auto-continue: ```markdown === GATE === Sign-off required to proceed to Step 3. Evidence: - Bakeoff diff: migration/bakeoff-diff.md - Pilot results: migration/pilot-results.md - Proposed amendments: migration/rule-amendments.md Your approval kicks off Step 3 translation fan-out. ``` **Your sign-off = starting the next prompt.** ### Adversarial Review Each unit gets 3 reviewers with different mandates: ```python # In translation loop reviewers = [ {"role": "rule_compliance", "rejects_on": "any rulebook deviation"}, {"role": "safety", "rejects_on": "memory unsafety, data races"}, {"role": "performance", "rejects_on": "allocations in hot path"}, ] ``` ### Dependency Map Usage ```python # Check if file is ready to translate import json