Home › Agent workflows › Safe refactoring rules

Safe refactoring rules

Cursor rules for behavior-preserving refactors: small steps, tests first, no mixed feature changes, and clear diffs.

CursorAgent workflows

How to use

Save this as .cursor/rules/refactoring.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

---
description: Use when the user asks to refactor, clean up, restructure, rename, or extract code.
alwaysApply: false
---

# Refactoring

A refactor changes structure, not behavior.

## Before
- Find the tests covering the code. If coverage is thin, add characterization tests that pin current behavior (including odd behavior) first.
- Run the suite and note the result, so you know the starting point.
- State the plan in 3-6 steps and the end state.

## During
- One kind of change per step: rename, extract function, move file, inline, change signature. Run tests after each step.
- Use the editor/language tooling for renames and moves so all references update; then search (`rg 'oldName'`) for strings, docs, and configs.
- Keep public APIs stable. If a signature must change, add the new one, migrate callers, then delete the old one.
- Don't mix in bug fixes, new features, formatting of untouched files, or dependency upgrades. Note them as follow-ups.
- Delete dead code you've proven unused; don't comment it out.

## Smells worth fixing
Long functions, deep nesting (use early returns), duplicated logic, boolean flag parameters, large modules mixing concerns, unclear names.

## After
- Tests, typecheck, and lint pass with no new warnings.
- Summarize what moved where and confirm "no behavior change", or list any intentional change explicitly.