Safe refactors with Cursor without breaking the build

Refactoring with an agent feels powerful until typecheck fails in twelve files and you are late for a handoff call.

I start by writing the invariant out loud. Public API stays the same. Behavior unchanged except in these three places. Or: we are renaming X to Y and nothing else. If I cannot state the invariant, I am not refactoring — I am fishing.

Ask for a plan first: files touched, risky spots, rollback. Approve the plan. Then let it edit. Skipping the plan is how you get a “cleanup” that rewrites your contact form for sport.

Chunk the work. Types and imports first. Then call sites. Then delete the dead path. Run the build after each chunk. Waiting until the end to discover failure is how freelancers burn evenings.

If the diff is hard to review, the agent did too much. Split it. Reviewability is a shipping constraint, not a nicety. I would rather merge three boring PRs than one clever disaster.

On marketing sites the scary refactors are usually content types and shared section components. Touch hero stats in JSON and forget the TypeScript type, and the homepage 500s. So I keep content.ts and the JSON in the same agent brief on purpose.

Safe rule of thumb: Cursor accelerates the mechanical moves. You still decide whether the architecture deserved moving in the first place.