Agent Refactoring Workflow

Agent refactoring workflow

Agents are effective at mechanical restructuring and prone to changing behaviour while doing it. Working in verified steps is what keeps a refactor a refactor rather than an unreviewable rewrite.

Method

1. Establish test coverage first. Refactoring without tests is rewriting and hoping, and the agent should add characterisation tests before changing anything (see refactoring).
2. State the target structure. What the code should look like afterwards, since an agent asked to improve it will change things you did not want changed.
3. Work in small verified steps. One transformation, run the tests, commit. Large refactors in one turn are unreviewable and hard to bisect (see pull-request-size).
4. Forbid behaviour changes explicitly. Say that the refactor must preserve behaviour exactly, and treat any behaviour change as a separate commit (see negative-instructions).
5. Review the diff yourself. Agent refactors touch many files, and an unreviewed large diff is where unintended changes hide.
6. Keep tests untouched during the refactor. Changing tests and implementation together removes the safety net entirely.
7. Commit at every green point. Frequent commits make it trivial to discard a bad step rather than unpicking it (see git-workflow).

Boundaries

Refactoring preserves behaviour and does not fix design problems that need a rethink. Agents can miss subtle behavioural differences that tests do not cover. Large-scale restructuring may need a migration plan rather than a refactor (see integration-migration).