$ cat choices/monorepo.md
the call
For an org, this is my default, and I'll defend it hard. One repo, one source of truth: every cross-cutting change lands atomically, the tooling is shared, and rollback is one revert. And in the age of LLMs it's gone from preference to leverage. The monorepo is the one context boundary an agent can actually reason over.
One repo, one source of truth. A change that spans the API, the web app, and the mobile client lands as one atomic commit: reviewed together, shipped together, reverted together. Tooling, CI, and standards are defined once instead of drifting across a dozen repos. The connection between a change and the thing it changes is never lost in cross-repo navigation. For an org, the alternative (polyrepo) quietly taxes every cross-cutting change and every refactor, and the tax compounds as you grow.
The honest exceptions are narrow: a polyrepo earns it for genuinely independent teams that share nothing, a strict regulatory regime where the deploy actor must have zero path to app code, or open-sourcing a single library on its own. Outside those, “we’ll just use separate repos” is usually inherited habit, not a decision. The one real cost to respect: a monorepo demands tooling that scales (fast, path-aware CI and good codeowners) or the shared repo becomes a shared traffic jam.
The reason I now argue for it even harder: the agent era. An agent fleet is only as good as the context it can see, and a monorepo is the largest coherent context boundary there is: the whole system, its tests, its history, and its deploy manifests in one place an agent can read and reason over. Split that across ten repos and the map an agent (or a new engineer) needs is scattered across ten places it has to stitch back together. The monorepo keeps the map legible, which is the whole game when generation is cheap and understanding is the scarce thing.— see: choices / the-agent-fleet · writing / Volume Is Free Now
Put the whole system where one mind, human or model, can hold it at once. Boundaries should exist because the domain demands them, not because the repo tooling made splitting the path of least resistance. The cost of a monorepo is paid once, in tooling you’d want anyway. The cost of sprawl is paid forever, by everyone who has to reassemble the picture before they can change it.
the gaps — what it costs even when it’s right
It demands tooling that scales. Path-aware CI, incremental builds, and codeowners aren’t optional. Without them the shared repo turns into a shared bottleneck where everyone waits on everyone.
Access control gets more deliberate. “Everyone can see everything” is a feature until it isn’t. You enforce boundaries through codeowners and merge rules instead of repo permissions. A different discipline, not a free one.
It can hide missing boundaries. One repo makes it easy to reach across modules that should be decoupled. A unified repo doesn’t excuse the architecture from having real seams. It just stops being the thing that enforces them.