ki-praxis/checklists/monorepo-entscheidung.md

Checkliste: Monorepo ja / nein / hybrid

Kurzentscheidung für Teams mit Coding-Agents.
Details und Begründung: Kapitel 9 (Projekt-Struktur: Monorepos als Vorteil für Coding-Agents).

Kontext (2 Minuten)

• Wir nutzen Coding-Agents regelmäßig für Features über mehrere Module/Services
• Cross-Cutting-Änderungen (Shared Types, APIs, Events) sind häufig (≥ ca. monatlich spürbar)
• Heute scheitern Agents oft an fehlendem Consumer-Kontext oder Versionsdrift zwischen Repos

Wenn hier viel „nein“: Monorepo ist kein Muss — Contracts und Codegen zuerst.

Org-Grenzen (zuerst klären)

• Compliance- oder Security-Zonen erzwingen getrennte Repos/Zugriffe
• Ownership/ACLs sind team- oder org-seitig hart (kein geteiltes Repo-Vertrauen)
• Regulatorik oder Blast-Radius verlangt isolierte Secrets/Systeme
• Multi-org- oder Lieferanten-Grenzen trennen den Code

Wenn hier 2+ Häkchen: Polyrepo, Hybrid oder federated ist oft die richtige Organisationswahl — nicht ein Defizit. Agent-Strategie: Contracts + Codegen + scoped Verify, nicht erzwungenes Monorepo.

Für Monorepo (oder Monorepo behalten/verbessern)

Zählt, wie viele zutreffen (und Org-Grenzen erlauben einen gemeinsamen Workspace):

• Eng gekoppelte Full-Stack- oder Platform-Codebases
• Shared Domain-Types/Contracts sollen eine Wahrheit haben
• Ein PR für API + Consumer + Tests ist der Normalfall
• Teams teilen Repo-Vertrauen (ACL-/Compliance-Trennung nicht hart erforderlich)
• Größe beherrschbar oder Graph/Affected/Cache sind investierbar (Richtwert oft unter ~30–50 klaren Packages)
• Bereitschaft für hierarchische AGENTS.md, Boundaries, Ignore-Rules

Faustregel: 4+ Häkchen und keine harten Org-/Compliance-Schnitte → gut strukturiertes Monorepo ist für Agents oft vorteilhaft.

Gegen erzwungenes Mono-Repo / für Polyrepo, Hybrid, federated

• Domains sind release- und organisationsseitig unabhängig
• Compliance/Security verlangt getrennte Repos oder getrennte Zugriffe
• Ownership/CODEOWNERS widersprechen monorepo-weiten Write-Rechten
• Starke Contracts + generierte Clients existieren bereits und werden enforced
• Monorepo-CI wäre absehbar ein Dauerenpass ohne Affected-Invest
• Sehr große Codebase ohne realistische Graph-/Sparse-Strategie

Faustregel: 3+ Häkchen → Polyrepo, Hybrid oder federated; Agent-Mitigationen (Contracts, Codegen, scoped Rules) als vollwertige Strategie budgetieren — nicht als Trostpreis.

Hybrid erwägen

• Eine Domain ist eng gekoppelt, eine andere ist eigenes Produkt
• Ein „großes“ Monorepo lässt sich entlang von Domain-Schnitten teilen, ohne wöchentliche Cross-Repo-Features zu erzeugen
• Zwischen den Teilen reichen versionierte Packages + CI
• Ownership oder Compliance trennt zwischen Domains, nicht innerhalb

Mindest-DoD, falls Monorepo

• Root-AGENTS.md + mind. ein Package-AGENTS.md für das heißeste Package
• Scoped Verify-Commands dokumentiert (affected / --filter)
• Ignore-Rules gegen node_modules, dist, Caches, große Binaries
• Module Boundaries benannt (ideal: enforced)
• Parallel-Agent-Regel: disjunkte Scopes, Lockfile serialisiert

Mindest-DoD, falls Polyrepo / federated

• API-Contracts (OpenAPI/Proto/JSON Schema) als Source of Truth
• Generierte Clients/SDKs — Agent schreibt keine Hand-Clients über Repo-Grenzen
• Pro-Repo-AGENTS.md / Rules mit Verify-Commands
• Versions- und Release-Prozess für shared Packages dokumentiert

Betrieb, sobald die Lage feststeht

Kopierblöcke und Leiter für den Alltag — Begründung in Kapitel 9.

Task-Scope (Kopierblock)

Erlaubt: packages/billing/**, packages/shared-types/** (nur public export)
Verboten: apps/** außer apps/api; Root-Refactor; Lockfile ohne Auftrag
DoD: pnpm turbo run lint test --filter=@your-org/billing...
Bei Contract außerhalb Scope: stoppen, Handoff — nicht „kurz mitziehen“

Hierarchische Instruction-Files

• Root-AGENTS.md: Mission, Karpathy-Skills, Context-Richtlinie, Default-Verify, Git-Risiken, „lies Package-Rules im Arbeitsverzeichnis“.
• Pro Package/App: Zweck, Ownership, erlaubte Imports, lokale Verify-Commands, Ausschlüsse.
• Vorlagen: templates/agents-md-monorepo-root.md, templates/agents-md-monorepo-package.md. Weniger Text, dafür wahr.

DoD-Leiter (Monorepo)

Stufe	Beispiel	Wann
Tight-Loop	turbo run lint test --filter=@your-org/billing	jeder Edit-Zyklus
Slice-DoD	nx affected -t lint,test / turbo mit Dependents (...)	vor „done“ / Hand-back
Heavy	e2e, full monorepo, Nightly	CI — nicht Default-DoD des Agents

Kanonische Filter-Commands in AGENTS.md = dieselben, die CI nutzt.

Ignore

node_modules, dist, build, .next, Coverage, Caches, große Fixtures, generierte Blobs, Vendor-Trees. Patterns: templates/cursorignore-monorepo-beispiel.md. Prinzip: Artefakte raus, Sources rein.

Symptom → Hebel

Symptom	Diagnose	Hebel
Agent greift 15 Packages an	Task-Scope unklar	Task-Scope-Block + Package-AGENTS.md
Package grün, System rot	Verify nur lokal	affected / Dependents; Boundary-Tests
Client driftet trotz Mono	Shared Types nicht enforced	Public API + Import-Lint
Session voll nach Explore	Artefakte / Half-Repo im Context	Ignore + Graph-first + prune
Parallel-Diffs unmergbar	Lockfile / Schema-Hotspot	serialisieren; Worktrees; disjunkte Scopes

Parallel-Agents

Regel	Umsetzung
Disjunkte Schreib-Scopes	Agent A: packages/billing, Agent B: apps/admin
Eine Wahrheit für Lockfiles	Nur ein Agent ändert pnpm-lock.yaml / package-lock.json
Getrennte Isolation	Git Worktrees oder getrennte Workspaces
Eigene DoD pro Agent	Scoped test/lint; Integration erst nach Merge
Konflikt-Hotspots serialisieren	Schema-Migrationen, generierte Clients, Root-Configs

Ab Größe: Sparse Checkout / turbo prune; Handoff hält den Scope fest.

Tooling-Hinweise (Stand 2026, UI/CLIs driften)

Hebel	Praxis
Workspace-Scope	Task auf Packages begrenzen; Experimente in Worktrees
Nested Rules	Package-AGENTS.md / path-scoped Rules
Nx	nx affected, Project Graph; npx nx configure-ai-agents (Befehl kann driften)
Turborepo	--filter, Remote Cache, turbo prune
IDE-Context	nicht Half-Repo @-füttern; nur betroffene Packages
CI	Affected-Pipelines; Agent-PRs treffen dieselben Gates wie Menschen

Ein kanonischer Weg für Build/Test pro Package, in Rules und CI.

Entscheidung (eine Zeile)

Option	Gewählt	Nächster Schritt
Monorepo verbessern	[ ]	Boundaries + Package-Rules + affected CI
Hybrid schneiden	[ ]	Domain-Schnitt skizzieren, Contracts an der Naht
Polyrepo + Contracts behalten/härten	[ ]	OpenAPI/Proto + Codegen + Agent-Verbote für Hand-Clients
Federated nachziehen	[ ]	Published Packages + semver + scoped Agent-Workspaces
Noch messen	[ ]	2 Wochen: Cross-repo-PRs und Agent-Rework zählen

Datum: ________ Team: ________