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 the writer moved back to the edge — agents living inside the work environment, pulling state toward them. This is the sequel. The writer didn't just relocate. It multiplied. When writers multiply, the constraint that matters in a design changes too.

Not advice, and not "monorepo is over." One person's notes, written mostly to find where they're wrong.

Where I've landed for now (and expect to revise):

• monorepo is still good for AI — concentrated context is more efficient.
• But the real question isn't monorepo vs multirepo. It's how little your structure obstructs human + agent parallelism.
• On a team, human coordination is the bottleneck, and it caps how many agents any one person can actually run.
• Solo, with clear responsibilities and in/out contracts, multirepo works just as well — clone into a parent directory and implement across it.
• Before any of that: directory layout, naming, and feature names have to be AI-readable. That precondition matters more than the repo shape — in a monorepo and a multirepo.

monorepo helps — when "same place" is machine-readable

monorepo genuinely helps agents. Code, types, tests, dependencies, design decisions in one place; change an API and its downstream app in one commit; reason across boundaries. That's real.

But Nx keeps warning that repos merely dumped into one directory aren't a monorepo — they're code collocation: no boundaries, unstructured tooling, irrelevant tests running. What turns collocation into a benefit is the layer on top — affected-only build/test, a dependency graph, CODEOWNERS, enforced API boundaries.

So the value isn't "same place." It's same place, made machine-readable. That distinction runs through everything below.

The bottleneck is coordination, not the repo

When several people share one repo, their work collides. To avoid that, tasks, responsibilities, and review units get carved to fit human collaboration. That's correct — because the human is the bottleneck. But it also caps how many agents one developer can run. If you can drive ten agents but review-and-consensus only clears three, your effective parallelism is three.

When one person owns the whole repo, that ceiling lifts. You dispatch agents on your own judgment, across features, with no review queue in the way. You spend the parallelism directly. A concrete afternoon looks like this:

• Agent A — update the API contract
• Agent B — fix the frontend calls to match
• Agent C — write the migration and seed data
• Agent D — chase the failing tests and typecheck

Four changes moving at once, all mine to reconcile — no one to sync with first. That's the shape of work this whole post is about.

	Team, shared repo	Solo, many agents
Bottleneck	Human coordination (review, consensus)	Attention, verification, tooling
What sets the repo boundary	Coordination units	Whatever the agent reads well
Effective parallelism	Capped by review throughput	Capped by your attention, machine, and tooling
Right shape leans toward	Boundaries that fit people	Boundaries that fit agents

That gap is why the monorepo-vs-multirepo axis stopped feeling central to me. The center is the coordination boundary — and it doesn't have to line up with the repo boundary. Teams cut repos to match coordination. Solo-with-many-agents, coordination nearly vanishes, so you can draw repo lines however you like. The only constraint left is: can the agent explore, change, and verify without getting lost?

Claude Code and Codex already assume this — worktrees running a feature and a bugfix as separate checkouts at once, tasks executing in independent sandboxes. One human orchestrating many agents, treated as a first-class workflow.

At scale, "sees everything" backfires

Counterintuitively, seeing everything in a big monorepo often hurts. Anthropic's large-codebase guidance notes that a giant root CLAUDE.md and stray file reads fill the context window and degrade cost and performance; the fix is per-directory CLAUDE.md, read-deny rules, code intelligence, sparse worktrees. Research points the same way — agents don't solve more just by reading more, because broad context doesn't automatically become useful structure, and can even drop performance.

What agents need isn't full visibility. It's fast paths to the structure that matters — true in monorepo and multirepo alike. The problem was never size by itself. It's undirected size. Large is fine when the map is good; large without a map is just noise.

Before any of this: the structure has to be readable

Here's the part I actually care about most, and it sits underneath everything above. Whether you land on monorepo or multirepo, none of it works if the directory layout, the naming conventions, and even the feature names aren't legible to the agent. That precondition is more fundamental than the repo shape — it's what makes a monorepo worth its concentration and a multirepo worth stitching together.

Repo structure is itself a fact you hand the agent — rigor compresses. 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:

Layer	What it is	Why the agent needs it
AGENTS.md / CLAUDE.md	Instructions at root + per directory	Tells the agent where to look, not just what the project is
Workspace manifest	Which repos exist, how they connect	Turns a folder of clones into one workspace
Cross-repo dependency map	What depends on what	Lets the agent trace impact across repos
Unified verify commands	test / lint / typecheck / build / dev	One way to check work, everywhere
Contracts	API schema, event schema, migrations	Makes boundaries machine-checkable, not assumed

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.

Area	Do this
Structure	apps/ packages/ services/ libs/ contracts/ — responsibility legible from the name
Agent instructions	AGENTS.md / CLAUDE.md at root and per directory
Contracts	API / event schema, DB migrations, input/output contracts, made explicit
Verify	Standard test / lint / typecheck / build / dev commands everywhere
Boundaries	CODEOWNERS, public API, import boundaries, dependency rules
Parallelism	Assume worktree / sandbox / branch-naming from the start
Multirepo	Parent workspace manifest + cross-repo dependency map
AI readability	A separate "where to look" doc for agents, apart from the human README

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.