Refactoring legacy code with Cursor

Refactoring legacy code with Cursor is a sequenced workflow: map the codebase in Plan Mode, pin current behaviour with characterization tests, then let the agent change one function or module per commit. Each step is accepted only when the pinned tests pass unchanged and the diff stays inside its scope, so nobody reads every line.

Documentation freshness

Covers: the Cursor 3.x line, checked on 26 September 2026. Plan Mode was verified against cursor.com on 28 August 2026. Cursor’s pages on keyboard shortcuts, mode switching and checkpoints could not be re-checked on 26 September 2026. On 12 October 2026 Cursor’s docs confirm that Cmd+I (Ctrl+I on Windows and Linux) opens the Agent panel and Shift+Tab cycles through the agent modes. Checkpoints are stored locally, separate from Git, and restoring one reverts files only. This page still uses git commits for every rollback.

You inherited a five-year-old Express API: about 50 JavaScript files, callbacks nested four deep, business rules inside route handlers, and no tests. Real users depend on every quirk, including the undocumented ones. Asking the agent to “modernize this” produces a 3,000-line diff that nobody can review and that changes behaviour in ways nobody notices until production. This page is for developers doing that refactor in Cursor, and for tech leads who have to approve the result.

What a safe legacy refactor in Cursor gives you

• A read-only mapping prompt and a critical-path trace that tell you where the risk is before any file changes.
• A characterization-test prompt that pins what the code does today, bugs included, plus two checks that prove those tests can catch a change.
• Scoped prompts for the three mechanical moves: callbacks to async/await, service extraction, and incremental TypeScript.
• A gate you run after every step (locked tests, scoped diff, type check, cycle check) and a pre-PR evidence prompt a reviewer can approve without reading the whole diff.
• Recovery steps for the six ways this refactor usually goes wrong.

This page is the Cursor implementation. The tool-independent programme (slicing, parallel waves, and cut-over evidence) is legacy modernization with agents, and the Codex equivalent is codebase modernization with Codex, and in Claude Code see refactoring with Claude Code.

Why does the order of a legacy refactor matter?

Every step below depends on the one before it. Tests before refactoring, because without them “the behaviour did not change” is an opinion. Mechanical changes before structural ones, because a pure async conversion is easy to verify and makes the later extraction smaller. Bug fixes last, in separate commits, because a refactor commit that also fixes a bug cannot be verified by the tests that pin the old behaviour.

Step	Cursor surface	What the agent may change	Gate that accepts it
1. Map the codebase	Plan Mode	Nothing	A committed map where every finding cites a file or is marked “inferred”
2. Trace critical paths	Plan Mode	Nothing	You can name the three riskiest paths and the edge cases each one needs
3. Pin behaviour	Agent	New test files only	Tests pass on the untouched code, twice, and fail when you break it on purpose
4. Convert callbacks	Inline edit, one function	One function	Locked tests pass, diff touches only that file
5. Extract services	Agent, one module	The named module, its new service file and its errors file	Locked tests pass, git status --short lists only those files, no new import cycle
6. Add types	Agent, one layer	Renamed files and their importers, after a setup-only commit	tsc --noEmit clean, locked tests pass
7. Fix bugs and queries	Agent	Code and the matching test expectation	The test change and its fix land together in one fix: commit

How do you refactor legacy code with Cursor, step by step?

Before the first prompt, set up the safety net. Create a branch, commit the current state, and write down the one command that runs the tests. Add a project rule such as: “During this refactor, change only the files named in the prompt. Never edit files under tests/characterization/. Never change a response body, status code or error message.” A rule is an instruction, not a fence. The fence is the gate you run after every step (first shown in Step 4), which the agent cannot talk its way past.

Step 1: Map the codebase in Plan Mode

Plan Mode “creates detailed implementation plans before writing any code”, so it is a safe place to read an unfamiliar codebase. Ask, Cursor’s read-only mode (Cursor’s help, checked 2026-10-12), works here too. How to feed a large repository to the agent without flooding its context is covered in context management.

Copy-paste prompt: legacy codebase map (read-only)

@src

Do not change any file. Analyse this Node.js/Express codebase and produce a report with:

1. The 10 most-imported modules and which files depend on each.
2. The 5 largest files by line count, with a one-line description of each.
3. Every database access pattern in use (raw SQL, ORM, query builder) and where.
4. Error handling gaps: empty catch blocks, callbacks that ignore the err argument,
   promises without a rejection handler.
5. Every external API call and what happens when it fails or times out.
6. Global state, singletons and module-level caches that will make testing hard.
7. A ranked list of the 3 modules you would refactor first and the 3 you would leave
   for last, with the reason for each.

Cite file paths and line numbers for every finding. Mark anything you inferred
rather than read as "inferred".

Save the report as docs/refactor/map.md and commit it. The “inferred” markers tell you which findings to check yourself before you rely on them.

Step 2: Trace the critical paths

Pick the two or three flows that would hurt most if they broke, for example login, checkout, and payment. Trace each one end to end before any test is written, because the trace tells you which edge cases the tests must pin.

Copy-paste prompt: trace one critical path

@src/routes/checkout.js @src/controllers/orders.js @src/models/order.js @src/services/payment.js

Do not change any file. Trace POST /checkout from the HTTP request to the last
database write:

1. The exact sequence of function calls, with file:line for each.
2. Where request data is validated, and which fields are never validated.
3. Every database write, whether it runs in a transaction, and where a failure
   would leave partial state.
4. What the client receives if the payment call fails, times out, or succeeds
   after the client has disconnected.
5. Any shared state two concurrent checkouts could race on.

Finish with a Mermaid sequence diagram and a list of edge cases a characterization
test must cover, each with the input that triggers it.

Step 3: Pin current behaviour with characterization tests

A characterization test records what the code does today, not what it should do. If a refactor changes a result, the test goes red, and you know behaviour moved. The general technique (golden masters, approval tests, choosing seams) is in characterization tests; here is the Cursor prompt for one module.

Copy-paste prompt: characterization tests for the order flow

@src/controllers/orders.js @src/models/order.js @docs/refactor/map.md

Write characterization tests for the order endpoints in
tests/characterization/orders.test.js, using Jest and supertest against the real
Express app and a local test database seeded by a fixture file.

1. Cover every status code these endpoints can return today, and assert the exact
   response body and error message, not only the status.
2. Include the edge cases from the checkout trace: negative quantity, empty cart,
   duplicate items, unknown product, payment failure.
3. Record current behaviour exactly, including behaviour that looks wrong. If the code
   returns 200 for an invalid order, the test expects 200. Add a comment
   "// PINNED: looks like a bug" on those tests and list them at the end.
4. Do not modify any file under src/. If a test needs a seam that does not exist,
   stop and tell me instead of adding one.
5. Run the tests and show me the result. Every test must pass against the current code.

Read the tests, not the implementation. You are checking that each assertion is exact and that the edge cases from the trace are there. Then prove the suite is an oracle and not decoration:

1. Run the suite twice in a row. A test that passes once and fails once is flaky; fix or delete it now, or it will cause false alarms in every later step.

2. Break the code on purpose. Change one status code or one price calculation in src/, run the suite, and confirm at least one test fails. Revert the change with git checkout -- src/.

3. For a stronger signal on the modules you will touch first, run a scoped mutation test. Stryker 10.0.0 (npm, checked 2026-09-26) changes the code in small ways and reports every change your tests missed:

   # Terminal, repo root
   npm install --save-dev @stryker-mutator/core @stryker-mutator/jest-runner
   npx stryker run --testRunner jest --mutate src/controllers/orders.js --concurrency 1

   --concurrency 1 runs one test runner at a time. Stryker runs several in parallel by default, and parallel mutants writing to one shared test database produce survivors and kills that have nothing to do with your tests. If you want parallel runs, give each Stryker worker its own database instead.

   A surviving mutant in code you plan to change means the tests cannot see that change. Write one extra test per surviving mutant in tests/characterization/, re-run the suite twice, and only then commit in the next step. If a mutant cannot change observable behaviour (an equivalent mutant), note it in the Stryker report instead of writing a test; no test can kill it.

   Add reports/, stryker.log and .stryker-tmp/ to .gitignore before the commit in the next step.

4. Commit the tests on their own: git commit -m "test: pin current order behaviour". Note the commit hash; this is BASELINE in every gate below.

How strong is your oracle explains what score to aim for.

Step 4: Convert callbacks one function at a time

Use inline edit on a single selected function, so the edit is aimed at that selection; the git status --short gate below confirms it stayed there. Select a single callback-based function and give it this instruction:

Copy-paste prompt: mechanical callback-to-async conversion (inline edit)

Convert this callback-based function to async/await. Pure mechanical conversion:
same return values, same thrown or passed errors, same side effects in the same
order, same exported name. Keep the callback signature working for existing
callers by wrapping, unless every caller is in this selection. Do not add
validation, logging, or new error messages.

If the function leans on module-level state or helpers outside the selection, inline edit may miss them. Switch to the agent for that function and reference the whole file with @. After each function, run the gate:

# Terminal, repo root. BASELINE is the commit that added the characterization tests.
git diff --exit-code BASELINE -- tests/characterization/   # the tests were not touched
npx jest tests/characterization                              # behaviour did not move
git status --short                                           # only the intended file changed, and no new untracked files

git status --short rather than git diff --stat, because the diff ignores untracked files, and a new file is exactly what an over-eager agent leaves behind. All three pass, commit. Any one fails, run git restore . && git clean -n to discard the edits and list the untracked files, then git clean -f after checking that list. Redo that function with a narrower selection or a more explicit instruction. One function per commit feels slow, but each commit is trivially reviewable and bisectable. For the general refactoring patterns behind these moves, see refactoring strategies.

Step 5: Extract a service layer, one module per run

Once a module is async, move its business logic out of the route handler. This is a multi-file change, so use the agent, and fence the scope in the prompt.

Copy-paste prompt: extract the order service

@src/controllers/orders.js @src/models/order.js @tests/characterization/orders.test.js

Extract the business logic from src/controllers/orders.js into a new file
src/services/order-service.js.

1. Move validation, price calculation, inventory checks and database calls into the
   service. The service takes plain objects and never sees Express req or res.
2. The service throws named errors (ValidationError, NotFoundError, PaymentError)
   defined in src/services/errors.js. The controller catches them and maps each to
   the exact status code and body the characterization tests expect today.
3. You may change only: src/controllers/orders.js, src/services/order-service.js,
   src/services/errors.js. Do not modify any other file, and never edit anything
   under tests/.
4. After the change run: npx jest tests/characterization
5. If a test fails, fix the service or controller, never the test. If the same test
   still fails after three attempts, stop and explain what you think the test pins.

Run the same gate as in Step 4 (git status --short must list only the three named files), and add a cycle check, because extraction is where circular imports appear:

# madge 8.0.0 (npm, checked 2026-09-26): exits 1 and prints 'Found … circular dependency' when a cycle exists
npx madge --circular src/

Step 6: Add TypeScript from the bottom up

Convert models first, then services, then controllers, then routes. Each layer depends on the one below it, so typing the foundation first gives the upper layers real types to check against.

Set up the toolchain before the first rename, or the gate goes red for a toolchain reason rather than a behaviour reason: Jest cannot load a .ts module and Node cannot require one.

# Terminal, repo root. ts-jest 29.4.14 accepts TypeScript >=4.3 <7 and npm's latest
# TypeScript is 7.0.2 (both checked 2026-09-26), so pin TypeScript 6.
npm install --save-dev typescript@6 @types/node @types/express @types/jest ts-jest tsx
npx tsc --init
npx ts-jest config:init

Then edit tsconfig.json:

• Set allowJs: true so .js and .ts files coexist, checkJs: false so untouched JavaScript is not type-checked yet, and noEmit: true so tsc only checks. Keep strict: true.
• TypeScript 6’s tsc --init writes "types": [] and verbatimModuleSyntax: true. Change them to "types": ["node", "jest"] and, for a CommonJS codebase that uses require, verbatimModuleSyntax: false.
• Add "rootDir": "."; without it ts-jest stops with error TS5011.

ts-jest config:init writes a jest.config.js whose transform covers .ts files only, so the existing .js files load as before. If the project already has a Jest config, add the ts-jest transform to it instead. For the app, start it with tsx (for example npx tsx src/server.js in the start script), which resolves an extensionless require('./models/order') to the renamed .ts file; a tsc build step that emits to dist/ works too.

Run npx jest tests/characterization and npx tsc --noEmit. Both must pass before any file is renamed; commit this setup on its own (chore: add TypeScript toolchain), so a later red test points at a conversion, not at the toolchain.

Copy-paste prompt: convert one module to TypeScript

@src/models/order.js @tsconfig.json

Convert src/models/order.js to src/models/order.ts:

1. Add exported interfaces for every data shape (Order, OrderItem, OrderStatus).
2. Type every parameter and return value. No `any`; use `unknown` and narrow it.
3. Do not change runtime behaviour. Where a type reveals a value that can be
   undefined or the wrong type at runtime, keep the behaviour and add a
   "// TYPE-FINDING:" comment instead of fixing it.
4. Update imports in every file that references this module, and change nothing
   else in those files.
5. Run npx tsc --noEmit and npx jest tests/characterization, and report both results.

The TYPE-FINDING comments are your bug backlog. They go into step 7, not into this commit.

Step 7: Fix bugs and slow queries in separate commits

Now change behaviour on purpose. Take one PINNED: looks like a bug test or one TYPE-FINDING at a time: change the test expectation first and run the suite to watch it fail, so you know the test sees the bug. Then ask the agent to make it pass, and commit the test change and the fix together under a fix: message that names the old and the new behaviour. Do not commit the red test on its own: it breaks the “every commit is bisectable” promise from Step 4, and it fails CI on the branch. The reviewer still reads the test change first, because the pre-PR evidence below lists every commit that changed a test expectation, and that change is a one-line diff under tests/characterization/ stating the new behaviour. After each fix: commit, point BASELINE at that commit (for example git tag -f refactor-baseline) so the per-step gate guards the new expectation; the pre-PR evidence prompt still compares against the original characterization commit.

Query work splits the same way. An N+1 query or a full-table read can be fixed without changing what a function returns, so the characterization tests still guard it. A missing WHERE clause on an UPDATE is a bug fix and follows the red-test route above. For query profiling after the refactor, see performance optimization.

How do you prove the refactor without reading every line?

The reviewer’s job becomes checking evidence, not diffs. Ask the agent to assemble it before you open the pull request.

Copy-paste prompt: pre-PR evidence for a refactor branch

Do not change any file. Prepare the evidence for this refactor branch against
BASELINE_COMMIT (replace with the hash of the characterization-test commit):

1. Run: git diff --exit-code BASELINE_COMMIT -- tests/characterization/
   and report whether any pinned test changed. List every commit that changed a
   test expectation on purpose, with its message.
2. Run npx jest tests/characterization and npx tsc --noEmit; paste the summary lines.
3. Run npx madge --circular src/ and report any cycles.
4. Run git diff --stat BASELINE_COMMIT and flag every changed file that no commit
   message explains.
5. Output a markdown table: check, command, result, pass or fail.

Paste the table into the pull request description. The reviewer approves when every row passes, reads only the commits that changed a test on purpose, and spot-checks any file flagged in row 4. The developer signs off on the characterization tests in step 3; the tech lead signs off on the evidence table. An automated reviewer such as Bugbot can add a second pass on the diff; it does not replace the pinned tests. The full format for this record is the evidence bundle.

Tests only cover the paths you pinned. For a high-traffic service, ship the refactored path behind a feature flag and run it in shadow mode: serve the old response, compute the new one, log any difference, and cut over only after a period with no differences you cannot explain. Keep the old path in the code until then, so rollback is a flag change, not a deploy.

What breaks in a Cursor legacy refactor, and how do you recover?

The agent “improves” code during a mechanical step. It adds validation, rewrites an error message or fixes an edge case while converting a callback. Recovery: the characterization tests catch changed responses; git status --short catches changed and new files. Run git restore . && git clean -n, then git clean -f after checking the list, and repeat the prompt with the forbidden changes listed (“no validation, no new messages”).

The agent edits a test to get to green. Recovery: git diff --exit-code BASELINE -- tests/characterization/ exits non-zero. Restore the tests with git checkout BASELINE -- tests/characterization/ and re-run the prompt with “the test directory is read-only”. To stop it happening at all, add a CI job that fails the pull request when files under tests/characterization/ change without a test: or fix: commit; protecting the oracle shows the patterns.

The agent rewrites half the repository. A prompt that references @src for a change, not a question, invites a sweeping edit. Recovery: git restore . and git clean -n, then git clean -f after checking the list. Re-run with an explicit list of files the agent may change.

Tests pass, production breaks. The input that triggers the difference was never pinned. Recovery: flip the feature flag back, capture the failing request from logs, add it as a characterization test against the old code, then redo the step.

A circular import appears after extraction. Two services now import each other. Recovery: npx madge --circular src/ names the cycle. Ask the agent, in Plan Mode, to propose where the shared types or functions should live, then move them to a separate module in their own commit.

Characterization tests are flaky. Time, random IDs, or test-order dependence make the oracle lie. Recovery: freeze the clock and seed the random source in the fixture, give each test its own data, and re-run the suite twice before trusting it again.

Where to go next after a legacy refactor

Legacy modernization with agents The tool-independent programme: slicing, parallel waves, and cut-over evidence.

Characterization tests Golden masters, approval tests and seams for pinning untested behaviour.

Test-driven development in Cursor Once behaviour is pinned, write new features test-first.

Framework and library migration Move the refactored code to a new framework or major version.