Claude Code Microservices: Verteilte Systeme entwerfen und implementieren mit KI

Microservices-Architekturen versprechen Skalierbarkeit, unabhängige Deployments und technologische Freiheit pro Service. Was sie tatsächlich liefern, hängt davon ab, ob die hundert kleinen Entscheidungen — Service-Grenzen, Kommunikationsprotokolle, Discovery-Mechanismen, Observability — zusammen sinnvoll sind. Falsch geschnittene Services sind teurer als ein gut gewärteter Monolith.

Claude Code kann bei Microservices mehr leisten als bei einem einzelnen Service, weil der Kontext, den es gleichzeitig sieht, genau das ist, was bei verteilten Systemen fehlt: der Überblick über das Ganze. Dieser Artikel zeigt, wie Claude Code in jedem Schritt eingesetzt wird — von der Architekturentscheidung über Service-Kommunikation bis zum Kubernetes-Deployment.

1. Microservices-Architektur vs. Monolith

Die Entscheidung für Microservices ist keine technische — sie ist eine organisatorische. Services sollten an Team-Grenzen geschnitten werden, nicht an technischen Schichten. Ein Auth-Service, ein Order-Service, ein Notification-Service: das macht Sinn, wenn drei Teams unabhängig entwickeln und deployen. Drei Teams, die alle in einen "User-Service" schreiben, der alles mit Benutzern macht, erzeugt nur einen verteilten Monolithen.

Claude Code hilft bei dieser Entscheidung nicht durch eine Formel, sondern durch gezieltes Hinterfragen. Ein praktischer Einstieg:

claude "Ich habe eine monolithische Django-Anwendung mit folgenden Modulen:
users, orders, products, payments, notifications, inventory.
Unsere zwei Teams arbeiten aktuell an orders+payments und products+inventory.
Analysiere, welche Services sinnvoll wären und welche zu early wären."

Claude Code liest dabei die bestehende Codebase, analysiert die tatsächlichen Abhängigkeiten zwischen den Modulen (welche importieren was, welche Datenbank-Tabellen werden geteilt, welche Events werden ausgetäuscht) und gibt eine fundierte Empfehlung: nicht was theoretisch sauber wäre, sondern was angesichts der realen Kopplungen und Team-Struktur Sinn ergibt.

Die drei Anti-Pattern bei Microservices

Claude Code erkennt diese Muster zuverlässig, wenn du deine Architektur beschreibst:

• Nano-Services: Jede Funktion ein Service. Overhead durch Netzwerk-Calls übersteigt jeden Vorteil. Faustregel: ein Service muss eigenständig deployt werden können, ohne dass andere Services neu gestartet werden müssen.
• Shared Database: Mehrere Services teilen eine Datenbank-Tabelle. Das ist ein Monolith mit Netzwerk-Latenz. Jeder Service muss seine eigene Datenbank oder Schema besitzen.
• Synchrone Ketten: Service A ruft B auf, B ruft C auf, C ruft D auf — synchron. Ein Timeout in D bricht die gesamte Kette. Lange synchrone Ketten sind ein Zeichen, dass die Service-Grenzen falsch gesetzt sind.

Migration vom Monolith: der Strangler-Fig-Ansatz

Den Monolithen in einem Schritt umzuschreiben scheitert fast immer. Der Strangler-Fig-Ansatz extrahiert einen Service nach dem anderen, während der Monolith noch läuft. Claude Code unterstützt diesen Prozess konkret:

claude "Ich möchte den Notification-Teil aus meinem Django-Monolithen
extrahieren. Zeige alle Stellen im Code, die Notifications auslösen,
alle Notification-Models und alle externen Dependencies (SMTP, Twilio etc.).
Erstelle dann einen Migrationsplan in 3 Schritten."

Das Ergebnis ist ein konkreter Plan: welche Dateien angepasst werden müssen, welche Daten migriert werden, wie der Traffic-Cutover aussieht und was rückrollbar ist, wenn etwas schiefgeht.

2. Service-Kommunikation: REST vs. gRPC vs. Message Queue

Das ist die Entscheidung, die am häufigsten falsch getroffen wird — nicht weil die Optionen unklar sind, sondern weil der Kontext unklar ist. Welche Anforderung hat der konkrete Use Case? Antwort-Zeit, Durchsatz, Fehlertoleranz, Konsistenz?

Eine einfache Heuristik, die Claude Code beim Design bestätigt oder hinterfragt:

• REST/HTTP: Wenn die Antwort des aufgerufenen Service direkt für die Antwort an den Client benötigt wird (synchrone Abhängigkeit, einfaches Request-Response-Muster, öffentliche oder externe APIs).
• gRPC: Wenn Latenz und Durchsatz zwischen internen Services kritisch sind, stark typisierte Kontrakte wichtig sind oder Streaming benötigt wird (bidirektional oder server-side).
• Message Queue (Kafka, RabbitMQ, NATS): Wenn die Verarbeitung asynchron sein kann oder muss — Events, Notifications, schwere Hintergrundverarbeitung, Fan-out an mehrere Empfänger.

gRPC-Service mit Claude Code implementieren

gRPC-Implementierungen sind repetitiv und fehleranfällig, wenn man sie von Hand schreibt: Proto-Datei definieren, Code generieren, Server implementieren, Client implementieren, Error-Handling. Claude Code macht daraus eine einzige Konversation:

claude "Erstelle einen gRPC-UserService in Go mit folgenden Methoden:
- GetUser(id string) -> User
- ListUsers(filter UserFilter) -> stream User
- CreateUser(UserInput) -> User

Inkl. Proto-Datei, Server-Implementierung mit PostgreSQL-Backend,
Client-Wrapper mit Retry-Logik und Timeout, und Unit-Tests."

Claude Code generiert die vollständige Proto-Datei, den generierten Go-Code, die Server-Implementierung mit Datenbankzugriff, einen Client-Wrapper der Retries und Context-Timeouts korrekt handhabt, und Tests die sowohl den Happy Path als auch Fehlerfälle abdecken. Was ohne Claude Code einen halben Tag benötigt, ist in 20 Minuten produktionsreif.

Event-Driven mit Kafka

Message Queues führen neue Komplexität ein: Idempotenz, At-Least-Once-Delivery, Dead Letter Queues, Consumer Groups. Claude Code kennt diese Fallstricke und implementiert sie korrekt:

claude "Implementiere einen Kafka-Consumer für Order-Events in TypeScript.
- Topics: order.created, order.updated, order.cancelled
- Jedes Event soll idempotent verarbeitbar sein (order_id als Key)
- Fehler landen in einer Dead Letter Queue
- Consumer soll graceful shutdown können"

Protokoll-Vergleich direkt anfragen

Wenn du unsicher bist, welches Protokoll passt, frage direkt:

claude "Mein Order-Service muss den Inventory-Service informieren wenn
eine Bestellung aufgegeben wird. Der Inventory-Service soll den Bestand
reduzieren. Brauche ich REST, gRPC oder eine Message Queue?
Erkläre die Trade-offs für meinen konkreten Fall."

Claude Code analysiert den Use Case und gibt eine Empfehlung mit Begründung — und zeigt dabei auch, was passiert wenn die erste Wahl unter Last versagt.

3. Service Discovery und Load Balancing

In einer Microservices-Architektur mit mehr als drei Services wird die Frage, wo ein Service zu finden ist, komplex. IP-Adressen ändern sich bei Deployments. Instanzen werden hochgefahren und beendet. Service Discovery löst das Problem, dass Services einander finden müssen, ohne hardcodierte Adressen.

Es gibt zwei grundlegende Ansätze:

• Client-Side Discovery: Der Client fragt eine Service Registry (z.B. Consul, Eureka) und wählt selbst eine Instanz aus. Mehr Kontrolle, mehr Komplexität im Client.
• Server-Side Discovery: Ein Load Balancer (z.B. Nginx, AWS ALB, Kubernetes Service) übernimmt die Auswahl. Der Client spricht nur den Load Balancer an. Einfacher für den Client, Infrastruktur-Abhängigkeit.

In Kubernetes-Umgebungen ist Server-Side Discovery der Standard und meistens die richtige Wahl. Claude Code hilft dabei, die Kubernetes-Service-Konfiguration korrekt aufzusetzen:

claude "Erstelle Kubernetes-Service-Definitionen für meine drei Services:
- user-service (Port 8080, 3 Replicas)
- order-service (Port 8081, 2 Replicas, braucht user-service)
- notification-service (Port 8082, 1 Replica, nur intern)

Inkl. ClusterIP vs LoadBalancer-Entscheidung und Health Check-Konfiguration."

Health Checks richtig implementieren

Load Balancer können nur dann intelligent verteilen, wenn sie wissen, welche Instanzen gesund sind. Kubernetes unterscheidet zwischen Liveness Probe (läuft der Prozess noch?) und Readiness Probe (kann der Service Traffic annehmen?). Der Unterschied ist wichtig:

claude "Implementiere Health Check-Endpoints für meinen FastAPI-Service.
- /health/live: Nur prüfen ob der Prozess läuft
- /health/ready: Datenbankverbindung, Redis-Verbindung, externe APIs prüfen
Erkläre den Unterschied für die Kubernetes-Konfiguration."

Claude Code implementiert beide Endpoints korrekt und erklärt, warum ein Liveness-Probe der auf die Datenbank prüft gefährlich ist: wenn die Datenbank kurz nicht erreichbar ist, würde Kubernetes den Pod neu starten — obwohl der Pod selbst gesund ist. Das verstärkt den Ausfall statt ihn zu dämpfen.

Circuit Breaker Pattern

Wenn ein abhängiger Service ausfällt, soll der aufrufende Service nicht warten bis zum Timeout. Der Circuit Breaker unterbricht den Aufruf frühzeitig und gibt schnell eine Fehlerantwort zurück:

claude "Implementiere einen Circuit Breaker für HTTP-Aufrufe in meinem
Go-Service. Nach 5 Fehlern in 10 Sekunden soll der Circuit öffnen
und für 30 Sekunden keine Anfragen durchlassen. Danach halb-offen
testen mit einem Probe-Request."

Claude Code implementiert den Zustandsautomaten (Closed → Open → Half-Open) korrekt und zeigt dabei auch, wie der Circuit-Status für Monitoring exportiert wird — weil ein Circuit Breaker den man nicht sieht keinen Mehrwert hat.

4. API Gateway Pattern implementieren

Ein API Gateway ist der einzige Eintrittspunkt für externe Clients. Statt dass ein Mobile-Client direkt den User-Service, den Order-Service und den Product-Service anspricht, spricht er das Gateway an — das die Aufrufe aufteilt, aggregiert, authentifiziert und rate-limitet. Das Gateway ist die Stelle, wo Cross-Cutting-Concerns einmal implementiert werden statt in jedem Service.

Was ein API Gateway typischerweise übernimmt:

• Authentifizierung und Autorisierung (JWT-Validierung, OAuth2)
• Rate Limiting (pro Client, pro Endpoint)
• Request-Logging und Distributed Tracing
• Response-Caching
• Request/Response-Transformation
• Routing zu den richtigen Backend-Services

Kong-Gateway mit Claude Code konfigurieren

claude "Konfiguriere Kong API Gateway für meine drei Services.
Routes:
- /api/users/* -> user-service:8080
- /api/orders/* -> order-service:8081 (nur authenticated)
- /api/products/* -> product-service:8082 (public, gecacht 60s)

Plugins:
- JWT-Auth für /api/orders/*
- Rate Limiting: 100 req/min pro IP global
- Prometheus-Metrics auf /metrics

Erstelle die Kong-declarative-Konfiguration (deck format)."

Claude Code erzeugt die vollständige YAML-Konfiguration für den declarativen Kong-Betrieb inklusive der Plugin-Konfigurationen. Kein manuelles API-Klicken in einer Admin-UI — alles als Code, versionierbar in Git.

Eigenes Gateway mit Fastify implementieren

Für kleinere Setups oder spezielle Anforderungen ist ein eigenes leichtgewichtiges Gateway manchmal sinnvoller als Kong oder AWS API Gateway:

claude "Implementiere ein API Gateway in TypeScript mit Fastify.
Anforderungen:
- JWT-Validierung (RS256, public key aus JWKS-Endpoint)
- Rate Limiting mit Redis-Backend (sliding window)
- Proxy zu Backend-Services mit Timeout und Retry
- Request-ID generieren und als Header weiterleiten
- Health-Check-Endpoint /health"

BFF-Pattern: Backend for Frontend

Ein häufig unterschätztes Pattern: statt einem generischen Gateway ein spezialisiertes Backend pro Frontend-Typ. Das Mobile-BFF gibt andere Datenstrukturen zurück als das Web-BFF, weil die Anforderungen unterschiedlich sind. Claude Code unterstützt dabei die Implementierung:

claude "Ich habe eine Mobile App und eine Web-App. Beide brauchen
Userdaten, aber die Mobile App braucht deutlich weniger Felder.
Implementiere zwei BFF-Endpoints die denselben User-Service aufrufen
aber unterschiedliche Response-Shapes liefern."

5. Distributed Tracing und Monitoring

Das größte Debugging-Problem in Microservices: ein Request geht durch sechs Services, einer davon ist langsam — aber welcher? Ohne Distributed Tracing ist die Antwort ein Ratespiel zwischen sechs Teams. Distributed Tracing macht den Pfad eines Requests durch das System sichtbar.

Der Standard für Distributed Tracing ist OpenTelemetry (OTel) — ein vendor-neutrales Framework das in alle gängigen Observability-Backends exportieren kann: Jaeger, Zipkin, Grafana Tempo, AWS X-Ray, Datadog.

OpenTelemetry in einen Node.js-Service einbauen

claude "Instrumentiere meinen Express.js-Service mit OpenTelemetry.
- Alle HTTP-Requests sollen automatisch getracet werden
- Datenbankaufrufe (PostgreSQL mit pg-Bibliothek) sollen als Spans erscheinen
- Eigene Business-Logic-Spans für calculateDiscount() und validateOrder()
- Export zu Jaeger via OTLP
- Trace Context soll in ausgehenden HTTP-Requests weitergegeben werden"

Claude Code implementiert die OTel-Initialisierung, konfiguriert die automatischen Instrumentierungen für Express und pg, zeigt wie manuelle Spans für Business-Logic-Funktionen erstellt werden, und löst das Context-Propagation-Problem: der Trace-Context muss in jedem ausgehenden HTTP-Request als Header mitgegeben werden, sonst bricht die Trace-Kette zwischen Services ab.

Strukturiertes Logging mit Korrelations-IDs

Tracing allein reicht nicht. Logs müssen mit Trace-IDs korreliert sein, damit man von einem Trace direkt in die relevanten Logs springen kann:

claude "Konfiguriere strukturiertes JSON-Logging mit pino in meinem
Node.js-Service. Jeder Log-Eintrag soll automatisch die aktuelle
TraceId und SpanId aus dem OpenTelemetry-Kontext enthalten.
Das Log-Level soll über Umgebungsvariable konfigurierbar sein."

SLI, SLO und Alerting

Monitoring ohne Alerting ist sinnlos. Alerting ohne SLOs ist Lärm. Claude Code hilft dabei, die richtigen Metriken zu definieren und sinnvolle Alerts zu konfigurieren:

claude "Definiere SLIs und SLOs für meinen Order-Service:
- Availability: wie messe ich sie?
- Latency: P50, P95, P99 — welche Schwellenwerte sind realistisch?
- Error Rate: welche Fehler zählen, welche nicht?

Erstelle dann Prometheus-Recording-Rules und Alertmanager-Alerts
die bei SLO-Verletzung pagen — nicht bei jedem einzelnen Fehler."

Distributed Tracing-Probleme debuggen

Wenn ein Trace zeigt, dass ein Request 800ms dauert, aber du nicht weisst wo die Zeit verloren geht:

claude "Mein Jaeger-Trace zeigt 800ms Gesamtdauer für einen Order-Request.
Ich sehe folgende Spans:
- gateway: 5ms
- order-service: 790ms
  - db.query (getUser): 2ms
  - http.call (inventory-service): 785ms
    - inventory-service: 10ms

Was ist das Problem und wie behebe ich es?"

Claude Code erkennt sofort: 785ms warten auf einen Service der nur 10ms braucht bedeutet 775ms Netzwerk- oder Verbindungs-Overhead. Das deutet auf Connection Pool Exhaustion, DNS-Resolution-Probleme oder fehlende Keep-Alive-Verbindungen hin. Klare Diagnose, klare Lösung.

6. Deployment mit Kubernetes und Helm

Kubernetes ist der De-facto-Standard für Microservices-Deployment. Helm ist der Paketmanager dafür. Zusammen lösen sie das Problem, dass dieselbe Anwendung in verschiedenen Umgebungen (dev, staging, production) mit unterschiedlichen Konfigurationen deployt werden muss — ohne dass für jede Umgebung eine separate YAML-Sammlung gepflegt wird.

Das Hauptproblem bei Kubernetes-YAML: es ist viel, repetitiv, und ein kleiner Tippfehler führt zu schwer debugbaren Fehlern. Claude Code generiert korrektes Kubernetes-YAML und erklärt dabei die Entscheidungen.

Vollständiges Deployment für einen Microservice

claude "Erstelle vollständige Kubernetes-Manifeste für meinen order-service:
- Deployment: 3 Replicas, Rolling Update, Resource Limits/Requests
- Service: ClusterIP
- HorizontalPodAutoscaler: 2-10 Replicas, CPU-Target 70%
- ConfigMap für non-secret Konfiguration
- Secret-Referenz für DATABASE_URL (aus externem Secret-Manager)
- PodDisruptionBudget: mindestens 2 Pods verfügbar
- Liveness und Readiness Probes"

Claude Code generiert alle sechs YAML-Manifeste korrekt, wählt sinnvolle Resource-Requests und Limits (nicht 0, nicht unbegrenzt), konfiguriert Rolling Updates so dass immer mindestens eine Instanz verfügbar ist, und zeigt wie Secrets aus externen Secret-Managern (AWS Secrets Manager, HashiCorp Vault) injiziert werden ohne sie direkt in Kubernetes-Secrets zu speichern.

Helm Chart erstellen

claude "Erstelle ein Helm Chart für meinen Microservice-Stack
mit user-service, order-service und notification-service.

values.yaml soll konfigurierbar machen:
- Image-Tag pro Service
- Replica-Anzahl pro Service
- Ingress-Konfiguration (Hostname)
- Resource-Limits
- Feature Flags als Umgebungsvariablen

Erstelle separate values-dev.yaml und values-prod.yaml."

Das Ergebnis ist ein vollständiges Helm Chart mit Templates für alle drei Services, einer durchdachten values.yaml Hierarchie und den umgebungsspezifischen Override-Dateien. Dev hat kleinere Limits und einen Ingress auf dev.example.com, Prod hat mehr Replicas, höhere Limits und Production-Ingress mit TLS.

GitOps mit ArgoCD

Helm allein löst das Deployment-Problem. GitOps löst das Problem, dass Cluster-State und Git-State auseinanderlaufen:

claude "Konfiguriere ArgoCD für mein Helm-basiertes Deployment.
- Dev-Umgebung: Auto-Sync nach jedem Push auf main
- Prod-Umgebung: Manual-Sync, Sync nur nach Approval
- Notifications: Slack bei Failed Sync
- Application-Set für alle drei Services aus einem gemeinsamen
  Helm-Chart-Repository"

Zero-Downtime Deployments sicherstellen

Der häufigste Fehler bei Kubernetes-Deployments: die Rolling-Update-Strategie ist konfiguriert, aber die Pods werden zu schnell beendet bevor neue ready sind. Das Ergebnis ist kurze Downtime beim Deployment:

claude "Mein order-service hat kurze Downtime bei Deployments trotz
Rolling Update. Ich habe 3 Replicas, maxUnavailable=1, maxSurge=1.
Was könnte das Problem sein? Prüfe meine Deployment-Konfiguration
und die Readiness-Probe-Timing."

Claude Code identifiziert in 95% der Fälle eines von drei Problemen: die Readiness-Probe-initialDelaySeconds ist zu kurz (der alte Pod wird beendet bevor der neue wirklich ready ist), es fehlt ein preStop-Hook der dem Pod Zeit gibt, laufende Requests abzuschliessen, oder der Load Balancer hält Verbindungen noch offen zum alten Pod während Kubernetes ihn schon beendet hat.

Microservice-Deployment-Checkliste

Bevor ein Microservice in Production geht, sollte Claude Code folgende Punkte prüfen:

claude "Review meine Kubernetes-Konfiguration für production-readiness:
[Konfiguration einfügen]

Prüfe:
1. Resource Requests und Limits gesetzt?
2. Liveness und Readiness Probes konfiguriert?
3. PodDisruptionBudget vorhanden?
4. HPA konfiguriert?
5. Security Context: non-root user, read-only filesystem?
6. Network Policies: minimal required traffic?
7. Secrets korrekt injiziert, nicht als Env-Vars hardcoded?"

Das ist der Unterschied zwischen einem Service der bei der ersten Last-Spitze zusammenbricht und einem der in Production stabil läuft: nicht mehr Code, sondern die richtigen Konfigurationen an den richtigen Stellen. Claude Code kennt die Liste und prüft sie systematisch.

Zwei verwandte Artikel, die auf diesem Thema aufbauen:

• Claude Code Debugging — Stack Traces, Logs und Race Conditions in Minuten analysieren
• Claude Code für Unternehmen — Deployment, Zugriffskontrolle und Team-Workflows auf Unternehmensebene