Warum das modulare Monorepo für Coding-Agenten geeignet ist: Alles sehen, nur wenig anfassen.

Ein alter Streit mit neuen Implikationen

Seit Jahren teilen sich Ingenieure in zwei Gruppen auf. Die eine Gruppe bewahrt den gesamten Code in einem einzigen Repository auf, während die andere jedem Bestandteil einen eigenen Ort zuweist, wobei es viele Kompromisse gibt. Niemand hat in allen Fällen recht, und wer das behauptet, extrapoliert in der Regel aus einem einzigen Projekt. Wenn man fragt, ob ein Monorepo oder ein Polyrepo besser ist, lautet die ehrliche Antwort „es hängt davon ab“: davon, wie groß das System ist, wie eng seine Komponenten miteinander verbunden sind, wer zum Team gehört und wie häufig neue Versionen veröffentlicht werden. Einige lose miteinander verbundene Dienste gehören in separate Repos. Ein Produkt, das eng an gemeinsame Kontrakte gebunden ist, deutet in die entgegengesetzte Richtung.

Die Codier-Agenten verstärkten diese Argumentation noch. Geben Sie einem Agenten eine Aufgabe, die einen Frontend-, einen gemeinsamen Bibliotheks- und einen Backend-Vertrag betrifft, dann ist die Struktur des Repositories nicht mehr eine Frage des Geschmacks. Die Folgen zeigen sich in der Codequalität, in der Häufigkeit, mit der der Agent raten muss, und in seinem Grad der Desorientierung. Dieser Fall wird aus der Perspektive einer TypeScript NX-Umgebung beschrieben, die sechs Plattformen abdeckt. Das ist eine bewusst gewählte Sichtweise, die nicht allen entsprechen wird – betrachten Sie sie daher als eine festgehaltene Meinung, die dazu dienen soll, eine Diskussion in Gang zu bringen. Vier Worte fassen diese These zusammen: Alles sehen, wenig anfassen.

Erster Abgrund: Mauern, hinter denen der Agent nichts sehen kann

Stellen Sie sich die geteilte Welt vor, in der die meisten Teams arbeiten: ein Frontend-Repository, zwei Backend-Service-Repositories, ein gemeinsames Types-Paket in einem privaten Registry-System und ein Infrastruktur-Repository. Die Grenzen sind sinnvoll und jedes Element hat einen Verantwortlichen.

Angenommen, ein Agent im Frontend-Repo wird gebeten, die Art und Weise zu ändern, wie er auf einen Endpunkt zugreift, der zu einem Service-Repo gehört, das er nicht öffnen kann. Ohne einen Handler zum Lesen muss er raten, wie die Antwort aussehen könnte. Ein veralteter Typ-Stub oder ein einzelnes Testbeispiel dienen ihm als Beweismittel. Das Ergebnis kompiliert zwar auf dem lokalen Rechner, ist aber nach der Integration wahrscheinlich falsch. Jede Grenze zwischen den Repos ist eine Mauer, hinter der der Agent nicht blicken kann, und er füllt jede mit einer plausiblen Annahme aus. Was die Menschen schützt, lässt die Agenten nach Informationen dürsten.

Teams schließen diese Lücke auf drei Hauptwegen, wobei einige der Lösungen gut sind:

• Git-Submodule platzieren die abhängigen Repos innerhalb des Haupt-Repo, sodass die Dateistruktur einheitlich erscheint. Der Agent erhält so die Möglichkeit, alles zu lesen – zum üblichen Preis: Fixierte Commits verschieben sich, das Aktualisieren der Inhalte wird zu einer lästigen Aufgabe, und der Workflow befriedigt niemanden.
• Mehrfach-Wurzel-IDE-Arbeitsbereiche ermöglichen es Cursor oder VS Code, mehrere Repositorien gemeinsam zu indizieren, was hilft, wenn das Ziel lediglich das Durchblättern dieser Repositorien ist. Die Anordnung gehört jedoch zu einem einzigen Rechner und nicht zum Projekt, wodurch der Agent eine Menge von Dateien ohne Abhängigkeitsgraphen erhält. Er weiß, dass Code vorhanden ist, kennt aber nicht, was von was abhängt.
• Synthetische Monorepos sind die seriöse Alternative. NXs Polygraph zum Beispiel vereint separate Repositorien zu einem einzigen Abhängigkeitsgraphen, während der Code an seinem ursprünglichen Ort bleibt. Ein Koordinationsagent prüft diesen Graphen, um herauszufinden, auf welche Repositorien eine Änderung Auswirkungen hat, startet in jedem davon einen Agenten und öffnet entsprechende Pull Requests, während er überall den CI-Verlauf verfolgt. Dies kommt dem Verhalten eines Monorepos am nächsten, basierend auf einer Polyrepo-Struktur.

Dem synthetischen Ansatz gebührt Respekt, aber man sollte sich ansehen, was er tatsächlich leistet: Er bohrt sich durch Wände, die weiterhin stehen bleiben. Ingenieure investieren erhebliche Anstrengungen in die Tool-Ebene, um die Sichtbarkeit zu erzeugen, die ein Monorepo strukturell kostenlos bietet. Und wenn es solche Tools nicht gibt, ist der Mensch der „Tunnel“ – er liest Service B, übermittelt die Erkenntnisse an den Agenten in Service A, klebt Typdefinitionen in den Chat ein und fungiert als Kurier zwischen abgeschlossenen Sitzungen.

Der zweite Abgrund: der strukturlose Haufen

Also wandert alles in ein einziges Repo, und die Angelegenheit ist erledigt? Nicht ganz. Ein Monorepo ohne interne Struktur versagt noch schlimmer, denn es verführt. Alles ist sichtbar, was wie ausreichend erscheint. In Wirklichkeit gibt es jedoch einen einzigen riesigen Anwendungsordner, Bibliotheken, die sich aus allen Richtungen gegenseitig importieren, keine vorgeschriebenen Grenzen und kein Verständnis dafür, wem welcher Teil gehört.

Hier schadet ein offener Kontext. Ein Agent, der alles sieht, erhält keinen Hinweis darauf, was übersprungen werden soll. Das Fenster füllt sich mit Code, der auf der Festplatte in der Nähe liegt und für die Aufgabe irrelevant ist; eine einzige Änderung wirkt sich auf Importe aus, die niemand verfolgt hat, und die entscheidende Frage – welche Auswirkungen hat diese Änderung? – erhält die Antwort „möglicherweise alles“. Sichtbarkeit ohne Struktur ist lauter Lärm und kein Kontext – deshalb ist das Hineinwerfen aller Codeabschnitte in ein einziges Repository keine gute Lösung.

Drei Säulen eines modularen Monorepos

Ein modulares Monorepo gewinnt, indem es gleichzeitig drei Dinge erledigt. Wenn eines davon fehlt, gerät man vom richtigen Weg ab.

Offener Kontext. Ein einziger Baum enthält alles, und der Agent kann in einer einzigen Sitzung darin navigieren: Frontend, Backend, gemeinsame Bibliotheken, Tests sowie die Typverträge, die alles miteinander verbinden. Keine Barrieren, kein Raten, kein Kurier. NXs Roadmap betont diesen Aspekt am stärksten – und zu Recht, denn ein Agent, der in einer einzigen Durchlaufphase den Ersteller sowie alle Verbraucher eines Vertrags liest, kann bessere Änderungen vornehmen.

Encapsulation. Bibliotheken sind abgegrenzt und bieten explizite öffentliche Schnittstellen, sodass der Agent das gesamte System nicht im Kopf behalten muss. Er arbeitet mit einem Teilbereich. Genau diese Abgrenzung ermöglicht es, alles zu sehen und dennoch nur wenig zu verändern – ohne sie würde der offene Kontext in das Problem Nummer zwei übergehen.

Eine echte Abhängigkeitsgraphik mit Werkzeugen zur Erkundung. Das ist der Pfeiler, den die Leute unterschätzen. NX behandelt die Graphik als ein erstklassiges Objekt, das abgefragt werden kann. Anstatt nach Mustern zu suchen und zu hoffen, die Struktur erschließen zu können, kann der Agent nx show projects ausführen, nx graph öffnen, fragen, welche Änderungen betroffen sind, und eine präzise Antwort erhalten, die von einer Maschine verarbeitet werden kann. Die Karte befindet sich im Repository und nicht in einer Wiki-Seite oder im Gedächtnis eines Senior-Entwicklers – und sie ist ausführbar.

Zusammen lösen diese Aspekte die vier Wörter der These auf. Alles sehen ist der erste Pfeiler, nur wenig anfassen der zweite Pfeiler, und zu wissen, welches Wenige man anfassen soll, ist der dritte Pfeiler – die Brücke, die es ermöglicht, die ersten beiden sicher miteinander zu verbinden.

Erfassen und überprüfen

Die Agenten arbeiten in einem Zyklus, bei dem sie Kontext abrufen, Code ändern, die Änderung überprüfen und anschließend wieder von vorn beginnen. Alle Maßnahmen zur Aufrechterhaltung der Ordnung im Monorepo dienen einem von zwei Zwecken: dem günstigen Abrufen von Kontext oder der günstigen Überprüfung von Aktionen.

• Starke Typen (Erwerb). Eine gemeinsame Typenbibliothek liefert dem Agenten einen Vertrag, den er lesen kann und den der Compiler durchsetzen kann. Dadurch wird das Problem des „blinden Agenten“ aus Schritt eins gelöst, denn es ist nicht notwendig, die Form der Antwort zu erraten, wenn sie schriftlich festgehalten und überprüft wird. Typen dienen außerdem als Dokumentation, die niemals veraltet.
• Lint- und Modulgrenzregeln (überprüfen). Mit NXs @nx/enforce-module-boundaries führt eine verbotene Importierung zu einem Fehler, anstatt unbemerkt durchzugehen, wobei der Fehler als Feedback innerhalb der eigenen Schleife des Agents angezeigt wird. Wenn der Agent eine UI-Bibliothek in die Datenschicht einbindet, weist die Regel dies ab, und die Architektur wird aus dem Fehler gelernt, ohne dass jemand sie explizit festlegen muss.
• TDD und betroffene Tests (überprüfen). nx affected macht einfache Überprüfungen konkret. Nach der Bearbeitung eines Teils führt der Agent nur die darunterliegenden Tests aus und kann schnell erkennen, ob sie erfolgreich waren oder nicht – ohne auf einen vollständigen Testlauf warten zu müssen oder Zweifel daran zu haben, ob die Änderung Bestand hat. Kurze Schleifen sorgen dafür, dass die Arbeit mit dem Agent wie das Bauen und nicht wie das Aufpassen erscheint.
• Fähigkeiten und AGENTS.md oder CLAUDE.md (erwerben). Das Ausführen von npx nx configure-ai-agents in einer Arbeitsumgebung installiert einen MCP-Server, Agent-Fähigkeiten sowie die Konventionsdateien. Die Fähigkeiten werden nach Bedarf bereitgestellt und nicht alle auf einmal im Prompt, wodurch man genau dann lernt, wie man eine Bibliothek aufbaut, wenn man eine solche erstellt. Zudem leiten sie den Agenten dazu an, den Graphen statt durch Suchen abzufragen, was wieder auf Punkt drei verweist.
• Atomare Leitfäden pro Modul (erwerben). Jede Bibliothek kann eine kurze README-Datei oder ein AGENTS.md enthalten, die den lokalen Kontext direkt dort liefern, wo der Agent gerade ankommt. Das Öffnen dieser Bibliothek bringt ihren Vertrag sowie die Konventionen mit, ohne den Rest des Baums mitzuziehen.

Zählt man die Aufgaben in der Liste auf, erhält man „erhalten“, „überprüfen“, „überprüfen“, „erhalten“, „erhalten“ – wobei die Reihenfolge zufällig ist. Jede Funktionalität passt zu einer der beiden Aufgaben. Ein modulares Monorepo besteht nicht aus einer einzigen Funktion für die Agenten, sondern aus vielen kleinen Funktionen, die den Prozess schnell und effizient halten.

Die Gegenargumente

Niemand profitiert von Verkaufspräsentationen, daher sollte man die Gegenargumente berücksichtigen. Die Kontextfenster werden ständig erweitert, und mehrfach verwendete Arbeitsumgebungen sowie Tools für synthetische Monorepos verringern den Abstand zunehmend. Ein Skeptiker könnte den Vorteil des Monorepos als vorübergehendes Phänomen aufgrund der aktuellen Einschränkungen bezeichnen, das durch ausreichend große Kontextfenster sowie gute Tools zur Verwaltung mehrerer Repositorien beseitigt werden könnte. Die präzisere Sichtweise bezieht sich nicht auf Kontextfenster. Polygraph zeigt, dass ein Abhängigkeitsgraph über ein Polyrepo neu aufgebaut werden kann, sodass die Struktur, der oft den Monorepos zugeschrieben wird, nicht ausschließlich ihnen zukommt.

Jede Version irrt sich darüber, woher der Nutzen stammt. Es ging niemals darum, mehr Rohtext zu lesen – es geht um Struktur. Ein größeres Fenster ermöglicht es einem verlorenen Agenten, in feineren Details zu „verloren“ gehen, ohne die richtige Tür zu benennen. Ein synthetisches Graph ist ebenfalls eine Struktur, die erklärt, warum es funktioniert – doch diese Struktur wird auf der Basis der Aufteilung neu aufgebaut und aufrechterhalten und wird nicht durch die Anordnung vorgegeben. Der Rohkontext wächst mit dem Modell, die Struktur wächst durch Disziplin – und die Struktur verwandelt das Sehen von allem als Gefahr in einen Vorteil. Wenn die Fenster größer werden, wird ein Monorepo ohne Module riskanter, denn die „Schleuse“ öffnet sich weiter. Das Adjektiv trägt die Last.

Was das Agentenzeitalter aufgedeckt hat

Projektgraphen, Modulgrenzen und gemeinsame Typen schienen einst nur praktische Hilfsmittel für ein menschliches Team zu sein. Die Ära der Agenten zeigte jedoch, was sie die ganze Zeit über gewesen waren: eine Schnittstelle für nicht-menschliche Mitwirkende. Architekturen, die für menschliches Denken entwickelt wurden, erwiesen sich als Kontextengineering auf Repository-Ebene – Jahre, bevor der Begriff überhaupt existierte. Das erklärt, warum andere Ansätze als Monorepos wieder in Mode kommen. Das modulare Monorepo beantwortete leise eine Frage, die noch niemand gestellt hatte: Alles sehen, nur wenig anfassen – und die Agenten machten das lediglich deutlich.