How to Refactor a Real Codebase with Cursor (Without Breaking It)

The rule that makes this work

An AI agent is a fast, tireless engineer with no memory of your product decisions and no fear of being wrong. Every part of the process below exists to catch that second property before it reaches main.

Step 0: Make the codebase legible

Agents perform in proportion to how well your repository explains itself. Before a big refactor:

• Ensure the test suite runs with one command and passes.
• Add a .cursorrules file describing conventions: language version, patterns you use, patterns you ban, how errors are handled, how modules are organised.
• Commit everything. You want a clean diff to review.

A short rules file changes output quality more than any prompt.

Step 1: Scope the change precisely

Bad: modernise the payments module. Good:

In src/payments, replace all callback-based functions with async/await.
Do not change public function signatures.
Do not touch src/payments/legacy — it is deleted next quarter.
Update the tests in tests/payments to match.
Run the test suite after each file and stop if anything fails.

The constraints matter more than the instruction. Every boundary you fail to state is a boundary the agent may cross.

Step 2: Ask for a plan before edits

Before changing anything, list the files you will modify, what you will
change in each, and the risks. Wait for my approval.

Reading a plan takes two minutes and catches misunderstandings before they become forty file edits. If the plan mentions a file you did not expect, your scope was wrong.

Step 3: Work in reviewable increments

Have the agent commit after each logical unit rather than producing one enormous change. Small commits mean:

• git bisect still works when something breaks next week.
• You can review meaningfully instead of skimming a 3,000-line diff.
• Reverting one bad decision does not undo six good ones.

Step 4: Review the diff like a code review

The temptation is to check that tests pass and move on. Resist it. Look specifically for:

• Silently dropped edge cases. Agents love to simplify away a condition that looked redundant and existed for a reason.
• Changed error handling. A swallowed exception is invisible in tests and expensive in production.
• New dependencies. Check anything added to your package manifest.
• Weakened tests. If a test was modified to pass rather than the code fixed, that is the single most common failure mode.

Step 5: Verify beyond the test suite

Run the application. Exercise the changed path manually. Check logs. Tests prove the behaviour you thought to encode, and a refactor's danger lives in the behaviour you did not.

When to stop and do it yourself

Stop when:

• The agent has failed the same test three times — it is now guessing.
• The change requires knowing why a decision was made, not what the code does.
• You cannot describe the desired end state precisely. If you cannot, neither can it.

What agents are genuinely excellent at

• Mechanical migrations: framework versions, API changes, import restructuring.
• Writing tests for existing untested code — often the highest-value use of an agent.
• Adding a parameter through a long call chain.
• Translating a module to another language with the tests as a specification.
• Explaining unfamiliar code before you change it.

A realistic session

A 40,000-line service needs its date handling moved to a new library. You write the rules file, scope the change to two directories, approve a nine-file plan, and let it work. Ninety minutes later you have eleven commits, a green suite, and three places where you disagree with its choices, which you fix by hand. The alternative was two days.

That ratio — most of the work automated, the judgement retained — is what these tools are for. Compare approaches with Claude Code if you prefer a terminal-first loop, or GitHub Copilot for lighter in-editor assistance.