Compare monorepo vs polyrepo trade-offs for code discovery, ownership and shared contracts. Use practical search and change tasks to assess your own team.
The monorepo vs. polyrepo debate has been going on for years, and most of it misses the point. Teams argue about build tooling, CI performance, and dependency management. Those are real concerns. But the factor that actually determines whether your team ships or stalls is something nobody benchmarks: how well engineers understand the code they're working with.
I've managed teams on both sides. I ran a 140-service polyrepo setup at one company and migrated a 50-engineer team to a monorepo at another. The technical tradeoffs are well-documented. What isn't documented is how each approach changes the way engineers think about, discover, and reason about code.
Here's my contrarian take: the best repo strategy is the one that minimizes the time between "I need to change something" and "I understand what to change." Everything else is secondary.
I tracked this metric informally across both setups. In the polyrepo world, engineers spent an average of 47 minutes just finding the right code before they could start making changes. In the monorepo, that dropped to 11 minutes. That's 36 minutes of cognitive overhead per task, multiplied by every engineer, every day.
The monorepo also had an understanding tax. Use the codebase understanding guide to examine discovery and boundaries in either arrangement.
In a polyrepo setup, each service or library lives in its own repository. The pitch is clean separation of concerns. The reality is fragmented understanding.[1]
When an engineer needs to understand how user authentication works end-to-end, they might need to look at:
auth-service repo (handles login)
user-service repo (manages profiles)
api-gateway repo (routes and validates tokens)
shared-types repo (TypeScript interfaces)
auth-sdk repo (client library)
That's 5 repos to clone, 5 README files to read, 5 different project structures to learn. Each repo has its own conventions, its own folder structure, its own way of doing things.
bash
# The polyrepo discovery workflowgit clone git@github.com:company/auth-service.gitgit clone git@github.com:company/user-service.gitgit clone git@github.com:company/api-gateway.git# Now figure out which versions are compatible...# Now figure out which branch each team is working from...# Now figure out where the actual logic lives in each one...
In one polyrepo setup, I found that the shared-types package had 14 different versions in use across 23 services. Engineers were building against different contracts without knowing it. Bugs that should've been caught by TypeScript sailed through because each service compiled against its own snapshot of the types.
Each repo develops its own culture. The auth team uses a result pattern for errors. The billing team throws exceptions. The notifications team uses event-driven error propagation. A new engineer joining the company has to learn 3 different paradigms to understand 3 services.
I measured this: it took new engineers an average of 4.2 months to feel "productive" in our 140-repo polyrepo setup. In a comparable monorepo org, the number was 2.1 months.
# How Monorepos Create Different Understanding Problems
Figure 1. Repository layout changes the discovery and coordination work.
Monorepos solve the discovery problem but create their own challenges. The common narrative that monorepos are strictly better for understanding is wrong.
A monorepo with 2 million lines of code can be intimidating. In a polyrepo, repository names may suggest boundaries such as auth or billing. A monorepo needs explicit module structure and code ownership so engineers can locate the responsible team.[2]
# Without clear structure, monorepos become a maze
src/
components/ # 400+ files
services/ # 200+ files
utils/ # 150+ files - the junk drawer
lib/ # what's the difference between this and utils?
helpers/ # seriously?
core/ # everything is "core" apparently
Because everything is in one repo, engineers assume they understand modules they've never worked in. I call this the "I can see it, so I understand it" fallacy. In polyrepos, the act of cloning a new repo creates a natural pause where the engineer acknowledges "I'm entering unfamiliar territory." Monorepos remove that signal.
The result: engineers make changes to unfamiliar modules with unearned confidence. In one quarter, 60% of our production incidents came from engineers modifying code outside their team's ownership area, without consulting the owning team.
In a monorepo, a well-intentioned refactor can touch 200 files across 15 teams. The person making the change understands their module. They don't understand the 14 other modules they're affecting.[3]
typescript
// "I'll just rename this shared interface, what could go wrong"// git diff --stat:// 247 files changed, 1,893 insertions(+), 1,891 deletions(-)// Now 14 teams need to review changes they didn't ask for
Track how often engineers need to modify code owned by another team. If more than 30% of your PRs cross team boundaries, a monorepo reduces friction. If less than 10%, polyrepos enforce healthy boundaries.
Count the number of shared libraries, types, and utilities. If you have more than 20 shared packages, a monorepo makes versioning and discovery dramatically easier. Fewer than 5? Polyrepos are fine.
Ask recent hires: "How long until you could make changes confidently?" If the answer is over 3 months, you have an understanding problem that repo structure might help solve.
Test code search across the repositories your team needs to understand a workflow. Sourcegraph and GitHub code search offer cross-repository queries. A monorepo also needs appropriate indexing and navigation as it grows, so include search infrastructure in either decision.[4]
After years on both sides, I've landed on a pattern I call "monorepo core, polyrepo periphery." Here's the structure:
In the monorepo:
All shared libraries and types
All core business logic
All API definitions and contracts
Internal tools and scripts
In separate repos:
Infrastructure and IaC (different lifecycle)
ML/data pipelines (different toolchain)
Mobile apps (different build systems)
Third-party integrations with dedicated teams
This gives you unified understanding for the code that matters most (business logic and shared contracts) while allowing specialized toolchains where they're needed.
Figure 2. Use realistic navigation tasks when evaluating repository structure.
Before choosing a repo strategy, run the FIND test with 5 engineers on your team:
Find: "Find the code that handles payment refunds." Time how long it takes.
Inspect: "What other services does the refund flow touch?" See if they can trace the full path.
Navigate: "Find the test for this logic." Measure the hop count between production code and its tests.
Discover: "What changed in the refund flow in the last month?" See if they can reconstruct recent history.
Run FIND in your current setup. If average times exceed: F > 15 min, I > 30 min, N > 5 min, D > 20 min, your repo structure is hurting understanding.
The right repo strategy isn't about what Google or Facebook uses. It's about whether your specific team, with your specific codebase, can find, understand, and safely change code. Measure that, and the repo decision makes itself.
Frequently asked questions
Does a monorepo remove the need for module boundaries?
A shared repository still needs clear module structure and ownership. Define which projects may depend on each other and make those rules visible in review or automated boundary checks.
What makes polyrepos harder to explore?
A single workflow may span several repositories with different conventions and versions. Cross-repository search and explicit shared contracts help engineers follow the full path before changing code.
Can a team combine monorepos and polyrepos?
The article proposes keeping core business logic and shared contracts together while using separate repositories for systems with distinct toolchains or lifecycles. Evaluate that arrangement against the changes your team actually makes.
How should I test whether our repository structure works?
Give engineers realistic tasks that involve finding an entry point, tracing its dependencies and locating tests and recent changes. Compare the friction you observe with the coordination and ownership needs of the system.
Architecture fitness functions are automated tests for your system's structural properties. Here's how to implement the 5 most impactful ones and integrate them into your CI pipeline.
A 3-tier succession planning framework for engineering orgs, with a 90-day sprint for accelerating candidates from potential to ready. Based on succession plans built at 4 companies.
The CTO's real job in product development isn't attending every meeting or making every technical call. It's connecting feasibility, viability, and capacity while letting EMs handle the day-to-day.
Four years of data from a fully remote engineering team across 4 time zones. Specific metrics on productivity, retention, and onboarding with the frameworks that actually worked.
Small frictions cost more than big blockers. 47 micro-frictions consume 96 minutes per engineer per day. Here's the TAX Return framework for finding and eliminating the developer productivity tax.
A structured 30-60-90 day framework for handling engineering underperformance. Based on 14 real cases with a 64% success rate, starting with diagnosis before intervention.