Refactor Legacy Code Safely with AI Assistance

Define the goal of the refactor

Refactoring changes structure without changing behaviour. Decide what you want to achieve: making a feature easier to add, removing duplication, separating responsibilities or improving testability. Write down the scope and what is out of scope. A refactor with a clear goal can be finished; an open-ended clean-up tends to grow until it is abandoned halfway, leaving the code in a mixed state.

Understand before changing

Use an assistant to summarise the module, trace how it is called and list its inputs, outputs and side effects, such as database writes, emails or global state. Verify the summary by reading the code and, where possible, running it with logging. Ask the assistant which parts look risky, then confirm with version history: frequently changed files and recent bug fixes point to fragile areas.

Build a safety net first

Write characterisation tests that capture current behaviour. An assistant can propose inputs and edge cases quickly, but produce expected outputs by running the existing code rather than asking the model to predict them. Cover the main paths, boundary values and known odd behaviour. If the code is hard to test because it creates its own dependencies, make the smallest possible change to inject them, such as passing a clock or client as a parameter, and test that change carefully.

Refactor in small, verified steps

• Ask the assistant for one specific transformation at a time: extract a function, rename for clarity, replace a conditional with a lookup, move a responsibility to a new module.
• Review each diff and run the full test suite after every step.
• Commit each green step with a clear message, so any step can be reverted alone.
• Keep behaviour changes and bug fixes out of refactoring commits; record them for a separate change.
• Restart the AI session with a short summary when context becomes long or confused.

Watch for typical AI mistakes

Assistants sometimes change behaviour while claiming to refactor: altering rounding, error messages, default values or the order of side effects. They may also update tests to match new behaviour or touch files outside the scope. Read diffs carefully, protect test files from modification during refactoring steps and compare outputs before and after on real or realistic inputs.

Finish and leave it better documented

When the goal is reached, replace characterisation tests with clearer behaviour-focused tests where useful, remove dead code and update documentation and diagrams. Write a short note in the pull request about what changed structurally and why, so reviewers and future maintainers understand the new shape.

Checklist

• The refactor has a written goal and scope
• Module behaviour and risks are understood and verified
• Characterisation tests use outputs from running the current code
• Each step is small, reviewed, tested and committed
• Behaviour changes are kept separate
• AI diffs are checked for silent behaviour changes
• Documentation reflects the new structure