AI Agents Don't Need a Monorepo. They Need a Readable Codebase

For an AI, a monorepo is good — concentrated context is more efficient, everything in one place. But lately I've stopped asking whether a project is monorepo or multirepo. The repo boundary is no longer the unit I care about most. The coordination boundary is — and underneath even that, one plainer thing: whether the codebase is readable to the agent at all.

By readable I mean something concrete: the agent can infer responsibility from names, find the right files fast, see where boundaries are, and verify a change with predictable commands. That holds in a monorepo and a multirepo alike — and it decides more than the repo shape does.

The situation I'm writing about is the solo-or-small-team case: one person orchestrating many agents, with little time spent negotiating boundaries with other humans. So the question I ask first is — can I run several agents on this codebase at once without them, or me, becoming the thing everyone waits on?

I once wrote that . Vague structure burns tokens on guesses; machine-readable structure lands in a line. Reports back this up — LLM-friendly structure maps improving accuracy and cutting completion time, text+structure hybrids trimming input tokens, AGENTS.md alone reducing runtime and token spend. The numbers are workload-dependent, so I don't take them literally, but the direction is consistent.

So the order of operations is the opposite of how the debate usually runs. Pick the repo shape last. Make the structure readable first.

The repo is physical. The workspace is operational.

Readable first — then the question becomes how to keep it readable when the code is split across repos. The unit shifts from repo to workspace. Claude Code's --add-dir pulls sibling repos into one session; Nx points at "synthetic monorepo" infrastructure to view across repos. The idea: repos can be split, but the agent sees one meaningful workspace.

My old line — clone several repos locally, open the parent directory, implement across them in one context — fits here. But the parent directory alone is weak. What earns its keep is the thin layer above it:

With that layer, multirepo behaves like a synthetic monorepo. Without it, even a clean monorepo wastes context.

Objections I'd raise myself

• 
  "multirepo is just heavier ops." Half true — migration fan-out, cross-repo visibility, dependency tracking. My claim is conditional: when the coordination boundary disappears, multirepo + parent workspace beats a team-shaped monorepo more often. Not always.


• 
  "contracts rot." The load-bearing objection. The moment a contract drifts from the code, the synthetic workspace is a fiction. So contracts have to be enforced in CI, not kept as a promise humans remember.


• 
  "don't generalize solo to teams." I don't. Teams need coordination; carving repos to fit it is correct. My one point: the right shape moves with coordination cost. Fewer people, more agents per person → the scale tips toward workspace + contracts.


• 
  "synthetic monorepo is fragile." It is. Clones under a parent directory collapse fast without a manifest and a dependency map. Tooling is still thin here, and I'm feeling my way.

A checklist that earns its place

Not exhaustive — roughly the order I've found things matter.

The shape, in one line

monorepo is still a good way to colocate context — for an AI, concentration is efficiency. But the win isn't the monorepo. On a team, split responsibilities so humans don't block each other. Solo with many agents, clear contracts let a multirepo do the same job. And underneath both, the thing that actually decides whether an agent thrives is the same: is the structure readable?

The writer moved to the edge, then multiplied. What paces the multiplied writer is no longer where the code lives. It is how far humans and agents can move without waiting on each other — and how quickly an agent can find its way around before it moves at all.

Repo design in the AI era isn't about where you put the code. It's about how readable the structure is, and how little you obstruct the parallelism between humans and agents. Held loosely — a view I plan to keep testing as I design against it.