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

Agent Teams & Checkpointing

Level 3 | 45 Minuten

Mehrere Claude-Code-Instanzen als Team orchestrieren – Architektur, Display Modes, Task-System, Hooks, Troubleshooting – und Checkpointing mit allen Restore-Optionen.

Lernziele

Teil 1: Agent Teams

Agent Teams lassen dich mehrere Claude-Code-Instanzen koordinieren, die als Team zusammenarbeiten. Eine Session ist der Team Lead, der Arbeit koordiniert, Tasks zuweist und Ergebnisse zusammenfasst. Teammates arbeiten unabhängig, jeder in seinem eigenen Kontextfenster, und können direkt miteinander kommunizieren – nicht nur über den Lead. (Quelle: code.claude.com/docs/en/agent-teams)

⚠️ Experimentell Agent Teams sind experimentell und standardmäßig deaktiviert. Sie haben bekannte Limitierungen bei Session-Resumption, Task-Koordination und Shutdown-Verhalten. Immer den Changelog und die Docs für den aktuellen Stand prüfen.

Wann Agent Teams einsetzen?

Agent Teams sind am effektivsten, wenn parallele Exploration echten Mehrwert bringt: - Research und Review: Mehrere Teammates untersuchen verschiedene Aspekte eines Problems gleichzeitig, teilen dann Ergebnisse und hinterfragen gegenseitig. - Neue Module oder Features: Jeder Teammate übernimmt ein separates Modul, ohne sich in die Quere zu kommen. - Debugging mit konkurrierenden Hypothesen: Teammates testen verschiedene Theorien parallel und konvergieren schneller auf die Antwort. - Cross-Layer-Koordination: Änderungen, die Frontend, Backend und Tests betreffen – jeder Bereich gehört einem anderen Teammate. Agent Teams erzeugen Koordinations-Overhead und verbrauchen deutlich mehr Tokens als eine einzelne Session. Für sequentielle Tasks, Same-File-Edits oder Arbeit mit vielen Abhängigkeiten ist eine einzelne Session oder Subagents effektiver.

Agent Teams vs. Subagents – Vergleichstabelle

Beide parallelisieren Arbeit, funktionieren aber fundamental anders: | | Subagents | Agent Teams | |---|---|---| | Kontext | Eigenes Kontextfenster; Ergebnisse gehen zurück an den Aufrufer | Eigenes Kontextfenster; vollständig unabhängig | | Kommunikation | Berichten nur an den Hauptagenten zurück | Teammates können sich direkt gegenseitig Nachrichten schicken | | Koordination | Hauptagent verwaltet alle Arbeit | Geteilte Task-Liste mit Selbst-Koordination | | Ideal für | Fokussierte Tasks, bei denen nur das Ergebnis zählt | Komplexe Arbeit, die Diskussion und Zusammenarbeit erfordert | | Token-Kosten | Niedriger: Ergebnisse werden zusammengefasst zurückgegeben | Höher: jeder Teammate ist eine eigene Claude-Instanz | Faustregel: Subagents für schnelle, isolierte Aufgaben. Agent Teams wenn Teammates Ergebnisse teilen, sich gegenseitig hinterfragen und eigenständig koordinieren müssen.

Agent Teams aktivieren

Agent Teams sind standardmäßig deaktiviert. Aktiviere sie über die Umgebungsvariable oder die Settings:

// In .claude/settings.json oder ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

// ODER als Umgebungsvariable in der Shell:
// export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Ein Agent Team starten

Nach der Aktivierung beschreibst du einfach in natürlicher Sprache, was das Team tun soll. Claude erstellt das Team, startet Teammates und koordiniert die Arbeit basierend auf deinem Prompt. Beispiel-Prompts (aus den offiziellen Docs):

# Beispiel 1: Exploration aus verschiedenen Perspektiven
Ich designe ein CLI-Tool, das Entwicklern hilft, TODO-Kommentare im Code
zu tracken. Erstelle ein Agent Team mit drei Perspektiven: ein Teammate
für UX, einer für technische Architektur, einer als Devil's Advocate.

# Beispiel 2: Paralleles Code-Review
Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

# Beispiel 3: Competing Hypotheses Debugging
Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them
talk to each other to try to disprove each other's theories, like a
scientific debate. Update the findings doc with whatever consensus emerges.

Der Lead erstellt eine geteilte Task-Liste, startet die Teammates, und sie arbeiten los. Die Task-Liste zeigt, woran jeder arbeitet. Mit Shift+Up/Down wählst du einen Teammate direkt an.

Display Modes: In-Process vs. Split-Pane

Agent Teams unterstützen zwei Darstellungsmodi: In-Process (Standard): Alle Teammates laufen in deinem Hauptterminal. Mit Shift+Up/Down wählst du einen Teammate, tippst und sendest direkt Nachrichten. Mit Enter siehst du die Session eines Teammates, mit Escape unterbrichst du seinen aktuellen Turn. Ctrl+T togglet die Task-Liste. Funktioniert in jedem Terminal – kein tmux nötig. Split-Pane: Jeder Teammate bekommt ein eigenes Pane – du siehst alle gleichzeitig und klickst in ein Pane, um direkt zu interagieren. Erfordert tmux oder iTerm2 mit der it2 CLI. Der Default ist "auto": Split Panes wenn du bereits in einer tmux-Session bist, sonst In-Process.

// Display-Modus konfigurieren in settings.json:
{ "teammateMode": "in-process" }  // oder "tmux" für Split-Panes

// Oder als Flag für eine einzelne Session:
// claude --teammate-mode in-process

Team steuern – alle Optionen im Detail

Du gibst dem Lead in natürlicher Sprache Anweisungen. Hier die wichtigsten Steuerungsmöglichkeiten: Teammates und Modelle festlegen: Du kannst Anzahl und Modell für Teammates bestimmen: „Create a team with 4 teammates. Use Sonnet for each." Plan Approval verlangen: Für riskante Tasks kannst du verlangen, dass Teammates erst planen und du den Plan freigibst, bevor sie implementieren: „Spawn an architect teammate. Require plan approval before they make any changes." Der Teammate arbeitet dann im Read-Only Plan Mode bis der Lead zustimmt. Der Lead entscheidet autonom über die Freigabe – du kannst Kriterien mitgeben: „Only approve plans that include test coverage." Delegate Mode (Shift+Tab): Verhindert, dass der Lead selbst Code schreibt statt zu delegieren. Aktiviere mit Shift+Tab nach dem Team-Start. Der Lead kann dann nur noch koordinieren: Teammates spawnen, Nachrichten senden, Tasks verwalten – kein Code anfassen. Direkt mit Teammates sprechen: - In-Process: Shift+Up/Down zum Auswählen, dann tippen. Enter = Session ansehen, Escape = Turn unterbrechen. - Split-Pane: Ins Pane klicken. Jeder Teammate ist eine vollständige, unabhängige Claude-Code-Session.

Das Task-System im Detail

Die geteilte Task-Liste ist das Herzstück der Agent-Teams-Koordination: Drei Task-Zustände: - Pending: Task wartet auf Bearbeitung - In Progress: Teammate arbeitet daran - Completed: Task ist abgeschlossen Abhängigkeiten: Tasks können von anderen Tasks abhängen. Ein Pending-Task mit unerledigten Abhängigkeiten kann nicht beansprucht werden, bis die Abhängigkeiten erledigt sind. Das System verwaltet das automatisch. Task-Zuweisung: - Lead weist zu: Du sagst dem Lead, welchen Task er an welchen Teammate geben soll. - Self-Claim: Nach Abschluss eines Tasks nimmt sich ein Teammate automatisch den nächsten freien, unblockierten Task. - File-Locking: Race Conditions werden verhindert – wenn zwei Teammates gleichzeitig denselben Task beanspruchen wollen, gewinnt einer und der andere sucht sich den nächsten. Empfehlung: 5-6 Tasks pro Teammate als Richtgröße. Zu wenig Tasks → Teammates stehen schnell still. Zu viele → Unübersichtlich.

Teammates beenden: „Ask the researcher teammate to shut down." Der Lead sendet einen Shutdown-Request; der Teammate kann zustimmen (graceful exit) oder mit Begründung ablehnen (z.B. „Ich bin noch mitten in einer Analyse"). Team aufräumen: „Clean up the team." Entfernt geteilte Ressourcen (Task-Listen, Config). Immer zuerst alle Teammates beenden, dann über den Lead aufräumen. Wichtig: Der Lead prüft auf aktive Teammates und verweigert Cleanup wenn noch welche laufen. Nie über einen Teammate aufräumen – nur über den Lead.

Architektur im Detail

AGENT TEAM ARCHITEKTUR
━━━━━━━━━━━━━━━━━━━━

┌──────────────────────────────────────────────┐
│                 TEAM LEAD                     │
│  (Deine Hauptsession)                        │
│  • Erstellt Team, spawnt Teammates           │
│  • Koordiniert, weist Tasks zu               │
│  • Synthesiert Ergebnisse                    │
│  • Delegate Mode: nur Koordination           │
└───────┬──────────┬──────────┬────────────────┘
        │          │          │
   ┌────▼────┐ ┌──▼──────┐ ┌▼─────────┐
   │Teammate │ │Teammate │ │Teammate  │
   │  "API"  │ │ "Tests" │ │"Frontend"│
   │  Opus   │ │ Sonnet  │ │ Sonnet   │
   └────┬────┘ └───┬─────┘ └────┬─────┘
        │          │             │
        └──────────┼─────────────┘
                   │
         ┌─────────▼──────────┐
         │  GETEILTE RESSOURCEN │
         │  • Task-Liste        │
         │  • Mailbox           │
         │  • CLAUDE.md (lokal) │
         └─────────────────────┘

SPEICHERORTE:
  ~/.claude/teams/{team-name}/config.json  → Team-Config
  ~/.claude/tasks/{team-name}/             → Task-Liste

KONTEXT:
  • Jeder Teammate hat eigenes Kontextfenster
  • Lädt: CLAUDE.md + MCP-Server + Skills + Spawn-Prompt
  • Lead-History wird NICHT übertragen
  • Nachrichten werden automatisch zugestellt

Quality Gates mit Hooks

Du kannst Hooks nutzen, um Regeln durchzusetzen, wenn Teammates fertig werden: - TeammateIdle Hook: Wird ausgelöst, wenn ein Teammate idle wird. Exit Code 2 → Feedback senden und Teammate weiterarbeiten lassen (z.B. „Tests fehlen noch", „Lint-Errors beheben"). - TaskCompleted Hook: Wird ausgelöst, wenn ein Task als fertig markiert wird. Exit Code 2 → Fertigstellung verhindern und Feedback geben (z.B. „Typ-Checks müssen passen"). Beispiel: Du willst sicherstellen, dass kein Teammate „fertig" meldet, ohne dass die Tests grün sind. Der TaskCompleted-Hook führt npm test aus und gibt Exit Code 2 zurück wenn Tests fehlschlagen.

Troubleshooting Agent Teams

Best Practices für Agent Teams (offizielle Docs)

Teil 2: Checkpointing

Checkpointing ist ein Sicherheitsnetz, das Claude Codes Datei-Edits automatisch trackt. Du kannst jederzeit zu einem früheren Zustand zurückspulen – sowohl Code als auch Konversation. Das erlaubt dir, ambitionierte, weitreichende Änderungen zu verfolgen, weil du weißt, dass du immer zurückkannst. (Quelle: code.claude.com/docs/en/checkpointing)

Wie Checkpoints funktionieren

Automatisches Tracking: - Claude Code erfasst den Zustand deines Codes VOR jeder Bearbeitung durch seine File-Editing-Tools. - Jeder User-Prompt erzeugt einen neuen Checkpoint. - Checkpoints bleiben über Sessions hinweg erhalten – du kannst sie in fortgesetzten Konversationen nutzen. - Automatische Bereinigung nach 30 Tagen (konfigurierbar). Du musst nichts manuell „speichern" – die Checkpoints entstehen automatisch im Verlauf deiner Session.

WIE CHECKPOINTING FUNKTIONIERT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Dein Prompt → Claude bearbeitet Dateien
                ↓
      ┌─────────────────────┐
      │  CHECKPOINT ERSTELLT │
      │  • Zustand aller     │
      │    bearbeiteten      │
      │    Dateien (vorher)  │
      │  • Konversations-    │
      │    position          │
      │  • Prompt-Text       │
      └─────────────────────┘
                ↓
Nächster Prompt → Nächste Bearbeitung
                ↓
      ┌─────────────────────┐
      │  NEUER CHECKPOINT   │
      └─────────────────────┘
                ↓
         ... und so weiter

/rewind oder Esc+Esc → Checkpoint-Liste:

  Prompt 1: "Erstelle Login"    [+120 Zeilen, 3 Dateien]
  Prompt 2: "Füge Validierung"  [+45/-12 Zeilen, 2 Dateien]
  Prompt 3: "Refaktoriere"      [+89/-67 Zeilen, 4 Dateien]

→ Wähle Punkt → Wähle Aktion (5 Optionen)

Rewind aufrufen und die 5 Optionen

Es gibt zwei Wege, das Rewind-Menü zu öffnen: - Esc + Esc (zweimal Escape drücken) - /rewind Slash-Command Du siehst eine scrollbare Liste aller deiner Prompts aus der Session. Wähle den Punkt, zu dem du zurück willst, und dann eine der fünf Aktionen:

💡 Summarize vs. Fork Summarize hält dich in derselben Session und komprimiert Kontext. Wenn du stattdessen einen neuen Ansatz ausprobieren willst OHNE die Original-Session zu verändern, nutze Fork: claude --continue --fork-session. Fork erstellt eine Kopie der Session an dem Punkt, an dem du warst.

Typische Anwendungsfälle für Checkpointing

TYPISCHER WORKFLOW MIT CHECKPOINTING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Du: "Erstelle eine Login-Komponente mit React Hook Form"
   → Claude implementiert. Checkpoint 1 entsteht.
   → Code sieht gut aus ✓

2. Du: "Füge jetzt E-Mail-Validierung hinzu"
   → Claude implementiert. Checkpoint 2 entsteht.
   → Code sieht gut aus ✓

3. Du: "Refaktoriere alles zu einem Custom Hook"
   → Claude refaktoriert. Checkpoint 3 entsteht.
   → Hmm, das hat die Struktur verschlechtert ✗

4. Esc+Esc → Checkpoint-Liste:
   [1] "Erstelle Login-Komponente"  [3 Dateien, +120/-0]
   [2] "Füge Validierung hinzu"    [2 Dateien, +45/-12]  ← hier
   [3] "Refaktoriere zu Hook"      [4 Dateien, +89/-67]

5. Du wählst [2] → "Restore code and conversation"

6. Ergebnis:
   - Code ist auf Stand nach Schritt 2 (Validierung OK)
   - Chat zeigt nur Prompt 1 und 2
   - Prompt 2 erscheint im Eingabefeld
   - Schritt 3 (Refactoring) ist komplett weg

7. Du gibst jetzt eine andere Anweisung:
   "Extrahiere nur die Validierungslogik in eine utils-Datei"
   → Neuer, besserer Ansatz ab dem guten Punkt

Grenzen von Checkpointing

🎓 Zusammenfassung: Agent Teams + Checkpointing Agent Teams: ✅ Mehrere Claude-Instanzen als koordiniertes Team ✅ Lead + Teammates + geteilte Task-Liste + Mailbox ✅ In-Process oder Split-Pane (tmux/iTerm2) Display ✅ Delegate Mode, Plan Approval, direkte Teammate-Kommunikation ✅ Quality Gates mit TeammateIdle/TaskCompleted Hooks ✅ Deutlich mehr Tokens als Single-Session – bewusst einsetzen Checkpointing: ✅ Automatisch bei jedem Prompt – kein manuelles Speichern ✅ 5 Optionen: Restore Code+Chat, nur Chat, nur Code, Summarize, Abbrechen ✅ Esc+Esc oder /rewind zum Öffnen ✅ Bash/externe Änderungen nicht erfasst – Git weiterhin nutzen ✅ Sessions übergreifend, 30 Tage aufbewahrt