Monorepo vs polyrepo: proč používáme obojí

Monorepo vs polyrepo je otázka, jakou hranici potřebujete. Monorepo dává mnoho balíčků do jednoho repozitáře, takže jedna změna může projít všemi. Polyrepo dává každému projektu vlastní repozitář, takže každý může mít vlastní přístup, CI i vydání.

My používáme obojí, záměrně. Každý produkt, který stavíme, je Turborepo monorepo. Samotná firma je polyrepo: každý klient, každá služba a každá důvěrná oblast je samostatný repozitář, propojené přes git submoduly. AI agent pracuje v obou každý den.

Jaký je rozdíl mezi monorepem a polyrepem?

Stručně: monorepo kreslí hranici kódu kolem balíčků, polyrepo kreslí hranici přístupu kolem repozitářů.

Většina článků na toto téma obhajuje jeden sloupec. Podle nás mají pravdu oba, jen pro jinou jednotku. Otázka je, kolem čeho kreslíte čáru.

Proč je každý produkt monorepo?

Produkt je kód, který se nasazuje spolu. Náš šablonový projekt i wizrd, náš interní plugin a CLI pro Claude Code (není veřejný), vypadají stejně: jedna aplikace a balíčky, ze kterých se skládá.

{
  "packageManager": "bun@1.3.13",
  "workspaces": {
    "packages": ["apps/*", "packages/*"],
    "catalog": { "zod": "^4.1.13", "typescript": "^6", "better-auth": "1.5.5" }
  },
  "scripts": { "build": "turbo build", "check-types": "turbo check-types", "deploy": "turbo -F @wizrd/infra deploy" }
}

apps/web je aplikace. V packages/ jsou api, db, auth, infra, ui, env a pár dalších. Aplikace je importuje jako workspace:*, takže není co publikovat. catalog určí sdílené verze jednou, takže API a aplikace nikdy neběží na dvou verzích téže knihovny.

Nahoře sedí Turborepo s krátkým turbo.json:

{
  "tasks": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] },
    "check-types": { "dependsOn": ["^check-types"] },
    "dev": { "cache": false, "persistent": true },
    "deploy": { "cache": false }
  }
}

^build znamená: nejdřív postav to, na čem závisím. Buildy, kontrola typů a lint jdou z cache. Nasazení a zápis do databáze nikdy. Cache je přesně důvod, který pro Turborepo uvádí jeho dokumentace:

Skutečná výhra ale není rychlost. Je to jeden pull request. Když se změní databázové schéma, API, typy i obrazovka se změní v tomtéž commitu a check-types selže, pokud něco z toho chybí. Pro AI agenta je to zlato: kontrola typů mu řekne, co rozbil, dřív, než to musí říct člověk.

Klient s online marketplace běží ve stejném tvaru, jeho crawler je jen další aplikace v monorepu.

Proč je firma polyrepo?

Protože přístup je pro nás nejdůležitější hranice a GitHub dává přístup na repozitář. Právo číst jednu složku neexistuje. Všechno, co potřebuje jiné publikum, proto dostane vlastní repozitář:

• Klientské repozitáře pro každého klienta, čitelné pro tým, který pro něj pracuje. Spediční firma, pro kterou jsme postavili a provozujeme systém, má vlastní klientský repozitář a v něm své repozitáře služeb jako submoduly.
• Místnosti pro důvěrné oblasti, například finance a brand, každá čitelná jen pro svůj GitHub tým.
• Repozitáře služeb pro naše vlastní nástroje, například plugin a harness, které používají naši agenti.

Firemní repozitář v kořeni je propojuje přes git submoduly. Celý strom nedostane nikdo automaticky. Session bez přístupu k financím finance nepřečte, ať je v jejím promptu cokoli.

Tohle vám monorepo nedá. Monorepo s pravidlem „prosím, neotevírejte složku finance“ je jen prosba. Samostatný repozitář s vlastním týmem je zámek.

Jak AI agent pracuje v obou?

Agent dodržuje stejných pár pravidel na notebooku člověka i na vlastním stroji:

Poslední pravidlo nehlídá důvěra, ale skript. Naše brána zastaví větev úkolu, která změní gitlink, tedy git objekt za ukazatelem submodulu:

moved=$(git diff --raw "$base"...HEAD | awk '$1 ~ /160000/ || $2 == "160000" {print $NF}')
[ -z "$moved" ] || { echo "FAIL submodule pointer changed: pointers move only via sync"; exit 1; }

Bez ní by agent, který se v jednom úkolu dotkl dvou repozitářů, potichu posunul ukazatel v rodiči na nesloučený commit. Všichni ostatní by si pak stáhli kód, který existuje jen ve větvi.

Vnořený worktree je druhý detail, na který jsme přišli až časem. Obyčejný worktree služby by minul klientův CLAUDE.md o složku výš, takže agent by pracoval bez pravidel klienta. Když je služba vnořená do worktree svého klienta, zůstane celý řetěz kontextu.

Co nás polyrepo stojí?

Zadarmo to není a nebudeme předstírat opak:

• Změna napříč repozitáři znamená víc pull requestů. Pravidlo, které se mění pro všechny klienty, znamená pull request v každém klientském repozitáři.
• Submoduly mají své mouchy. Nový checkout potřebuje git submodule update --init a zastaralý ukazatel ukáže starý kód bez jediného varování.
• CI se konfiguruje mnohokrát. Každý repozitář potřebuje vlastní workflowy.

Poslední bod jsme vyřešili tak, že CI nekopírujeme. Každý repozitář volá tenké sdílené actions z jednoho repozitáře nástrojů, připnuté na plovoucí major tag. Nová validační kontrola přibude na jednom místě a do každého repozitáře se dostane při jeho dalším běhu. Všechny běží na jednom GitHub Actions self-hosted runneru pro celou firmu.

Monorepo, nebo polyrepo: jak se rozhodnout pro váš tým?

Projděte si, co dnes platí pro váš kód:

Další otázka bývá Turborepo vs Nx. Upřímně: používáme Turborepo, protože naše monorepa jsou TypeScript aplikace na Bun workspaces a stačí jim krátký turbo.json. Nx jsme v produkci neprovozovali, takže jejich pořadí neurčíme.

Jak pouštíme víc agentů paralelně přes worktrees, rozebíráme v článku Claude Code subagenti a worktrees. Celou smyčku od issue po pull request popisuje Harness engineering v praxi.

Potřebujete repozitáře, ve kterých může agent bezpečně pracovat?

Rozložení repozitářů, sdílené CI a pravidla pro agenty nastavujeme přímo v kódu týmu v rámci služby AI-native SDLC pro vývojové týmy. Chybí vašemu týmu spíš ruce než struktura? Podívejte se na seniorního vývojáře do týmu. AI dnes píše veškerý náš kód a za výsledek ručí senior. Od roku 2023 jsme dodali 15+ produkčních projektů.

Ozveme se do dvou pracovních dnů a společně vybereme, co vyřešíme jako první.

Pokud si chcete nejdřív promluvit, domluvte si meeting na 15 minut s Filipem.

Kde váš kód potřebuje hranici kódu a kde hranici přístupu?

Časté otázky

Jaký je rozdíl mezi monorepem a polyrepem?

Monorepo drží mnoho projektů nebo balíčků v jednom git repozitáři s jednou historií. Polyrepo dává každému projektu vlastní repozitář. V monorepu jeden commit změní najednou víc balíčků. V polyrepu má každý repozitář vlastní přístup, vlastní CI a vlastní vydání.

Kdy je lepší volba monorepo?

Když se části nasazují spolu a sdílejí kód: webová aplikace, její API, databázové schéma a UI komponenty. Jeden pull request změní všechny a typy odhalí, co už nesedí, dřív, než se cokoli nasadí.

Kdy je lepší volba polyrepo?

Když různí lidé smějí vidět různé části. GitHub dává přístup na repozitář, ne na složku, takže kód klientů, finance a interní nástroje s různým publikem patří do různých repozitářů.

Turborepo, nebo Nx?

Používáme Turborepo s Bun workspaces, protože naše monorepa jsou TypeScript aplikace a Turborepo potřebuje nad workspaces jen krátký turbo.json. Nx jsme v produkci neprovozovali, takže je ze zkušenosti porovnat neumíme.

Zvládne AI agent polyrepo s git submoduly?

Ano, pokud má pravidla. Náš agent do submodulu naviguje místo klonování kopie, na každý úkol má vlastní worktree a brána zastaví každou větev úkolu, která posune ukazatel submodulu.