· Development · 8 min read
Prepare Your Codebase for AI Agents, One Change at a Time
A practical method for making an existing codebase easier to change: name one painful change, clear only its path, and let the finished change justify the cleanup.
Prepare Your Codebase for AI Agents, One Change at a Time
Earlier this year I wrote about why teams should prepare a codebase before handing it to AI agents. Agents amplify the patterns already living in the repository, so cleanup and standardization should come first.
Most teams I talk to agree with the argument. Then nothing happens.
Not because they are lazy. Because “prepare the codebase” has no shape. It competes with features in the prioritization meeting, and it always loses. A feature has a customer waiting. Cleanup has a principle.
The meeting is really a standoff of differing priorities. Sales points at next quarter’s revenue. Engineering points at next year’s maintenance bill. Both are right, and as long as the two arguments stay separate, the same meeting repeats with the same outcome.
So the preparation gets deferred, quarter after quarter, while the agents arrive anyway and start copying whatever they find.
The fix is not a bigger cleanup plan. The fix is to stop preparing the codebase in the abstract.
A codebase is not prepared in general. It is prepared for a change.
TL;DR
When you know agents are coming but the cleanup never seems to win priority:
- Name one change the business wants and cannot make cheaply today.
- Walk that change’s path through the codebase by hand.
- Clear only what blocks that path.
- Let the agent help with the clearing, with the usual verification discipline.
- Make the change, then record what became easier.
The result is not a clean codebase. It is a codebase that is measurably easier to change than it was last quarter, with evidence to prove it.
The loop looks like this:
Named change → walk the path → clear the path → make the change → keep what you learnedWhy cleanup without a change stalls
A cleanup wishlist is a backlog pretending to be a plan. Every item feels important; no item has a reason to happen now. I wrote about that pattern in A Backlog Is Not a Plan, and it applies to technical work as much as product work.
Abstract cleanup also has no finish line and no evidence. If a team spends a month “reducing technical debt,” nobody can say what changed. When a team ships a change that used to be expensive and is now cheap, everybody can.
And when cleanup does win a slot, it drifts into busywork: polishing modules no upcoming change will cross, tidying code that was never expensive to begin with. Busywork is what preparation becomes when it is allowed to pick its own targets. It generates diffs and a feeling of progress while leaving the cost of the next change exactly where it was.
That is why preparation needs to borrow its urgency from a real change.
Step 1: Name the change in business terms
Finish this sentence:
We cannot ______ today without ______.
Some real examples I have seen:
- add usage-based billing without rebuilding the quote engine;
- support a second currency without touching forty files;
- onboard an enterprise customer without a manual security review;
- change the onboarding flow without breaking three unrelated features.
A good named change has three properties. The business already feels the pain, so it does not need to be sold. Engineering can point at where the cost lives, so the work has a location. And done is recognizable, so the effort has an end.
It also settles the standoff of differing priorities from that meeting: the business reason and the technical work travel together. The debate stops being features versus cleanup and becomes one piece of work that pays both bills.
If you cannot fill in the sentence, that is useful information too. The next move is a conversation with sales, support, or the roadmap—not a cleanup sprint.
Step 2: Walk the path before the agent does
Before asking anyone to implement the change, trace it by hand, end to end. Follow the data. Open the files. Write down every place you hesitate.
Every stumble is a preparation task:
- the same rule implemented three different ways along the route;
- a critical behavior with no test protecting it;
- a pattern that exists only in one person’s head;
- an area where nobody can say what “broken” would look like.
This is where the readiness checklist from the earlier article becomes practical. Patterns, duplication, guardrails, documentation—each item stops being a general good intention and becomes a specific obstacle on one real route. You are not auditing the whole territory. You are mapping the path you are about to walk.
The walk usually takes a day or two. It regularly changes the estimate, because the expensive part of the change is rarely the feature. It is the ground the feature has to cross.
Step 3: Clear only the path you will walk
Preparation that will not serve the named change waits its turn. On the path itself:
- Reduce the wrong examples. If the change touches three near-identical implementations, consolidate them before the agent reads them. An agent facing one pattern makes one kind of decision; facing three, it makes a blend.
- Add guardrails where the risk lives. Write characterization tests for the behavior the change must preserve. Not everywhere—in the modules the change will cross.
- Write down what an agent must know for this change. Entry points, invariants, the shortcut that looks fine and is not. A short task brief beats a long wiki nobody maintains.
- Name the boundary. Decide explicitly what you are not cleaning yet, so the change does not quietly absorb the whole backlog.
The boundary deserves emphasis. The point of preparing one path is focus. A named boundary is what keeps a two-week change from becoming a two-quarter platform project.
Step 4: Let the agent help with the clearing
The cleanup itself is good agent work: finding duplication across the route, drafting characterization tests, proposing codemods for repetitive consolidation, writing the first version of the module notes.
But the discipline from When AI Gets Faster, Verification Becomes the Bottleneck applies to cleanup exactly as it applies to features. An agent editing code you do not understand, in the name of preparation, carries the same risk as an agent editing code you do not understand in the name of progress.
A simple rule keeps it honest: the agent clears, you verify, the test suite decides. Cleanup that cannot be verified is not preparation. It is just more debt, created faster.
Step 5: Make the change, then keep what you learned
Once the path is clear, the change itself is usually smaller than the original estimate suggested. Ship it.
Then ask the same three questions I use for weekly reviews:
- What became real? The change, and the cleared path underneath it.
- What did we learn? Which preparations actually paid off, and which were ceremony.
- What is possible now that was not before? The next change that just got cheaper.
The residue matters more than the change. Each cleared path leaves behind tests, consolidated patterns, and notes that make the next path cheaper. That is the real definition of a codebase getting easier to change—not one heroic cleanup, but a sequence of changes that each left the ground better than they found it.
A practical example: usage-based billing that kept getting deferred
A B2B subscription team wanted usage-based pricing. Sales was asking for it every quarter. Engineering estimated it in months, so it was deferred. Three times.
They named the change: “We cannot add usage-based billing without rebuilding the quote engine.”
Walking the path by hand, they found pricing rules duplicated across the quote service, the invoice service, and an export script. Rounding behavior had no tests. Discount handling lived in one engineer’s memory.
The preparation was unglamorous: consolidate the billing rules into one module, with characterization tests written with agent assistance and verified against a month of real invoices. Two weeks. Then the billing change itself landed in another three.
The change shipped in five weeks after three quarters of deferral. And the evidence stuck around: the next pricing change, two months later, took days.
The cleanup got finished because it was attached to a change with a customer, a deadline, and a definition of done.
When the path stays blocked
Sometimes every path runs through the same wall. The architecture fights every change, nothing reliable protects anything, and nobody can name where the value lives. That is not a preparation problem; it is a diagnosis problem.
A focused technical diagnosis can identify which wall is load-bearing, which change is worth unclogging first, and what a credible first slice looks like. Better to spend a few days on that than a quarter on cleanup that clears paths nobody will walk.
Start with one change
Pick one change you cannot make cheaply today. Write the sentence. Walk its path this week, alone, with a notebook.
What you stumble over is your preparation backlog. It will be short, it will be justified, and unlike most cleanup plans, it will get finished.
That is how preparation stops being a wish list: one change, one path, one piece of evidence at a time.
