# The Agents Are Fine. Your Codebase Is a Mess.

Source: https://agentdrivendevelopment.com/the-agents-are-fine-your-codebase-is-a-mess/
Agent-readable URL: https://agentdrivendevelopment.com/the-agents-are-fine-your-codebase-is-a-mess/?agent=1
Published: 2026-10-15T11:21:00-05:00
Modified: 2026-10-15T11:23:29-05:00
Attribution: If you quote, paraphrase, summarize, or cite this material, credit agentdrivendevelopment.com and link to the source URL above.

## Summary

Your codebase teaches agents how your team works. If that lesson is a mess, refactor the repository before buying another layer of AI tooling.

## Article

Did you know the VS Code team now ships a new stable release every week? That cadence is striking, but this is not a story about how one company builds an editor. It raises a question for every engineering team: when agents make it possible to write much more code, can your team understand, verify, and clean up that code just as easily? (VS Code documents its weekly stable releases. (https://code.visualstudio.com/docs/getstarted/overview))

The useful question is not which agent wrote the code. It is whether the repository lets the team change that code safely. Clear boundaries, reliable tests, and a build path that works for everyone make it possible to produce more and still keep the system understandable. Nobody gets to announce a transformation because the team removed a few hundred lines of duplicated state handling. Yet.

That is where I think the bigger constraint sits: not in how much code an agent can generate, but in how easily the team can improve what it generated.

## The code teaches the agent

An agent reads the repository. It follows imports, inspects neighboring implementations, finds tests, tries to run the build, and infers which patterns are real. The repository is not only the thing it edits. It is the example it studies while deciding how your system works.

If the code is clear and the boundary is consistent, the agent can follow the example. If three patterns compete in the same module, there is an instruction file somewhere explaining which one is correct. Good luck to the agent, which is now doing archaeology with a word processor attached.

We see this and write another rule: do not use the legacy client; do not add another helper like this; do not put business logic in this layer. The rule may prevent another instance. It does not remove the old code, clarify the boundary, or make the tests tell us which behavior matters. We have started writing increasingly sophisticated notes about why the repository is confusing instead of making it less confusing.

We keep teaching the agent not to do what the repository keeps demonstrating.

## Stop documenting the mess

The useful question is not whether the skill is good. It is why the skill needs to be so long. If it has to explain undocumented behavior, contradict local examples, warn about missing tests, and describe the manual build sequence, congratulations: you have created an excellent incident report that runs before every change.

## Code can move. The organization still has to move it.

The scale of code change is different now. In September, GitHub’s Stephen Toub described porting the Copilot runtime from TypeScript to Rust. About 430,000 lines of production TypeScript passed through the migration; the finished runtime included more than 800,000 lines of Rust. It moved through 128 pull requests and 135 releases over roughly fourteen weeks. The project was not a one-prompt rewrite. It shipped incrementally, with extensive tests and a team supporting the work. Toub’s account (https://github.blog/ai-and-ml/generative-ai/migrating-the-github-copilot-runtime-to-rust-using-copilot/) is useful precisely because it describes the unglamorous machinery as well as the agents.

Anthropic’s published migration work describes a similar discipline: inventory the code, write a rulebook, map dependencies, then migrate in verified slices. Its migration account (https://claude.com/resources/articles/ai-code-migration) is a practical example of using agents to make a large project tractable. The token bill is real. So is the option value of a codebase the team can actually change.

The limiting factor is not simply whether a model can produce code. The hard questions are closer to home. Who understands the existing behavior? Can the team run the system and test it? Which customer promises must survive? Who owns the component that needs to change? Where does the work fit in a roadmap that is already full? Evan Boyle recently described how an agent could leave him feeling less able to modify code he had just reviewed, because generating and skimming changes had displaced the work of building a deeper model. That is worth hearing as an engineering leader: more generated code does not magically create more understanding. Boyle’s post (https://www.linkedin.com/posts/evan-boyle-107a1445_people-often-ask-me-why-use-a-cli-vs-an-ide-based-activity-7402577414612250624-2IR0) makes the cost of skipping that understanding concrete.

Those are organizational questions expressed through code. They are not solved by giving the agent a longer instruction file.

## What the executive team can change

If your teams are not seeing the benefit they expected from AI, ask them to bring you a repository and a recent change that was harder than it should have been. Follow the work with them. Where did the change get stuck? Which test established the intended behavior? How many systems or owners did it cross? What part was waiting for someone else? Then ask what would make the next change easier. Give the team room to answer before commissioning another agent strategy deck.

Do not turn that conversation into a scorecard for the team. The people who maintain the code know where it hurts. They may also know why the current structure exists: an acquisition, a rushed customer commitment, a vendor boundary, a production incident, or a decision made before the team owned the system. Ask them what makes a safe change difficult, then help remove the obstacle they cannot remove themselves.

Pick one high-churn area with a clear customer outcome. Have the team map the path from request to production. Identify duplicated patterns, missing tests, unclear ownership, slow checks, and manual steps. Agree on one improvement that makes the next change easier to understand and verify. Reserve time for it, decide what existing commitment moves, and measure the next few comparable changes. If the roadmap has no room for work that makes future delivery cheaper, then the roadmap has already made a choice. It chose to keep paying the tax.

You might find that instructions are missing. Write the short ones. You might find that the tests are useless, the build depends on one person’s laptop, or a shared module has no clear owner. Fix the thing you found. When the code and delivery path become clearer, the instructions tend to get shorter. That is a decent measure of progress: fewer paragraphs telling the next contributor how to survive the repository.

Before you conclude that AI is not delivering, look at the codebase with the people who have to change it. Your next productivity improvement may be a refactor nobody can put in a vendor comparison spreadsheet. The repository is teaching every contributor, human or agent, how your company builds software. If the lesson is a mess, stop buying better tutors and clean up the classroom.