CursorRefactoringLevel 2: Context

How Do You Refactor Safely in Cursor?

@-mention the code and its tests, say the tests must pass without being modified, and ask for one structural step at a time. Commit between steps. The tests define "still correct", and Agent can run them itself after each change.

Prompt to copy
Refactor @[target file] to [goal: remove duplication / split up this function / clearer names].

This must not change behavior. The tests in @[test file] must keep passing, and you must not modify them.

First, run the tests and confirm they pass. Then list the steps you'd take, and do only step 1. After step 1, run [test command] and [type check command], show me the result, and stop so I can review and commit.
  1. 1Commit, tests green
  2. 2One structural step
  3. 3Tests still green
  4. 4Commit
Repeat until the refactor is done
Rule of thumb, not a Cursor chart: run the checks on both sides of every step.

Try it now

  1. 1Commit your current work, so the only diff you see comes from this refactor.
  2. 2Open Agent with Cmd+I (Ctrl+I), paste the prompt above, and use @ to attach the code and test files.
  3. 3Read the diff after step 1. It worked if the test file is unchanged and the suite still passes. Commit, then ask for step 2.

Use it when

Improving code you're keeping: removing duplication, breaking up a long function, clearer names, moving a module. It needs tests that cover the behavior or a willingness to add them first.

Skip it when

When you mean to change behavior as well. Split that into a separate task, or the diff won't show which change caused what. Also skip Agent for a plain rename if your language server's rename is available, since that's exact and doesn't need a model.

Why it works

A refactor shouldn't change behavior, so you need something outside the agent to confirm that it didn't. Cursor's course says each test run gives Agent concrete feedback, and lists tests, type checking and linting as the signals that let you delegate with confidence. Small steps matter as well. The course warns that one common failure is asking for too large a change, after which the agent starts editing files you didn't intend and loses focus. A small diff is one you can actually read.

Example

Say billing.ts has three functions that each build the same invoice header. You mention billing.ts and billing.test.ts, and ask for a single shared helper. Agent confirms the tests pass, proposes three steps, then extracts the helper and uses it in one function. The tests still pass, so you commit. Two more short rounds finish the job, and each commit is small enough for a teammate to review.

Going further

If the code has no tests, ask for characterization tests first: tests that record what it does today, including odd behavior. Commit those, then refactor against them. Keep any surprises you find as a separate decision, because fixing a bug during a refactor makes both harder to review. If a change goes wrong across many files, use Restore Checkpoint, or Cursor's advice for plans: revert, refine the request and run it again, rather than patching with follow-ups.

Common mistakes

  • Letting Agent adjust a test to get it passing. Say "do not modify the tests", and check the diff for it anyway.
  • Mixing a behavior change into the refactor, so a regression has no clear source.
  • Asking for "clean this up" with no goal, which invites scope creep.
  • Relying on a test suite that doesn't cover the code being moved. Passing tests only prove what they check.

Sources

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Beyond the course