April 4, 2026Claude7 min read

Using Claude to plan a large codebase refactor

Published April 4, 20267 min read

Large refactors fail for predictable reasons: underestimated scope, no clear migration path, and surprises discovered mid-way that invalidate the original plan. I now run every significant refactor through a Claude planning session before writing a single line. The session surfaces hidden dependencies, produces a phased migration plan, and identifies the tests that need to pass at each phase. The refactor itself is still hard — but it is no longer full of surprises.

Step 1: Context dump

The first prompt gives Claude the full picture of what we are working with. I paste the most relevant files — the module being refactored, its entry points, its tests, and the calling code that will be affected.

prompt

I need to plan a refactor. Here is the context:

GOAL: Migrate our authentication system from JWT stored in localStorage to httpOnly cookies with refresh token rotation.

CURRENT CODE:
[paste auth.ts — current JWT implementation]
[paste AuthContext.tsx — React context that wraps auth]
[paste api.ts — axios instance with auth header injection]
[paste login.tsx — login form component]

CONSTRAINTS:
- Must maintain backward compatibility for existing mobile app clients for 3 months
- Zero downtime migration — cannot have a maintenance window
- Test coverage must not decrease

Analyse the current implementation. Tell me:
1. What will break when we make this change
2. Hidden dependencies I may not be thinking about
3. The riskiest part of this migration

This first step almost always surfaces something I had not considered. In one recent refactor, Claude pointed out that our password reset flow was bypassing the AuthContext entirely and directly reading from localStorage — something I would have discovered mid-refactor and which would have cost a day to fix. With the heads-up, it was a thirty-minute addition to the plan.

Step 2: Phase breakdown

prompt

Given the analysis above, design a phased migration plan. Requirements for each phase:
- Each phase must leave the codebase in a deployable state
- Each phase should take no more than one sprint (two weeks) to implement
- Each phase must have a clear rollback plan if something goes wrong
- Specify what should be tested at the end of each phase before moving to the next

Also tell me: what is the minimum viable phase 1 if we need to ship something in one week?

The "deployable at each phase" requirement is the most important constraint. Refactors that leave the codebase in a broken intermediate state are how teams end up in months-long migration hell. Claude enforces this constraint in the plan.

Step 3: Risk matrix

prompt

Create a risk matrix for this migration with:
- Risk name
- Likelihood (low/medium/high)
- Impact (low/medium/high)
- Mitigation strategy
- How to detect if this risk has materialised (what monitoring alert or test failure would indicate it)

Focus on production risks — things that would affect live users — not just development complexity.

The detection column is what makes this useful. "Auth tokens are not being rotated correctly" is a risk. "How would I know?" is the question most engineers skip. Claude's answer: "Track the ratio of refresh token requests to access token requests in your API metrics. If refresh tokens are not being issued, the rotation is broken." That monitoring check is now in our runbook.

Step 4: Interface design before implementation

prompt

Design the new interface for the authentication module. I want the TypeScript types for:
1. The auth context value (what components will consume)
2. The cookie structure (what gets set in the httpOnly cookie)
3. The refresh token rotation contract (what the API endpoint sends and receives)
4. The error types (authentication errors a component needs to handle)

Design for the final state, not the migration path. Once I approve these types, I will start implementation.

Designing types before implementation is the most underrated practice in large refactors. If you define the target interface first, every phase of the migration is measured against "does this bring us closer to the final interface?" It prevents the common failure mode of refactoring yourself into a different mess.

Step 5: Test plan

prompt

Generate a test plan for this migration. For each category, list specific test cases (not just "test authentication"):

1. Unit tests for the new auth module
2. Integration tests for the cookie/refresh token flow
3. E2E tests for critical user paths (login, logout, session expiry, password reset)
4. Backward compatibility tests (verifying old mobile clients still work during the transition period)
5. Performance tests (refresh token rotation should not add perceptible latency)

Format as a Markdown checklist I can add to the PR description.

Step 6: Implementation order

prompt

Given the phases above, tell me the exact order to implement files in phase 1. For each file:
- The specific changes to make
- Whether it is a new file, modification, or deletion
- Any gotchas or non-obvious things to be careful about

I want to be able to hand this to another engineer with less context and have them implement it correctly.

What this process is not

Claude does not write the code in this workflow. It plans. The implementation is still your job, and Claude's plan will have gaps that the code reveals. But those gaps are far smaller than the gaps you would find without a plan.

Two numbers from our team: the average large refactor before this process took 6-8 weeks. After: 3-4 weeks. The time saved is not in the coding — it is in the "wait, I didn't realise X depended on Y" moments that used to cost days each.

One planning session, one hour, thirty minutes of prompts. It is the highest-leverage hour I spend on any significant feature.