Refactoring is where Claude Code earns its keep on large projects. Writing new code is fast with any AI assistant — but refactoring safely, maintaining behavior while improving structure, is genuinely difficult. Claude Code handles it well because it reads and understands existing code rather than just generating from a description.

This guide covers systematic refactoring workflows for real codebases: legacy code, large files, naming inconsistencies, duplicated logic, and outdated patterns.

Why Refactoring Is Different from New Code

With new code, the risk is low — if it doesn’t work, you rewrite it. With refactoring, you’re modifying code that’s already running in production. The risk is behavioral regression: changing what the code does while trying to change only how it does it.

The three rules for safe refactoring with Claude Code:

Tests must exist before you start — if they don’t, write them first (see our testing guide)
Refactor in small steps — don’t ask Claude to rewrite 500 lines at once
Verify behavior between steps — run tests after each change

Claude Code follows these rules well if you enforce them in your CLAUDE.md.

Setting Up for Refactoring

Add refactoring constraints to your CLAUDE.md:

## Refactoring Rules
- Never change behavior during refactoring — only structure
- Break refactors into steps that pass tests independently
- Flag if a refactor would require changing tests (may indicate behavioral change)
- Prefer small, named extractions over large rewrites
- Keep git commits small: one logical change per commit

See the full CLAUDE.md guide for more on setting up project context.

Workflow 1: Extracting Large Functions

The most common refactoring need: a 200-line function that does too many things.

Step 1: Analyze First

Before changing anything:

Read this function and identify all the distinct responsibilities it has.
Don't write any code yet — just describe what it does in bullet points
and suggest where the extraction boundaries should be.
[paste 200-line function]

Claude returns something like:

Lines 1-30: Input validation
Lines 31-80: Database query construction
Lines 81-130: Data transformation
Lines 131-160: Cache invalidation
Lines 161-200: Response formatting

Now you have a plan before touching anything.

Step 2: Extract One Piece at a Time

Extract the input validation piece (lines 1-30) into a validateInput function.
Keep the original function calling it. Don't change any other behavior.

Run your tests. Commit if they pass. Repeat for each piece.

Step 3: Name the Extracted Functions Well

The function I just extracted is called validateInput, but reviewing it again,
it actually validates AND normalizes the input (trims whitespace, lowercases email).
Suggest a better name and update all call sites.

Claude suggests validateAndNormalizeInput or prepareInput and updates every reference.

Workflow 2: Eliminating Duplication

Duplicated code is a maintenance burden — fix one bug, remember to fix it in three places. Claude Code finds and consolidates duplication effectively.

Search this codebase for duplicated logic.
I suspect there are multiple places doing similar things with 
date formatting and user permission checking.
List the duplication you find — don't fix it yet.

Claude scans the codebase and returns a map of duplication with file locations. Then you decide what to consolidate:

The three date formatting patterns at utils/dates.ts:14, 
components/UserCard.tsx:45, and api/reports.ts:112 
should all use the same function.
Create a formatDate utility and update all three call sites.
Preserve the exact format strings each one uses — don't standardize them.

The “don’t standardize” instruction matters. Claude might see they all use slightly different formats (long date, short date, ISO) and decide to “clean up” by making them all use one format — changing behavior. Being explicit prevents that.

Workflow 3: Modernizing Legacy Code

Older codebases have patterns that were fine at the time but create friction now: callbacks instead of async/await, var instead of const/let, class components instead of hooks (in React), direct DOM manipulation in jQuery.

Callbacks to Async/Await

Convert this callback-style function to async/await.
Keep error handling equivalent — map each error callback 
to a try/catch that handles the same errors.
[paste callback function]

Specify error handling explicitly — Claude will faithfully convert errors unless you tell it what to do with them.

Promise Chains to Async/Await

This promise chain has 8 .then() blocks and 3 .catch() handlers.
Convert to async/await. Keep the exact same error handling behavior —
if the first catch currently swallows the error and continues,
keep that behavior (even if it's bad) — we're refactoring, not fixing bugs.

That last instruction is important. When refactoring, fixing bugs at the same time makes it impossible to know what caused a regression. Fix bugs separately.

Replacing Deprecated APIs

This codebase uses the deprecated componentWillMount lifecycle.
Find all usages and replace with the correct modern equivalent.
For componentWillMount: use either constructor or useEffect depending on context.
Show me each replacement before applying — I want to verify the mapping.

The “show me before applying” step is valuable for deprecated API replacements because the migration isn’t always 1:1.

Workflow 4: Naming Cleanup

Bad names are technical debt that compounds. Cryptic abbreviations (usrMgr, getDF, proc) slow down every future developer. Claude Code handles rename-everywhere correctly:

This codebase uses 'usr' as an abbreviation for 'user' throughout.
List every variable, parameter, and function that uses this abbreviation 
in all TypeScript files in src/.

After reviewing the list:

Rename all of these from usr/Usr to user/User.
Include: variable names, parameter names, function names, TypeScript interfaces.
Don't rename things in comments or strings yet — just code identifiers.

Breaking rename operations into code-then-comments prevents accidental breakage (a comment might say “usr means the user who…” which becomes “user means the user who…” — valid, just verbose. Review those manually).

Workflow 5: File Structure Refactoring

Files that grew too large, wrong locations, circular imports — structural issues that make codebases hard to navigate.

Breaking Up a Large File

This file is 1,200 lines and contains 8 different concerns.
Suggest a new file structure that separates these concerns.
Show me what would go in each file, including the import changes needed.
Don't move anything yet.

After reviewing the proposed structure:

Create the new file structure you proposed.
Move UserService class to user-service.ts,
UserRepository to user-repository.ts,
and UserTypes interfaces to user-types.ts.
Update all imports throughout the codebase.
Keep the original big file temporarily, but have it re-export everything 
from the new files so existing imports don't break.

The re-export trick gives you a migration path — the original file becomes a barrel that you can delete after updating all imports.

Fixing Circular Imports

I'm getting circular import errors between models/user.ts and services/auth.ts.
Read both files and the modules they import.
Explain why the circular dependency exists and suggest how to break it.

Circular dependencies usually mean a piece of shared logic (often utility functions or types) is incorrectly co-located with a class that uses it. Claude identifies which code to extract into a separate module.

Workflow 6: Type Safety Improvements

If you have a TypeScript codebase with too many any types, improving type coverage reduces bugs at the source.

Strengthening Types

Find every use of 'any' in src/api/. 
For each one, read the surrounding code and suggest a proper type.
Group them by: easy (can infer type), medium (need to understand the data shape), 
hard (generic wrapper, might need type parameters).

Then tackle the easy ones:

Fix the 12 easy cases you identified. 
Replace each 'any' with the inferred type.
Don't touch the medium or hard ones yet.

Adding Generic Types

For utility functions that work with multiple types:

This function currently takes (data: any, transform: Function) 
but it always returns an array of the same type as the input.
Add proper generic types: T for input, U for transform output.

Claude writes <T, U>(data: T[], transform: (item: T) => U): U[] — correctly typed generics that preserve the relationship between input and output types.

Tracking Refactoring Progress

Large refactoring efforts need tracking. Claude Code memory files are useful here:

# IN-PROGRESS REFACTOR: User module cleanup

## Done ✓
- Extracted validateUser() from processUser()
- Renamed `usr` → `user` throughout src/
- Moved UserService to /services/user-service.ts

## In Progress
- Breaking up user.ts (890 lines) into 3 files

## Remaining
- Fix circular import: models/user.ts ↔ services/auth.ts  
- Add types to 12 'any' uses in src/api/users.ts

Keep this in REFACTORING.md at the project root. Claude reads it automatically and knows where you left off.

When to Use Claude Skills for Refactoring

Repetitive refactoring tasks are ideal for skills. If you’re doing the same kind of refactoring across 20 files (e.g., “convert every function component using setState to hooks”), create a skill for it or use the codebase refactoring skills included in Claude Skills 360.

The refactoring skills in the bundle handle:

Callback → async/await conversion
Class component → hooks migration
Barrel file creation
Import reorganization
Type coverage improvement

Having these as skills means you describe the intent once and apply it consistently across your whole codebase. The free tier includes 360 skills — try the code quality ones before committing to the full bundle.

The Golden Rule of AI-Assisted Refactoring

The most important thing when using Claude Code for refactoring: change one thing at a time.

The temptation is to say “refactor this entire module” — and Claude will do it. But when something breaks, you won’t know if it was the naming change, the function extraction, the type fix, or the callback conversion. Small, named, committed steps are what make AI-assisted refactoring safe at scale.

The testing guide has workflows for writing tests before you refactor — that’s the safety net that makes fast refactoring possible.

Claude Code’s real advantage in refactoring isn’t speed — it’s consistency. When you ask it to rename a pattern across 50 files, it gets all 50. When you extract a function, it updates all 23 call sites. That’s where the leverage is.

How to Refactor Code with Claude Code: A Systematic Approach