Claude Code Masterkurs – KI-gestuetztes Programmieren lernen mit Anthropics Coding-Agent

Agent Orchestration

Level 3 | 45 Minuten

Koordiniere mehrere spezialisierte Agents für komplexe Aufgaben

Lernziele

Was ist Agent Orchestration?

Agent Orchestration bedeutet, mehrere spezialisierte KI-Agents koordiniert zusammenarbeiten zu lassen — wie ein Dirigent der ein Orchester leitet. Statt alles in einer einzelnen Session sequentiell abzuarbeiten, verteilst du Aufgaben auf spezialisierte Agents die parallel oder in einer Pipeline arbeiten. Stell dir ein großes Feature-Projekt vor: Du brauchst Datenbankänderungen, Backend-API, Frontend-Komponenten, Tests und Dokumentation. In einer normalen Session würdest du alles nacheinander machen — und gegen Ende hätte Claude den Anfang schon halb vergessen weil das Context Window voll ist. Mit Orchestration stattdessen: Ein Planungs-Agent analysiert die Anforderungen. Ein Database-Agent erstellt das Schema und die Migrationen. Ein Backend-Agent baut die API. Ein Frontend-Agent erstellt die UI. Ein Testing-Agent schreibt die Tests. Jeder Agent hat sein eigenes Context Window und ist auf seinen Bereich spezialisiert. Der Koordinator (deine Hauptsession) hält alles zusammen. Das Ergebnis: Schnellere Ausführung (parallel statt sequentiell), bessere Qualität (jeder Agent hat vollen Kontext für sein Gebiet), geringere Kosten (Exploration mit günstigem Haiku, Implementation mit Sonnet), und sauberer Hauptkontext (nur die Ergebnisse kommen zurück, nicht die Details). Claude Code unterstützt Orchestration auf mehreren Ebenen: Das Task-Tool spawnt Subagents für einzelne Aufgaben. Custom Agents definieren spezialisierte Rollen. Agent Teams koordinieren mehrere unabhängige Sessions. Und der Headless Mode ermöglicht programmatische Orchestration in Skripten. Orchestration ist kein Feature das du für jede Aufgabe brauchst. Für einen einzelnen Bug-Fix ist es Overkill. Aber für alles was mehrere Schritte, mehrere Dateien oder mehrere Fachgebiete umfasst, ist es ein Game-Changer.

💡 Kernkonzept Jeder Subagent hat: • Eigenes isoliertes Context Window (teilt NICHT den Verlauf) • Eigene Tool-Berechtigungen (konfigurierbar) • Eigenen Fokus-Bereich (spezialisiert) • Gibt nur ein kompaktes Ergebnis zurück (nicht die volle Konversation)

Das Task-Tool

Das Task-Tool ist die Schnittstelle über die Claude Code Subagents spawnt und koordiniert. Es ist das technische Fundament der Agent-Orchestrierung — der Mechanismus der hinter den Kulissen arbeitet wenn Claude einen Subagent startet. Wenn Claude entscheidet dass eine Aufgabe von Isolation profitieren würde, nutzt es intern das Task-Tool. Du kannst es auch explizit triggern, indem du Claude aufforderst Subagents einzusetzen. In Slash Commands und Skills hast du sogar direkten Zugriff auf die Task-Konfiguration. Das Task-Tool arbeitet in vier Schritten: Erstens spawnt es einen neuen Subagent mit eigenem Context Window. Zweitens übergibt es die Aufgabenbeschreibung und optional Konfiguration (Modell, Tools, Dateien). Drittens wartet es bis der Subagent die Aufgabe erledigt hat. Viertens empfängt es das zusammengefasste Ergebnis und macht es der Hauptsession verfügbar. Der entscheidende Vorteil: Die gesamte Arbeit des Subagents — alle gelesenen Dateien, alle Zwischenschritte, alle Fehlversuche — bleibt in seinem isolierten Kontext. Nur das finale Ergebnis kommt in deinen Hauptkontext zurück. Das ist der Schlüssel zu effizientem Context Management. Du kannst das Task-Tool für verschiedene Szenarien nutzen: Parallele Aufgaben (mehrere Subagents gleichzeitig), isolierte Exploration (große Codebase durchsuchen ohne den Hauptkontext zu füllen), günstige Vorab-Analyse (Haiku-Subagent für eine schnelle Übersicht), oder spezialisierte Arbeit (ein Agent der nur Tests schreibt, ein anderer der nur dokumentiert). Das Task-Tool respektiert die Subagent-Konfiguration: Welches Modell der Subagent nutzt, welche Tools er hat und wie lange er maximal arbeiten darf — alles konfigurierbar. Die Standard-Konfiguration funktioniert für die meisten Fälle, aber für spezielle Anforderungen lohnt sich das Feintuning.

DAS TASK-TOOL: SUBAGENTS SPAWNEN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

BUILT-IN SUBAGENT TYPEN:
┌─────────────────┬──────────────────────────────────┐
│ Typ             │ Zweck                            │
├─────────────────┼──────────────────────────────────┤
│ Bash            │ Shell-Befehle ausführen           │
│ Explore         │ Codebase erforschen (schnell)     │
│ general-purpose │ Komplexe Multi-Step Tasks         │
│ Plan            │ Architektur-Planung               │
└─────────────────┴──────────────────────────────────┘

SUBAGENT AUFRUF:
Task({
  subagent_type: "Explore",
  description: "Find auth files",
  prompt: "Finde alle auth-relevanten Dateien",
  model: "haiku"  // Optional: haiku, sonnet, opus
})

ERGEBNIS:
→ Agent läuft isoliert
→ Gibt kompaktes Ergebnis zurück
→ Hauptagent verarbeitet das Ergebnis

Parallel vs. Sequentiell

Die Entscheidung zwischen paralleler und sequentieller Ausführung von Subagents ist fundamental für die Effektivität deiner Orchestrierung. Parallele Ausführung ist schneller, aber nur möglich wenn die Aufgaben voneinander unabhängig sind. Sequentielle Ausführung ist zuverlässiger bei abhängigen Aufgaben. Parallel bedeutet: Mehrere Subagents arbeiten gleichzeitig an verschiedenen Aufgaben. Claude Code unterstützt bis zu 7 parallele Subagents. Das ist ideal wenn die Aufgaben keine gemeinsamen Abhängigkeiten haben: Frontend und Backend parallel entwickeln, verschiedene Aspekte gleichzeitig prüfen (Security, Performance, Style), oder mehrere unabhängige Dateien gleichzeitig refactoren. Sequentiell bedeutet: Subagents arbeiten nacheinander, wobei das Ergebnis eines Subagents als Input für den nächsten dient. Das ist nötig wenn Abhängigkeiten bestehen: Erst das Datenbankschema erstellen, DANN die API die darauf zugreift, DANN die Tests. Oder: Erst den Bug analysieren, DANN den Fix planen, DANN implementieren. In der Praxis nutzt du oft eine Kombination: Der erste Schritt (Analyse) läuft sequentiell. Dann spawnt die Hauptsession basierend auf der Analyse mehrere parallele Implementation-Agents. Nach der parallelen Phase läuft wieder ein sequentieller Testing-Agent der alles prüft. Die Zeitersparnis durch Parallelisierung ist erheblich: 5 Aufgaben die jeweils 2 Minuten dauern, brauchen sequentiell 10 Minuten. Parallel nur 2 Minuten (plus etwas Overhead für Koordination). Bei größeren Aufgaben multipliziert sich der Vorteil. Ein wichtiger Praxis-Tipp: Starte mit sequentieller Ausführung bis du den Workflow verstehst. Dann identifiziere welche Schritte parallel laufen können, und optimiere schrittweise. Zu früh zu parallelisieren führt oft zu Koordinationsproblemen.

WANN PARALLEL? (alle Bedingungen erfüllt)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ 3+ unabhängige Tasks
✅ Kein geteilter State zwischen Tasks
✅ Klare Dateigrenzen ohne Überlappung

Beispiel: Code-Review aus 4 Perspektiven
→ Security Agent    ─┐
→ Performance Agent  ├─ PARALLEL ─→ Ergebnisse sammeln
→ Style Agent       ─┤
→ Test Agent        ─┘

WANN SEQUENTIELL? (eine Bedingung reicht)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ Tasks haben Abhängigkeiten (B braucht Output von A)
⚠️ Geteilte Dateien oder State
⚠️ Merge-Conflict Risiko

Beispiel: Feature implementieren
→ Agent A: Schema definieren
    ↓ (Output benötigt)
→ Agent B: API implementieren
    ↓ (Output benötigt)
→ Agent C: Tests schreiben

Custom Agents definieren

Für wiederkehrende Orchestrierungsszenarien definierst du Custom Agents als Markdown-Dateien. Jeder Agent hat seinen eigenen System-Prompt, sein eigenes Modell und seine eigenen Tool-Berechtigungen. Das ist die Grundlage für konsistente, wiederholbare Multi-Agent-Workflows. Custom Agents werden als Markdown-Dateien im .claude/agents/ Verzeichnis gespeichert. Der Dateiname wird zum Agent-Namen: security-reviewer.md wird zu @security-reviewer. Du kannst Agents über @-Mention in der Konversation aufrufen oder sie in Slash Commands und Workflows einbinden. Die Struktur einer Agent-Datei folgt einem klaren Muster: Ein YAML-Frontmatter definiert die technische Konfiguration (Modell, Tools, Timeout). Der Markdown-Inhalt definiert den System-Prompt — die Identität, Aufgabe und Arbeitsweise des Agents. Ein gut definierter Agent hat vier Kernelemente: Erstens eine klare Rolle ('Du bist ein spezialisierter Security-Auditor'). Zweitens spezifische Aufgaben ('Prüfe auf OWASP Top 10, fokussiere auf Input-Validierung und Authentifizierung'). Drittens definierte Qualitätsstandards ('Jedes Finding braucht Schweregrad, betroffenen Code und konkreten Fix-Vorschlag'). Viertens klare Grenzen ('Du analysierst nur, du änderst keinen Code'). Die Modellwahl pro Agent ist ein mächtiges Feature: Ein Explore-Agent braucht nur Haiku (günstig und schnell), ein Implementation-Agent braucht Sonnet (gute Balance), ein Architecture-Agent braucht Opus (maximale Qualität). Diese gezielte Zuweisung kann deine Kosten um 50-80% senken. Für Teams: Custom Agents im .claude/agents/ Verzeichnis werden ins Repository committed. Jedes Teammitglied hat automatisch Zugriff auf die gleichen spezialisierten Agents. Das standardisiert Workflows und sorgt für konsistente Qualität.

# .claude/agents/security-auditor.md

---
name: security-auditor
description: Spezialisierter Security-Analyst
model: claude-sonnet-4-5-20250929
allowed-tools: Read, Grep, Glob
---

# Security Auditor Agent

Du bist ein spezialisierter Sicherheits-Analyst.

## Deine Aufgabe
Analysiere Code auf Sicherheitslücken mit Fokus auf:
- Injection Attacks (SQL, XSS, Command)
- Authentication/Authorization Schwächen
- Data Exposure Risiken
- Kryptografie-Fehler

## Output Format
Für jeden Fund:
1. Schwachstelle (CVSS Score wenn möglich)
2. Betroffene Datei:Zeile
3. Proof of Concept
4. Empfohlener Fix
# .claude/agents/test-writer.md

---
name: test-writer
description: Spezialisierter Test-Autor
model: claude-haiku-4-5-20251001
allowed-tools: Read, Grep, Glob, Write, Edit
---

# Test Writer Agent

Du bist ein Test-Spezialist.

## Regeln
- Nutze das bestehende Test-Framework
- Schreibe Unit UND Integration Tests
- Edge Cases immer abdecken
- Mocke externe Abhängigkeiten
- Strebe >80% Coverage an

Das 7-Agent Feature Pattern

Das 7-Agent Feature Pattern ist ein bewährtes Orchestrierungsmuster für die Implementierung großer Features. Es nutzt die maximale Anzahl paralleler Subagents (7) um ein Feature von der Analyse bis zur Dokumentation durchzuentwickeln — systematisch, parallel und mit hoher Qualität. Die sieben Agents und ihre Rollen: Agent 1 — der Analyst — untersucht die bestehende Codebase und identifiziert alle betroffenen Dateien und Abhängigkeiten. Agent 2 — der Architekt — erstellt basierend auf der Analyse einen Implementierungsplan. Agent 3 — der Database-Engineer — erstellt Schema-Änderungen und Migrationen. Agent 4 — der Backend-Developer — implementiert API-Endpoints und Business-Logik. Agent 5 — der Frontend-Developer — erstellt UI-Komponenten und State-Management. Agent 6 — der Test-Engineer — schreibt Unit, Integration und E2E Tests. Agent 7 — der Documentation-Writer — aktualisiert README, API-Docs und Inline-Kommentare. Der Ablauf ist teilweise sequentiell, teilweise parallel: Agent 1 (Analyse) läuft zuerst allein. Agent 2 (Architektur) basiert auf der Analyse. Agent 3 (Database) basiert auf dem Plan. Dann laufen Agent 4 (Backend) und Agent 5 (Frontend) parallel — sie hängen beide vom Schema ab, aber nicht voneinander. Agent 6 (Tests) kann teilweise parallel laufen. Agent 7 (Docs) läuft am Ende. In der Praxis braucht dieses Pattern 5-10 Minuten für ein Feature das du manuell in 2-4 Stunden umsetzen würdest. Die Qualität ist konsistent hoch weil jeder Agent seinen vollen Kontext für seine Spezialisierung hat. Ein Wort der Warnung: Das Pattern ist für GROSSE Features gedacht — neue Module, umfangreiche Refactorings, Multi-Layer-Changes. Für einen einzelnen API-Endpoint ist es Overkill. Nutze es wenn die Aufgabe mindestens 3 verschiedene Bereiche (DB, Backend, Frontend, Tests) berührt.

7-PARALLEL TASK DISTRIBUTION
━━━━━━━━━━━━━━━━━━━━━━━━━━━

In CLAUDE.md konfigurieren:

# Feature Implementation Pattern
Wenn Features implementiert werden, nutze 7 parallele Tasks:

1. 🎨 Component Agent  → Hauptkomponente erstellen
2. 🎭 Styles Agent     → CSS/Styling erstellen
3. 🧪 Test Agent       → Unit Tests schreiben
4. 📝 Types Agent      → TypeScript Types definieren
5. 🔧 Utils Agent      → Helper-Funktionen
6. 🔗 Integration Agent→ Routing und Imports updaten
7. 📚 Config Agent     → Docs und package.json updaten

Alle 7 Agents laufen PARALLEL
→ Statt 30 Min sequentiell: ~5 Min parallel
→ Jeder Agent hat klare Dateigrenzen
→ Kein Merge-Conflict Risiko

Background Agents

Background Agents sind eine fortgeschrittene Funktion die es ermöglicht, Agents im Hintergrund laufen zu lassen während du andere Dinge tust. Statt auf das Ergebnis zu warten, startest du den Agent und arbeitest weiter — das Ergebnis kommt wenn es fertig ist. Das Konzept ist einfach: Manche Aufgaben dauern lang — eine umfangreiche Codebase durchsuchen, alle Tests einer großen Suite ausführen, oder ein komplettes Refactoring durchführen. Statt diese Zeit untätig zu warten, startest du den Agent im Hintergrund und erledigst andere Aufgaben. Background Agents eignen sich besonders für: Langwierige Code-Analysen (Security-Audit eines großen Projekts), umfangreiche Test-Generierung (Tests für alle ungetesteten Dateien), große Refactorings (alle API-Endpoints auf ein neues Schema migrieren), und Dokumentations-Updates (API-Docs für das gesamte Projekt regenerieren). Technisch laufen Background Agents als separate Claude Code Prozesse. Sie haben ihren eigenen Context, ihre eigenen Tools und ihre eigene Terminal-Session. Du kannst den Fortschritt überwachen und die Ergebnisse abrufen wenn der Agent fertig ist. Ein wichtiger Aspekt: Background Agents verbrauchen Tokens unabhängig von deiner Hauptsession. Wenn du einen Background Agent startest und gleichzeitig in deiner Hauptsession arbeitest, zahlst du für beides. Behalte den Kosten-Monitor im Blick. Die Kombination von Background Agents mit Git Worktrees ist besonders mächtig: Jeder Agent arbeitet in seinem eigenen Worktree (einem separaten Checkout des Repositories). So können mehrere Agents gleichzeitig an verschiedenen Branches arbeiten ohne sich gegenseitig zu stören. Mein Empfehlung: Starte mit einfachen Background-Tasks die klar definiert sind und deren Ergebnis du leicht verifizieren kannst. Erst wenn du Vertrauen aufgebaut hast, delegiere komplexere Aufgaben.

# Background Agent starten:
# Wenn Claude einen Subagent spawnt:
# → Ctrl+B drücken → Agent läuft im Hintergrund

# Workflow:
# 1. Du fragst Claude nach einer Analyse
# 2. Claude spawnt einen Subagent
# 3. Du drückst Ctrl+B
# 4. Agent läuft im Hintergrund
# 5. Du arbeitest mit Claude weiter
# 6. /tasks zeigt den Status
# 7. Ergebnis kommt automatisch zurück

# Laufende Agents prüfen:
/tasks

# Agent als bestimmter Agent debuggen:
claude --agent security-auditor
# → Startet Claude Code mit Agent-Konfiguration

# Agent Definition prüfen:
/agents
# → Zeigt alle verfügbaren Agents an

Task-System für Koordination

Wenn mehrere Agents zusammenarbeiten, brauchen sie ein System zur Koordination — wer macht was, in welcher Reihenfolge, und wie werden Ergebnisse zusammengeführt. Claude Code nutzt intern ein Task-System das genau diese Orchestrierung übernimmt. Das Task-System verwaltet den Zustand aller Subagents: Welche Tasks sind geplant (pending), welche laufen gerade (in_progress), welche sind fertig (completed) und welche abgebrochen (cancelled). Die Hauptsession sieht diesen Status und kann darauf reagieren. Abhängigkeiten werden über die Reihenfolge gesteuert: Wenn Task B auf das Ergebnis von Task A angewiesen ist, startet B erst nachdem A abgeschlossen ist. Unabhängige Tasks können parallel laufen. Claude erkennt Abhängigkeiten oft automatisch, aber du kannst sie auch explizit definieren. Das Ergebnis-Management ist elegant: Jeder Subagent fasst sein Ergebnis zusammen und übergibt es der Hauptsession. Die Zusammenfassung enthält die wesentlichen Erkenntnisse oder Änderungen — nicht die gesamte Detailarbeit. So bleibt der Hauptkontext kompakt. Fehlerbehandlung ist eingebaut: Wenn ein Subagent fehlschlägt, wird die Hauptsession informiert und kann entscheiden: Nochmal versuchen mit angepasstem Prompt, den Task an einen anderen Agent delegieren, oder den Fehler dem Nutzer melden und um Hilfe bitten. Für Custom Workflows kannst du das Task-System über Slash Commands und Skills steuern. Ein /project:feature Command könnte zum Beispiel einen vordefinierten Multi-Agent-Workflow starten der automatisch die richtigen Agents in der richtigen Reihenfolge orchestriert. Das Task-System wird besonders wertvoll wenn du Agent Teams nutzt — mehrere unabhängige Claude Code Sessions die über Messaging-Kanäle kommunizieren. Hier koordiniert das Task-System nicht nur Subagents innerhalb einer Session, sondern auch die Zusammenarbeit zwischen Sessions.

TASK-SYSTEM: MULTI-AGENT KOORDINATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

TaskCreate → Tasks erstellen mit IDs
TaskUpdate → Status ändern (pending → in_progress → completed)
TaskList   → Alle Tasks und deren Status sehen
TaskGet    → Einzelnen Task mit Details abrufen

ABHÄNGIGKEITEN:
Task #1: "Database Schema erstellen"
Task #2: "API implementieren" (blocked by: #1)
Task #3: "Tests schreiben" (blocked by: #2)

→ Task #2 kann erst starten wenn #1 fertig ist
→ Automatische Dependency-Auflösung

SHARED TASK LIST (Multi-Session):
export CLAUDE_CODE_TASK_LIST_ID=shared-list-123
→ Mehrere Claude-Sessions teilen dieselbe Task-Liste
→ Session A beendet Task → Session B sieht Update

Zusammenfassung