Schritt 1 von 4Wissen
Jeder Subagent hat seinen eigenen Kontext
Das zentrale Prinzip von Subagents: Isolation. Wenn der Hauptagent einen Subagent startet, bekommt dieser ein eigenes, frisches Context Window. Der Subagent sieht nicht, was der Hauptagent vorher gelesen oder geschrieben hat -- er startet mit einer sauberen Arbeitsfläche.
Was der Subagent mitbekommt:
- Die Aufgabenbeschreibung vom Hauptagent
- Seinen System-Prompt (bei Custom Agents aus dem Frontmatter)
- Zugriff auf die Codebase über seine erlaubten Tools
Was der Subagent nicht sieht:
- Den bisherigen Gesprächsverlauf des Hauptagents
- Dateien, die der Hauptagent gelesen hat (sofern sie nicht explizit erwähnt werden)
- Ergebnisse anderer Subagents
Am Ende liefert der Subagent eine Zusammenfassung zurück. Nur diese Zusammenfassung landet im Kontext des Hauptagents -- nicht die ganzen Zwischenschritte.
Genau das macht Subagents so wertvoll: Ein Explore-Agent liest vielleicht 80 Dateien und führt 20 Suchen durch. Im Hauptkontext landet davon nur ein Absatz: "Die Authentifizierung ist in src/lib/auth.ts implementiert und nutzt JWT-Tokens mit 24h Ablauf."
Git Worktrees: Echte Dateisystem-Isolation
Standardmäßig arbeitet ein Subagent im selben Verzeichnis wie der Hauptagent. Wenn der Subagent Dateien ändert, sieht der Hauptagent diese Änderungen sofort. Das kann zu Konflikten führen.
Die Lösung: Worktree-Isolation. Mit isolation: worktree im Frontmatter bekommt der Subagent einen eigenen Git Worktree -- eine separate Arbeitskopie des Repositories:
---
name: feature-builder
description: Implements features in isolated worktree
isolation: worktree
model: sonnet
tools:
- Read
- Write
- Edit
- Grep
- Glob
- Bash
---
Implementiere das Feature im isolierten Worktree.
Wenn du fertig bist, beschreibe die Änderungen.
Was passiert bei isolation: worktree:
- Claude Code erstellt automatisch einen neuen Git Worktree
- Der Subagent arbeitet in diesem separaten Verzeichnis
- Änderungen im Worktree beeinflussen das Hauptverzeichnis nicht
- Nach Abschluss wird der Worktree automatisch aufgeräumt
Worktree-Isolation funktioniert nur in Git-Repositories. Ohne Git fällt der Agent auf das Standard-Arbeitsverzeichnis zurück.
Background Tasks mit Ctrl+B
Subagents können als Hintergrund-Tasks gestartet werden. Drücke Ctrl+B in Claude Code, um die aktuelle Aufgabe in den Hintergrund zu verschieben. Du kannst dann weiterarbeiten, während der Subagent seine Aufgabe erledigt.
Alternativ kannst du im Custom Agent background: true setzen:
---
name: long-analysis
description: Deep codebase analysis
background: true
model: haiku
tools:
- Read
- Grep
- Glob
---
Background Tasks sind besonders nützlich für:
- Langwierige Recherchen (gesamte Codebase durchsuchen)
- Paralleles Arbeiten (du codest, der Agent analysiert)
- CI/CD-ähnliche Checks (Linting, Test-Analyse im Hintergrund)
Persistent Memory für Subagents
Subagents können auf das Memory-System von Claude Code zugreifen. Über das memory-Feld im Frontmatter legst du den Scope fest:
user-- Zugriff auf~/.claude/CLAUDE.md(globale Präferenzen)project-- Zugriff auf das Projekt-CLAUDE.md(Coding Standards, Architektur)local-- Zugriff auf lokale Memory-Dateien
So kann ein Code-Reviewer zum Beispiel automatisch die Coding Standards des Projekts kennen, ohne dass du sie jedes Mal erklären musst.
Preloaded Skills
Mit dem skills-Feld im Frontmatter werden Skills vollständig in den Subagent-Kontext injiziert -- nicht nur als Discovery-Referenz, sondern als kompletter Inhalt:
---
name: test-writer
skills:
- testing
- typescript-patterns
---
Der Subagent startet damit sofort mit dem Wissen aus diesen Skills, ohne sie erst suchen und laden zu müssen.
Subagent-spezifische MCP-Server
Über mcpServers im Frontmatter kannst du einem Subagent Zugriff auf spezifische MCP-Server geben:
---
name: issue-tracker
mcpServers:
- linear
- github
---
So hat der Agent Zugriff auf externe Systeme, die für seine Aufgabe relevant sind -- ohne dass der Hauptagent diese Server-Verbindungen laden muss.
Subagents können keine weiteren Subagents starten. Es gibt nur eine Ebene der Delegation: Hauptagent delegiert an Subagent, Subagent liefert Ergebnis zurück. Wenn du mehrere Ebenen brauchst, schau dir Agent Teams an (Modul 8).
Schritt 2 von 4Verstehen
Das Zusammenspiel von Kontext und Worktree
Stell dir zwei Isolationsebenen vor:
Kontext-Isolation (immer aktiv): Der Subagent hat sein eigenes Context Window. Das ist der "Schreibtisch" -- was er liest und denkt, bleibt bei ihm. Nur das Ergebnis geht zurück.
Dateisystem-Isolation (optional, via isolation: worktree): Der Subagent arbeitet in einer separaten Kopie des Codes. Das ist der "Büroraum" -- seine Dateiänderungen betreffen nicht das Hauptverzeichnis.
Für reine Recherche reicht Kontext-Isolation. Für Subagents, die Code schreiben, ist Worktree-Isolation oft die sicherere Wahl.
Schritt 3 von 4Anwenden
Ein typischer Workflow mit Worktree-Isolation:
- Du arbeitest an Feature A im Hauptverzeichnis
- Du startest einen Subagent mit
isolation: worktreefür Feature B - Der Subagent implementiert Feature B in seinem eigenen Worktree
- Du reviewst die Änderungen und mergst sie bei Bedarf
- Der Worktree wird automatisch aufgeräumt
Das ist besonders mächtig in Kombination mit Background Tasks: Du codest an Feature A, während der Subagent im Hintergrund Feature B in einem isolierten Worktree implementiert.
Schritt 4 von 4Reflektieren
Kontextmanagement ist das Fundament effizienter Subagent-Nutzung. Kontext-Isolation hält deinen Hauptagent schlank, Worktree-Isolation verhindert Dateikonflikte, und Background Tasks ermöglichen paralleles Arbeiten. Im nächsten Abschnitt lernst du, wann du welche Delegation-Strategie wählen solltest.