Monorepo vs polyrepo: prečo používame oboje

Monorepo vs polyrepo je otázka, akú hranicu potrebujete. Monorepo dáva veľa balíčkov do jedného repozitára, takže jedna zmena môže prejsť všetkými. Polyrepo dáva každému projektu vlastný repozitár, takže každý môže mať vlastný prístup, CI aj vydania.

My používame oboje, zámerne. Každý produkt, ktorý staviame, je Turborepo monorepo. Samotná firma je polyrepo: každý klient, každá služba a každá dôverná oblasť je samostatný repozitár a spájajú ich git submoduly. AI agent pracuje v oboch každý deň.

Aký je rozdiel medzi monorepom a polyrepom?

Stručne: monorepo kreslí hranicu kódu okolo balíčkov, polyrepo kreslí hranicu prístupu okolo repozitárov.

Väčšina článkov na túto tému obhajuje jeden stĺpec. Podľa nás majú pravdu oba, len pre inú jednotku. Otázka je, okolo čoho kreslíte čiaru.

Prečo je každý produkt monorepo?

Produkt je kód, ktorý sa nasadzuje spolu. Náš šablónový projekt aj wizrd, náš interný plugin a CLI pre Claude Code (nie je verejný), vyzerajú rovnako: jedna aplikácia a balíčky, z ktorých sa skladá.

{
  "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 aplikácia. V packages/ sú api, db, auth, infra, ui, env a pár ďalších. Aplikácia ich importuje ako workspace:*, takže nie je čo publikovať. catalog určí zdieľané verzie raz, takže API a aplikácia nikdy nebežia na dvoch verziách tej istej knižnice.

Navrchu sedí Turborepo s krátkym turbo.json:

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

^build znamená: najprv postav to, od čoho závisím. Buildy, kontrola typov a lint idú z cache. Nasadenie a zápis do databázy nikdy. Práve cache uvádza dokumentácia Turborepa ako dôvod na jeho použitie:

Skutočná výhra však nie je rýchlosť. Je to jeden pull request. Keď sa zmení databázová schéma, API, typy aj obrazovka sa zmenia v tom istom commite a check-types zlyhá, ak niečo z toho chýba. Pre AI agenta je to zlato: kontrola typov mu povie, čo pokazil, skôr než to musí povedať človek.

Klient s online marketplace beží v rovnakom tvare, jeho crawler je len ďalšia aplikácia v monorepe.

Prečo je firma polyrepo?

Lebo prístup je pre nás najdôležitejšia hranica a GitHub dáva prístup na repozitár. Právo čítať jeden priečinok neexistuje. Všetko, čo potrebuje iné publikum, preto dostane vlastný repozitár:

• Klientske repozitáre pre každého klienta, čitateľné pre tím, ktorý pre neho pracuje. Špedičná firma, pre ktorú sme postavili a prevádzkujeme systém, má vlastný klientsky repozitár a v ňom svoje repozitáre služieb ako submoduly.
• Miestnosti pre dôverné oblasti, napríklad financie a brand, každá čitateľná len pre svoj GitHub tím.
• Repozitáre služieb pre naše vlastné nástroje, napríklad plugin a harness, ktoré používajú naši agenti.

Firemný repozitár v koreni ich spája cez git submoduly. Celý strom nedostane nikto automaticky. Session bez prístupu k financiám financie neprečíta, nech je v jej prompte čokoľvek.

Toto vám monorepo nedá. Monorepo s pravidlom „prosím, neotvárajte priečinok financie“ je len prosba. Samostatný repozitár s vlastným tímom je zámok.

Ako AI agent pracuje v oboch?

Agent dodržiava tých istých pár pravidiel na notebooku človeka aj na vlastnom stroji:

Posledné pravidlo nestráži dôvera, ale skript. Naša brána zastaví vetvu úlohy, ktorá zmení gitlink, teda git objekt za ukazovateľom 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 nej by agent, ktorý sa v jednej úlohe dotkol dvoch repozitárov, potichu posunul ukazovateľ v rodičovi na nezlúčený commit. Všetci ostatní by si potom stiahli kód, ktorý existuje len vo vetve.

Vnorený worktree je druhý detail, na ktorý sme prišli až časom. Obyčajný worktree služby by minul klientov CLAUDE.md o priečinok vyššie, takže agent by pracoval bez pravidiel klienta. Keď je služba vnorená do worktree svojho klienta, ostane celá reťaz kontextu.

Čo nás polyrepo stojí?

Zadarmo to nie je a nebudeme predstierať opak:

• Zmena naprieč repozitármi znamená viac pull requestov. Pravidlo, ktoré sa mení pre všetkých klientov, znamená pull request v každom klientskom repozitári.
• Submoduly majú svoje muchy. Nový checkout potrebuje git submodule update --init a zastaraný ukazovateľ ukáže starý kód bez jediného varovania.
• CI sa konfiguruje mnohokrát. Každý repozitár potrebuje vlastné workflowy.

Posledný bod sme vyriešili tak, že CI nekopírujeme. Každý repozitár volá tenké zdieľané actions z jedného repozitára nástrojov, pripnuté na plávajúci major tag. Nová validačná kontrola pribudne na jednom mieste a do každého repozitára sa dostane pri jeho ďalšom behu. Všetky bežia na jednom GitHub Actions self-hosted runneri pre celú firmu.

Monorepo, alebo polyrepo: ako sa rozhodnúť pre váš tím?

Prejdite si, čo dnes platí pre váš kód:

Ďalšia otázka býva Turborepo vs Nx. Úprimne: používame Turborepo, lebo naše monorepá sú TypeScript aplikácie na Bun workspaces a stačí im krátky turbo.json. Nx sme v produkcii neprevádzkovali, takže ich poradie neurčíme.

Ako púšťame viac agentov paralelne cez worktrees, rozoberáme v článku Claude Code subagenti a worktrees. Celú slučku od issue po pull request opisuje Harness engineering v praxi.

Potrebujete repozitáre, v ktorých môže agent bezpečne pracovať?

Rozloženie repozitárov, zdieľané CI a pravidlá pre agentov nastavujeme priamo v kóde tímu v rámci služby AI-native SDLC pre vývojové tímy. Chýbajú vášmu tímu skôr ruky než štruktúra? Pozrite si seniorského vývojára do tímu. AI dnes píše všetok náš kód a za výsledok ručí senior. Od roku 2023 sme dodali 15+ produkčných projektov.

Ozveme sa do dvoch pracovných dní a spolu vyberieme, čo vyriešime ako prvé.

Ak sa chcete najprv porozprávať, dohodnite si meeting na 15 minút s Filipom.

Kde váš kód potrebuje hranicu kódu a kde hranicu prístupu?

Časté otázky

Aký je rozdiel medzi monorepom a polyrepom?

Monorepo drží veľa projektov alebo balíčkov v jednom git repozitári s jednou históriou. Polyrepo dáva každému projektu vlastný repozitár. V monorepe jeden commit zmení naraz viac balíčkov. V polyrepe má každý repozitár vlastný prístup, vlastné CI a vlastné vydania.

Kedy je lepšia voľba monorepo?

Keď sa časti nasadzujú spolu a zdieľajú kód: webová aplikácia, jej API, databázová schéma a UI komponenty. Jeden pull request zmení všetky a typy odhalia, čo už nesedí, skôr než sa čokoľvek nasadí.

Kedy je lepšia voľba polyrepo?

Keď rôzni ľudia smú vidieť rôzne časti. GitHub dáva prístup na repozitár, nie na priečinok, takže kód klientov, financie a interné nástroje s rôznym publikom patria do rôznych repozitárov.

Turborepo, alebo Nx?

Používame Turborepo s Bun workspaces, lebo naše monorepá sú TypeScript aplikácie a Turborepo potrebuje nad workspaces len krátky turbo.json. Nx sme v produkcii neprevádzkovali, takže ich zo skúsenosti porovnať nevieme.

Zvládne AI agent polyrepo s git submodulmi?

Áno, ak má pravidlá. Náš agent do submodulu naviguje namiesto klonovania kópie, na každú úlohu má vlastný worktree a brána zastaví každú vetvu úlohy, ktorá posunie ukazovateľ submodulu.