Refactoring Legacy Code With Cursor (Tests First, Courage Second)

The module was 600 lines, ten years old, load-bearing, and tested by production traffic only. Cursor refactored it well, but the AI was maybe a third of the story. The other two thirds were the sequencing: tests, boundaries, and refusing to let the agent move fast.

Step one is characterization tests, and Cursor is genuinely good at helping write them. I asked it to read the module and list every observable behavior: inputs, outputs, edge cases, error paths. Then to generate tests asserting current behavior, including the weird stuff, explicitly labeled 'characterization: asserts current behavior, not correctness.' Those tests are the safety net that makes everything after possible.

Step two is boundaries before surgery. I had Cursor extract pure functions at the seams first (parsing, calculation, formatting) without changing any behavior, each extraction verified green. Only then did the real refactoring start, function by function, with the instruction that matters most: 'change one thing per pass, run the tests, stop.' Agents that refactor boldly rewrite confidently and break subtly. Small passes with verification between them are how you keep control.

The step nobody expects to matter: I made Cursor explain each change in one sentence before applying it. The explanations caught two things the tests did not: a mutation of a shared object that only bit under concurrency, and a reordering of operations that was safe in the tests' timezone and not in production's. Reading the one-sentence rationale is ten seconds per change and caught what the nets missed.

Final tally: the module is now 300 lines with structure a new hire can read, behavior verified identical by the characterization suite, and zero production incidents. The AI did the typing. The discipline did the refactoring. Both were necessary; only one of them was optional.