The explore-plan-execute framework
Large refactors fail when the agent starts editing before it understands the blast radius. The fix is a strict three-phase approach where you keep Claude in plan mode until the map is complete — lean on the techniques from exploring codebases here — and only then switch to making edits.
1 · Explore
Plan mode. Map every file, class, function, dependency, and caller. No edits yet.
2 · Plan
Still plan mode. Produce an ordered list of changes that minimizes broken intermediate states.
3 · Execute
Switch to acceptEdits. Work the plan file by file, running tests after each.
Phase 1 — Explore (plan mode):
> [Plan mode] Analyze the entire authentication module. Map all the files, classes, and functions.
Identify all the dependencies and callers. I want to refactor from class-based to functional,
but I need to understand the full scope first.Phase 2 — Plan (still plan mode):
> Based on what you found, create a detailed refactoring plan. List every file that needs to change,
every function signature that changes, and the order of changes to minimize broken intermediate states.Phase 3 — Execute (switch to acceptEdits):
> Execute the plan. After each file, run the tests. If any test fails, fix it before moving on.Safe refactoring patterns
Most large refactors are combinations of four primitive operations. Naming the pattern explicitly in your prompt gives Claude a clear contract and keeps it from drifting into unrelated changes.
# Pattern 1: Rename + update all references
> Rename UserService to AuthService across the entire codebase. Update all imports,
all instantiations, and all type references.
# Pattern 2: Extract a new module
> Extract the email-related functions from UserService into a new EmailService.
Update all existing callers to use EmailService instead.
# Pattern 3: Change function signatures
> Add a required `requestId` parameter to all logging calls. Find every call site
and update it. Use a UUID generator if none is available at the call site.
# Pattern 4: Type migration
> Convert all uses of `any` type in src/ to proper TypeScript types.
Infer from usage context where possible.Keeping tests green throughout
The single most important guardrail is a tight test-driven verification loop. Tell Claude to run the suite after every file rather than once at the end — fixing a failure while the change is still small is cheap; untangling a hundred accumulated failures is not.
> Run tests after every file you modify. If tests fail, fix them immediately
rather than accumulating technical debt. Show me a status update after each batch of files.Tip: A green suite is your rollback insurance. Commit after each clean batch so any later failure has a recent, known-good checkpoint to revert to.
Handling breaking changes
When a refactor touches a public API that other services depend on, you can't just flip it. Ask Claude to add a deprecation wrapper that preserves the old interface while routing to the new implementation — buying downstream consumers time to migrate.
> This refactor changes a public API that other services depend on. Add a deprecation wrapper
that maintains the old interface while routing to the new implementation.
Add a comment marking the old interface for removal in v2.0.Practice: a real migration
Pick a module in your own codebase and migrate it from one pattern to another — callbacks to promises, classes to functions, REST to GraphQL — in a single Claude Code session. Run it through explore → plan → execute, keep tests green the whole way, and time it against your estimate for doing it by hand. The gap is usually the convincer.
Large-Scale Refactoring FAQ
What is the explore-plan-execute framework for refactoring?
It is a strict three-phase approach that separates understanding from change. You keep Claude in plan mode to explore and map every file, class, function, dependency, and caller, then still in plan mode produce an ordered list of changes that minimizes broken intermediate states, and only then switch to acceptEdits to work the plan file by file while running tests after each.
Why do large refactors with Claude Code fail?
Large refactors fail when the agent starts editing before it understands the blast radius. The fix is to keep Claude in plan mode until the map is complete — every file, dependency, and caller identified — and only then begin making edits, so changes happen against a full understanding of the scope rather than discovering surprises mid-edit.
What are the common safe refactoring patterns?
Most large refactors reduce to four primitive operations: rename and update all references, extract a new module and update callers, change function signatures across every call site, and migrate types. Naming the pattern explicitly in your prompt gives Claude a clear contract and keeps it from drifting into unrelated changes.
How do you keep tests green during a refactor?
Tell Claude to run the suite after every file rather than once at the end, and to fix any failure immediately while the change is still small. A green suite is your rollback insurance, so commit after each clean batch to give any later failure a recent, known-good checkpoint to revert to.
How do you handle breaking changes in a refactor?
When a refactor touches a public API that other services depend on, you cannot just flip it. Ask Claude to add a deprecation wrapper that preserves the old interface while routing to the new implementation, plus a comment marking the old interface for removal in a future version, which buys downstream consumers time to migrate.
Quick summary
- Separate understanding from change: explore and plan in plan mode, then execute
- Most refactors reduce to rename, extract, signature change, or type migration
- Run tests after every file and commit clean batches as rollback checkpoints
- Wrap breaking public-API changes in a deprecation shim to protect consumers