Legacy Code Retrofit Kit
A three-phase playbook for safely modernizing any existing codebase with Claude Code — without context explosion, hallucinated dependencies, or out-of-scope changes.
What it is
A three-phase playbook and toolkit for safely introducing Claude Code agents into an existing, real-world codebase — without the context explosion, hallucinated dependencies, and out-of-scope changes that make standard approaches unreliable on legacy code.
Most Claude Code tutorials assume greenfield. Legacy code is harder: high cyclomatic complexity, undocumented tribal knowledge, and enough surface area to exhaust context before the agent understands what it is working with. This kit was built specifically for that situation.
What's inside
- ✓**Phase 1 — Analysis**: A CLAUDE.md that instructs Claude to map dependencies, identify hotspots, and document hidden business logic before touching a single line of code
- ✓**Phase 2 — Transformation**: Module-by-module refactor prompts with hard scope constraints — the agent changes what you point it at, and nothing else
- ✓**Phase 3 — Validation**: Automated test generation before and after each module, so you can verify nothing broke
- ✓"Surgical changes" guardrail config: prevents agents from touching out-of-scope code during refactors
- ✓Context-chunking strategy for projects over 100K lines of code
- ✓Three worked examples: Python Django, Node.js Express, PHP Laravel
What you get
legacy-code-retrofit-kit/
phase-1-analysis/
CLAUDE.md — dependency mapping
prompts/ — hotspot identification
phase-2-transform/
CLAUDE.md — surgical refactor config
prompts/ — module-by-module patterns
phase-3-validate/
CLAUDE.md — test generation
prompts/ — regression checks
guardrails/ — scope constraints
examples/
django/
express/
laravel/
README.mdReviews
“We have a 6-year-old Rails monolith. The context-window strategy in the CLAUDE.md and the chunked summarisation hooks meant Claude could actually navigate it without hallucinating file paths.”
“The dependency-map generation and the incremental eval approach are clever. Took me half a day to adapt to our stack — the architecture notes made it obvious where the seams were.”