Keeping an AI-built codebase from rotting
AI writes code fast. That is the whole pitch, and it is real. But speed cuts both ways. The same agent that ships a feature in twenty minutes can also, in those same twenty minutes, quietly duplicate a helper you already had, invent a third way to fetch data, and grow a file to nine hundred lines by appending to the bottom every time you ask for "one more thing." Fast code and fast mess are the same motion. The difference is discipline.
I have watched clean codebases turn to sludge in a couple of weeks of enthusiastic AI-assisted building. It does not announce itself. It just gets a little harder to change, then a little harder, until one day a "small" edit takes an afternoon and you cannot say why.
What rot actually looks like
It is rarely one dramatic thing. It is an accumulation of small ones.
- Duplication. The agent does not always find the utility you wrote last week, so it writes a slightly different one. Now you have two functions that do almost the same thing, and a bug fixed in one lives on in the other.
- N ways to do one thing. Three date formatters. Two patterns for calling the API. A component that fetches its own data and another that gets it via props. Every inconsistency is a small tax on the next person who has to guess which one is "right."
- Dead code left behind. You pivot, the agent writes the new path, and the old path just sits there. It still compiles. It still imports. Nobody deletes it because nobody is sure it is safe to.
- Ballooning files. Ask an agent to add behavior and it will happily append to whatever file you point it at. Do that ten times and you have a module that does eight unrelated jobs and no natural place to put the ninth.
None of these breaks anything today. That is exactly why they pile up.
The AI does not feel the pain. You do.
Here is the core asymmetry. A messy codebase costs readers. It costs the next person who has to hold the whole tangle in their head before they can safely change one line. The agent is not that person. It reloads fresh every session, reads only the slice you feed it, and never has to live with the thing. It feels no dread opening a bloated file. It pays no interest on the debt it just created.
You do. Future-you does most of all. The mess the agent makes today is drawn against an account you will pay from for as long as the code is alive.
So the taste, the standards, the refusal to let it get sloppy - that has to come from you. The agent will match the bar you set and no higher. Set none and it will cheerfully build you a swamp, one reasonable-looking commit at a time.
The disciplines that keep it clean
None of this is new. It is ordinary engineering hygiene. What is new is that you have to apply it to a collaborator who writes ten times faster than you and cares about the result exactly zero.
Smallest possible blast radius. Every change should touch as few files as possible. When I ask for something and the agent wants to edit seven files, that is usually a signal the change is wrong, not that it is big. Fewer files touched means less to review, less to break, and a diff you can actually hold in your head.
Write the conventions down. The single highest-leverage move is a house-rules file the agent reads every session - a CLAUDE.md or equivalent. Path aliases, which library does what, where things live, the naming you use, the patterns you have already chosen. Without it the agent re-decides these every time and re-decides them differently. With it, consistency stops being something you police by hand and becomes something the agent just does.
One way to do a thing. Pick the date library, the data-fetching pattern, the error-handling shape - and make it the only one. When the agent proposes a second way, that is the moment to stop and fold it back into the first. Two ways is how you get to five.
Prune aggressively. Deleting code is a feature, not a loss. Dead paths, abandoned experiments, the throwaway from last week - cut them the moment they stop earning their place. Every line you keep is a line the next change has to reason around. A smaller codebase is a faster one to work in, for you and the agent both.
Review for consistency, not just correctness. The agent's code usually works. That is the trap. Working is table stakes; the real question is whether it looks like the rest of the codebase or introduces a new dialect. I read AI diffs asking "is this how we already do it here?" at least as hard as "is this right?"
Refactor continuously, not "later." "Later" never comes. The cost of cleaning up compounds the longer you wait, so the only sane time is now, while the change is small and you still remember why. The good news: refactoring is one of the things AI is genuinely great at. Point it at a mess, describe the shape you want, and it will do the tedious part in minutes.
Keep a test suite. This is what makes all the rest safe. Refactoring without tests is a bet; refactoring with them is a chore. A decent suite is the net that lets you and the agent tear things apart and put them back with confidence. It is also the thing that catches the regression the agent introduced three edits ago, before it becomes a bisecting expedition.
Rot compounds, and it eats the speed you paid for
Here is the part that matters most. Every one of those small messes makes the next change slower and riskier. Duplication means fixing a bug in two places, or forgetting to. Inconsistency means every edit starts with a guess. A bloated file means more to read before you can safely touch anything. It compounds silently, like debt, and the interest is paid in the currency you bought the AI for in the first place: speed.
That is the quiet tragedy. You adopt AI to move fast, let the codebase rot because moving fast felt more urgent than staying clean, and six months in you are moving slower than you would have without it - now dragging a swamp the agent will also struggle to navigate. The mess does not just cost you. It costs the tool you were counting on.
The codebase is the asset. Not any single feature - the whole thing, and how cheap it stays to change. AI makes writing the next hundred changes nearly free. Keeping the codebase clean is the entire reason that stays true.