Workflow guide · 3 tools
How to refactor legacy code with AI
Refactor to make the next change easier without changing what the system does today. Start with one boundary you can test rather than asking an agent to “clean up” a whole subsystem.
Compare the tools
| Tool | Best for | Tradeoff |
|---|---|---|
| Claude Code | A terminal-led refactor that needs to trace several callers and run targeted tests. | Broad instructions can produce large edits and costly sessions; keep the allowed scope narrow. |
| Cursor | Interactive multi-file edits when you want to inspect and adjust the diff in an editor. | Requires adopting a separate editor and deciding which repository context the agent may see. |
| Aider | Git-centric terminal pairing on small changes you want to review as separate commits. | The workflow is CLI-first, and its default auto-commits may not match your team’s review cadence. |
A practical workflow
- Identify callers and record current behavior with characterization tests, including surprising cases clients may rely on.
- Choose one change, such as extracting a parser or moving a dependency behind an interface. Defer API changes and formatting churn.
- Review the diff against the intended scope and rerun the tests after each step. Keep commits small enough to revert independently.
Try one on your project
-
Claude Code
Inspect callers first with no edits. Approve one extraction only after the agent identifies the contract and how to verify it.
-
Cursor
Open the old implementation and its tests side by side. Accept only the edits that preserve the public interface.
-
Aider
Work on a branch, narrow the editable files and inspect the diff before building on the first commit.