Multi-File Refactoring

Why Multi-File Refactoring Is Hard

Traditional refactoring tools work syntactically — they find and replace text or AST nodes. They don't understand intent. Claude Code understands what you're trying to achieve and can handle edge cases, conditional logic, and semantic differences that fool regex-based tools.

Planning the Refactor First

Before touching a single file, ask Claude to plan:

I want to replace our custom fetch wrapper with the native fetch API across the entire codebase.
Before making changes, list all the files that use the wrapper, note any non-obvious usages,
and describe what the migration plan should look like.

Claude will audit the codebase and produce a migration checklist. Review it before proceeding.

Incremental Execution

For large refactors, don't try to do everything in one shot. Break it into phases:

Phase 1: Migrate the auth module only. Run tests after each file.
Phase 2: Migrate the API routes.
Phase 3: Migrate the UI components.

This keeps each step reviewable and reduces risk.

Handling Type Changes

When a refactor changes types (e.g., renaming an interface), Claude will:

1. Update the type definition
2. Find all usages via TypeScript's type system understanding
3. Update each usage in sequence
4. Run tsc --noEmit to verify no type errors remain

Rename the ApiResponse interface to ServiceResponse. Update all files that import or use it.
Run tsc after to verify.

Preserving Behavior

Always ask Claude to verify behavior is preserved:

After each file change, run the tests for that module before moving on.

Dead Code Removal

Refactors often reveal dead code:

After migrating all usages of the old wrapper, find and remove the wrapper itself
and any utilities that only it used.

Commit Checkpoints

For large refactors, create git commits after each phase:

After migrating the auth module, create a git commit with message
"refactor: migrate auth to native fetch (phase 1/3)"

This gives you clean rollback points throughout a large refactor.