Monorepo vs Polyrepo and AI Coding Assistants

Introduction

AI assistants now help write and change code every day. An assistant can only work with what it can see, which raises a simple question: does the way a team organizes its code change how well the assistant can help?

There are two common ways to organize code, and capable teams use both. This guide explains them in plain words, offers a way to think about the choice, and suggests a simple test teams can run themselves. It doesn't favor either approach.

Where this comes from. These are my notes from what I've read so far and from my own experience. Please treat it as a starting point rather than a final answer.

1. Two ways to organize code

• Monorepo (one shared place): the code for many projects lives together, including the shared parts they all rely on.
• Polyrepo (separate places): each project or team keeps its code in its own place, with its own history and its own rules about who can access it.

In a polyrepo, a project usually uses a published version of each shared part, much like using a finished product from another team. Many organizations mix the two, for example one monorepo per business area, with shared libraries kept in their own repository.

Solid arrows are direct use; dashed arrows are use through a published version.

2. Common trade-offs at a glance

Topic	One shared place	Separate places
Finding code	One place to search	Search spans several places and may need extra tools
Changing a shared part	Update it and everything that uses it together	Update it, publish it, then update each user
Versions of shared parts	One version for everyone	Projects can end up on different versions
Team independence	Teams share rules and schedules	Teams choose their own tools and release timing
Who can see what	Usually broad visibility; tighter limits take extra setup	Easy to limit access to each place
Effort to keep it running well	Search, build, and testing need ongoing investment as it grows	Each place is simpler, but connecting them takes effort

Good tools matter as much as the structure. A well-supported polyrepo can beat a neglected monorepo, and the reverse is also true.

3. Keeping either setup healthy

Neither setup stays healthy on its own. Each has its own failure pattern, and each shows up in a few recognizable signs.

	What goes wrong	Signs it's time to act
Monorepo	Unneeded links between projects pile up, so small changes touch more than expected and checks slow down	Searching or building has become noticeably slow; one change keeps pulling in unrelated teams
Polyrepo	Fixes reach some projects but not others, and habits drift between teams	The same fix is repeated in many places; teams wait on each other to release

Either way, clear ownership of every part, including the shared ones, prevents most of these problems. A change in access rules, such as new limits on who can see what, is also a reason to revisit the choice.

4. A helpful rule of thumb: keep together what changes together

Look at how often a single change has to cross a boundary. If two projects usually change together, putting them in the same place reduces coordination. If they rarely change together, or must stay apart for access or ownership reasons, separate places fit better.

Team structure shapes code structure too, so it helps to line the two up.

5. Why an AI assistant might care

Picture asking a helper to update a shared part and everything that uses it. In a monorepo, the change happens in one place and goes through one review. In a polyrepo, the shared part changes first, a new version is published, and then each project that uses it is updated one at a time, each with its own review and checks.

The polyrepo path adds a publish step and one review per project.

A pull request is a change that a person reviews before it's accepted. The polyrepo path means more of them, which can add rounds of fixing and review effort. Real setups vary, and tools can shorten the longer path.

One idea is worth testing here: relevant information tends to help an assistant, while very large amounts can make it less reliable. The right information may matter more than the most information. The next two sections look at this in practice.

6. A worked example

The task: a field called customer_name needs to become full_name. It appears in a shared data definition, and three things use it: a web app, a mobile app, and a backend service.

In a monorepo

1. The assistant searches one place and finds the shared definition and all three users.
2. It changes all four in one go and runs the checks for the affected parts.
3. One pull request covers everything.

What can go wrong: the pull request touches several teams' code, so it needs several reviewers, and one mistake can break all three apps at once.

In a polyrepo

1. The assistant changes the shared definition in its own repo, and a new version is published.
2. Each of the three projects then needs its own update, its own pull request, and its own checks.
3. If the assistant can only see one repo, it can't tell which others use the field. It may finish the first step and stop.

What can go wrong: one project gets missed and stays on the old version, and the three updates land at different times.

What's the same in both. Renaming everything at once is risky either way. The safer path is to add the new field, move each user over, then remove the old one. That order matters more than the repo layout.

What helps in each

• Monorepo: tools that run only the affected checks, and a file naming who owns each folder, so the right people review.
• Polyrepo: a bot that opens update pull requests automatically, tests that confirm the shared definition still matches what each project expects, and a written map of which projects use which shared parts. Giving the assistant a workspace with several repos checked out side by side also helps.

7. How an AI assistant actually works with your code

Section 5 talks about what an assistant "can see." The mechanics behind that shape how well either layout works.

1. It reads in limited amounts. An assistant can only hold so much text in view at once. This limit is often called its context window. A large codebase never fits entirely, so the assistant has to choose what to read. This is true in both layouts. A monorepo isn't "all visible" and a polyrepo isn't "hidden." The real question is how well the assistant finds the right few files.

2. It finds code by searching. Most assistants search the way a developer does: looking for names and text, opening the matching files, and following references. Some tools add an index that finds code by meaning, or a map of how pieces connect.

• In a monorepo, one search covers everything, but results get noisy as the code grows. Good folder structure and clear names help a lot.
• In a polyrepo, a search only covers the repo the assistant has open. Without extra setup, it can't tell who else uses a shared part.

3. It follows written guidance. Many assistants read a plain text file of instructions kept with the code, such as how to run the tests, how to name things, and what to avoid. Common examples are files called CLAUDE.md or AGENTS.md, though names vary by tool, so check your tool's current documentation.

• In a monorepo, a team can keep one file at the top for shared habits, plus smaller ones inside each project for local rules.
• In a polyrepo, each repo needs its own file, and the files can drift apart. A shared template, or a short note pointing to the common rules, keeps them aligned.

4. Its reach across repos depends on setup. Out of the box, many assistants work inside one repo. To handle a change that spans several, teams commonly do one of these:

• check out the related repos side by side and open them together in one workspace
• give the assistant tools that search across repos
• keep a short written map of which projects depend on which

This matters most for the case in the worked example, where one change must reach several places.

5. Access is a safety question too. An assistant can usually read, and sometimes change, whatever it is given access to. A monorepo can hand it broad reach by default, including code unrelated to the task. Separate repos make it easier to give access only where needed. Either way, limit what the assistant can change, give it the related code a task needs and not much more, and keep a person reviewing every change before it's accepted.

What this means in practice. Neither layout wins on its own. The assistant does best when it can quickly find the related code, read clear written guidance, and run fast checks. A monorepo makes the first easier by default. A polyrepo makes tight access easier by default. Each can be improved with the tooling above.

8. Practical ideas for either setup

• Make the automatic checks quick and easy to run, so the assistant gets feedback fast.
• Keep changes small enough for a person to review.
• Decide ahead of time how changes that cross several places will be coordinated.

9. Writing the spec first

A spec is a short written description of what a feature should do and how to check it. The assistant builds against it. It helps in both layouts, and its unit is the feature, not the pull request: one spec, many small pull requests under it.

What it does in each setup

• Monorepo: keeps a multi-step change consistent across pull requests and gives reviewers one reference.
• Polyrepo: acts as the coordination point. It lists the affected repos, the order of steps, and a task per repo, which fills the gap left by having no shared view. A spec that a machine can check, such as an API schema or data definition, lets each repo's checks confirm it still matches.

In the worked example, one spec says: add full_name, move each project over, then remove customer_name, with a task for each repo.

Where to keep it. Monorepo: beside the shared part. Polyrepo: in the shared part's repo, or in a small specs repo linked from each task.

Limits

• A spec goes stale. Give it an owner, keep a short status next to each task, and retire it when the feature ships.
• On a small change it costs more than it saves.
• It tells the assistant what to build; fast automatic checks still decide whether it worked.
• Evidence that it improves assistant results is still thin; section 10 covers what is known and how to test it.

10. What we know, and how a team could find out

Careful, measured comparisons of AI assistants working in one shared place versus separate places are still limited. Most of today's thinking rests on reasoning and day-to-day practice, which is useful, and measured results would add a lot. Here is a simple way to produce them.

Pick a realistic change that touches several projects, such as renaming a field that many parts of the software use. Try the same job in both setups, keeping everything else the same:

• the same AI assistant and the same instructions
• the same way of showing it the team's habits and rules
• the same automatic checks to confirm the result works
• several tries, because results vary from run to run

Optional extra variable: run the change once with a written per-feature spec (section 9) and once without, then compare the same measures below.

Then write down:

What to record	In plain words
Rounds of fixing until the checks pass	How much back-and-forth it took
First-try success rate	How often it worked without any fixing
Number of places and pull requests involved	How much coordination was needed
How much the assistant had to read	How much information it needed
Cost per job that succeeded	Total cost divided by the jobs that worked
Time a person had to step in	Where people still needed to help

Also note how the assistant was set up, since that can affect the results as much as the layout.

Whichever setup you choose, good tools and clear habits are likely to matter as much as the layout.

Comments

[kholnnaw]

when the assistant only sees the files in its current repo, how do you expose types from other packages in a monorepo without pulling the whole tree? do you generate index stubs on demand or keep a shared schema service