Claude Code in Monorepos: Kontext begrenzen und genau bleiben

Warum große Monorepos Claude ungenauer machen

Claude Code in Monorepos wirkt aus einem einfachen Grund unberechenbar: das Repo ist größer als das, was das Modell gleichzeitig im Arbeitsspeicher halten kann.

„Kontext“ ist die Menge an Dateien, Schnipseln, Notizen und Anweisungen, die Claude für diese Aufgabe gesehen hat, plus das, was es daraus erschließen kann. Fehlen wichtige Details, füllt Claude die Lücken mit Vermutungen. In einem großen Repo passiert das deutlich öfter.

Drei Fehlerarten treten immer wieder auf:

Erstens: fehlende Dateien. Eine Änderung, die in einem Ordner harmlos aussieht, hängt tatsächlich von einem geteilten Typ, einer Konfigurationsregel oder einem Build-Schritt an einer anderen Stelle ab. Wenn diese Abhängigkeit nicht im Kontext ist, bearbeitet Claude möglicherweise selbstsicher die falsche Stelle oder bricht ab, weil es die wirkliche Quelle der Wahrheit nicht sehen kann.

Zweitens: falsche Ähnlichkeit. Monorepos enthalten oft mehrere Pakete, die sich ähnlich sehen: zwei Auth-Module, drei API-Clients oder mehrere React-Apps mit ähnlicher Ordnerstruktur. Claude kann Muster zwischen ihnen vermischen, einen Helfer im falschen Paket aktualisieren oder aus einem „fast richtigen“ Modul importieren.

Drittens: Zeitdrift. Große Codebasen haben meist alte und neue Wege, dieselbe Aufgabe zu erledigen. Wenn Claude nur ältere Dateien sieht, kopiert es möglicherweise veraltete Muster (deprecierte Konfigurationsoptionen, Legacy-APIs), obwohl das Team weitergezogen ist.

Ein häufiges reales Beispiel: Du bittest um eine kleine Änderung an einer Billing-UI und Claude ändert eine gemeinsame payments-Komponente, die von anderen Apps genutzt wird, weil es den app-spezifischen Wrapper, der geändert werden sollte, nie gesehen hat.

Das Ziel ist nicht, Claude das ganze Monorepo zu zeigen. Ziel ist es, kleinere, bewusst gewählte Eingaben zu machen, die trotzdem die Frage beantworten: das Paket, das du änderst, seine direkten Abhängigkeiten und die ein oder zwei „Quellen der Wahrheit“ für Typen und Konfiguration. Nenne außerdem Bereiche, die nicht berührt werden dürfen (andere Apps, infra, generierter Code) und bestätige, welches Paket das Verhalten besitzt.

Fang damit an, die Aufgabe zu definieren, nicht das Repo

Die Genauigkeit hängt weniger davon ab, wie viel Code du einfügst, als davon, wie klar du den Auftrag beschreibst.

Beginne mit dem gewünschten Ergebnis: ein konkreter Fix, ein Refactor oder eine Antwort. Eine „Frage zum Code“ kann oberflächlich bleiben. Eine „Mach eine Änderung“-Anfrage braucht Grenzen, Eingaben und Erfolgskriterien.

Schreibe vor dem Teilen eine einzige Satz, der diesen Satz vervollständigt: „Nachdem du fertig bist, sollte ich in der Lage sein…“. Zum Beispiel: „die Unit-Tests für Paket X ohne Fehler auszuführen“ oder „das neue Feld in der API-Antwort für Endpoint Y zu sehen.“ Dieser Satz wird zum Nordstern, wenn das Repo riesig ist.

Bei Änderungen teile die kleinstmögliche Menge an Artefakten, die beweisen, dass die Änderung korrekt ist: die Entry-Point(s), die relevanten Typen/Interfaces oder Schema, ein fehlgeschlagener Test oder ein Repro-Schritt mit dem erwarteten Ergebnis und jede Konfiguration, die diesen Pfad beeinflusst (Routing, Feature Flags, Build- oder Lint-Regeln). Wenn es hilft, füge eine kurze Ordnerkarte des Pakets hinzu, damit Claude versteht, wofür jeder Ordner da ist.

Sei explizit darüber, was nicht betrachtet werden soll. Sag: „Ignoriere generierte Dateien, Vendor-Ordner, Build-Outputs, Snapshots und Lockfiles, wenn ich nicht darum bitte.“ Das verhindert Verschwendung und Änderungen an Stellen, die du nicht reviewen wirst.

Setze auch Erwartungen für Unsicherheit. Bitte Claude, Annahmen und Unbekanntes zu kennzeichnen, anstatt zu raten. Zum Beispiel: „Wenn du nicht sehen kannst, wo diese Funktion aufgerufen wird, sag das und schlage 2 Wege vor, sie zu finden."

Ziehe klare Grenzen, die Claude nicht überschreiten darf

In einem großen Monorepo sinkt die Genauigkeit, wenn das Modell anfängt, „hilfreich“ angrenzenden Code heranzuziehen, der nicht Teil der Aufgabe ist. Die Lösung ist einfach: definiere vor den Änderungen, was in Umfang ist und was nicht.

Beginne mit einer Grenze, die zur Organisation deines Repos passt: ein Paket, ein Service, eine App oder eine gemeinsame Bibliothek. Wenn die Änderung „Checkout UI aktualisieren“ lautet, ist die Grenze wahrscheinlich ein App-Paket, nicht jede Stelle, an der das Wort „checkout“ vorkommt.

Signale, die Claude helfen, sich zu beschränken, sind Ordnerkonventionen (apps/, services/, packages/, libs/), Paketmanifeste (Exports und Dependencies), öffentliche Einstiegspunkte (Index-Dateien, exportierte Komponenten, Handler) und Tests (sie zeigen oft die beabsichtigte Oberfläche). Ein README im Ordner kann der schnellste Boundary-Marker sein.

Grenzen funktionieren am besten, wenn du die Brücken zwischen ihnen nennst. Benenne die spezifischen Schnittstellen, die Claude berühren darf, und behandle alles andere als tabu. Typische Brücken sind HTTP-API-Verträge, Event-Themen und Payloads, geteilte Typen oder eine kleine Menge exportierter Funktionen.

Nenne außerdem „Do not touch“-Zonen, wann immer die Änderung sie nicht betreffen darf. Häufig sind das Infrastruktur- und Deployment-Konfigurationen, Security- und Auth-Logik, Billing und Payments, Daten-Migrationen und Produktionsschemata sowie Shared Libraries, die von vielen Teams genutzt werden.

Ein konkretes Prompt-Detail, das hilft:

„Ändere nur in packages/cart/ und dessen Tests. Du darfst geteilte Typen in packages/types/ lesen, aber nicht ändern. Bearbeite nicht infra, auth oder billing.“

Wie man nützliche lokale Zusammenfassungen schreibt

Die Genauigkeit steigt, wenn du eine kleine, stabile Karte des Bereichs lieferst, den du ändern willst. Eine „lokale Zusammenfassung“ ist diese Karte: kurz genug, um schnell zu lesen, spezifisch genug, um Vermutungen zu vermeiden.

Behalte jede Zusammenfassung bei etwa 10–20 Zeilen. Schreibe sie so, als würdest du den Code einem neuen Teammitglied übergeben, das nur diese Grenze anfassen muss, nicht das ganze Repo. Nutze klare Sprache und echte Namen aus dem Code: Ordner, Pakete, exportierte Funktionen.

Eine nützliche lokale Zusammenfassung beantwortet fünf Fragen:

• Wofür dieses Paket/Service gedacht ist und wofür nicht (Scope-Boundaries)
• Wo die Arbeit beginnt (Haupt-Entry-Points wie Schlüsseldateien, Routen, Commands oder Komponenten)
• Was von außen sicher aufrufbar ist (öffentliche APIs, exportierte Module, Events, Endpunkte)
• Wovon es abhängt (DBs, Queues, Caches, Config, externe Dienste)
• Welche Regeln hier wichtig sind (Benennungsmuster, Fehlerstil, Logging und wie Tests geschrieben werden)

Füge eine „Gotchas“-Zeile hinzu. Das ist der Ort, um teure Fehler zu verhindern: verstecktes Caching, Feature Flags, Migrationsschritte und alles, was still kaputt gehen kann.

Hier ist eine kompakte Vorlage, die du kopieren kannst:

Local summary: <package/service name>
Purpose: <1 sentence>
Scope: <what to touch> | Not: <what not to change>
Entry points: <files/routes/commands>
Public surface: <exports/endpoints/events>
Data sources: <tables/collections/queues/caches>
Conventions: errors=<how>, logging=<how>, tests=<where/how>
Gotchas: <flags/caching/migrations/edge cases>

Beispiel: Wenn du an einem Billing-Paket arbeitest, nenne die genaue Funktion, die Rechnungen erstellt, die Tabellennamen, in die geschrieben wird, und die Regel für retryable Errors. Dann kann Claude sich auf diese Grenze fokussieren anstatt in Shared Auth, Config oder nicht verwandte Pakete zu wandern.

Wo Zusammenfassungen liegen sollten und wie man sie aktuell hält

Die beste Zusammenfassung ist die, die Claude sieht, wenn es sie braucht. Leg sie neben den Code, den sie beschreibt, sodass sie schwer zu übersehen und leicht zu aktualisieren ist. Zum Beispiel: ein kurzes SUMMARY.md (oder ein Abschnitt in README.md) in jedem Paket, Service oder App-Verzeichnis statt eines einzigen riesigen Dokuments im Repo-Root.

Eine einfache, wiederholbare Struktur hilft. Halte sie kurz genug, damit Leute sie pflegen:

• Wofür dieser Ordner ist (Zweck in 1–2 Sätzen)
• Öffentliche Oberfläche (Haupt-Entry-Points, exportierte Module oder APIs)
• Wichtige Abhängigkeiten (intern und extern)
• Grenzen (was er nicht importieren oder ändern darf)
• Wie man testet (der schnellste lokale Check)
• Last updated: YYYY-MM-DD - <what changed in one sentence>

Zusammenfassungen veralten aus vorhersehbaren Gründen. Behandle Updates wie das Aktualisieren einer Typdefinition: Teil des Fertigstellens der Arbeit, nicht eine separate Aufgabe.

Aktualisiere die Zusammenfassung, wenn ein Refactor Struktur oder Namen ändert, ein neues Modul der Hauptweg wird, eine API/Event/Scheme sich ändert (auch wenn Tests noch bestehen), Grenzen zwischen Paketen sich verschieben oder eine Abhängigkeit entfernt/ersetzt wird.

Eine praktische Gewohnheit: Wenn du einen Change mergest, füge eine „Last updated“-Zeile hinzu, die kurz sagt, was geändert wurde. Tools wie Koder.ai können helfen, schneller an der Code-Änderung zu arbeiten, aber die Zusammenfassung ist das, was zukünftige Änderungen genau hält.

Ein schrittweiser Workflow, um im richtigen Kontext zu bleiben

Die Genauigkeit hängt oft davon ab, wie du das Gespräch taktest. Lass Claude Kontext in kleinen Stücke „verdienen“, statt aus einem riesigen Snapshot zu raten.

Schritt 1: Frage zuerst nach einer kurzen Karte

Bevor du änderst, bitte Claude zu beschreiben, was es sieht und was es noch braucht. Eine gute Karte ist kurz: die beteiligten Pakete, der Entry-Point für den Flow und wo Tests oder Typen liegen.

Prompt:

„Create a map of this change: packages involved, main flow, and likely touch points. Do not propose code yet."

Schritt 2: Beginne mit einem Slice und einer klaren Grenze

Wähle einen engen Slice: ein Feature, ein Paket, einen User-Flow. Nenne die Grenze klar (z. B.: „Ändere nur packages/billing-api. Berühre shared-ui oder infra nicht.“).

Ein Workflow, der die Kontrolle hält:

• Definiere Ziel und Grenze in einem Satz.
• Fordere Annahmen und Unbekanntes (Claude muss sie auflisten).
• Frag nach den genauen Dateien, die es als nächstes braucht (begrenzt auf 3–6).
• Gib nur diese Dateien und wiederhole den Prozess.
• Fordere einen kurzen Plan, bevor gepatcht wird.

Schritt 3: Erzwinge explizite Annahmen und Dateianfragen

Wenn Claude etwas fehlt, soll es das sagen. Bitte es zu schreiben: (1) die Annahmen, die es trifft, (2) was diese Annahmen falsifizieren würde, und (3) die nächsten Dateien, die benötigt werden, um das zu bestätigen.

Beispiel: Du musst ein Feld zur Invoice-Antwort in einem Paket hinzufügen. Claude fordert den Handler, die DTO/Typ-Definition und einen Test an. Du teilst nur diese. Wenn du einen chat-basierten Builder wie Koder.ai verwendest, gilt dieselbe Regel: gib die kleinste Menge an Quelldateien, erweitere nur, wenn es wirklich nötig ist.

Verwende Constraints und Contracts in deinen Prompts

Dein bester Schutz gegen falsche Änderungen ist ein kleiner „Vertrag“ im Prompt: was Claude anfassen darf, wie du Erfolg beurteilst und welche Regeln es befolgen muss.

Beginne mit einer Grenze, die leicht einzuhalten und zu verifizieren ist. Sei explizit, wo Änderungen erlaubt sind, und nenne „do not touch“-Zonen, damit keine Versuchung zum Abschweifen besteht.

Vertrags-Vorlage:

• Nur Dateien unter packages/payments/ ändern.
• Nicht packages/auth/, infra/ oder gemeinsame Konfigurationen ändern.
• Wenn Änderungen außerhalb des Umfangs nötig sind, stoppen und zuerst fragen.
• Änderungen minimal halten: Bug fixen, Refactors vermeiden.

Dann definiere Akzeptanzchecks. Ohne sie liefert Claude vielleicht Code, der oberflächlich richtig aussieht, aber gegen die Repo-Regeln verstößt.

• Führe Unit-Tests für das Paket aus (nenne den Befehl).
• Führe Lint/Format aus (nenne das Tool oder sag „use existing config").
• Führe Typecheck/Build für das Paket aus.
• Bestätige, dass die App noch startet (ein einfacher Run-Befehl reicht).

Style-Constraints sind ebenfalls wichtig. Sag Claude, welche Patterns zu verwenden sind und welche zu vermeiden, basierend auf dem, was dein Codebase bereits tut. Zum Beispiel: „Benutze vorhandene Error-Helper in diesem Paket; füge keine neuen Dependencies hinzu; bleibe bei camelCase für Funktionsnamen; führe keine neue Architektur-Schicht ein."

Fordere schließlich einen kurzen Änderungsplan, bevor gepatcht wird:

„Bevor du editierst, liste die 3–5 Dateien auf, die du erwartest zu ändern, und die genaue Verhaltensänderung. Warte auf Bestätigung."

Beispiel:

„Fix rounding in invoice totals. Only edit packages/billing/src/ and tests under packages/billing/test/. Acceptance: pnpm -C packages/billing test and typecheck. Follow existing money utils; do not rewrite API types. Provide a 4-step plan first."

Häufige Fallen, die Drift und falsche Änderungen verursachen

Der schnellste Weg, falsche Änderungen in einem Monorepo zu bekommen, ist, Claude zu viel auf einmal zu geben. Wenn du einen großen Codehaufen einfügst, greift es oft auf generische Muster zurück statt auf das spezifische Design deines Repos.

Eine weitere Falle ist, ihm die Architektur raten zu lassen. Wenn du keine echten Entry-Points zeigst, wählt es möglicherweise die erste Datei, die plausibel aussieht, und verankert dort Logik. In der Praxis kommt Genauigkeit von einer kleinen Menge „Sources of truth“ (Entry-Module, Router, Service-Registries, Paketboundary-Dokumente). Fehlen diese im Kontext, füllt das Modell die Lücken.

Namen können auch täuschen. Monorepos haben oft Pakete wie ui, ui-kit, shared-ui oder duplizierte Helfer wie date.ts an zwei Orten. Wenn du Schnipsel von beiden mischst, könnte Claude an der einen Datei patchen, während es über die andere nachdenkt. Beispiel: Du willst einen Button-Stil ändern, es editiert packages/ui/Button.tsx, aber die App importiert packages/ui-kit/Button.tsx. Der Diff sieht gut aus, aber in Produktion ändert sich nichts.

Konfiguration ist eine weitere Quelle stiller Drift. Verhalten kann von Env-Variablen, Feature Flags, Build-Settings oder Workspace-Tools abhängen. Wenn du das nicht erwähnst, entfernt Claude eventuell eine „seltsame“ Prüfung, die nur bei aktivem Flag relevant ist, oder fügt Code hinzu, der einen Build-Schritt bricht.

Warnsignale für Drift:

• Die Antwort spricht über „typische Muster“ ohne deine echten Dateien zu nennen
• Es führt ein neues Shared-Utility ein statt ein bestehendes zu nutzen
• Es ändert Importe über Paketgrenzen hinweg
• Es ignoriert Feature Flags oder env-spezifische Branches
• Es schlägt vor, eine Dependency zu einem Core-Sharing-Paket hinzuzufügen

Behandle Cross-Package-Imports als Entscheidung, nicht als Standard. Halte Änderungen lokal, es sei denn, du erweiterst bewusst den Umfang.

Schnelle Checkliste, bevor du Claude ansprichst

Der schnellste Weg zu korrekten Änderungen ist, mit Grenzen statt mit Volumen zu starten. Ein gutes Prompt ist etwas strikt: es sagt Claude, wo es suchen soll, was zu ignorieren ist und was „fertig“ bedeutet.

Bevor du Code einfügst, schreibe eine kurze Präambel, die die Arbeit an einem Ort im Repo verankert. Nenne das Paket, den genauen Ordner und das spezifische Ziel. Füge dann eine lokale Zusammenfassung (Zweck, Schlüsselabhängigkeiten, wichtige Konventionen) und die Entry-Datei bei, die die Änderung verankert.

Checkliste:

• Boundary: Arbeite nur in <>package</>/<path>. Ziel: <>one sentence>. Ignoriere alles andere, sofern nicht angefragt.
• Context starter: Lokale Zusammenfassung: <>5-10 lines>. Entry-Datei: <>path/to/file>.
• Constraints: Erlaubte Ordner: <>...>. Nicht ändern: <>folders/files or APIs>. Verhalten beibehalten: <>what must stay true>.
• File requests first: „Bevor du Änderungen vorschlägst, liste die minimalen Dateien (max 5) und warum.“
• Output format: „Antworte zuerst mit einem kurzen Plan. Nach meiner Bestätigung gib Patch-ähnliche Vorschläge pro Datei.“

Wenn Claude Änderungen außerhalb deiner Grenze vorschlägt, sieh das als Signal: entweder das Prompt straffen oder die Grenze bewusst erweitern und klar neu formulieren.

Beispiel: Eine Änderung in einem Paket durchführen, ohne das ganze Monorepo aufzuwecken

Angenommen, dein Monorepo hat apps/web-store (eine React-App) und packages/ui-kit (geteilte Buttons, Inputs und Styles). Du willst eine kleine Funktion: einen „Save for later“-Button auf der Cart-Seite hinzufügen, der ein neues SaveIcon aus ui-kit verwendet. Sonst soll nichts geändert werden.

Erstelle vor der Anfrage zwei lokale Zusammenfassungen, die als Grenzen fungieren. Halte sie kurz, spezifisch und meinungsstark darüber, was wichtig ist.

# apps/web-store/LOCAL_SUMMARY.md
Purpose: Customer shopping UI.
Entry points: src/routes.tsx, src/pages/cart/CartPage.tsx
Cart rules: cart state lives in src/cart/useCart.ts
Do not touch: checkout flow (src/pages/checkout), payments, auth.
Tests: npm test -w apps/web-store

# packages/ui-kit/LOCAL_SUMMARY.md
Purpose: shared UI components.
Exports: src/index.ts
Icons: src/icons/*, add new icons by exporting from index.
Do not touch: theming tokens, build config.
Tests: npm test -w packages/ui-kit

Dann halte die Schleife eng:

1. Map: „Diese Änderung ist auf CartPage und ui-kit icons begrenzt. Keine Checkout/Auth-Edits.“
2. Annahmen: fordere eine Liste der Annahmen an und warte auf Bestätigung.
3. Dateianfragen: genehmige nur die Dateien, die es wirklich braucht (CartPage, useCart, ui-kit icons, ui-kit index).
4. Plan: bestätige, dass er zu den Grenzen passt.
5. Änderungen: mache den kleinstmöglichen Diff und fordere dann aktualisierte Tests an.

Nach der Änderung dokumentiere sie so, dass zukünftiger Kontext klein bleibt:

• Aktualisiere beide lokalen Zusammenfassungen mit dem neuen Export und den genau getroffenen Dateien.
• Füge einen kurzen Kommentar-Header in der Cart-Seite hinzu: was der Button macht und wo der State gehandhabt wird.
• Notiere die Testbefehle, die bestanden wurden (und ggf. aktualisierte Snapshots).

Nächste Schritte: Mach das für dein Team wiederholbar

Wenn es bei einer Person gut funktioniert, aber nicht beim Rest des Teams, fehlt meist die Wiederholbarkeit. Mache „gute Kontext-Hygiene“ zur Vorgabe, nicht zur persönlichen Gewohnheit.

Mach eure besten Prompts zur Teamvorlage

Speichere ein Prompt-Skelett, das jeder kopieren und ausfüllen kann. Halte es kurz, aber strikt. Enthält das Ziel (was „done“ bedeutet), erlaubten Umfang, harte Grenzen (und warum), eine lokale Zusammenfassung und einen Output-Contract (erst Plan, dann Diff-ähnliche Änderungen und Tests).

Halte Zusammenfassungen mit einer leichten Kadenz aktuell

Vermeide große Monats-Reviews, die niemand macht. Hänge Summary-Updates an normale Arbeit: wenn eine Änderung Verhalten, Abhängigkeiten oder APIs ändert, aktualisiere die lokale Zusammenfassung in derselben PR.

Eine einfache Regel: Wenn ein Kollege fragen würde „wo lebt das?“ oder „was hängt davon ab?“, ist die Zusammenfassung veraltet.

Wenn du eine Chat-first-Workfow bevorzugst, kann Koder.ai helfen, diese Iterationsweise sicherer zu machen. Der Planning-Mode hilft, Scope und Grenzen vor Änderungen zu klären, und Snapshots mit Rollback erlauben es, Änderungen auszuprobieren, ohne in Sackgassen zu laufen.