The Problem

This repository provides a structured kit for running large-scale code migrations with Claude Code, defaulting to structure-preserving translations (same architecture, new language). The primary pain point it addresses is systematizing the migration process across potentially hundreds of files, where manual translation would be error-prone and inconsistent. It is designed for estates where migrating code between languages requires maintaining functional equivalence while changing syntax and semantics.

What This Does

The kit contains prompts, templates, and scripts that guide a migration through six defined steps, from feasibility assessment to final parity validation. It defaults to structure-preserving migrations where the architecture and data structures remain the same across languages. The repository has 56 files across multiple directories: fixtures/ contains reference implementations in C, Python, and TypeScript; scripts/ holds the dependency mapping and processing logic; prompts/ provides the step-by-step guide; and templates/ offers configuration skeletons. The kit is referenced from a CLAUDE.md that gets imported into the target repository, and a skill can be installed to extend Claude Code's capabilities.

How It Is Wired

Execution starts at main in scripts/depmap_c.py:117, which reaches 8 functions and is called from 1 place. The internal call graph contains 13 resolved call edges between self-contained functions. Key entry points and their responsibilities:

  • scripts/depmap_c.py defines find_files, extract_edges, tarjan_scc, and main — 4 functions, reads or writes files via path.read_text
  • scripts/depmap_python.py defines find_py_files, module_name, build_module_index, resolve_import, and extract_edges — 8 functions
  • scripts/make_manifest.py defines main

The traced path from entry to filesystem effect is main -> extract_edges [filesystem via path.read_text], meaning the dependency mapping functions are where file system interaction occurs. The module graph shows no circular dependencies across the 7 internal modules analyzed, but the depmap scripts exhibit high branching density (40 branch points over 126 lines in depmap_c.py, depmap_python.py, and depmap_ts.mjs) and deep nesting (max indentation depth of 6), making control flow hard to follow.

How To Use It

Setup: Clone the kit into or adjacent to the target repository: git clone https://github.com/moses-y/code-migration-kit-with-claude-code ./migration-kit. Copy the kit's CLAUDE.md into the target repo's CLAUDE.md before steps begin. Optionally install the skill: cp -r migration-kit/skill ~/.claude/skills/code-migration, then replace [kit path] inside the installed SKILL.md.

Configuration: Copy templates/settings.json to the target repo's .claude/settings.json — this is required before prompt 03 and active through Step 4 (prompt 05). The README's templates/settings.README.md documents the settings format.

Running it: The workflow is driven by Claude Code, not a local CLI. After installing the skill and configuring settings, the user works through prompts/01-06 in order, one gate at a time. Step 1 uses scripts/depmap_* and prompts/01-02 to create the dependency map and rulebook. Step 2 (prompts/03-stress-test.md) validates rules via dual-translation bakeoff. Steps 3-6 handle the actual translation fan-out with judge validation.

Real-World Use

A team migrating a 50,000-line Python codebase to TypeScript would clone this kit, import its CLAUDE.md, and follow the six steps. First, they'd run the dependency mapping scripts (scripts/depmap_python.py) to understand the call graph and ordering constraints. Then, through the stress-test gate in prompt 03, they'd validate translation rules on a small subset before fanning out to the full codebase. The templates/inventory.tsv and templates/RULEBOOK.md would capture decisions about how specific Python constructs map to TypeScript equivalents, with the judge harness (built per prompts/00b-judge-setup.md if needed) providing the exit condition.

Code Health & Issues

  • HIGH — Duplicated code blocks: 14 repeated 6-line blocks across scripts/depmap_c.py and scripts/depmap_python.py. Extract shared helpers to DRY the repeated logic.
  • MEDIUM — Deep nesting x2: Max indentation depth 6 in scripts/depmap_c.py and scripts/depmap_python.py. Control flow is hard to follow; flatten with early returns/guard clauses.
  • MEDIUM — High branching density x4: 40 branch points over 126 lines across scripts/depmap_c.py, scripts/depmap_python.py, and scripts/depmap_ts.mjs. Decompose decision-heavy logic; consider table/strategy dispatch.
  • SDLC: No CI/CD pipeline detected — no automated build/test gate. Every change merges with nobody having run the build once. Tests are present but unguarded by automation.

The Bottom Line

This is a functional reference kit that successfully systematizes the migration process described in the accompanying blog post. The dependency mapping scripts and step-by-step prompts provide concrete scaffolding for large-scale migrations. However, the code quality in the depmap scripts is poor — high nesting and duplicated blocks make them hard to maintain or extend, and the absence of CI means no automated guardrails on changes. Teams should use this kit's process and templates but plan to refactor the scripts before integrating them into an automated pipeline.