Bad codebases make bad agents, and agents can make a codebase bad fast: they copy whatever patterns they find, good or bad. Learn the principles that keep a codebase agent-friendly: make the shortest path the right path, deep modules, one way to do each thing, enforced architecture, simple code, and continuous cleanup.
Key takeaways
- Agents copy the patterns they find. Garbage codebase in, garbage code out.
- Without steering, agent-built codebases decay fast, sometimes within weeks.
- Make the shortest path the right path: conventional structure, one way to do each thing.
- Deep modules with thin interfaces, strong types and fast, reliable tests are agent superpowers.
- Clean continuously: encode golden rules and let background agents open small refactor PRs.
Try it with your agent
Audit your repo for agent-friendliness:
Audit this codebase from an agent's point of view. Find: several ways of doing the same thing, shallow or tangled modules, weak types, flaky or slow tests, and patterns an agent would copy badly. Rank the top 5 by how much they'd mislead an agent, with a fix each.
Transcript
Intro
Matt Pocock puts it bluntly: bad codebases make bad agents. If you have a garbage codebase, you'll get garbage out of the agent working in it. This lesson is about the codebase side of agentic engineering.
Agents copy patterns
Why does the codebase matter so much? Because agents imitate it. OpenAI's harness team found their agent replicates patterns that already exist in the repository, even uneven or suboptimal ones. Over time, that inevitably leads to drift.
Decay is fast
And drift is fast. Mario Zechner says agents, making local decisions, pile up abstractions, duplication and backwards-compatibility shims. You get enterprise-grade complexity within two weeks, with just two humans and ten agents. Dex Horthy finds agents start to struggle in a codebase after three to six months.
Why it happens
Kent Beck names the mechanism. Agents are prone to decisions that cause disruption at a distance. They don't reduce coupling or increase cohesion unless you tell them to. Each change is locally reasonable, and together they make a mess.
The shortest path
The first principle comes from Lauren Tan: make the shortest path the best path. Agents love shortcuts. So structure your code so that the lazy route is the correct one. Put a feature's code together in one place, and keep one obvious way to do each thing.
Deep modules
Second, prefer deep modules: a small interface hiding a lot of functionality. Left alone, agents tend to produce many tiny, shallow modules that are hard to navigate. Matt Pocock's approach: design the module interfaces yourself, and delegate the implementations, treating each module as a gray box with tests at its boundary.
Sameness
Third, sameness. Ryan Lopopolo's goal is to make the tokens needed for the job easy to predict, by making things the same as much as possible. One ORM, one language, one style of CI script, one way to do each shared thing. And with agents, finishing migrations is cheap, so don't leave two ways around for months.
Enforced architecture
Fourth, enforce your architecture. OpenAI's team gives every domain the same fixed layers, from types, to config, to repositories, services, runtime and UI, with dependency directions checked by custom linters. They note that this kind of architecture is usually postponed until you have hundreds of engineers. With agents, it's an early prerequisite.
Simple code
Fifth, keep code simple. Armin Ronacher's experience: simple code significantly outperforms complex code in agentic contexts. Ask for the dumbest thing that will work. Prefer plain functions with descriptive names over clever class hierarchies, and generating a few lines over adding a dependency.
Strong feedback
And give the agent strong feedback built into the code itself. Matt Pocock's wish list: more tests, higher quality tests, non-flaky tests, and above all, types, types, types. Thorsten Ball adds that over time, your codebase should hold more and more of the how-to knowledge, so your prompts can get shorter.
Clean continuously
Finally, clean continuously. OpenAI's team first spent every Friday, a fifth of the week, cleaning up AI slop by hand. It didn't scale. So they encoded golden principles as rules, and scheduled background agents that scan for deviations and open small refactoring pull requests. Garbage collection for code.
Quick check
Quick check. Your codebase has three different ways to query the database, and agents keep mixing them. What's the best fix? Tap your answer.
Try it
Audit your codebase from an agent's point of view. This prompt finds the places most likely to mislead an agent, and suggests a fix for each.
Recap
Recap. Agents copy what they see, so decay is fast. Make the shortest path the right path. Deep modules, one way to do each thing, enforced architecture, simple code and strong feedback. And clean continuously. Next: how to measure whether your agents are actually doing well, with evals.