Agenten-Coding in Mono-Repos: Ein Deep Dive in die Claude Code CLI - So gelingt der Einstieg

Agentenbasierte Werkzeuge zur Code-Erstellung sind mehr als nur Autocomplete-Funktionen; sie entwickeln sich zu vollwertigen Partnern im Entwicklungszyklus. 

Die Claude Code CLI von Anthropic demonstriert diesen Wandel eindrücklich, indem sie das volle Potenzial eines KI-Agenten (besonders im Kontext komplexer Mono-Repos) entfaltet. Dieser Artikel bietet einen Einstieg, die auf praktischer Erfahrung beruht und zeigt, wie das Werkzeug von einem Assistenten auf Dateiebene zu einem Architekten auf Systemebene wird. Wir beleuchten die Installation, den sicheren Betrieb im Unternehmenskontext und die gezielte Leistungssteuerung für die Generierung von qualitativ hochwertigem Code.

Kurz & Knapp

• Kontext-Vorteil: Nutzt die einheitliche Struktur von Mono-Repos, um systemweite Code-Anpassungen und Refactorings atomar und konsistent durchzuführen.
• Gezielte Denk-Leistung: Steuert die Planungsphase des Agenten mit Schlüsselwörtern wie think oder think harder, um die Code-Qualität auf Kosten einer höheren Latenz zu verbessern.
• Sicherheit im Fokus: Ermöglicht die präzise Steuerung von Dateizugriffen (.claudeignore) und Shell-Befehlsausführungen über lokale Konfigurationsdateien.
• Effizientes Onboarding: Beschleunigt die Einarbeitung in Projekte durch CLAUDE.md-Dateien, die dem Agenten als strukturierte Wissensbasis für die Codeanalyse dienen.
• Workflow-Integration: Lässt sich durch benutzerdefinierte Befehle und die Kombination mit Werkzeugen wie repomix tief in bestehende Entwicklungsprozesse integrieren.

Agentenbasiertes Coding mit der "Claude Code" CLI

Installation (npm oder brew (Mac OS))

npm install -g @anthropic-ai/claude-code

brew install --cask claude-code

Intellij: Claude Code 

VS Code: Claude Code Extension

Sicherheit und Qualitätskontrolle

Den Agent in die Schranken weisen

Eine wirksame Massnahme ist die Definition von erlaubten und verbotenen Bereichen im Dateisystem. Analog zu .gitignore oder .dockerignore kann eine .claudeignore-Datei verwendet werden, um dem Agenten explizit den Zugriff auf bestimmte Pfade zu verweigern.

# Zugriff auf alle Konfigurationsdateien blockieren
**/.env*
**/credentials.json

# Zugriff auf CI/CD-Pipelines blockieren
.github/
.gitlab-ci.yml

# Zugriff auf andere kritische Pakete im Mono-Repo blockieren
packages/billing-service/
packages/auth-infra/

Sandboxing und Werkzeugnutzung

Zusätzlich zu pfadbasierten Einschränkungen muss die Ausführung von Shell-Befehlen durch den Agenten kontrolliert werden. Der Agent sollte nicht die Fähigkeit haben, beliebige Befehle wie rm -rf auszuführen. Die Konfiguration muss eine Whitelist von erlaubten Werkzeugen und Befehlen definieren (z. B. git, npm, npx prisma, pytest). Fortgeschrittene Implementierungen können benutzerdefinierte Hooks bereitstellen, die zusätzliche Validierungen durchführen, bevor ein Befehl ausgeführt wird.

Konfiguration lokaler Berechtigungen

Erstelle die folgende Datei unter .claude/settings.local.json im Stammverzeichnis deines Projekts. Die Verwendung von .local.json stellt sicher, dass diese Einstellungen die Einstellungen auf Projektebene (settings.json) überschreiben und nicht in die Quellcodeverwaltung eingecheckt werden.

{
  "permissions": {
    "deny": [
      "WebFetch",
      "WebSearch",
      "Bash(curl:*)",
      "Bash(wget:*)",
      "Bash(git:pull*)",
      "Bash(git:fetch*)",
      "Bash(git:clone*)",
      "mcp__*__*",
      "Bash(*)"
    ]
  }
}

Wie es funktioniert

• "WebFetch" & "WebSearch": Deaktiviert die integrierten Werkzeuge für den Zugriff auf URLs oder die Durchführung von Websuchen.
• "Bash(curl:)" & "Bash(wget:)": Verhindert, dass der Agent die Befehle curl oder wget in der Shell verwendet, die gängige Methoden sind, um Daten zu exfiltrieren oder externe Skripte herunterzuladen.
• "Bash(git:pull)", "Bash(git:fetch)", "Bash(git:clone*)":** Blockiert Git-Befehle, die mit entfernten Repositories interagieren, und schränkt die Git-Nutzung effektiv auf das lokale Repository ein (z. B. wären git status, git diff, git commit weiterhin erlaubt).
• "mcp____": Deaktiviert alle MCP (Model Context Protocol)-Werkzeuge und verhindert Verbindungen zu externen Diensten wie Datenbanken oder APIs, die möglicherweise konfiguriert sind.

Kernbefehle

Starte die interaktive Sitzung, indem du claude in deinem Projektverzeichnis eingibst.

• /help
  Zeigt alle verfügbaren Befehle und ihre Beschreibungen an.
• /config
  Zeige oder ändere deine Konfigurationseinstellungen. Zum Beispiel, um das Thema festzulegen:

claude config set -g theme dark

• /login & /logout
  Verwalte deine Authentifizierung bei Anthropic.
• /clear
  Löscht den aktuellen Gesprächsverlauf.

Einen umfassenden Config Guide findest du hier.

Grundlegender Arbeitsablauf

Dein typischer Arbeitsablauf umfasst diese Schritte:

1. Sitzung starten: Navigiere zu deinem Projektordner und führe claude aus oder verwende Intellij.
2. Kontext hinzufügen: Du kannst eine CLAUDE.md-Datei im Stammverzeichnis deines Projekts erstellen, um persistente Anweisungen oder Kontext zu deinem Projekt bereitzustellen. Mit claude code:
   • Führe zuerst eine vollständige Analyse der aktuellen Projektstruktur durch. Identifiziere alle Hauptkomponenten, Dienste, Bibliotheken und ihre primären Verantwortlichkeiten.

   • Schritt 2: Erstelle die Stamm-CLAUDE.md mit einem Prompt. Du kannst folgendes Prompt nutzen/erweitern etc.. Auch CodeStyle und andere wichtige Projektdetails können hier erwähnt werden:

     Erstelle im Stammverzeichnis des Projekts eine CLAUDE.md-Datei. Diese Datei sollte der Master-Leitfaden sein und muss die folgenden Abschnitte unter Verwendung von Markdown enthalten:
     
     # Projektübersicht: Eine allgemeine Zusammenfassung des Projektzwecks.
     
     # Tech Stack: Eine Liste der primären Sprachen, Frameworks und Bibliotheken, die verwendet werden.
     
     # Architektur: Eine kurze Beschreibung der Kernarchitekturmuster (z. B. Mono-Repo, Microservices usw.).
     
     # Erste Schritte: Wichtige Befehle für die Einrichtung, Installation (npm install) und Ausführung des Projekts (npm run dev).
     
     # Teststrategie: Wie man Tests ausführt (npm test, mvn test).
     
     Schritt 3: Erstelle CLAUDE.md-Dateien in Unterverzeichnissen
     Als Nächstes durchlaufe jedes Unterverzeichnis in diesem Projekt. Erstelle in jedem eine neue CLAUDE.md-Datei mit Inhalt, der spezifisch für dieses Verzeichnis ist. Jede dieser Dateien sollte enthalten:
     
     # Verzeichniszweck: Eine einzeilige Beschreibung der Rolle dieses Verzeichnisses (z. B. "Enthält alle API-Routendefinitionen.").
     
     # Wichtige Dateien: Eine Aufzählungsliste der wichtigsten Dateien in diesem Verzeichnis und deren Zweck.
     
     # Abhängigkeiten: Notiere alle direkten Abhängigkeiten von anderen Verzeichnissen innerhalb dieses Projekts.
     
     Einschränkungen: ERSTELLE KEINE CLAUDE.md-Dateien in den folgenden Verzeichnissen: .git, node_modules, dist, build oder jedem anderen Verzeichnis, das mit einem Punkt (.) beginnt.
     
     Der Inhalt sollte prägnant, technisch und auf einen KI-Agenten ausgerichtet sein. 
     
     Bestätige den Plan, in welche Verzeichnisse du schreiben wirst, bevor du die Operationen zur Dateierstellung ausführst.

3. Verwende "Denk"-Schlüsselwörter: Füge bei komplexen Aufgaben Schlüsselwörter wie think oder think harder zu deinem Prompt hinzu, um Claude mehr Zeit für die Planung einer Lösung zu geben.

Diese Schlüsselwörter weisen Claude an, mehr Rechenressourcen (Tokens und Zeit) für die Planung aufzuwenden, bevor es mit der Generierung einer Antwort beginnt. Diese Vorberechnung umfasst das Zerlegen des Problems, die Bewertung verschiedener Ansätze und die Strukturierung der endgültigen Ausgabe.

Aufschlüsselung der Denk-Schlüsselwörter

Wichtige Erkenntnis: Der zentrale Kompromiss ist Qualität vs. Geschwindigkeit/Kosten. Das Ziel ist es, das niedrigstmögliche Schlüsselwort zu verwenden, das die gewünschte Qualität für deine Aufgabe erreicht. Beginne mit einem Standard-Prompt, und wenn der Ausgabe Weitsicht oder Struktur fehlt, füge think hinzu und eskaliere nur bei Bedarf. Die übermässige Verwendung von ultrathink für einfache Aufgaben wird deinen Arbeitsablauf unnötig verlangsamen.

Best Practices und fortgeschrittene Konzepte

Warum ein Mono-Repo agentenbasierte Werkzeuge maximiert

Ein Mono-Repo bietet einen einzigen, einheitlichen Kontext, der der primäre Kraftmultiplikator für ein agentenbasiertes Werkzeug ist. Es erhebt den Agenten von einem Assistenten auf Dateiebene zu einem Architekten auf Systemebene.

• Vollständiger Systemkontext: Der Agent sieht die gesamte Codebasis – Frontend, Backend und gemeinsam genutzte Bibliotheken. Er kann Abhängigkeiten nachverfolgen und die vollen Auswirkungen jeder Änderung verstehen, was die isolierten und unvollständigen Änderungen verhindert, die in Multi-Repo-Setups üblich sind.
• Atomares projektübergreifendes Refactoring: Ein einziger Prompt kann ein komplexes Refactoring über mehrere Pakete hinweg ausführen. Zum Beispiel: Aktualisiere das UserDTO in 'packages/types' und korrigiere alle verwendenden Stellen in 'apps/web' und 'services/api'. dieser Vorgang ist atomar und erhält die systemweite Konsistenz.
• Beschleunigte systemweite Analyse: Onboarding und Debugging werden schneller. Ein Dev kann den Agenten abfragen, um einen “request flow” vom Einstiegspunkt einer Web-App über den API-Service bis zum Datenbankschema zu verfolgen, da der Agent Zugriff auf den gesamten relevanten Code hat.

Ein praktischer Hinweis für SCS (Self-Contained Systems)-Teams: Erwäge die Erstellung von Mono-Repos für Gruppen von Systemen, die zwar unabhängig voneinander bereitstellbar sind, aber eine starke Geschäftsdomäne teilen oder sich häufig gemeinsam weiterentwickeln. Dies gibt dem Agenten den notwendigen Makro-Kontext für effektives, systemübergreifendes Refactoring.

Gezielte Aktivierung der „Thinking Capacity“

Standardmässig versuchen Agenten oft, eine Anfrage direkt in Code zu übersetzen. Bei komplexeren Aufgaben wie Refactoring führt dies zu suboptimalen Ergebnissen. Eine bewährte Methode ist die explizite Aktivierung der „Thinking Capacity“ des Agenten, oft über ein Flag wie --think.

THINK Refaktoriere die UserService-Klasse, um das Repository-Pattern zu verwenden. Trenne die Datenbanklogik von der Geschäftslogik.

Dieses Flag weist den Agenten an, zuerst einen detaillierten Plan zu erstellen (Chain of Thought oder Tree of Thoughts). Es legt die Schritte fest:

1. Definiere ein IRepository-Interface.
2. Implementiere eine UserRepository-Klasse.
3. Passe UserService an, um die Schnittstelle über DI zu verwenden.

Dieser Plan wird dem Entwickler zur Bestätigung vorgelegt, bevor der Code geschrieben wird. Dies erhöht die Qualität und reduziert die Anzahl der Iterationen, geht aber mit höheren Token-Kosten und erhöhter Latenz einher.

Gib Claude mehr Werkzeuge

Erweitere die Fähigkeiten von Claude, indem du es in deine bestehenden Skripte und Dienste integrierst.

• Bringe Claude deine Bash-Tools bei: Claude kann jedes Werkzeug in deiner Shell verwenden, aber du musst ihm sagen, dass es existiert. Dokumentiere deine benutzerdefinierten Skripte und ihre Verwendung in CLAUDE.md.
• Erstelle benutzerdefinierte Slash-Befehle: Speichere für sich wiederholende Aufgaben Prompt-Vorlagen als Markdown-Dateien im Ordner .claude/commands. Diese werden als benutzerdefinierte /-Befehle in der CLI angezeigt, sodass du komplexe Arbeitsabläufe schnell ausführen kannst.

Effektive Arbeitsabläufe anwenden (fortgeschritten)

Strukturiere deine Interaktion mit Claude, um bessere Ergebnisse zu erzielen, insbesondere bei komplexen Aufgaben.

• Erkunden, Planen, Coden, Committen: Bevor du Code schreibst, bitte Claude, die relevanten Dateien zu recherchieren und einen Plan zu erstellen. Verwende "Denk-Schlüsselwörter" (think, think hard, think harder, ultrathink), um Claude schrittweise mehr Zeit und Ressourcen für die Entwicklung eines robusten Plans zu geben.
• Verwende testgetriebene Entwicklung (TDD): Bitte Claude, zuerst fehlschlagende Tests zu schreiben. Sobald du mit den Tests zufrieden bist, weise es an, den Implementierungscode zu schreiben, damit sie erfolgreich sind.
• Onboarding mit Codebase Q&A: Wenn du einem neuen Projekt beitrittst, stelle Claude Fragen wie "Wie funktioniert das Logging?" oder "Wie erstelle ich einen neuen API-Endpunkt?". Es wird die Codebasis agentenbasiert durchsuchen, um Antworten zu finden, und so die Belastung für andere Ingenieure reduzieren.

Optimiere deine Interaktion

Optimiere deinen Prozess, um Claude effektiv zu führen.

• Sei spezifisch: Statt "füge Tests hinzu", frage "schreibe einen neuen Testfall für foo.java, der den Randfall abdeckt, bei dem der Benutzer abgemeldet ist. Vermeide Mocks.". Klare Anweisungen führen zu besseren Ergebnissen.
• Korrigiere frühzeitig und oft: Lass Claude nicht zu lange unbeaufsichtigt laufen.
  • Drücke Escape, um es jederzeit zu unterbrechen.
  • Drücke Escape zweimal, um einen vorherigen Prompt zu bearbeiten und eine andere Richtung auszuprobieren.
• Verwende den /clear-Befehl häufig zwischen verschiedenen Aufgaben, um das Kontextfenster zurückzusetzen und Claude fokussiert zu halten.
• Verwende Checklisten für grosse Aufgaben: Weise Claude bei komplexen Arbeitsabläufen wie Migrationen oder der Behebung von Hunderten von Lint-Fehlern an, zuerst eine Markdown-Checkliste zu erstellen und diese dann Punkt für Punkt abzuarbeiten.

Kontextmanagement für lange Sitzungen

In langen Codierungssitzungen kann sich das Kontextfenster des Agenten mit irrelevanter Historie füllen, was die Leistung beeinträchtigt und die Kosten erhöht. Verwende diese Befehle, um den Agenten fokussiert zu halten.

• /clear (Hard Reset)
  Dieser Befehl löscht den gesamten Gesprächsverlauf und den Dateikontext. Es ist, als würde man eine brandneue Terminalsitzung starten.
  Anwendungsfall: Verwende /clear, wenn du komplett zu einer neuen, nicht zusammenhängenden Aufgabe wechselst und das vorherige Gespräch nicht mehr relevant ist.
• /compact (Intelligente Zusammenfassung)
  Dieser Befehl fasst das Gespräch intelligent zusammen, verwirft Zwischenschritte und "Sackgassen", während die wesentlichen Einstellungen, Ziele und Schlüsselentscheidungen erhalten bleiben. Er behält den übergeordneten Kontext ohne das Rauschen bei.
  Anwendungsfall: Verwende /compact, wenn eine einzelne Aufgabe sehr lang geworden ist und du das Gefühl hast, dass der Agent von frühen, jetzt irrelevanten Details abgelenkt wird. Es ist perfekt, um den Agenten mitten in einem komplexen Problem neu zu fokussieren.

Das Kontextfenster verstehen und verwalten mit /context

Der /context-Befehl ist dein wichtigstes Diagnosewerkzeug. Er fungiert wie ein Task-Manager für den "Arbeitsspeicher" der KI und zeigt dir, wie das Kontextfenster – dein Budget an Tokens – aktuell genutzt wird.

Was die Anzeige bedeutet

• Gesamtkapazität: Dein maximales Token-Budget (z.B. 200k). Je grösser, desto mehr Informationen kann die KI gleichzeitig verarbeiten.
• System-Overhead (System prompt & System tools): Die "Fixkosten" für die Grundanweisungen und Werkzeuge der KI. Dieser Teil ist immer belegt.
• Konversation (Messages): Der wachsende Verlauf deiner Anfragen und der KI-Antworten.
• Freier Speicher (Free space): Dein verfügbarer Arbeitsbereich für Code, Dateien und neue Anweisungen.

Führe /context vor grossen Aufgaben (z.B. Refactoring einer ganzen Klasse) aus, um sicherzustellen, dass du genügend freien Speicher für den Code und die Anweisungen hast. Das aktive Management des Kontextes ist entscheidend für die Performance und die Qualität der Ergebnisse.

• /clear: Nutze diesen Befehl, wenn du zu einer komplett neuen Aufgabe wechselst. Dies verhindert, dass alter Kontext die neuen Ergebnisse beeinflusst.
• /compact: Setze diesen Befehl bei langen, andauernden Aufgaben ein, um den bisherigen Verlauf intelligent zu kürzen und den Fokus der KI zu schärfen.

Ein fast volles Kontextfenster kann die Antwortzeiten der KI verlängern. Regelmässiges Aufräumen mit /compact oder /clear hält den Agenten reaktionsschnell.

Erklärungen erhalten, wenn du verwirrt bist

Behandle Claude Code wie einen erfahrenen Pair-Programmierer, der immer verfügbar ist. Gib ihm nicht nur Befehle; stelle Fragen, um dein Verständnis zu klären und deinen Arbeitsablauf zu beschleunigen.

Wann du nach Erklärungen fragen solltest

• Codebase Onboarding: Wenn du auf eine neue Datei oder eine komplexe Funktion stösst.
  • "Erkläre den Zweck der ExecutionFactory-Klasse in diesem Projekt."
• Verständnis von spezifischem Code: Für komplexe Syntax oder Logik, die du nicht sofort verstehst.
  • "Erkläre diesen Regex-Block in Zeile 42 von validator.js."
• Fehlerbehebung: Wenn du eine Fehlermeldung erhältst, die du nicht verstehst.
  • "Ich erhalte einen TypeError: cannot read properties of undefined nach meiner letzten Änderung. Was bedeutet dieser Fehler und wo sollte ich zuerst suchen?"

Best Practice: Für die genauesten Erklärungen, gib immer Kontext. Erwähne die spezifische Datei (@path/to/specific/file) und Zeilennummer oder füge den Codeausschnitt, über den du verwirrt bist, direkt in den Prompt ein.

Fortgeschritten

• Führe parallele Claude-Code-Sitzungen mit Git-Worktrees aus: https://docs.claude.com/en/docs/claude-code/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees

Hilfreiche Links/Videos

• Claude Code Best Practices
• Claude Code Usage Monitor
• Claude Code Config Guide

repomix + Claude Code

repomix konsolidiert dein gesamtes Repository in einer einzigen Textdatei. Mit Claude Code verwendest du es, um eine Sitzung sofort mit dem vollen Projektkontext zu starten und so die langsame dateiweise Erkundung zu umgehen.

Es ist ideal für einen "Kaltstart" bei einem neuen Projekt, Architekturbewertungen oder Headless-Scripting.

Arbeitsablauf

1. Installieren

   npm install -g repomix
   repomix

2. Mit claude verwenden

   Interaktiver Start (für die anfängliche Planung):

   (claude) > Unter Verwendung von `project-context.txt` als vollständigen Projektschnappschuss, erstelle eine Dokumentation für ......
   

   Headless-Analyse (für einmalige Aufgaben):

   repomix | claude -p "Überprüfe diese gesamte Codebasis auf Sicherheitslücken und liste sie auf."
   

Verwende repomix für:

• Den allerersten Prompt in einer neuen Sitzung, um den vollen Kontext bereitzustellen.
• Dokumentation
• Übergeordnete Architekturbewertungen.
• Einmalige Analyse-Skripte im Headless-Modus.
• Die Erstellung einer "Wissensdatenbank" für einen spezialisierten, schreibgeschützten Sub-Agenten.

Wichtiger Vorbehalt

Die Ausgabe von repomix ist ein statischer Schnappschuss. In dem Moment, in dem Claude Code eine Datei bearbeitet, wird der Kontext in project-context.txt veraltet. Verwende es für den ersten Prompt und lass den Agenten dann mit dem Live-Dateisystem arbeiten.