Is your codebase ready for AI agents?

Why readiness matters: the economics of an agent's work

An agent works by reading context, forming a plan, editing files, and checking its work — repeatedly, within a finite context window and a token budget. Everything that makes your repo hard to reason about taxes that loop directly. When module boundaries are fuzzy, the agent can't tell what a change will touch, so it reads more files than it needs, fills its context with noise, and still guesses wrong. When there are no tests, it has no way to know whether its change worked, so it either declares victory blindly or loops trying to verify by inspection. Ambiguity doesn't slow an agent down gracefully; it makes the agent thrash — expensive, and often wrong.

This is why "can an agent work here?" is really the question "is this codebase legible?" A legible repo is one where a competent stranger could open it, find the boundary of the thing they need to change, understand the local conventions, make the change, and prove it works — without a tour from a senior engineer. Agents are that competent stranger, every single session, with no memory of the last one. The features that help them are not agent-specific tricks; they are the features that make onboarding fast and make changes safe. Readiness work is engineering-quality work that happens to have an immediate, measurable payer attached.

The corollary matters for setting expectations: an agent will not fix a badly structured codebase for you, and pointing one at a fragile repo tends to amplify the fragility rather than reveal a shortcut around it. The leverage runs the other way. Invest a little in legibility first, and the agent becomes genuinely useful across the whole repo; skip it, and you get plausible-looking diffs that quietly break things two modules away.

The dimensions of an agent-ready repository

We assess readiness qualitatively across a handful of dimensions. It isn't a numeric score — treat it as a rubric that tells you where the next hour of effort should go. Module boundaries come first because everything else rides on them. If the responsibilities of a module are clear and its dependencies are explicit, an agent can scope a change to a small, correct blast radius. If everything imports everything, the agent has to hold the whole system in context to be safe, which it cannot, so it makes locally plausible edits with global consequences.

Tests are the agent's feedback loop. A change an agent can't verify is a change you can't trust. A suite that runs fast, covers the critical paths, and fails loudly gives the agent a way to check its own work and self-correct before you ever see the diff — this is the single feature that most changes how much you can delegate. Types do a related job at a finer grain: a well-typed interface tells the agent what's allowed before it runs anything, catching whole categories of mistake at the boundary and shrinking the space of wrong guesses.

Documentation and specs carry the intent that code alone can't. Code says what the system does; it rarely says what it's supposed to do, or why a non-obvious decision was made. An agent that can read a short design note or an accurate README doesn't have to reverse-engineer intent from implementation — and reverse-engineered intent is exactly where confidently-wrong changes come from. Context files — an agent rules or instructions file such as CLAUDE.md or the equivalent your tool reads — are where you write down the things that live in senior engineers' heads: how to run the tests, which patterns to follow, what to never touch. Consistent conventions make the whole repo predictable, so the agent can pattern-match from existing code instead of inventing a new style each file. And CI is the backstop: lint, type-check, and test gates that catch a bad agent diff automatically, so an agent's mistake is a red check rather than a production incident.

How to assess your repo honestly

You can get most of the signal in an afternoon, and the fastest way is empirical: give an agent a small, real, self-contained task in the repo and watch what happens. Where does it get confused? Which files does it pull into context looking for something that should have been obvious? Does it invent a convention because it couldn't find yours? Can it tell whether its change worked? The friction the agent hits is a direct readout of where your repo is illegible — it's the same friction a new hire hits, compressed into one observable session.

Then walk the dimensions and mark each honestly as strong, workable, or weak. Can you draw the module map from memory, or does everything depend on everything? Does a clean checkout build and test with documented commands, or is there tribal knowledge in the setup? If a test fails, is the message actionable? Is there a single place that tells a newcomer how this repo works — and is it current, or quietly lying? Resist the urge to grade generously. The point of the assessment is to find the one dimension that, fixed, unblocks the most agent work — usually it's whichever weak spot the agent tripped over first.

Weight the rubric by where you actually want to use agents. If you're delegating bug fixes in one well-worn service, the readiness of that service is what matters, not a monorepo-wide average. Readiness is local: a repo can be excellent in the module you've been maintaining for years and hostile in the one nobody understands. Scope your assessment to the surface you plan to hand over.

The highest-leverage fixes, in order

Start with the smallest thing that removes the most guessing: a context/rules file. Writing down how to run the tests, the conventions to follow, the commands that matter, and the parts of the system to leave alone is usually an hour of work that immediately stops the agent reinventing your setup every session. It's cheap, it's reversible, and it pays off on the very next task. Do this first even if the rest of the repo is a mess.

Next, make the repo verifiable. If there's a test suite, make sure the agent can find and run it and that failures are legible; if there isn't one, backfill tests on the critical paths you most want to hand over — you don't need full coverage, you need a signal the agent can trust on the code it will touch. A characterization test around a gnarly module is worth more to an agent than a hundred trivial ones elsewhere. Only after verification is in place should you invest in the deeper structural work: clarifying module boundaries and tightening types at the interfaces the agent crosses most.

Sequence matters because the fixes compound. Tests make boundary refactors safe — including refactors an agent helps you do. A context file makes every subsequent task cheaper. Clear boundaries make types easier to add. The wrong move is a big-bang "agent-readiness project" that tries to fix everything at once; the right move is to fix the one thing blocking the work in front of you, use the agent on that now-unblocked surface, and let the improvements accrete where you're actually spending time.

Context files and agent instructions, specifically

A context file — CLAUDE.md, an agent rules file, or whatever your tooling reads — is the single artifact with the best effort-to-payoff ratio, so it deserves its own treatment. Think of it as the README you'd write for a sharp engineer who is joining for one task and leaving immediately, with no memory of last time. It should cover how to build and test, the conventions that aren't obvious from the code, the architectural facts an agent would otherwise have to rediscover, and — crucially — the things not to do: the module that looks refactorable but isn't, the generated files to leave alone, the pattern you've deliberately moved away from.

Keep it short and true. A long, stale context file is worse than none, because the agent trusts it and acts on the lie. Treat it as living documentation: update it when conventions change, and when you catch the agent making the same mistake twice, the fix usually belongs in the context file, not in a one-off correction you'll have to repeat next session. That feedback loop — mistake, then a durable line in the rules file — is how the repo gets more agent-ready over time instead of just once.

Context files are also where you connect the agent to the rest of your world. If your team uses MCP servers to expose internal tools, docs, or data, referencing them here lets the agent reach the context it needs instead of hallucinating around a gap. But keep the boundaries in the instructions themselves — what it may touch, what requires human review — because the file is guidance, not a hard permission boundary. The real guardrail is still your CI and your review process; the context file just makes the agent far less likely to need catching.