Use this guide when part of your code has become hard to read, full of duplication or risky to change. Have tests covering the area, or add some first, and make sure your version control is up to date.
Step by step
Define the goal of the refactor
Write down what you want to improve, such as splitting a long function, removing duplication or making names clearer. Keep the behaviour exactly the same; refactoring is not the time to add features or fix unrelated bugs. A clear goal stops the work sprawling.
Make sure tests protect the area
Run the existing tests and check they cover the code you are changing. If they do not, add tests that capture current behaviour first. Without tests, you cannot be confident the refactor has not broken anything.
Ask for a plan before code
Give the AI the code, your goal and the constraint that behaviour must not change. Ask it to propose a sequence of small refactoring steps rather than a single rewrite. Review the plan and remove anything that changes behaviour or goes beyond your goal.
Apply one step at a time
Ask for the first step only, review the change and run the tests. If they pass and you understand the change, commit it. Repeat for each step, so any problem can be traced to one small change.
Check behaviour beyond the tests
Run the application and use the affected features manually. Look out for performance changes, different error messages or altered logging. Compare with the previous version if you are unsure.
Tidy up and document
Remove any code that is now unused, update comments and documentation and make sure names are consistent. Write a short summary of what changed and why in your commit message or pull request. This helps you and others understand the history later.
Ready-to-use checklist
- Refactor goal written down
- Behaviour kept the same
- Tests cover the area
- Step-by-step plan agreed
- One step per commit
- Tests run after every step
- Manual check completed
- Unused code removed
Practical tips
- Separate refactoring commits from feature or bug-fix commits so each is easy to review.
- If the AI proposes a full rewrite, ask it to break it into smaller steps instead.
- Stop and commit when the code is better, even if it is not perfect.
Common problems
The tests broke after a refactoring step.
Undo that step with version control and ask the assistant to explain what the change did. Try a smaller step, and check whether the test or the code was at fault.
The refactored code is harder to understand than before.
Clever code is not always better. Revert the change and ask for a simpler approach that prioritises readability, such as clearer names and shorter functions.
The code has no tests and adding them seems too hard.
Start with a few high-level tests that run the feature end to end and check the result. They are less precise than unit tests but still catch major breakages.