Refactoring Strategies

Your user service file has grown to 800 lines. It handles authentication, profile management, notification preferences, and account deletion — all in one file. Every developer on the team touches it for different reasons, merge conflicts are constant, and the test file is 1,200 lines of tightly coupled test cases. You know it needs to be split up, but the last time someone tried a big refactor, it broke three other services and took a week to stabilize.

AI-assisted refactoring solves the “too risky to touch” problem by making large refactors incremental, verifiable, and reversible. The key is breaking the refactor into small, safe steps where each step is verified by the existing test suite before moving to the next.

What You’ll Walk Away With

• An incremental refactoring workflow that keeps the test suite green at every step
• Copy-paste prompts for the most common refactoring patterns
• Strategies for refactoring code that other services depend on
• Techniques for using Cursor’s checkpoints and git to stay safe

The Incremental Refactoring Workflow

Never refactor everything at once. Instead:

1. Run the full test suite. Confirm it passes. Commit.
2. Make one structural change (extract a function, move a file, rename a variable).
3. Run the full test suite. If it passes, commit. If it fails, fix the specific breakage.
4. Repeat until the refactoring is complete.

Each commit is a checkpoint you can return to. If step 7 of a 10-step refactor goes wrong, you only lose step 7’s work.

Tip

Copy-paste prompt for safe incremental refactoring:

I need to refactor @src/services/user-service.ts (800 lines) into smaller modules.

Let's do this incrementally. For each step:
1. Make one structural change
2. Update all imports across the codebase
3. Run `npm test` to verify nothing broke
4. Tell me the result before moving to the next step

Start with: Extract the authentication functions (login, logout, refreshToken, validateToken) into a new file @src/services/user/authentication.ts. Create a barrel export in @src/services/user/index.ts that re-exports everything so existing consumers do not break.

Common Refactoring Patterns

Pattern: Extract Module

Split a large file into focused modules while maintaining backward compatibility:

Tip

Copy-paste prompt: Extract module

Extract all payment-related functions from @src/services/order-service.ts into a new @src/services/payment-service.ts.

Functions to move: processPayment, refundPayment, validatePaymentMethod, getPaymentStatus.

Requirements:
- Create the new file with the moved functions
- Update order-service.ts to import from payment-service.ts instead of defining them inline
- Update all other files that import these functions directly
- The public API must not change -- any file that imported from order-service should still work
- Run tests after each file change

Do this step by step. Do not change all files at once.

Pattern: Interface Extraction

When you need to change a function signature that is used across the codebase:

The createUser function currently takes 6 positional parameters.
Refactor it to take a single options object.

Before: createUser(email, password, firstName, lastName, role, teamId)
After: createUser({ email, password, firstName, lastName, role, teamId })

Update every caller across the codebase. There are approximately 15 call sites.
Run tests after updating each file to catch any mistakes immediately.

Pattern: Callback to Async/Await Migration

Tip

Copy-paste prompt: Modernize async code

Refactor @src/services/data-service.ts to replace all callback-based patterns with async/await.

Rules:
- Preserve all error handling behavior (callbacks with (err, result) must become try/catch)
- Do not change function signatures if they are exported
- Internal helper functions can be updated freely
- Update the test file to use async/await as well

Run the tests after refactoring. If any test fails, the refactoring introduced a behavioral change -- fix it.

Pattern: Rename Across Codebase

Rename the `getUserData` function to `getUserProfile` everywhere in the codebase.

This includes:
- The function definition in @src/services/user-service.ts
- All imports and call sites
- All test references
- Any string references in route definitions or documentation

Run tests after the rename to verify nothing broke.

Large-Scale Refactoring with Plan Mode

For refactors that touch many files, use Plan mode to create a structured plan before executing:

I need to migrate our API from Express middleware pattern to a controller pattern.

Current structure:
- Routes define middleware chains directly
- Business logic is mixed into route handlers
- Validation happens at the route level

Target structure:
- Routes map URLs to controller methods
- Controllers handle request/response
- Services contain business logic
- Validation middleware is applied automatically

Create a detailed plan. For each step, specify:
- Which files to modify
- What the change is
- How to verify it works

Ask me up to 3 clarifying questions before creating the plan.

Review the plan, adjust priorities, then execute step by step with Agent mode.

Safety Strategies

Use Parallel Agents to Compare Approaches

For refactors where there are multiple valid approaches, use Cursor’s parallel agent feature:

1. Send the same refactoring prompt to two different models
2. Each works in its own worktree
3. Compare the approaches side by side
4. Apply the one that is cleaner and passes tests

The “Pre-PR” Verification

After completing a refactoring, run your full verification suite before submitting:

Tip

Copy-paste prompt: Pre-PR verification

The refactoring is complete. Run the following checks and fix any issues:

1. `npm run build` -- TypeScript compilation (fix all type errors)
2. `npm run lint` -- ESLint (fix all lint errors)
3. `npm test` -- Full test suite (fix any failures)
4. `npm run format` -- Code formatting

Iterate until all four pass cleanly. Do not skip any step.

When This Breaks

Agent changes too many files at once. The refactoring step is too large. Break it into smaller pieces. “Move 3 functions to a new file” is better than “reorganize the entire service layer.”

Tests fail after a refactor but the code looks correct. The tests may be testing implementation details rather than behavior. Use Ask mode to analyze whether the test failure is a real regression or a test that needs updating.

Imports break after moving files. Make sure you are creating barrel exports (index.ts files) that re-export from the new locations. This maintains backward compatibility while you update imports incrementally.

Other team members’ PRs conflict with the refactoring. Communicate large refactors to the team before starting. Merge the refactoring quickly (in small PRs if possible) to minimize the conflict window.

What’s Next

• Testing Patterns — Tests are your safety net during refactoring
• Debugging Workflows — Diagnosing issues introduced during refactoring
• Checkpoints and Branching — Git strategies for safe refactoring