Monorepo vs Polyrepo Tradeoffs for Agentic Software Factories

A developer spends weeks with a codebase and slowly builds a feel for it: which service calls which, where the fragile parts hide, what breaks the moment someone touches the auth module. An agent gets none of that. It starts cold every session, and whatever it knows about a repo has to come from the structure and tooling sitting in front of it right then, not memory of last Tuesday's incident.

Three things matter, in this order. First, queryable structure: an agent has to find blast radius, meaning which packages or services a change touches, through a tool call, not a hunch. Second, bounded context: agents do better with the right slice of a codebase, filtered down to fit inside a context window, without a pile of irrelevant files crowding out what matters. Third, canonical instructions: a file like AGENTS.md gives an agent a fixed, predictable place to find project rules and intent, the same job an onboarding doc does for a new hire, except this one is machine-readable and doesn't rot the way a forgotten Confluence page does.

Most teams get this backwards. The instinct is to assume more visible code helps: more files loaded up front, more of the repo exposed to the model. That instinct rarely holds up once real work starts. Whether the code sits inside a structure the agent can walk through predictably matters far more than how much of it is visible. A monorepo running a real build graph, Bazel or Nx or something in that family, answers the queryable-structure problem directly: one dependency query, blast radius returned. A polyrepo with no parsed cross-repo dependency graph puts the agent into exploratory mode instead, and that mode is slow, burns tokens and compute, and misses consumers nobody thought to check. Queryable structure decides whether an agent navigates a codebase well or badly. Proximity to files barely factors in.

Where monorepos genuinely serve agent-driven pipelines better

Cross-service changes are where the monorepo wins, and it isn't close. Picture an agent modifying a shared interface inside a polyrepo: it has no visibility into who consumes that interface unless someone already built extra tooling to bridge the gap. The change passes every check in its own repo and still quietly breaks three services downstream that nobody flagged, because nothing in the agent's workflow ever asked the question in the first place.

In a monorepo, those consumers sit right next to the code being changed. One dependency query resolves them, and the agent updates the library and every caller in a single atomic PR, instead of coordinating a chain of separate merges across separate repos and hoping the sequencing holds. A single AGENTS.md at the repo root also means every agent working in that codebase reads the same conventions, ownership boundaries, and guardrails, with no drift between what repo A expects and what repo B expects. Merge queue design gets simpler too: one queue, one CI policy, one affected-target analysis deciding what actually needs to run.

Google and Meta have already proven the monorepo model holds at enormous scale, though neither got there without building serious custom tooling first. That's the real lesson buried in their published accounts: the structure is sound, but the tooling investment behind it is substantial and non-optional. For agentic pipelines specifically, the payoff comes from fewer round trips spent figuring out what an agent is even allowed to touch. Having more code sitting under one roof matters less on its own; the tooling built around that code carries much of the weight.

Where polyrepos still hold up, and what closes the context gap

None of this makes polyrepos the wrong call across the board. The real weakness only shows up when agents operate without cross-repo context, and that turns out to be a narrower, more fixable problem than it looks once the organizational argument gets separated from the tooling argument.

Deployment independence, separate security boundaries, distinct release schedules: these are real reasons to stay on polyrepos, and none of them go away just because an agent is now writing the commits. Here's the honest failure mode: an agent working inside one repository cannot see who consumes the code it's editing, so any change spanning repositories needs coordination the agent has no way to start on its own.

Tooling is starting to close that gap. Meta-harness tools designed for cross-repository dependency context can effectively stretch the monorepo's queryable-structure advantage across a polyrepo world. A maintained, parsed cross-repo dependency graph gives an agent the same blast-radius answer a monorepo's build graph hands out for free. So the trade-off comes down to this: a polyrepo with a maintained cross-repo graph and consistent per-repo AGENTS.md files works fine, while one with neither leaves agents exploring, and exploration is exactly the mode that produces context drift and missed dependencies.

Teams running hundreds of independently deployed services aren't going to fold everything into one monorepo just to make agents happier; the migration risk alone rules that out for most of them. Investing in the graph and the per-repo instruction files is the better bet, and it's the one that actually scales with the org they already have. Early production experience backs this up: a polyrepo setup can carry serious agentic throughput once the verification and coordination layer gets built out properly.

How CI/CD and merge queue behavior shifts under agent throughput

Human developers open pull requests at a pace set by reading, thinking, and reviewing each other's work. Agents open them at a pace set by compute and queue depth, and the two run at entirely different orders of magnitude.

Once agents become the primary source of pull requests, merge queue pressure climbs fast enough to expose CI weaknesses that used to sit quietly in the background. Things mildly annoying at human throughput turn into real blockers at agent throughput. Take a monorepo with no selective testing against its dependency graph: every PR can trigger a full build, and at agent volume that becomes a real cost and latency problem fast. Affected-target analysis, meaning the CI system actually knows which modules a change touches and only runs checks against those, stops being a nice-to-have and becomes load-bearing infrastructure the moment a monorepo goes agentic.

Real-world experience shows what happens when merge dynamics go unmanaged at scale: rising commit velocity can expose diamond merge failures, where two separate PRs each pass CI cleanly on their own but break main the moment both land together. Diagnosing and fixing that pattern takes real engineering time, and getting latency back under control typically means narrowing CI scope rather than bolting on a bigger queue and hoping the problem went away.

Polyrepos keep the CI surface small per repo, but that alone doesn't dodge the problem. Cross-repo agent changes that need coordinated merges across several repositories bring sequencing and ordering problems that no single repo's merge queue can solve alone. A merge queue built for agentic pipelines has to handle ordering and conflict detection, sure, but it also has to answer a harder question: what actually needs testing. Teams that wire affected-target awareness into their queues tend to claw back a real chunk of CI capacity they didn't even know they were losing. Repo layout decides which CI optimizations are even on the table, which makes this a structural decision rather than a downstream detail.

Harness design and how repo structure shapes what agents can reliably do

Harness engineering, the work of building the environment around a model so it behaves like a reliable autonomous agent rather than a clever autocomplete, is where the real engineering effort in software factories is going right now. Repo layout is part of that harness whether anyone planned it that way or not. It decides what context an agent gets handed, how tightly bounded that context stays, and which tool calls resolve cleanly versus which ones send the agent into exploratory fallback.

A recurring pattern in enterprise agent deployments is that harness defects — specifically context drift, schema misalignment, and state degradation — surface as common failure modes distinct from any shortfall in the underlying model. Trace each one back far enough and repo structure feeds all three. Context drift shows up when a polyrepo has no consistent AGENTS.md files, so agents end up working off different assumptions about conventions and ownership depending on which repo they landed in that day. Schema misalignment shows up when an agent changes a cross-repo interface with zero visibility into who consumes it, leaving callers running against a schema that no longer matches. State degradation shows up when an agent makes changes across several PRs in a polyrepo with no shared dependency graph; the result reads as internally consistent on paper and breaks the moment it all lands together.

The fix leans on one rule: make bad behavior structurally difficult rather than relying on agents to behave well on their own. Encode the conventions as linter rules, path-based access controls, and build graph queries that fail loudly instead of quietly. Telling an agent to "follow project conventions" in a prompt rarely holds up once real work starts. Transcript analysis, a close look at what an agent's tool calls actually did, which paths it explored, which queries came back empty or noisy, is how platform engineers catch a bad repo layout in the act. An agent making a dozen exploratory file reads before it finds the right module is a sign the structure underneath it isn't legible, a signal that only shows up if someone bothers to capture the transcript in the first place.

A practical framework for evaluating repo structure through the agent lens

The real decision was never monorepo versus polyrepo as some abstract ideology. It's which configuration, at the current scale and with the current agent workflow, produces the fewest harness defects and the clearest structure for automated traversal.

Four questions settle most of it. Do agents regularly make cross-service changes? If so, and the org runs polyrepo, a maintained cross-repo dependency graph is required, or silent breakage becomes the default outcome, not the exception. Is the CI architecture affected-target-aware? A monorepo without that is a liability the moment agent throughput kicks in; it's the prerequisite, not an upgrade to get around to later. Is there a canonical, predictable location for agent instructions in every repo? AGENTS.md or its equivalent counts as infrastructure here, not documentation housekeeping. Also worth asking: is anyone capturing agent transcripts and studying the tool call patterns? That's the only real way to tell whether the current layout produces clean resolution or just a lot of expensive wandering.

By scenario, the guidance splits cleanly. A greenfield agentic software factory should start with a monorepo running a build graph and affected-target CI; it's the lower-friction starting point, and agents get queryable structure from day one instead of earning it later. An existing polyrepo already carrying high agent PR volume should invest in cross-repo graph tooling and standardize AGENTS.md across every repo before anyone floats consolidation, since consolidation is a large migration carrying its own risk profile that rarely pays for itself on schedule. Hybrid or domain-segmented orgs often do best with a composable middle path: one monorepo per domain, tied together with cross-domain dependency graphs, a setup that tends to fit better than either a single global monorepo or a fully scattered polyrepo.

The merge queue needs planning alongside the repo layout from day one, since the layout decides which queue optimizations are even reachable later. Purpose-built merge queues, agent transcript analysis, and agent-optimized code storage stack onto either repo structure, and the infrastructure wrapped around the repo ends up mattering as much as the repo layout itself. Analyst projections suggest task-specific AI agents will become a significant presence in enterprise applications within the next few years. Teams settling the repo structure question now are pouring the foundation for a load that's only going to get heavier.