Monorepo vs. Multi-repo for AI Coding Agents

AI coding agents do not settle the monorepo vs. multi-repo debate — but they do make the stakes sharper. A good architectural decision becomes a force multiplier; a bad one becomes a liability that an agent will exploit at speed.

What a monorepo does well for agents

The core advantage is full codebase visibility. In a monorepo, an agent can grep, search, and retrieve across the full stack. It sees what the shared library does, what the API contract looks like, how the frontend consumes the backend. In a multi-repo setup, it is blind to anything not explicitly injected into its context and makes decisions accordingly.

This pays off most on cross-cutting features. An agent can implement a change end-to-end, landing as one atomic commit. For example, update the protobuf schema, fix the Go service handler, adjust the frontend component, update the tests... all in a single pass. Refactoring works the same way: rename a function and every caller updates in the same pass. In multi-repo, a signature change hits a hard boundary that requires human orchestration to cross.

Where monorepos work against agents

Context exhaustion

Large monorepos leave agents working with partial information. Token limits truncate the view; even within those limits, retrieval quality drops as the codebase grows.

Rules files that stop being read

Rules files (ie, AGENTS.md, .cursorrules, system prompts, etc) degrade as they grow. Instruction-following in LLMs is sensitive to prompt length: rules buried deep in a long file are followed less reliably than rules at the top of a short one.

In a monorepo, the AGENTS.md faces an uncomfortable choice: cover everything and become too long to be effective, or stay short and stay vague. Per-directory rule files are the obvious mitigation, but most tooling does not support hierarchical scoping cleanly. You end up with a patchwork the agent partially ignores.

Blast radius on stable components

A monorepo puts the fast-moving feature layer alongside the slow, carefully versioned foundation (ie, persistence, auth, shared clients, SDK, etc). An agent has no intrinsic reason to leave those stable layers alone. If refactoring a shared utility makes the feature cleaner, it will — and the change shows up buried in a 40-file diff that reviewers are unlikely to scrutinize fully.

Parallel agents

Multiple agents in the same repo create race conditions at the filesystem and git level. git worktree is the standard fix: each agent gets its own working tree on a separate branch. But it adds setup, cleanup, and branch lifecycle overhead that most tooling does not abstract away. In practice, teams either serialize their agents or accept a coordination overhead that falls on the human.

What a multi-repo setup does well for agents

Scope is the key benefit. The agent works in one repo, with one AGENTS.md, covering one component — the rules file stays short enough to be effective. Foundation libraries are physically absent, so an agent working on the API service cannot touch the persistence layer. Parallel agents are isolated by default.

Cross-repo changes force explicit reasoning about the interface boundary. If that API is poorly defined, the moment you try to describe the change to an agent makes it obvious.

Where multi-repo sets agents up to fail

Cross-cutting features are painful. The agent cannot follow a change across a repo boundary on its own. Implementing something that spans multiple repos means multiple PRs, potentially multiple agents, and a human orchestrating the sequence.

Version drift is the quiet failure mode: an agent that updates one side of an interface without updating the other introduces a break that may not surface until CI runs against the integrated system. Without a machine-readable contract enforced in CI, there is no way to catch it before it lands.

Practical guidance

My take: the decision comes down to one question — do your components have explicit interfaces?

A contract does not have to be a protobuf schema. For a small project, a well-maintained README describing what a component accepts and returns is often enough. As complexity grows, machine-readable contracts earn their weight: versioned packages with semver, OpenAPI or protobuf definitions, CI-enforced compatibility checks.

The hybrid approach

For most non-trivial projects, neither extreme works cleanly. The pattern that tends to work: one monorepo for fast-moving application code — services, frontends, infra config, tests — and separate repos for stable shared libraries with a slow release cadence and a broad consumer surface.

The shared libraries have their own AGENTS.md and their own release process. The boundary is a versioned dependency, enforced by the repo structure, not by a rule the agent might ignore.

Conclusions

The shortcuts:

• Components have explicit interfaces → multi-repo or hybrid
• Cross-cutting changes are the norm → monorepo; scope AGENTS.md per subdirectory and add explicit exclusion rules for stable layers
• Running parallel agents → git worktree or repo isolation, regardless of everything else.