Skip to content
Arara Code

Guides and comparisons

Refactoring with AI without breaking your code: guide

Refactoring with AI means asking the agent to change the internal structure of code without altering observable behavior. The safe process has three parts: tests that cover current behavior, small steps with one commit each and diff review before moving on.

Arara Code

Published by the Arara Code project based on the official documentation cited.

What refactoring is and what changes with AI

Martin Fowler defines refactoring as changing the internal structure of software to make it easier to understand and modify, without changing its observable behavior. The definition works as an acceptance criterion: if behavior changed, it was not refactoring.

AI agents rename and extract across many files quickly, but they can also mix refactoring and feature changes in the same diff, which makes review harder.

Refactoring.com: Martin Fowler refactoring catalog

Write the tests before asking for the change

Without tests, there is no way to prove behavior stayed the same. In legacy code with no coverage, first ask for characterization tests, which record what the code does today, and only then the refactoring.

Run the suite before and after each step. If a test fails, undo the step with git instead of asking the agent for successive fixes.

Wikipedia: Code refactoring

Small steps, using names from the catalog

The refactoring catalog on refactoring.com gives precise names, such as Extract Function, Rename Variable and Inline Function. Using these names in the prompt reduces ambiguity and limits the scope of the change.

Ask for one kind of refactoring at a time, in one module, and make one commit per step. Small diffs are quick to review and let you use git bisect to find the responsible commit if something breaks later.

Git: git bisect documentation

Refactoring workflow in Arara Code

In Arara Code you use Claude Code, Codex or Kiro in the same editor: ask for the step, see the agent diff and run the tests in the integrated terminal before accepting.

Record the refactoring rules in the repository AGENTS.md: do not change behavior, run the tests at every step and ask for one kind of refactoring at a time. All agents follow the same instructions.

Arara Code repository on GitHub

Sources and further reading

Read as Markdown

Keep exploring

Make room for your next idea.

Get to know Arara Code in your own project. Start with the installer and review the changes your assistant makes.