Give the agent a contract it can check
Name one transformation: extract a duplicated calculation, simplify a conditional or isolate a dependency. Supply representative valid inputs, invalid inputs and the side effects that must not change. State which files are outside scope.
Ask for a proposed plan before edits. Compare its assumptions with the actual repository, including language version, build tools and error-handling conventions. Do not let a stylistic cleanup silently update packages or change public interfaces.
Challenge both the implementation and its tests
A model can write a test that repeats the same mistake as its patch. Check where the expected value came from. Prefer a business example or an independently calculated result to a value copied from the implementation.
Run the test against a small deliberate mutation in a disposable working copy. It should fail when the preserved rule is broken. Restore the original candidate after the experiment and retain only evidence of the test’s sensitivity.
Review the final commit rather than the narrative
Inspect the actual diff for deleted validation, changed exceptions, new dependencies and altered persistence behaviour. Run the agreed checks on the exact candidate. Keep the review tied to that version, not an earlier draft of the patch.
AI can accelerate the edit, but the owner still decides whether the behaviour should stay. Separate a bug fix from a structural refactor so that an intentionally changed result has its own acceptance evidence.
Working sheet
| Give the agent | Concrete example | Independent check |
|---|---|---|
| Transformation | Extract duplicate shipping calculation | Diff contains one shared function |
| Invariant | Free shipping starts at the same threshold | Boundary examples below and at threshold |
| Scope limit | Do not change dependency versions | Manifest and lockfile comparison |
| Error contract | Invalid currency keeps the same error | Negative-case assertion |
Questions about aI code refactoring with evidence
Which model is best for refactoring?
Use a repository-specific evaluation with the same representative task and acceptance checks. Compare correctness, review effort, data handling and total cost; an unverified general ranking does not answer those questions.
Can AI refactor legacy code without tests?
It can propose edits, but there is less evidence that behaviour survived. Establish a narrow characterisation check before relying on the transformation.
How should I use the working sheet?
Download the CSV and replace the sample rows with evidence from your repository. Record a clear acceptance check and an owner for each item. Keep unresolved assumptions visible rather than treating the example as a completed assessment.
Sources and further reading
Examples are illustrative. They are not customer results, security guarantees, or a substitute for checking the documentation for your installed version.
