Refactoring Patterns

You open src/services/checkout.service.ts to add one discount rule and find a single processOrder function that is 340 lines long: inline validation, three nested if branches for payment type, a pricing calculation, an inventory write, and an email send — all sharing local variables. The existing Vitest suite is green, but nobody wants to touch it because any change might silently break a path that only fires in production. This is the exact situation where Claude Code earns its keep: it can characterize the current behavior in tests first, then move code in small, reversible steps you can verify after each one.

What You Will Walk Away With

• A test-first refactoring loop that keeps a green suite at every step
• A copy-paste Extract Method prompt that names real files and runs your suite to prove behavior is unchanged
• A prompt that replaces a payment-type switch with the Strategy pattern and a factory
• A legacy-modernization prompt (callbacks to async/await) that updates call sites and tests together
• The failure modes that actually bite during AI-assisted refactoring, and how to recover

The Refactoring Loop

Refactoring with Claude Code is not “ask it to clean this up.” It is a disciplined loop where tests are the contract and each step is small enough to review:

1. Pin the behavior. Generate characterization tests for the current code so any behavior change shows up as a red test. If the area already has good coverage, skip to step 2.

2. Make one named transformation. Extract a method, introduce a parameter object, replace a conditional — one move per turn, not a rewrite.

3. Verify. Run the test suite, the type checker, and the linter. Green means the move was behavior-preserving.

4. Commit, then repeat. One refactoring per commit so a bad step is a one-line git revert, not an archaeology project.

The non-obvious part is step 1. Ask Claude to read the real file before it writes anything, so it reasons about the code that exists rather than the code it assumes exists.

Tip

Copy-paste prompt to pin behavior before any change:

Read src/services/checkout.service.ts in full, then read its test file
src/services/__tests__/checkout.service.test.ts.

Write characterization tests that lock in the CURRENT behavior of processOrder,
including the branches I am likely to break: credit-card vs PayPal payment,
the out-of-stock path, and the partial-refund path. Use the existing Vitest
patterns (vi.mock for the email and inventory clients, expect().toEqual for
objects). Do not change any production code. Run `npx vitest run checkout`
and show me that the new tests pass against the unchanged implementation.

Extract Method: The Workhorse

Most “this function is too long” problems are solved by extracting cohesive blocks into named functions. The win with Claude Code is that it threads the shared local variables correctly and updates the original to call the new functions — the tedious, error-prone part.

Show it the same concept in your language. The interaction is identical; only the idioms differ:

TypeScript

In src/services/checkout.service.ts, processOrder does five jobs. Extract three
pure functions in the same file: validateOrder(input), calculatePricing(cart),
and reserveInventory(items). Leave the email send and the DB write in
processOrder as the orchestrator. Keep every existing type; do not widen any
type to `any`. Then run `npx vitest run checkout` and `npm run type-check`
and report both results.

Python

In app/services/checkout.py, refactor process_order by extracting
validate_order(payload), calculate_pricing(cart), and reserve_inventory(items)
as module-level functions with type hints. Keep process_order as the
orchestrator. Run `pytest tests/test_checkout.py -q` and `mypy app/services`
and show me the output before and after.

Elixir

In lib/shop/checkout.ex, process_order/1 is doing too much. Extract
validate_order/1, calculate_pricing/1, and reserve_inventory/1 as private
functions, and pipe them together in process_order/1. Keep the existing
typespecs. Run `mix test test/shop/checkout_test.exs` and report the result.

Tip

Copy-paste Extract Method prompt with a verification gate:

Extract the validation block (lines that check input.email, input.items, and
input.paymentMethod) from processOrder in src/services/checkout.service.ts into
a new exported function validateOrder(input: OrderInput): void that throws the
same errors as today. Update processOrder to call it. Constraints:
- Do not change the error messages or status codes (tests assert on them).
- Do not add new dependencies.
After the edit, run `npx vitest run checkout`. If any test fails, revert your
change and tell me which assertion broke instead of "fixing" the test.

That last line matters. The most common failure mode in AI refactoring is the model editing a test to make it pass. Telling it to revert and report instead keeps the test as the source of truth.

Replace Conditional with Polymorphism

A payment-type switch that grows a new branch every quarter is a maintenance tax. The Strategy pattern moves each case behind a common interface. This is a multi-file change where order matters, so run it in Plan Mode first (Shift+Tab to cycle into Plan Mode) and approve the plan before any edits.

Tip

Copy-paste prompt for a Strategy-pattern refactor:

Plan first, then implement. In src/payments/, replace the switch(paymentType)
block in PaymentService.charge() with the Strategy pattern:
- Define an interface PaymentStrategy with charge(amount: Money): Promise<Receipt>.
- Create CreditCardStrategy, PayPalStrategy, and CryptoStrategy implementing it,
  each holding the logic currently in its switch case.
- Add a paymentStrategyFor(type) factory that returns the right strategy.
- PaymentService.charge() should resolve the strategy and delegate.
Keep the public signature of PaymentService.charge() unchanged so callers and
the existing tests do not move. After implementing, run `npx vitest run payments`
and `npm run type-check`, then show me a one-line summary of each new file.

The behavioral test of a good Strategy refactor is simple: the existing payments test suite should pass with zero edits, because you only moved logic, you did not change it. If a test needs editing, the refactor changed behavior and you should stop.

Modernize Legacy Code

Callback-based APIs, .then() chains, and CommonJS modules are the usual legacy targets. The trap is updating the implementation but leaving call sites or tests on the old shape. Make Claude update them together.

Tip

Copy-paste prompt to convert callbacks to async/await:

Read src/clients/api-client.ts and every file that imports from it (use Grep to
find them). Convert the callback-style methods (those ending in a (err, data)
callback) to return Promises and use async/await internally. Then update ALL
call sites you found to await the new Promises and handle errors with try/catch
instead of the err-first callback. Update the matching tests in
src/clients/__tests__/ to the async form. Run `npx vitest run clients` and
`npm run lint`. List every file you touched.

A current, realistic framework target is a React 18-to-19 migration. React 19 is the current stable major, so anchor on it rather than an older jump:

Create a migration plan to move this app from React 18 to React 19:
- Identify uses of the removed legacy APIs (ReactDOM.render, findDOMNode,
  legacy Context, string refs) with Grep and list each occurrence.
- Map any forwardRef components that can drop the wrapper now that ref is a prop.
- Note where the `use()` hook or Actions would simplify existing data-fetching.
Do not edit anything yet. Output the plan as a checklist I approve before you
start, smallest-risk items first.

Splitting a Fat Service

When a class has absorbed unrelated responsibilities, split it — but verify the seams with the type checker, not by eye.

src/services/user.service.ts has grown to ~900 lines and mixes authentication,
profile updates, and notification sending. Plan a split into AuthService,
ProfileService, and NotificationService. For each: list which existing methods
move, which private helpers they need, and which call sites must be updated.
Keep one thin UserService facade that delegates, so external imports do not
break in this PR. Implement only after I approve the plan, one service per
commit. Run `npm run type-check` after each service to catch a missed reference.

Note

For repository-wide moves — renaming a symbol used across dozens of files, or staging the change as a stacked set of PRs — wire up the GitHub MCP server so Claude can open and update the PRs directly. Add it once with claude mcp add --transport http github https://api.githubcopilot.com/mcp/. For deep, repeatable review of each refactoring commit, define a code-reviewer subagent (see What’s Next) and invoke it after every step instead of re-typing your review criteria.

When This Breaks

Claude edits the test to make it pass. This is the cardinal failure. Always include “if a test fails, revert your change and report which assertion broke” in the prompt, and review the diff for test-file edits you did not ask for. The test is the contract; the implementation moves around it.

The refactor “works” but a production-only path broke. Your characterization tests did not cover that path. Before refactoring high-stakes code, ask Claude to enumerate the branches first (“List every distinct code path through processOrder and the input that triggers it”) and write a test for each before touching anything.

A big-bang change lands as one giant diff. Stop and reset: git reset --hard <last-known-good-commit>. Then re-run the work with an explicit “one refactoring per commit, run the suite between each” instruction. Small steps are what make AI refactoring safe to review.

The model loses the codebase’s conventions mid-refactor. It started inventing a new error format or a different folder layout. Point it back at a concrete anchor: “Match the error-handling pattern in src/api/routes/orders.ts exactly — same error class, same response shape.” Encoding these conventions in your CLAUDE.md keeps every session consistent.

Performance “optimization” changes results. If you asked it to replace an O(n^2) loop, treat it as a refactor under test: pin the output with a test first, swap the algorithm, then confirm the test still passes and benchmark with real numbers (console.time or your bench harness) rather than trusting an asymptotic claim.

What’s Next

Multi-File Workflows Coordinate refactors that span many files without losing the thread.

Testing Integration Build the characterization and regression tests that make refactoring safe.

Custom Subagents Define a code-reviewer subagent to vet every refactoring commit.

Prompt Engineering for Claude Code Plan Mode, effort levels, and constraint-first prompts that drive precise edits.