Safe Refactoring with Claude Code: Diagnose First, Change Minimum, Verify Always

#claudecode #refactoring #typescript #bestpractices

Saying "refactor this" to Claude Code without constraints is asking for trouble. It might rename things, change APIs, add abstractions you didn't ask for, or "improve" code that wasn't part of the problem.

These patterns keep refactoring safe and focused.

1. Diagnose Before Fixing

Before asking for any changes, ask Claude Code to audit the code:

Analyze this file for refactoring opportunities. List specific issues
and what could be improved. Do NOT make any changes yet.

[paste the code]

The "do NOT make changes yet" is critical. Once you have the list, you decide what to address and in what order.

2. Constrain the Scope Explicitly

Never refactor an entire file at once. Specify exactly what to touch:

Refactor ONLY the processPayment() function in this file.
The function currently has 3 responsibilities mixed together.
Split them into separate functions.
Do not change any other functions or the public API signature.

[paste the file]

CLAUDE.md can reinforce this automatically:

## Refactoring Rules
- Only change what was explicitly requested
- Do not rename external-facing functions/methods without permission
- Do not change type signatures without asking first
- After refactoring, state what changed and what didn't

3. Write Tests Before Refactoring

If there are no tests for the code you're refactoring, get Claude Code to write them first:

Before refactoring this function, write tests that capture its
current behavior. The tests should cover:
- Happy path
- Edge cases (null inputs, empty arrays, etc.)
- Error cases

[paste the function]

Then refactor, run the tests, and you'll know immediately if anything broke.

4. Check the Diff Explicitly

After a refactoring change, ask Claude Code to summarize it:

Summarize what you changed:
1. What was modified
2. Why each change is an improvement
3. Any behavior changes (even intentional ones)
4. Any public API changes

Item 4 is the most important — behavior and API changes that seem obvious to Claude Code may not be obvious to you.

5. The /refactor-suggest Workflow

If you have the /refactor-suggest skill, the workflow becomes:

/refactor-suggest src/services/payment.service.ts

Output format:

## Refactoring Suggestions

### 1. Extract validation logic [RECOMMENDED]
processPayment() handles validation, processing, and notifications.
Extract validatePaymentInput() — reduces function from 200 to 60 lines.
Risk: Low (pure function, easily testable)

### 2. Replace magic numbers with constants [RECOMMENDED]
Line 45: if (amount > 1000000) → MAX_PAYMENT_AMOUNT
Line 89: if (retryCount < 3) → MAX_RETRY_COUNT
Risk: None

### 3. Simplify error handling [OPTIONAL]
5 separate try/catch blocks with similar patterns.
Could use withErrorHandling() wrapper.
Risk: Medium (changes error propagation behavior — verify tests pass)

Review the suggestions, pick what to address, then execute one at a time.

What to Watch Out For

Risk	How to avoid
API signature changes	Explicitly say "don't change the public API"
Behavior drift	Write tests before refactoring
Scope creep	Specify exactly what to touch
Hidden renames	Ask for a summary of what changed
Type changes	"Do not change type signatures" in CLAUDE.md

CLAUDE.md Template for Refactoring Safety

## Refactoring Safety Rules
- Only modify explicitly requested code
- No public API or type signature changes without explicit approval
- After any refactoring: list what changed and what's identical
- Run existing tests before and after and confirm they still pass
- Never rename variables/functions that appear in git blame (coordination needed)