Refactoring Safely in Small Steps

Ask an AI to "clean up this class" and you will often get a complete rewrite: new names, new structure, and a few subtle behaviour changes hidden inside 300 changed lines. Refactoring safely with AI means doing the opposite: small steps, each one keeping behaviour exactly the same, each one tested and committed.

The rule: behaviour stays the same

A refactor changes structure, not behaviour. Same inputs, same outputs, same side effects. If you also want to change behaviour (fix a bug, add a feature), do that in a separate step or pull request. Mixing the two makes review almost impossible.

Say this explicitly in every refactoring prompt:

This is a pure refactor: do not change behaviour, public API, exception
types, log messages or database queries. If any step would change
behaviour, stop and tell me instead.

Step 1: Tests before refactoring

If the code has no tests, add characterisation tests first: tests that record what the code does today, even if some of it is odd.

Write xUnit tests that capture the current behaviour of this class,
including edge cases and current error handling. The goal is to detect
any behaviour change during a refactor, not to judge the behaviour.
[paste class]

Run them and commit. Now you have a safety net.

Step 2: Ask for a plan, not code

This 400-line OrderService is hard to change. Suggest a refactoring plan
as a numbered list of small steps. Each step must keep behaviour the same,
compile on its own and be small enough to review in a few minutes.
Examples: extract method, introduce parameter object, move pricing logic
into its own class. Do not write code yet.

Reorder or remove steps you disagree with. Prefer the boring, mechanical steps first.

Step 3: One step at a time

For each step:

1. Ask the AI for only that step.
2. Apply it, build and run the tests.
3. Read the diff (git diff). Look for anything that is not a pure move or rename.
4. Commit with a clear message: "Refactor: extract CalculateShipping from CreateOrder".

If a step goes wrong, git checkout . and try again. Small commits make this cheap.

Use the IDE where you can

Many refactorings are safer done by the IDE than by AI, because the IDE understands every reference:

• Rename symbol
• Extract method or interface
• Move type to file
• Change method signature

A good split: let the AI decide what to do and why, let the IDE do the mechanical changes, and use the AI for the parts the IDE cannot do, such as splitting logic into new classes.

What to look for in AI refactor diffs

• Changed conditions (> became >=, && became ||)
• Changed order of side effects (save before validation, logging moved)
• Swallowed or changed exceptions
• LINQ rewritten in a way that changes the SQL EF Core generates (lesson 7)
• Async changes: a missing await, or .Result introduced
• "While I was there" changes you did not ask for

Ask the AI to review its own diff (Prompt Writing That Works, lesson 6):

Review this diff as a strict reviewer. Is there any change in behaviour,
however small? List each one with the line.

Agents and large refactors

Coding agents can carry out a refactor across many files and run the tests for you. Give them the same rules: pure refactor, one step per commit, stop if tests fail. Then review each commit, not just the final result.

Practice task

Pick one long method or class you have been avoiding. Add characterisation tests, ask for a step-by-step plan, and complete at least three steps, each with build, tests, diff review and its own commit.

Key takeaways

• A refactor keeps behaviour identical; do behaviour changes separately.
• Add characterisation tests first.
• Ask for a plan of small steps, then do one step per commit.
• Use IDE refactorings for mechanical changes, and review every AI diff for hidden behaviour changes.