dosa.dev logo Workflow guides

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

  1. Identify callers and record current behavior with characterization tests, including surprising cases clients may rely on.
  2. Choose one change, such as extracting a parser or moving a dependency behind an interface. Defer API changes and formatting churn.
  3. 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.

← All workflow guides