KI-Agenten in großen Monorepos einsetzen

In einem Monorepo verliert sich ein KI-Agent leicht im falschen Teilprojekt – mit der richtigen CLAUDE.md-Struktur bleibt er fokussiert.

Das Problem in großen Repos

Ein Monorepo enthält oft viele Teilprojekte: ein Backend, ein Frontend, gemeinsame Bibliotheken. Eine einzige CLAUDE.md-Datei für alles wird entweder riesig (und frisst bei jeder Session Kontext, den die Aufgabe gar nicht braucht) oder bleibt zu allgemein, um wirklich zu helfen.

Die Lösung: mehrere CLAUDE.md-Dateien

Statt einer Datei für alles legst du pro Teilprojekt eine eigene CLAUDE.md an. Eine Datei im Wurzelverzeichnis enthält Regeln, die überall gelten (Commit-Stil, grober Aufbau). Jedes Unterprojekt bekommt eine eigene Datei mit seinen spezifischen Befehlen und Konventionen.

Wie das Laden funktioniert

Startest du den Agenten im Wurzelverzeichnis, lädt er beim Start nur die Wurzel-CLAUDE.md; Dateien in Unterordnern lädt er erst, wenn er dort tatsächlich Dateien liest. Startest du ihn direkt in einem Teilprojekt, bekommt er dessen Datei plus alle übergeordneten – aber standardmäßig nur Zugriff auf diesen Teilbaum.

Fokus erzwingen

Für Aufgaben, die klar zu einem Teilprojekt gehören, lohnt es sich, den Agenten direkt dort zu starten statt im Wurzelverzeichnis. Das hält Kontext und Dateizugriff automatisch eng – ganz ohne dass du bei jeder Aufgabe erklären musst, welche Teile des Repos gerade irrelevant sind.

BEISPIEL

Ein Monorepo mit packages/api, packages/web und packages/shared bekommt eine Wurzel-CLAUDE.md ('Drei Pakete: api (Node/Express), web (React/Vite), shared (TS-Utils). Befehle immer im jeweiligen Paket-Ordner ausführen.') plus eine eigene packages/api/CLAUDE.md mit den API-spezifischen Testbefehlen. Wird der Agent direkt in packages/api/ gestartet, sieht er beide Dateien – aber nichts aus packages/web/.

KURZ-QUIZ

Was passiert standardmäßig, wenn du Claude Code direkt in einem Unterordner eines Monorepos (z. B. packages/api/) statt im Wurzelverzeichnis startest?