Architektur & Koordination

Wissen

Team Lead & Teammates

Meta-Controller

Ein zentraler Controller-Agent delegiert Aufgaben an spezialisierte Worker-Agents und aggregiert deren Ergebnisse.

Vorteile

Klare Hierarchie
Einfach zu debuggen
Gute Kontrolle über Workflow

Nachteile

Single Point of Failure
Controller-Bottleneck
Wenig Flexibilität

Beispiel

Claude Code mit Subagents: Orchestrator plant, Subagents führen Teilaufgaben aus.

Ein Agent Team besteht aus zwei Rollen:

Team Lead -- das ist deine Hauptsession in Claude Code. Der Lead:

Koordiniert die Gesamtaufgabe und teilt sie in Teilaufgaben auf
Spawnt Teammates für parallele Arbeit
Empfängt Statusupdates und Ergebnisse
Kann direkt mit einzelnen Teammates kommunizieren oder an alle broadcasten

Teammates -- das sind eigenständige Claude-Instanzen, die der Lead startet. Jeder Teammate:

Läuft als unabhängiger Claude-Prozess mit eigenem Context
Hat Zugriff auf die gleiche Codebase (typischerweise in einem eigenen Git Worktree)
Kann Tasks aus der Shared Task List übernehmen
Kommuniziert über ein Messaging-System mit dem Lead und anderen Teammates

iAnalogie: Scrum Team

Der Lead ist wie der Tech Lead in einem Scrum Team: Er plant die Aufgaben, verteilt sie und behält den Überblick. Die Teammates sind die Entwickler, die unabhängig an ihren Aufgaben arbeiten, aber bei Bedarf miteinander kommunizieren können.

Koordinationsprimitiven

Agent Teams nutzen drei Mechanismen zur Koordination:

1. Shared Task List

Alle Aufgaben werden in ~/.claude/tasks/ als Dateien gespeichert. Jede Task hat:

Einen Titel und eine Beschreibung
Einen Status: pending --> in_progress --> completed
Optionale Dependencies auf andere Tasks
Den zugewiesenen Teammate

File Locking stellt sicher, dass nicht zwei Teammates gleichzeitig die gleiche Task übernehmen. Wenn Teammate A eine Task claimed, wird sie atomar als in_progress markiert -- bevor Teammate B sie sehen kann.

2. Peer-to-Peer Messaging

Agents können direkt miteinander kommunizieren:

message -- eine Nachricht an einen bestimmten Teammate senden
broadcast -- eine Nachricht an alle Teammates senden

Das Messaging funktioniert über ein Mailbox-System: Jeder Agent hat eine Inbox, die er regelmäßig prüft. Nachrichten werden nicht sofort verarbeitet, sondern beim nächsten Tool-Call-Zyklus des Empfängers.

3. Automatische Dependency-Auflösung

Tasks können voneinander abhängen. Wenn Task B von Task A abhängt:

Task B bleibt im Status pending, solange Task A nicht completed ist
Sobald Task A abgeschlossen wird, wird Task B automatisch freigegeben
Der nächste verfügbare Teammate kann Task B dann übernehmen

Das ermöglicht natürliche Workflows: Erst die API implementieren, dann die Tests dafür schreiben.

Display-Modi

Agent Teams können in verschiedenen Modi angezeigt werden:

Modus	Beschreibung	Umschalten
in-process	Alle Teammates im gleichen Terminal	Shift+Down zum Durchschalten
tmux	Jeder Teammate in einem eigenen tmux-Pane	Automatisch bei tmux-Session
iTerm2	Jeder Teammate in einem eigenen iTerm2-Tab	Automatisch bei iTerm2

Der in-process-Modus ist der Standard. Du siehst den Lead im Hauptfenster und kannst mit Shift+Down durch die Teammates scrollen. Bei tmux oder iTerm2 bekommt jeder Teammate automatisch sein eigenes Pane oder Tab.

Aktivierung

Agent Teams aktivierst du über das Feature-Flag:

Option 1: In der settings.json (empfohlen für dauerhaften Einsatz)

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Option 2: Als Umgebungsvariable (für einmalige Tests)

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

!Experimentell -- Erwartungen anpassen

Da Agent Teams experimentell sind, können unerwartete Verhaltensweisen auftreten. Starte mit einfachen Szenarien (2 Teammates, klare Aufgabentrennung) und steigere die Komplexität schrittweise.

Was passiert, wenn zwei Teammates gleichzeitig die gleiche Task übernehmen wollen?

Verstehen

Warum diese Architektur?

Die Kombination aus Shared Task List und Messaging löst zwei grundlegende Probleme verteilter Systeme:

Koordination ohne Bottleneck: Der Lead muss nicht jeden Schritt überwachen. Teammates arbeiten selbstständig anhand der Task List.
Flexibilität bei unerwarteten Situationen: Wenn ein Teammate auf ein Problem stößt, kann er per Message den Lead oder einen anderen Teammate informieren.

Das File-Locking-System ist bewusst einfach gehalten -- es nutzt das Dateisystem statt einer Datenbank. Das ist robust genug für die typischen Team-Größen (2--10 Teammates, maximal bis zu 16) und erfordert keine zusätzliche Infrastruktur.

Reflektieren

Die Architektur von Agent Teams folgt bewährten Mustern aus der verteilten Systementwicklung: Task Queues, Message Passing und Lock-basierte Synchronisierung. Im nächsten Abschnitt schauen wir uns die Details der Task-Verwaltung und des Messaging-Systems genauer an.