---
title: "Fowler's Refactoring catalog as a vocabulary for agents"
description: "When an agent does the refactoring, the catalog's value is its names: a named move is a request you can check a diff against."
url: "https://michael.zazon.us/notes/fowlers-refactoring-catalog-as-a-vocabulary-for-agents"
published: "2026-04-04T12:00:00-04:00"
kind: "book-notes"
subject: "architecture"
tags: ["agents","code-quality"]
---
I've found that asking an agent to "refactor" a module can lead to unpredictable results.. sometimes it'll carefully clean up the code, and sometimes it'll rewrite half the file. This unpredictability made me curious about what the term was **intended** to mean. For a precise definition, we can turn to Martin Fowler's [Refactoring](https://martinfowler.com/books/refactoring.html). The 2nd edition (2018) is mostly a catalog of small named moves (Extract Function, Split Phase, Replace Loop with Pipeline, etc) with motivation and step-by-step mechanics for each one. All of the entries were redone with JavaScript examples for the 2nd edition. The defining property of all of these moves is that they **preserve the observable behavior** of the code.

Of course, the meaning of the word had drifted long before we had agents.. Back in 2004, Fowler [wrote](https://martinfowler.com/bliki/RefactoringMalapropism.html) that if your system is broken for a couple of days during a "refactoring", it's almost certainly not refactoring. But today, asking an agent to refactor a module will often result in a rewrite, and losing a feature along the way is a common complaint among users of these tools.

I think the names are what survive automation. The mechanics were always going to be handled by tools. A shared vocabulary lets you ask for one change and check that only that change happened. "Split Phase on this function, no behavior change" instructs the agent and tells the reviewer what to look for in the diff: just that move. "Refactor this" doesn't give you anything to check against. A [2025 study](https://arxiv.org/abs/2510.03914) showed that instructions built on Fowler's catalog let LLMs do every refactoring type in its benchmark while preserving behavior.

That same study found something unexpected: when the model was given the refactoring goal instead of the transformation to apply, it improved code quality more than when it was told exactly what to do. I'm landing on naming the move when I need to review the change, and naming the goal when exploring. For those using agents, the open question seems to be: if goal-led prompts produce better code, how much quality are you willing to trade for changes that are easy to review?