Large-Scale Refactoring

Refactoring that touches dozens or hundreds of files requires a different approach than typical Claude work. Context management, verification, and coordination become critical.

The Challenge

Claude excels at focused tasks but struggles when:

Changes span 50+ files
Context fills with diffs
Verification requires running tests repeatedly
Consistency across files matters

The solution: chunking, verification, and fresh contexts.

The Phased Approach

Phase 1: Analysis

Before touching code, understand the scope:

> I want to rename all instances of `UserService` to `AccountService`
>
> First, just analyze:
> - How many files are affected?
> - What are the different types of changes needed?
> - Are there any tricky cases (dynamic imports, strings, etc.)?
>
> Don't make changes yet.

Claude produces a report. Save it:

> save this analysis to refactor-plan.md

Phase 2: Planning

Break the work into chunks:

> Based on the analysis, divide this into chunks of ~10 files each
> Group by:
> 1. Direct imports (highest risk)
> 2. Type references
> 3. Test files
> 4. Documentation
>
> Output as a checklist I can track

Phase 3: Execution by Chunk

Work through chunks in separate sessions:

# Chunk 1: Core imports
claude
> Implement chunk 1 from refactor-plan.md
> Only touch these files: [list from plan]
> Run tests after changes
exit

# Chunk 2: Type references
claude
> Implement chunk 2 from refactor-plan.md
exit

# Repeat for each chunk

Phase 4: Verification

Final verification in clean session:

> Search the entire codebase for any remaining instances of "UserService"
> Check for: strings, comments, variable names, file names

Chunking Strategies

By Dependency Layer

Layer 1: Core modules (change first)
    ↓
Layer 2: Services using core
    ↓
Layer 3: API/Routes using services
    ↓
Layer 4: Tests
    ↓
Layer 5: Documentation

Why: Changes flow down. Fixing core first prevents cascading breaks.

By Risk Level

High risk: Files with complex logic, many dependencies
Medium risk: Standard implementation files
Low risk: Tests, docs, config

Why: Tackle hard problems when context is fresh.

By File Count

# Simple rule: 10-15 files per session
Chunk 1: files 1-12
Chunk 2: files 13-24
Chunk 3: files 25-36

Why: Keeps context manageable, enables verification.

Git Strategies

Commit Per Chunk

# After each chunk
git add -A
git commit -m "refactor: rename UserService to AccountService (chunk 1/4)"

# Easy to revert if something breaks
git revert HEAD  # Undo just the last chunk

Branch Per Chunk

For very large refactors:

git checkout -b refactor/user-to-account-core
# Do chunk 1
git checkout main
git merge refactor/user-to-account-core

git checkout -b refactor/user-to-account-services
# Do chunk 2
# ...

The Safety Branch

Always keep a clean branch:

git checkout -b refactor/user-to-account
# Work happens here

# main stays clean until everything is verified

Verification Patterns

After Every Chunk

> run the test suite
> focus on tests related to the files we just changed

Type Checking

# After Python refactors
mypy src/

Search Verification

> search for any remaining instances of the old pattern
> include: imports, strings, comments, type hints

Integration Test

> start the dev server
> verify [specific functionality] still works

When Claude Loses Track

Signs Claude is struggling:

Makes the same change twice
Misses obvious instances
Introduces inconsistencies
Forgets the original goal

Solutions:

# Reset context
> /clear
> We're doing [refactor]. Here's the plan: [paste from plan.md]
> We've completed chunks 1-3. Now do chunk 4.

# Or start fresh session
exit
claude
> Continue refactor from refactor-plan.md
> Chunks 1-3 are done. Do chunk 4.

Subagents for Parallel Work

For independent chunks:

> Use subagents to parallelize:
> - Subagent 1: Refactor test files in tests/unit/
> - Subagent 2: Refactor test files in tests/integration/
> - Subagent 3: Update documentation
>
> These are independent and can run simultaneously.

Real Example: API Versioning

Migrating from /api/v1 to /api/v2 across 80 files:

## Analysis
- 80 files affected
- 45 route definitions
- 23 test files
- 12 documentation files

## Chunks

### Chunk 1: Route definitions (15 files)
- src/routes/users.py
- src/routes/products.py
- [...]
Verification: Routes respond at /api/v2

### Chunk 2: Client calls (12 files)
- src/services/api_client.py
- [...]
Verification: All internal calls use v2

### Chunk 3: Test updates (23 files)
- tests/routes/test_users.py
- [...]
Verification: Tests pass

### Chunk 4: Documentation (12 files)
- docs/api/users.md
- [...]
Verification: No v1 references in docs

Refactoring Types That Work Well

Type	Why It Works
Renames (class, function, variable)	Mechanical, searchable
Import restructuring	Pattern-based
Adding type hints	Independent per file
API version migrations	Clear before/after
Framework upgrades	Documented patterns

Refactoring Types That Need Care

Type	Challenge
Architecture changes	Requires human judgment
Logic refactoring	Each case is unique
Performance optimization	Needs measurement
Security fixes	Requires expertise

For these, use Claude for analysis and suggestions, but review carefully.