Monorepo or Polyrepo? The Code Organization Debate from an AI Coding Assistant's Perspective

AI coding assistants have become deeply embedded in everyday development, but they can only work with code they can "see." This raises an easily overlooked question: does the way a team organizes its code affect how well AI assistants perform? Drawing on first-hand notes from the developer community, this article systematically lays out the trade-off logic between Monorepo and Polyrepo, and offers an actionable evaluation method.

The Basics of Two Code Organization Approaches

A Monorepo places the code of multiple projects in the same shared space, including the shared modules they depend on together. A Polyrepo keeps a separate repository for each project or team, with its own commit history and access rules.

In reality, few organizations make a pure either/or choice. As the original notes, many organizations mix the two models—for example, building one Monorepo per business domain while placing shared libraries in separate repositories. In a Polyrepo, projects typically consume shared modules through published versions, similar to consuming a finished product delivered by another team.

Six Key Trade-offs

The original lays out the core differences between the two models in a comparison table:

• Code lookup: A Monorepo needs a search in only one place; a Polyrepo requires searching across multiple locations and may depend on extra tooling.
• Modifying shared modules: A Monorepo can update all consumers in sync; a Polyrepo requires changing, then publishing, then updating each caller one by one.
• Version consistency: A Monorepo has everyone on the same version; in a Polyrepo, projects may be stuck on different versions.
• Team independence: A Monorepo means shared rules and release cadence; a Polyrepo lets teams choose their own tools and release times.
• Access permissions: A Monorepo is broadly visible by default, and tightening permissions requires extra configuration; a Polyrepo makes isolation naturally easy.
• Maintenance cost: A Monorepo requires ongoing investment in search, builds, and tests as it grows; a Polyrepo's individual repos are simple, but connecting them carries a cost.

The original stresses in particular: tool quality matters as much as structural choice. A well-supported Polyrepo can beat a poorly maintained Monorepo, and vice versa.

The "Illnesses" of Each Model and Their Warning Signs

No structure stays healthy on its own. The original summarizes the typical failure modes of each:

The Monorepo illness is unnecessary coupling accumulating between projects, where small changes ripple beyond the expected scope and checks slow down. The warning signs are search or builds slowing noticeably, and a single change repeatedly pulling in unrelated teams.

The Polyrepo illness is fixes reaching only some projects, with habits gradually drifting apart between teams. The warning signs are the same fix repeated in multiple places, and teams waiting on each other's releases.

In both cases, clarifying ownership for each module (including shared modules) prevents most problems. Changes to access rules are also a good time to revisit the structural choice.

The Rule of Thumb: Keep Things That Change Together, Together

The heuristic the original offers: observe how often a single change needs to cross boundaries. If two projects are frequently modified together, placing them in the same space reduces coordination cost; if they rarely interact, or must be separated for permission or ownership reasons, separate repositories are a better fit.

Team structure shapes code structure, and aligning the two helps—this echoes Conway's Law.

Why AI Assistants Care About Repository Structure

Imagine asking an assistant to update a shared module and all its consumers. In a Monorepo, the change happens in one place and goes through one review. In a Polyrepo, the shared module is changed and a new version published first, then each consumer is updated one by one, each with its own review and checks—meaning more pull requests and more rounds of fixes and review effort.

The original proposes a hypothesis worth testing: relevant information helps assistant performance, but too much information can actually reduce reliability. "The right information" may matter more than "the most information."

A context window is the maximum length of text a large language model can process in a single inference, usually measured in tokens. When an AI coding assistant works, it needs to fit system instructions, user requests, current file contents, search results, and conversation history into this window all at once. Because the window is limited, the entire codebase of a large Monorepo can never be loaded at once, so the assistant must rely on retrieval mechanisms to filter relevant snippets. The larger the window, the more context the assistant can reference—but more isn't always better: irrelevant or outdated information dilutes attention, causing the model to miss key details or hallucinate. The point of repository structure, then, is to help the assistant fit "the right information" into a limited window, not to pursue "the most information."

A Concrete Migration Case

The task is to rename the field customer_name to full_name. It appears in a shared data definition and is used by three consumers: a web app, a mobile app, and a backend service.

Monorepo path: The assistant finds the definition and three consumers with a single search, modifies all four places at once, runs checks on the affected parts, and covers everything in one PR. The risk is that this PR spans multiple teams' code, requires review from multiple parties, and a single mistake could break all three apps at once.

Polyrepo path: The assistant first modifies the shared definition in its repository and publishes a new version, then each of the three projects needs its own update, PR, and checks. If the assistant can see only one repository, it cannot tell who else uses the field and may stop after the first step. The risk is that some project gets missed and stays on the old version, with the three updates landing at inconsistent times.

What both models share: A one-shot full rename is always risky. The safer path is to add the new field first, migrate consumers one by one, and then remove the old field—this sequence matters more than the repository layout.

Enhancements for each: A Monorepo needs tooling that runs only affected checks, plus files marking the ownership of each directory; a Polyrepo needs a bot that automatically opens update PRs, tests verifying that the shared definition matches each project's expectations, a map of dependency relationships, and a way to check out multiple repositories side by side in one workspace for the assistant.

Five Mechanisms of How AI Assistants Interact with Code

The original breaks down the mechanisms behind what an assistant "can see," which determine the practical effect of each layout:

First, reading capacity is limited. The amount of text an assistant can hold at once is bounded by its context window, and a large codebase can never be fully loaded. A Monorepo is not "fully visible," nor is a Polyrepo "completely hidden"—the real question is whether the assistant can find the right few files.

Second, it locates code through search. Most assistants search like developers do: looking up names and text, opening matching files, and tracing references. Some tools add semantic indexes or dependency graphs. In a Monorepo, one search covers everything, but results grow noisy as the code grows; in a Polyrepo, search covers only the currently open repository and, without extra configuration, cannot determine the other consumers of a shared module.

Third, it follows written guidance. Many assistants read plain-text instruction files in the codebase (such as CLAUDE.md or AGENTS.md, with names varying by tool) to learn how to run tests and how to name things. A Monorepo can place shared conventions at the top level with local rules inside each project; a Polyrepo needs one in each repository, which tends to drift, and can be aligned with shared templates or short notes pointing to common rules.

Fourth, cross-repository capability depends on configuration. Out of the box, most assistants work within a single repository. Handling cross-repository changes usually takes one of three approaches: checking out the relevant repositories side by side and opening them in the same workspace; providing the assistant with a cross-repository search tool; or maintaining a short dependency map.

Fifth, access permissions are also a security issue. An assistant can usually read, and sometimes modify, everything it is authorized for. A Monorepo may give it overly broad reach by default, including code unrelated to the task; separate repositories make it easier to grant permissions on demand. In either model, you should limit what the assistant can modify, provide only the relevant code the task needs, and keep human review on every change.

The conclusion: each layout has its default strengths—a Monorepo makes "finding relevant code" easier by default, a Polyrepo makes "tightening permissions" easier by default, and both can compensate for their weaknesses with the tooling described above.

Conway's Law was proposed by programmer Melvin Conway in 1968. Its core idea is that the structure of systems an organization designs inevitably reflects that organization's communication structure. In other words, how teams are divided and how they collaborate tends to shape the boundaries and interfaces of software modules. In the discussion of repository layout, this law implies: if two teams frequently need to modify code in sync but sit in different repositories, coordination costs rise; conversely, if team boundaries are clear and changes rarely intersect, separate repositories are more natural. The original's advice to align team structure with code structure is a practical extension of Conway's Law—not to forcibly eliminate coupling, but to match organizational structure with code dependencies, thereby reducing communication overhead.

Spec First: An Anchor for Cross-Repository Coordination

A spec is a short written description of a feature's behavior and how to verify it, which the assistant builds from. Its unit is the feature, not the PR: one spec, many small PRs.

In a Monorepo, a spec keeps a multi-step change spanning multiple PRs consistent and gives reviewers a single reference. In a Polyrepo, a spec serves as the coordination point—listing affected repositories, the order of steps, and the task for each repository—filling the gap left by the absence of a shared view. If the spec is machine-checkable (such as an API schema or data definition), each repository's checks can confirm it still matches.

Specs have limits too: they go stale and need an owner and maintained status; they cost more than they're worth for small changes; and they tell the assistant what to build, but whether it was built still depends on fast automated checks. The original admits that evidence that specs improve assistant outcomes is still thin.

A machine-checkable spec is a file that describes an interface or data contract in a structured format (such as JSON Schema, OpenAPI, Protocol Buffers, or database DDL) that can be parsed and validated by automated tools. Unlike plain-text specs, these specs can be embedded in CI pipelines: when a repository's implementation doesn't match the contract, the check fails directly. In a Polyrepo scenario, once a shared module's contract is published in machine-checkable form, each consumer repository can confirm at every build that it still matches, with no manual comparison needed. This compensates for the lack of a shared cross-repository view, but it also requires the contract itself to have clear versioning and an owner—otherwise stale specs create a false sense of security.

How to Test the Answer Yourself

The original notes that rigorous comparative studies of AI assistant performance under the two layouts are still limited, and current judgments rest largely on reasoning and day-to-day practice. It offers a reproducible experimental design: pick a real change that spans multiple projects, run the same task under both layouts, keep the assistant, instructions, rule presentation, and automated checks consistent, and run it multiple times to account for variance. An optional variable is whether to include a spec file.

Metrics to record include: rounds of fixes before checks pass, first-attempt success rate, number of locations and PRs involved, amount of information the assistant needs to read, cost per successful task, and human intervention time. Also record how the assistant was configured, since its impact on results may equal that of the layout itself.

Whichever structure you choose, good tooling and clear habits are likely just as important as the layout itself.

One-line Summary

Monorepo and Polyrepo each have strengths and weaknesses; assistant performance depends on information discoverability and tooling support.

Paragraph Summary

This article explores how two code organization approaches—Monorepo and Polyrepo—affect AI coding assistants. Through six trade-offs (code lookup, shared module modification, version consistency, team independence, access permissions, maintenance cost), it shows there is no absolute winner and that tool quality matters as much as structural choice. The article analyzes the typical illnesses and warning signs of each model and proposes the rule of thumb "keep things that change together, together." For AI assistants, it breaks down five interaction mechanisms: limited context windows, locating code through search, following written guidance, cross-repository capability depending on configuration, and access permissions as a security issue. Finally, it presents a field-rename migration case and a reproducible self-testing plan, emphasizing that specs first and tooling habits may matter more than the layout itself.