How I use Claude Code to refactor legacy code — without breaking anything

Every developer has that codebase. The one with the 2,000-line file, the functions named doStuff2_final_FINAL, the commented-out code from 2019 that nobody dares delete. Refactoring it feels impossible — one wrong move and production breaks.

Claude Code changes this. Here's my complete workflow for safe legacy refactoring.

The core problem with legacy refactoring

Traditional refactoring requires you to hold the entire system in your head. What calls this function? What does this global variable affect? What will break if I rename this class?

With legacy code, that mental model is usually incomplete. The original author is gone. The comments are wrong. The tests don't exist.

Claude Code gives you a second brain that can hold all of it simultaneously.

Step 1: Build the map before touching anything

Before a single line changes, I ask Claude Code to map the blast radius:

Do NOT change any code yet. I want to understand this codebase first.

Read these files: [list the files you want to refactor]

Tell me:
1. What does each function/class do?
2. What calls what? (call graph)
3. What are the riskiest parts — highest coupling, most dependencies?
4. What would break if I renamed X?
5. Are there any hidden side effects I should know about?

This takes 2-3 minutes and saves hours of debugging later. The map tells you where the landmines are.

Step 2: Identify the refactoring scope

With the map in hand, I ask Claude Code to recommend a refactoring plan:

Given this analysis, I want to refactor [specific goal — e.g., 'extract the payment logic from utils.js into its own module'].

Before touching any code:
1. List every file that will need to change
2. List every test that might break
3. What's the safest order to make these changes?
4. What's the minimum viable refactor that reduces risk while still improving the code?

Key phrase: minimum viable refactor. Don't try to fix everything at once. Legacy code got complex slowly — fix it slowly.

Step 3: Write tests for what exists (not what should exist)

This is the step most developers skip. Before refactoring, write tests that capture current behavior, even if that behavior is wrong:

Write characterization tests for these functions. Don't test what they SHOULD do — test what they ACTUALLY DO right now.

Goal: I need a safety net so I know if my refactor accidentally changes behavior. If the current behavior is wrong, I'll fix that separately — after I've stabilized the structure.

Characterization tests are your insurance policy. If they still pass after refactoring, you haven't accidentally broken anything.

Step 4: Refactor in micro-commits

Now Claude Code starts making changes — but in tiny, verifiable steps:

Make ONLY this change: [specific, isolated change]

After making the change:
1. Show me the diff
2. Run the characterization tests
3. Tell me if anything unexpected changed
4. Wait for my approval before the next change

I commit after each approved step. This gives me a clean rollback point if anything goes wrong.

Step 5: Handle the hard cases

Global variables

This codebase uses global variables extensively. Help me eliminate them safely.

For each global: tell me everywhere it's read and written, propose the safest replacement (module-level variable, passed parameter, or singleton), and estimate the risk level.

Deep callback nesting (callback hell)

This code has callbacks nested 6 levels deep. Help me convert it to async/await.

Do it in stages:
1. First, just identify the outermost callback and convert that
2. Run tests
3. Then move to the next level
Do NOT convert everything at once.

Undocumented magic numbers

Find all magic numbers in this file. For each one:
1. Try to infer what it represents from context
2. Suggest a named constant
3. Flag any you're uncertain about — I'll explain those myself

The rate limit reality

Large legacy codebases are token-hungry. A single 2,000-line file can exhaust Claude Code's context window before you finish the refactor.

My workaround: I use the SimplyLouie API endpoint as a fallback when Claude Code hits its limits. It's Claude-compatible (same ANTHROPIC_BASE_URL swap), $2/month, and keeps the session going without losing context.

For really large refactors, I also split the work across multiple Claude Code sessions — one session per module, with a shared CLAUDE.md that tracks what's been done and what's in progress.

The pattern that actually works

After dozens of legacy refactors, this is what I've learned:

1. Map before touching — understand the system before changing it
2. Characterization tests first — capture current behavior, not ideal behavior
3. One change at a time — micro-commits, not mega-PRs
4. Refactor structure, then behavior — never both at once
5. Keep the old code around — deprecated but not deleted, until tests prove the new code works

The developers who get burned by refactoring are the ones who try to improve structure AND fix bugs AND add features in the same PR. Claude Code makes it tempting to do everything at once. Resist that.

Refactor structure. Commit. Verify. Then fix behavior.

Tools that help

• CLAUDE.md with the refactor plan written out — keeps Claude Code on track across sessions
• Git worktrees — refactor in a branch, compare behavior against main
• The SimplyLouie API — for long sessions that exceed Claude Code's rate limits
• Characterization test frameworks — Jest, pytest, whatever your stack uses

Legacy code isn't scary when you have a second brain that can hold the entire system at once. Claude Code is that brain.

Running long refactor sessions? Claude Code's rate limits hit fast on large files. SimplyLouie gives you a $2/month Claude API endpoint — same models, no rate limit anxiety. 7-day free trial.