Refactor or rewrite — and why the agent always votes for the rewrite

You show an agent a tangled file and ask what to do with it. The answer is almost certainly: "let me rewrite it from scratch, it'll be cleaner."

Sounds reasonable. Here's what's worth knowing before you agree: the model suggests this not because it's better. Because rewriting is cheaper for it than understanding.

Writing two hundred fresh lines is a straightforward task for it. Holding in mind why your two hundred old ones are written exactly that way — with three hacks and a strange condition in the middle — is much harder. The rewrite is the path of least resistance, and it arrives dressed as advice.

So let's work out when it actually is advice.

How refactoring differs from rewriting

One difference, but it determines everything else.

Refactoring — you change the code without changing behaviour. From the outside the app works exactly as before: same buttons, same answers, same bugs. Inside, it's tidier. The technique itself is covered separately: what refactoring is.

Rewriting — you throw the code away and make it again. Only the intent survives: "this thing should show a task list." How, you decide from scratch.

The key consequence: refactoring gives you a reference — the old behaviour to check against. Rewriting gives you none. You find out what you lost when a user shows up and tells you.

Five criteria

These are the axes the decision is actually made on — not "which is prettier."

1. What survives

• Refactor: behaviour in full, including the non-obvious parts. Every little "oh, and it also does this" survives the change.
• Rewrite: only what you remembered and wrote down. Everything else is lost silently.

2. Risk

• Refactor: small and spread out. Broke something — undo one step.
• Rewrite: large and deferred. It breaks not now but next month, in a rare scenario everyone forgot about.

3. What you check against

• Refactor: the old behaviour. Even without tests you can compare by hand: it did this, it still does this.
• Rewrite: tests, or a written list of scenarios. If you have neither, you aren't rewriting — you're guessing.

4. When you see a result

• Refactor: immediately. Every step is complete; the project works the whole time.
• Rewrite: at the end. In the middle you have two half-built versions and nothing that runs.

5. What happens to a known bug

• Refactor: the bug moves along with the code. It gets fixed separately, deliberately.
• Rewrite: the old bug disappears — and three new ones arrive that you don't know about yet.

One line summary: refactoring changes the form while the content is known; rewriting changes both at once. Which is why the second is nearly always more expensive than it looks at the start.

Why models vote to rewrite

Three reasons, and none of them is about your code's quality.

First, context. The agent sees the file but not its history: who added that condition, when, and after what pain. To it, a strange line is just a strange line.

Second, the shape of an answer. Models are trained to produce a finished, polished result. "Rewrite it all" is a beautiful complete answer. "Change these four lines and leave the rest alone" is a modest one — though it's often worth more.

Third, confidence isn't knowledge. A model states verified things and invented things with exactly the same assurance. Worth remembering always — including when it explains why your old code is bad.

The temptation predates neural networks, incidentally. Joel Spolsky's classic 2000 piece about Netscape deciding to rewrite its browser from scratch spread precisely because of the conclusion: the rewrite ate years while competitors just fixed theirs piece by piece. "Start with a clean slate" is an ancient and very human urge.

Who should do which

No fence-sitting.

Refactor if you can explain what the code does. It may be ugly — you understand its logic. That's your situation nine times out of ten, and especially if real users already depend on the project.

Rewrite if both conditions hold at once:

1. You cannot explain what the code does, even after asking a model to walk you through it line by line.
2. You have something to check the new version against — tests, or at minimum an honest written list of scenarios that must work.

One condition isn't enough. Don't understand the code and have nothing to verify with? Don't rewrite — do the second part first. Writing fifteen scenarios down takes an hour. Reconstructing lost behaviour from user complaints takes a month.

And one case people confuse with rewriting: the code is clear, but the architecture can't carry the new requirements. That isn't "rewrite" — that's redesign and migrate in pieces, leaving the old thing running until the new one is ready.

If you are rewriting — three rules

1. Pin the behaviour first, touch the code second. The scenario list or the tests come before, not after. Otherwise the reference exists only in your head.
2. Don't delete the old version. Let it sit alongside until the new one has survived a week in production. A commit with a working version is your only undo button.
3. Rewrite in shippable chunks. One screen, one module. A rewrite you can't ship in parts has a habit of never finishing.

And a small everyday move. Before agreeing to "let me rewrite it," ask the agent a different question: "explain line by line what this code does and why each condition is here." Sometimes it turns out the code is fine and was only confusing because of two bad variable names. Then the whole job is renaming. That's refactoring in its purest form — and models are far better at making sense of unfamiliar code than at guessing what mattered in it.

Should refactoring change behaviour?

No — that's the whole point. If behaviour changed, it isn't refactoring, it's a functional change, and it needs different verification. Mixing the two in one commit is a reliable way to not know later what actually broke.

Can I ask AI to refactor instead of rewrite?

Yes, but ask explicitly and with boundaries: "don't change behaviour, don't touch other files, show only the changed lines." Without limits a model defaults to rewriting — that's its natural mode.

How much code should I rewrite at once?

As much as you're willing to verify in one sitting. A practical yardstick: one screen or one module. If the chunk is big enough that verification can only happen "sometime later," it's too big.