Originally published at claudeguide.io/claude-code-refactoring-guide

Claude Code Refactoring Large Codebase: Strategy and Workflow (2026)

To refactor a large codebase with Claude Code, decompose the work into independently verifiable slices — one module or one concern at a time — run tests after each slice, and never ask Claude to refactor more than ~400 lines in a single operation. This incremental approach keeps diffs reviewable, prevents cascading failures, and lets you stop safely at any point. This guide covers the full strategy: scoping, prompt patterns, test gates, and rollback procedures.

Why Large-Codebase Refactoring Fails Without a Strategy

The most common failure mode: asking Claude to "refactor the entire auth module" and receiving 2,000 lines of changes that are impossible to review, break three tests, and introduce subtle regressions.

Effective refactoring with Claude requires treating it like a junior engineer — give it a tightly scoped task, review the output, run tests, then move to the next task. At a 50-engineer company using Claude Code for a legacy Python monolith migration, teams that used the slice-and-gate strategy completed 3.4x more refactoring per sprint than teams that used freeform "refactor everything" prompts.

Phase 1: Scope and Decompose

Before writing a single prompt, create a refactoring map.

Step 1: Generate a dependency graph

# Python: use pydeps or import-linter
pip install pydeps
pydeps src/auth --max-bacon=3 --show-deps-only

# Node.js: use madge
npx madge --image graph.svg src/

Step 2: Identify high-value, low-risk targets first

Ask Claude Code to prioritize for you:

Analyze the files in src/auth/ and rank them by:
1. Complexity (cyclomatic complexity proxy: long functions, deep nesting)
2. Test coverage (check if tests/ has matching test files)
3. Number of dependents (which files import this one)

Output a markdown table: File | Lines | Has Tests | Dependent Count | Priority

Step 3: Define your slices

A good refactoring slice:

• Touches 1 file or 1 clear concern
• Has existing tests OR can have new tests written first
• Produces a diff under 200 lines

Write your slice list to a file before starting:

# refactor-plan.md
## Auth Module Refactoring — April 2026

Slice 1: Extract UserValidator class from user.py (lines 45–120)
Slice 2: Replace manual DB session management with context manager in db.py
Slice 3: Convert synchronous HTTP calls to async in external_api.py
Slice 4: Standardize error types to use AuthError hierarchy

Phase 2: Prompt Patterns That Work

Pattern 1: Extract and Replace

Best for pulling a tightly coupled block into its own class or function.

Here is src/auth/user.py. Lines 45–120 contain validation logic
mixed into the UserService class.

Task:
1. Extract that validation logic into a new class: UserValidator(email: str, password: str)
2. Replace the inline calls with UserValidator(...).validate()
3. Keep method signatures unchanged — no downstream breakage
4. Do NOT change anything outside lines 45–120 and their call sites

Output ONLY the modified user.py. No explanations.

The "no explanations" instruction is important — it keeps Claude focused on code output and prevents verbose commentary padding responses.

Pattern 2: Type Annotation Pass

Safe, mechanical, and high-value for Python codebases.

Add full type annotations to every function in src/utils/helpers.py.
Rules:
- Use Python 3.10+ syntax (X | None instead of Optional[X])
- Do not change any logic — only add annotations
- Add `from __future__ import annotations` at top if missing
- If a type is genuinely unknown, use Any and add a # TODO: narrow type comment

Pattern 3: Test-First Refactoring

When the target has no tests, write them before refactoring.

Here is src/payments/calculator.py with no tests.

Step 1: Write tests/test_calculator.py covering:
- All public methods
- Edge cases: zero values, negative inputs, currency rounding
- At least one test per function

Do NOT write the refactored code yet. Just the test file.

Run the tests to confirm they pass against the current code, then proceed with the refactoring.

Phase 3: The Test Gate Workflow

Never move to the next slice without passing the test gate.

# After each Claude Code change:
# 1. Review the diff
git diff src/auth/user.py | head -100

# 2. Run affected tests
pytest tests/test_user.py -v

# 3. Run full suite (fast check)
pytest tests/ -x --timeout=30

# 4. Commit the slice
git add src/auth/user.py tests/test_user.py
git commit -m "refactor: extract UserValidator from UserService (slice 1/8)"

Committing each slice separately creates a clean rollback path. If slice 4 breaks something, git revert takes you back to after slice 3 — not all the way to the beginning.

Phase 4: Handling Complex Scenarios

Renaming across many files

The function `get_user_data()` in src/db/queries.py needs to be renamed
to `fetch_user_record()` to match our new naming convention.

Find all call sites in src/ (I will provide the grep output below) and
update them. Do NOT change any logic, only rename.

Grep output:
src/auth/login.py:    data = get_user_data(user_id)
src/api/routes.py:    result = get_user_data(request.user_id)
src/jobs/sync.py:    user = get_user_data(job.user_id)

Always provide the grep output explicitly rather than asking Claude to grep — it prevents hallucinated file paths.

Breaking circular imports

src/models/user.py and src/services/auth.py have a circular import.
user.py imports AuthToken from services/auth.py (line 3).
services/auth.py imports User from models/user.py (line 1).

Resolve by:
1. Creating src/models/auth_token.py with only the AuthToken class
2. Updating both files to import from the new location
3. Do NOT change any other logic

Output all three files.

Replacing a deprecated pattern site-by-site

We are migrating from our old logger (import logger from utils.log)
to the new structured logger (from structlog import get_logger).

Migrate ONLY src/services/payment.py. Leave all other files unchanged.
Replace every usage of logger.info/warn/error with the structlog equivalent.
The new structlog calls use keyword arguments: log.info("message", key=value).

Phase 5: Context Management for Large Files

Claude Code has a context window limit. For files over 600 lines, send only the relevant section:

# Show Claude only lines 200–350 of a large file
sed -n '200,350p' src/large_module.py

In your prompt:

Here is src/large_module.py lines 200–350. This is the payment processing
section. Context: the class PaymentProcessor is defined at line 45 (not shown).

Refactor the process_charge() method (lines 212–280) to:
1. Extract the retry logic into a separate _retry_with_backoff() method
2. Add type annotations
3. Replace the bare except: with except (PaymentError, NetworkError):

Return only the modified lines 200–350.

For extended context strategies, see the Claude Code Complete Guide.

Rollback and Recovery

Maintain a safe point before each major slice:

# Tag before starting a refactoring sprint
git tag refactor-checkpoint-2026-04-29

# Roll back to checkpoint if something goes wrong
git reset --hard refactor-checkpoint-2026-04-29

If you're mid-slice and Claude's output introduced a bug:

# Discard Claude's changes to a specific file
git checkout -- src/auth/user.py

# Start over with a more constrained prompt

The fastest way to recover is a clean checkout — don't try to have Claude fix its own broken output across multiple turns. Reset and reprompt with tighter constraints.

Measuring Progress

Track refactoring outcomes before and after each sprint:

# Complexity: use radon for Python
pip install radon
radon cc src/auth/ -a -s

# Lines of code changes
git diff --stat refactor-checkpoint-2026-04-29 HEAD

# Test coverage delta
pytest tests/ --cov=src/auth --cov-report=term-missing

A good refactoring sprint should: decrease average cyclomatic complexity, maintain or increase test coverage, and reduce total lines of code (consolidation, not expansion).

For integrating refactoring into automated pipelines with Claude, see Claude Code CI/CD Integration.

Frequently Asked Questions

How many lines can Claude Code safely refactor in a single prompt?

For reliable, reviewable output, keep each refactoring operation under 400 lines of changes. Beyond that, diffs become difficult to review and the risk of subtle regressions increases. For larger changes, decompose into multiple sequential slices — each with its own test gate before proceeding.

Should I write tests before or after refactoring with Claude?

Always before, when possible. Tests written before refactoring serve as a behavioral contract — if they pass before and after, Claude preserved the semantics. If the code has no tests, use Claude to write them first, verify they pass against the current code, then proceed with refactoring.

How do I prevent Claude from changing things I didn't ask it to change?

Be explicit in your constraints: "Do NOT change anything outside lines X–Y and their call sites." Also use the instruction "Output ONLY the modified [filename]" to prevent Claude from returning entire files with unrequested changes. Review diffs carefully with git diff.

What is the best model to use for refactoring tasks?

For mechanical refactoring (renaming, type annotations, pattern replacement), Claude Haiku 3.5 is fast and cost-effective. For complex architectural changes (circular import resolution, class extraction with semantic judgment), use Claude Sonnet. See Haiku vs Sonnet vs Opus: Which Model? for a decision framework.

How do I handle refactoring when the codebase has no tests?

Follow the test-first pattern: ask Claude to generate tests for the current behavior before touching any logic. Run those tests to confirm they accurately describe existing behavior. Then refactor and rerun. This creates a safety net even if the original codebase had zero coverage.

Can Claude Code refactor across multiple files in one operation?

Yes, but only for tightly related changes (like a rename across call sites). For structural changes affecting multiple files, always do it one file at a time — it produces better output and is far easier to review and debug if something goes wrong.