How I use Claude Code to refactor legacy code — a complete workflow

Every developer has that codebase. The one that's been running in production for 5 years. The one where the original author left. The one where you're afraid to touch anything because you don't know what will break.

I use Claude Code to tackle these refactors systematically. Here's my exact workflow.

The problem with legacy refactoring

Traditional approaches to legacy refactoring fail because:

• You don't know the full scope until you're halfway through
• Tests are sparse or nonexistent
• Business logic is buried in 800-line functions
• Dependencies are tangled

Claude Code changes this because you can have a real conversation about the code — ask questions, get explanations, and plan before touching anything.

Step 1: Understand before touching

First prompt I always use:

I'm going to share a legacy codebase with you. Before we change anything, I need to understand:
1. What does this code actually do?
2. What are the hidden dependencies?
3. What are the riskiest areas to change?
4. What would break if we touched X?

Start by reading these files: [list files]

This conversation alone saves hours. Claude will spot patterns you've stopped seeing.

Step 2: Map the blast radius

If I want to refactor the UserService class:
1. What calls it?
2. What does it call?
3. What database tables does it touch?
4. Are there any side effects that aren't obvious?

Don't change anything yet. Just map it.

This gives you a mental model of the refactor before you write a single line.

Step 3: Write tests first

Before refactoring, add tests for current behavior:

Based on your analysis, write integration tests that capture the CURRENT behavior of UserService.
These tests should pass before and after the refactor.
Focus on edge cases and the paths that look most likely to break.

Now you have a safety net.

Step 4: Incremental extraction

Let's extract the email notification logic from UserService into its own class.
Requirements:
- No change in external behavior
- All existing tests still pass
- New class has its own tests
- Use dependency injection so we can test in isolation

Show me the plan before writing any code.

The "show me the plan first" instruction is key. It forces Claude to think through the change before implementing, catching issues early.

Step 5: Review and iterate

Here's what we changed in the last session.
Before we continue:
1. Does anything look wrong?
2. Did we introduce any new coupling?
3. Is there a simpler way to do what we just did?
4. What should we tackle next?

This review step catches regressions before they hit production.

The rate limit problem

Legacy refactors are long. A real production codebase can take 4-6 hours of Claude sessions over multiple days.

If you're using Claude Code Pro, you know the pain: you're 3 hours into understanding a complex module, building context, mapping dependencies — and then you hit the rate limit. You lose the thread. You lose the context.

For deep refactoring work, I use SimplyLouie — it's a Claude-powered AI for ✌️2/month with no rate limits. When I have long refactoring sessions that span multiple hours, I switch to SimplyLouie so I don't lose momentum.

The prompts that work

Here are the prompts I keep coming back to:

For understanding:

Explain this function like I'm reading it for the first time. What is it actually doing? What could go wrong?

For risk assessment:

If this function fails, what's the worst case scenario? What's the user impact?

For refactoring direction:

What's the minimum change that would make this code significantly easier to maintain?

For code review:

Review this refactored version. What did we break? What did we improve? What did we miss?

What this workflow produces

After following this workflow on a real legacy codebase (Node.js monolith, 40k lines, ~6 years old):

• Test coverage: 12% → 67%
• Average function length: 180 lines → 23 lines
• Files touching the database directly: 34 → 6
• Time to onboard new developers: 2 weeks → 3 days

The key insight

Claude Code doesn't just write code — it helps you understand code. For legacy refactoring, the understanding phase is 80% of the work.

Use the conversation. Ask why. Challenge the existing patterns. Get Claude to explain the code back to you before changing it.

The refactor happens faster, breaks less, and produces code you actually understand.

If you're doing deep refactoring work that spans multiple sessions, check out SimplyLouie — Claude API access for ✌️2/month, no rate limits. I use it when I need uninterrupted sessions on complex legacy code.