Why Your Messy Codebase Is Now a Performance Problem · Hanh D. Brown

Watch a new hire on their first week. They open the codebase, find something that looks like the thing they were asked to build, and copy it. Nobody taught them that. It is what anyone sensible does in an unfamiliar room.

Now put an Artificial Intelligence (AI) agent in that chair. It does the same thing. At speed. All day.

That is why the mess in your repository stopped being a matter of taste. It is a setting on every tool you just bought.

Why does a messy codebase slow an AI coding agent down?#

Agents learn your house style the only way available to them. They read what is already there.

That is a reasonable strategy and it is the same one a person uses on their first day in a new office. Find the nearest working example, follow it, ask later. Like a house rewired halfway, the room has two kinds of wiring behind the wall. A person eventually notices. The machine keeps copying whichever one it found first.

So the cost of mess changed shape. It used to be paid slowly, in the hours people spent reading around a thing before they dared touch it. Now the bill arrives at once and keeps arriving, because a tool copies whatever it finds every time it is asked. It never gets the uneasy feeling that something looks wrong.

What does a half-finished migration do to an AI agent?#

Half a migration is worse than no migration at all, and that is the part teams get wrong.

Consider the arithmetic of it. An unmigrated codebase has one answer to any question, even if the answer is old. A fully migrated one also has one answer. Half migrated leaves two, side by side, both working. Nothing on the page says which one you meant.

A person resolves that by walking to the next desk and asking. An agent has nobody to ask, so it picks, and it reliably picks whichever pattern appears more often in the files around it. Old code is usually the code there is more of. That is the whole trap, and it springs every day.

The agent does not know which pattern you meant. It knows which one it found first.

Here the mess stops being a style argument and becomes an engineering one, which is a shift with real budget consequences. I wrote about the same move in why the quality bar rose.

How much does a clean codebase actually buy you?#

A clean, fully migrated codebase is reported to raise productivity by a double digit percentage.

Be careful with that number. It is the kind of figure that gets repeated until it sounds like physics. The speaker states it plainly and points at published work behind it, but that work is not named on the record in front of me.

No method reached this page. No baseline. No definition of the measure. That is why nothing here plots it on a chart. A number drawn as a bar reads as a measurement, and this one has not yet shown its working.

What the claim is good for is direction, not magnitude. It tells you the sign of the effect and roughly its weight in a week of work. Treat it as a reason to finish the migration you already started, not as a promise about your own numbers.

Independent work is beginning to arrive. Early studies look at redundancy in assistant written code. Others look at debt in assisted development. Read them before you quote a percentage to anyone holding a budget.

Why did plain search beat the vector database?#

The clever retrieval system lost to two ordinary commands.

One team built a local vector database so their tool could find relevant code. They removed it. In its place went two plain commands, the ones that match a pattern and walk a directory. The plain approach won once the model was good enough to drive it.

Two things sank the sophisticated version. The index drifted out of date the moment anyone wrote a new page of code. It returned yesterday’s answer, confidently. It also raised awkward questions about permissions, because an index is a second copy of your code and it needs the same wall around it as the first.

There is a lovely echo of this at Meta. A broken jump to definition feature pushed engineers to search the raw text across the whole codebase instead. That habit, born of a broken door, turned out to suit machines too.

Generalise that past search. A tool that reads your repository inherits your repository’s quality. So design the two together, as in a system and its parts at once.

What should you clean up first?#

Start where the agent trips most often, not where the code offends you most.

Those are different places, and confusing them is how cleanup budgets get spent on the wrong doors. The prettiest refactor in the repository may sit in a corner the machine never visits. The ugliest thing may be the file every single task touches on its way through.

A short way to find the loud corner:

• Read the changes the agent got wrong last week.
• Note which file each one touched.
• Look for the same name appearing twice.
• Finish the migration around that name first.

That is a morning of work. It names the culprit without argument, because the evidence sits in your review history rather than in anybody’s opinion. Nobody has to be persuaded. The file names repeat, and repetition is hard to argue with.

Who owns this work when nobody wants it?#

Somebody has to be told to do it, because nobody volunteers for it, and that is not a character flaw.

Cleanup has always lost the argument against shipping. It is invisible when it works and it never appears in a demo. One large company answered that with a mandate. Every engineer spent a fifth of their time on it. The time was split deliberately into two kinds: work a team chooses for itself, and large migrations decided from above.

Both halves matter. Teams know which floor creaks. Only leadership can fund the thing that crosses ten teams and pays back in a year.

Like a farm where everyone wants the harvest and nobody wants to clear the field, somebody has to put the clearing on the calendar.

What changed is the argument you get to make. This used to be a request for time to make things nicer. That loses. It is now a request to raise the speed of every tool the company just paid for. Different conversation. It also connects to where the real constraints sit, as in the weak links that decide the outcome.

There is a human side as well. The engineer who inherits an unfinished migration carries a quiet tax. Every task takes longer. Every review runs slower. None of it shows up in anything anyone praises. That wears on a person, and it follows them home to their family. Finishing the work is not only a performance decision. It is a decent one.

Source: Boris Cherny, Head of Claude Code at Anthropic, podcast interview.