Monorepos Pool Context
For AI-assisted development, a monorepo can be useful because it pools related project context in one visible, versioned place.
Monorepos are usually discussed as an engineering tradeoff.
They can make it easier to share code, coordinate changes, align dependencies, run tests, and refactor across package boundaries. They can also create tooling pressure, slower workflows, access-control headaches, and a feeling that too much unrelated work has been placed in the same room.
Those tradeoffs are real.
But for AI-assisted development, I think there is another reason to consider a monorepo:
A monorepo pools context.
That may matter more than the code sharing.
The Multi-Repo Context Problem
A lot of projects do not start as systems. They start as separate things.
There is a marketing site. Then there is a web app. Then a shared package. Then an internal tool. Then a docs site. Then scripts for imports, billing, reporting, migrations, or support. Each one gets its own repo because that was the easiest decision at the time.
At first, this is fine.
Then the repos start sharing a story.
They use the same product language. They depend on the same customer model. They encode the same permissions. They talk to the same API. They repeat the same copy, validation rules, analytics names, deployment assumptions, and environment variables. The business sees one system, but the context is split across several repositories.
Humans can often paper over that split because they remember the missing pieces.
Agents are worse at that unless you keep feeding them the missing context.
If the agent is working in the app repo, it may not see the docs repo. If it is editing the marketing site, it may not see the shared types. If it is updating an internal tool, it may not see the customer-facing workflow that explains why the tool exists. The operator becomes a context courier, carrying bits of one repo into another through prompts.
That gets old quickly.
It also creates drift.
One repo updates a concept. Another keeps the old language. A shared package changes behavior, but the consuming app still has stale documentation. A prompt summary describes yesterday’s architecture because the agent could not inspect the sibling project directly. The system is related in practice, but fragmented in memory.
A Monorepo Is a Shared Memory Surface
The repo is already one of the best memory systems for software work.
It is visible. It is versioned. It can be reviewed. It can be searched. It can contain code, tests, docs, scripts, examples, conventions, and decision history. Unlike hidden memory, repo context can be inspected and corrected.
A monorepo extends that property across related projects.
Instead of giving the agent one slice of the system and manually describing the rest, you can give it a larger local map. The app, shared package, content model, docs, tests, fixtures, scripts, and deployment assumptions can live close enough that a normal search can find them.
That changes the working model.
The agent does not have to rely as much on a stale package description or a compressed prompt summary. It can inspect the actual package. It can see how the type is used. It can find the test fixture. It can update the docs in the same commit as the code. It can notice that the marketing page and the app are using two different names for the same feature.
The monorepo becomes pooled operational context.
What Gets Pooled
Code is only one part of the pool.
A useful monorepo also pools the things around the code:
- Domain vocabulary.
- Shared schemas and types.
- API contracts.
- UI conventions.
- Product assumptions.
- Test fixtures.
- Content conventions.
- Scripts and command names.
- Environment variable patterns.
- Deployment notes.
- Architecture decisions.
- Examples of how the system prefers to solve recurring problems.
Those are the materials agents use to infer what a change should look like.
If those materials are scattered across repos, the agent gets a partial map. If they are pooled coherently, the agent has a better chance of following the system that actually exists.
That matters even when no code is shared.
A docs site and an app may not import from each other, but they can still depend on the same product concepts. A marketing site and an onboarding flow may not share components, but they should probably agree about what the product does. An internal support tool may not ship to users, but it may encode the real operational model of the business.
Those relationships are context relationships.
Atomic Context Changes
Monorepos are often praised for atomic code changes: update a library and its consumers in one commit.
The same idea applies to context.
If a product concept changes, the code, docs, tests, UI copy, and internal scripts can change together. If a schema changes, the migration, API client, fixtures, app screens, and documentation can move together. If the preferred architecture changes, the examples and conventions can be updated where future agents will actually read them.
This is a practical defense against contextual tech debt.
Drift happens when the system changes faster than its context is reconciled. Multi-repo systems make reconciliation easier to forget because the related context is not in the same review surface. The app PR updates the behavior. The docs PR comes later, or never. The shared package release goes out, but the internal tool keeps an old assumption.
A monorepo does not solve that automatically. It just makes the missed update more visible.
The pull request can show the code and the context together. The reviewer can ask, “Did we update the docs?” The agent can be told to search the repo for the old term. Tests can run against the affected packages. The context has fewer places to hide.
The Human Benefit
This is not only about agents.
Humans also benefit from having a single place to inspect the current truth.
A new contributor can learn the system from one repo instead of assembling a mental model from five partial repos. A maintainer can search for a product concept once. A reviewer can see whether a change crosses package boundaries. A founder can ask an agent to summarize the system and get an answer grounded in more of the actual work.
Shared context also makes standards easier to enforce.
If every repo has its own README, scripts, test patterns, and conventions, divergence is the default. Some divergence is healthy. But when the repos are part of the same product system, repeated divergence often becomes accidental complexity.
A monorepo gives you a place for root-level guidance:
- What the projects are.
- How they relate.
- Which commands matter.
- Which conventions apply everywhere.
- Which packages own which responsibilities.
- Which context is current.
That does not replace per-project docs. It gives them a shared frame.
The Risk Is Context Noise
Pooling context is not the same as dumping everything into one repo.
More files are not automatically better context. Coherent files are better context.
If a monorepo contains unrelated projects, vague ownership, contradictory conventions, and no clear map, it can make agent work worse. The agent may find examples that do not apply. Humans may stop trusting repo-wide search. Shared scripts may become fragile because nobody knows which package they were really meant for.
This is the monorepo version of context drift.
The cure is boundaries.
Apps and packages need clear directories. Shared conventions need a clear home. Project-specific details should stay local. Root-level docs should explain the map without trying to absorb every detail. AGENTS.md should tell agents what is globally true and when they should inspect a package-specific file. Tests and scripts should make it possible to work on affected areas without pretending every change touches everything.
The goal is not maximum context.
The goal is relevant context with visible boundaries.
When It Makes Sense
A monorepo starts to make sense when projects already depend on the same story.
That might mean they share domain concepts, types, schemas, API contracts, UI conventions, release steps, or operational assumptions. It might mean changes frequently need to land in more than one repo. It might mean you keep copying the same instructions into prompts because the agent working in one repo needs to understand another.
Those are signs that the split repositories may be an organizational artifact, not a useful boundary.
The question is not “Could these projects technically be separate?”
They probably could.
The better question is: how much context do they have to share to be changed safely?
If the answer is “a lot,” a monorepo may be a better container for the work.
When It Does Not
Some projects should stay separate.
If the projects are unrelated, a monorepo gives you noise instead of pooled context. If access-control needs are sharply different, combining repos may create more risk than value. If teams have incompatible workflows, the coordination cost may dominate. If the repo would become slow or unwieldy without tooling investment, the context benefit may not be worth the operational drag.
A monorepo is not a moral position. It is a shape.
Use it when the shape matches the system.
How to Move Without Making a Mess
If the motivation is pooled context, start by identifying the context that should be pooled.
What concepts are duplicated? Which docs disagree? Which packages change together? Which prompts keep requiring the same explanation? Which tests or fixtures would help another project? Which scripts represent shared operations?
Then move the most related projects first.
You do not have to merge everything at once. A useful monorepo can start with an app and a shared package, or a product site and its content model, or an internal tool and the schemas it manipulates.
Once the projects are together, create the map:
- A root
AGENTS.md. - A short architecture overview.
- A package/app directory guide.
- Shared commands for build, test, lint, and development.
- Clear ownership notes.
- Per-project READMEs for local details.
- A convention for marking historical context.
The migration is not finished when the files move.
It is finished when the repo explains itself better than the old collection of repos did.
The Point
A monorepo is not just a place to share code.
It is a place to share context.
For AI-assisted development, that is a real advantage. Agents work better when the project can show them the truth instead of relying on hidden memory, repeated prompts, or stale summaries. Humans work better when the system’s current shape is visible and reviewable.
Not every project belongs in a monorepo.
But when several projects already depend on the same product story, putting them in the same repo can make that story easier to maintain.
The goal is not one giant repository.
The goal is one coherent context surface for the work that already belongs together.