Wer AI-Agenten in einem Monorepo einsetzt, wird schnell feststellen: Die Defaults fuer Single-Repos funktionieren nicht. Der Agent braucht explizite Instruktionen, in welchem Workspace er operiert, welche Commands er ausfuehren darf und was "Erfolg" bei einem geaenderten Shared Package bedeutet.
Scope und Routing
In einem Single-Repo gibt es einen naheliegenden Kontext: das Root-Verzeichnis. Im Monorepo muss der Agent zuerst den zustaendigen Workspace identifizieren, bevor er irgendetwas tut. Ohne explizite Routing-Regeln wird der Agent entweder zu breit arbeiten (Root-Level-Commands mit weitreichenden Konsequenzen) oder im falschen Package landen.
Empfehlung: Routing-Regeln in der zentralen Instruction-Datei definieren, die den engstmoeglichen Scope setzen. Beispiel: "Identifiziere anhand des Datei-Pfads den betroffenen Workspace, bevor du Commands ausfuehrst."
Instruction Architecture
Ein Single-Repo kommt mit einer einzigen CLAUDE.md (oder AGENTS.md) am Root aus. Im Monorepo braucht es eine Hierarchie:
- Root-Instruction-File: Workspace-Map, verwendete Toolchain, Routing-Regeln, globale Verbote
- Lokale Instruction-Files: In High-Value-Workspaces (z.B.
packages/core/CLAUDE.md) mit paketspezifischer Guidance - Package-spezifische Hinweise: Besonderheiten einzelner Pakete -- abweichende Test-Commands, Build-Eigenheiten, Ownership-Regeln
Ohne diese Hierarchie muss der Agent Konventionen erraten, was zu inkonsistentem Verhalten fuehrt.
Command Execution
Root-Level-Commands wie npm test oder npm run build haben im Monorepo einen zu grossen Blast-Radius. Sie laufen entweder ueber alle Workspaces oder gar nicht korrekt.
Empfehlung: Workspace-gefilterte Commands als Standard vorgeben. Mit pnpm etwa:
pnpm --filter package-name test
pnpm --filter package-name build
Der Agent sollte explizit angewiesen werden, keine Root-Commands ohne Bestaetigung auszufuehren.
Verification Strategy
Im Single-Repo bedeutet "Verification": Tests laufen gruen. Im Monorepo reicht das nicht -- eine Aenderung an einem Shared Package kann Consumer-Pakete brechen, die selbst keine Tests haben, die den geaenderten Code direkt testen.
Drei-Stufen-Eskalation:
- Lokal: Tests im geaenderten Package
- Erweitert: Package + direkte Consumer
- Breit: Groesserer Dependency-Graph, wenn Aenderung fundamental ist
Der Agent muss wissen, wann er von Stufe 1 auf 2 eskalieren soll -- und das passiert nicht automatisch ohne explizite Instruktion.
Dependency Graph Transparency
Der Agent kann keine vernuenftigen Entscheidungen treffen, wenn er nicht weiss, was von einem Package abhaengt. "Was passiert, wenn ich packages/utils aendere?" -- ohne maschinenlesbares Dependency-Modell ist das eine Raterei.
Empfehlung: Ein Dependency-Dokument oder eine Konfigurationsdatei pflegen, die den Blast-Radius pro Shared Package beschreibt. Idealerweise maschinenlesbar (JSON/YAML), sodass der Agent es direkt auswerten kann. Mindestens als kommentierten Abschnitt in der Root-Instruction-Datei.
Ownership und Boundaries
In Monorepos gibt es typischerweise Bereiche, die verschiedenen Teams gehoeren -- und Bereiche, in die kein Agent ohne menschliche Ueberpruefung schreiben sollte.
Empfehlung:
CODEOWNERS-Datei pflegen und dem Agenten zugaenglich machen- Verbotene Verzeichnisse explizit benennen (z.B.
infra/,deploy/) - Compliance-sensitive Pfade markieren (z.B.
packages/auth/,packages/payments/) - High-Risk-Areas mit erhoehtem Bestaeitigungsbedarf kennzeichnen
Ein Agent, der nicht weiss, dass infra/ tabu ist, wird dort aendern, wenn es logisch erscheint.
Typische Fehler
Context Bloat: Der Agent laedt den gesamten Monorepo-Kontext, wenn er nur ein einzelnes Package aendern soll. Das fuehrt zu langsameren Antworten, hoeherem Token-Verbrauch und groesserem Fehlerrisiko.
Versehentliche High-Blast-Radius-Edits: Der Agent aendert ein Shared Package, ohne zu wissen, dass davon 12 Consumer-Pakete abhaengen. Gruene Tests im geaenderten Package verschleiern das Problem.
Falsche Verification: Tests laufen gruen -- aber nur im geaenderten Package. Consumer-Pakete werden nicht geprueft. Der Agent meldet Erfolg, obwohl der Build in CI bricht.
Parallele Agent-Konflikte: Mehrere Agenten arbeiten gleichzeitig an verschiedenen Workspaces und modifizieren dasselbe Shared Package in unterschiedliche Richtungen. Ohne Lock-Mechanismus oder Koordinationsregeln entstehen Merge-Konflikte oder inkonsistente Zustaende.
Quellen
- AI agents in monorepos | d4b.dev