Schritt 1 von 4Wissen
Die drei Built-in Subagents
Voller Zugriff auf alle Tools. Kann lesen, schreiben, Bash ausführen. Für komplexe, mehrstufige Aufgaben.
Feature implementieren, Tests schreiben, PR erstellen
Kann lesen und Bash ausführen, aber nicht schreiben. Für Analyse und Planung.
Codebase analysieren, Implementierungsplan erstellen
Nur Lese-Zugriff. Schlank und spezialisiert. Für Recherche und Navigation.
Datei finden, Funktion suchen, Abhängigkeiten prüfen
Claude Code stellt drei eingebaute Subagent-Typen bereit, die ohne Konfiguration verfügbar sind:
1. Explore (erbt Modell, read-only)
Der Explore-Agent ist dein schneller Recherche-Assistent. Er hat nur lesende Werkzeuge wie Read, Grep, Glob und Bash (read-only); Schreiben und Bearbeiten sind gesperrt. Das macht ihn ideal für schnelle Codebase-Suchen.
Explore nutzt das Modell der Hauptsitzung — bei Abo und API also in der Regel Opus. (Ältere Anleitungen nennen hier noch Haiku; maßgeblich ist die aktuelle Claude-Code-Dokumentation.) Wer die Recherche günstiger haben will, legt einen eigenen Subagent namens Explore mit model: haiku an. Er überschreibt den eingebauten:
---
name: Explore
description: Fast, read-only agent for searching and analyzing codebases
model: haiku
---
You are a fast, read-only codebase explorer. Search and analyze code
to answer questions, and do not modify files.
"Finde alle Stellen, wo die User-Authentifizierung aufgerufen wird"
Claude Code erkennt automatisch, dass das eine Recherche-Aufgabe ist, und delegiert sie an einen Explore-Subagent. Du bekommst eine kompakte Zusammenfassung zurück -- ohne dass dein Hauptkontext mit hunderten Dateien gefüllt wird.
2. Plan (erbt Modell, read-only)
Der Plan-Agent wird im Plan Mode aktiviert (Shift+Tab zum Umschalten). Er erbt das Modell des Hauptagenten, arbeitet aber ebenfalls nur lesend. Seine Aufgabe: komplexe Probleme analysieren und einen strukturierten Plan erstellen, bevor Code geschrieben wird.
3. General-purpose (erbt alles)
Der General-purpose Agent erbt Modell, Tools und Berechtigungen des Hauptagenten. Er ist für komplexe Teilaufgaben gedacht, die sowohl Lesen als auch Schreiben erfordern -- zum Beispiel ein Refactoring in einem bestimmten Verzeichnis.
Claude Code entscheidet oft selbstständig, wann ein Subagent sinnvoll ist. Wenn du eine Frage stellst, die viel Recherche erfordert, wird häufig automatisch ein Explore-Agent gestartet. Du kannst Subagents aber auch explizit anfordern.
Custom Agents erstellen
Custom Agents sind der eigentliche Gamechanger. Du definierst sie als Markdown-Dateien mit YAML-Frontmatter in .claude/agents/:
---
name: code-reviewer
description: Reviews code changes for best practices and potential issues
tools:
- Read
- Grep
- Glob
- Bash
model: sonnet
maxTurns: 20
---
Du bist ein erfahrener Code-Reviewer. Deine Aufgabe:
1. Lies die geänderten Dateien sorgfältig
2. Prüfe auf: Fehlerbehandlung, Typsicherheit, Performance, Lesbarkeit
3. Erstelle einen strukturierten Review mit konkreten Verbesserungsvorschlägen
4. Bewerte die Änderung auf einer Skala von 1-5
Sei konstruktiv, aber gründlich. Nenne konkrete Zeilennummern.
Frontmatter-Felder im Detail
| Feld | Beschreibung | Beispiel |
|---|---|---|
name | Eindeutiger Name des Agents | code-reviewer |
description | Kurzbeschreibung (wird in der Agent-Liste angezeigt) | Reviews code changes |
tools | Erlaubte Tools (Whitelist) | [Read, Grep, Glob] |
disallowedTools | Verbotene Tools (Blacklist) | [Write, Edit] |
model | Modell-Override | haiku, sonnet, opus |
permissionMode | Berechtigungsmodus | default, plan, bypassPermissions |
maxTurns | Maximale Anzahl an Tool-Aufrufen | 20 |
skills | Vorgeladene Skills (vollständig injiziert) | [testing, refactoring] |
mcpServers | Subagent-spezifische MCP-Server | [github, linear] |
memory | Memory-Scope des Agents | user, project, local |
background | Als Hintergrund-Task starten | true |
isolation | Isolationsmodus | worktree |
Verwende entweder tools (Whitelist) oder disallowedTools (Blacklist), nicht beides gleichzeitig. tools ist restriktiver und daher sicherer für Agents, die nur lesen sollen.
Custom Agents aufrufen
Es gibt drei Wege, einen Custom Agent zu starten:
1. Natürliche Sprache -- einfach im Gespräch erwähnen:
"Use the code-reviewer to check my latest changes"
2. @-Mention -- direkte Adressierung mit dem Agent-Namen:
@"code-reviewer (agent)" prüfe die Änderungen in src/auth/
3. CLI-Flag -- beim Start von Claude Code:
claude --agent code-reviewer
Wenn du einen Agent häufig nutzt, ist die @-Mention-Syntax am schnellsten. Das CLI-Flag eignet sich für Automatisierung, zum Beispiel in Git Hooks oder CI/CD-Pipelines.
Scope-Priorität
Custom Agents können an verschiedenen Orten definiert werden. Bei Namenskonflikten gilt diese Priorität (höchste zuerst):
- CLI-Flag (
--agent) -- höchste Priorität - Projekt-Agents (
.claude/agents/) -- projektspezifisch, im Repo versionierbar - User-Agents (
~/.claude/agents/) -- global für alle Projekte - Plugin-Agents -- von installierten Plugins bereitgestellt
Schritt 2 von 4Verstehen
Wann Custom, wann Built-in?
Die Built-in Agents decken die meisten Standardfälle ab. Custom Agents lohnen sich, wenn du:
- Wiederkehrende Aufgaben hast (Code Review, Test-Erstellung, Dokumentation)
- Eingeschränkte Berechtigungen brauchst (ein Agent, der nur lesen darf)
- Spezifische Anweisungen geben willst (Coding Standards, Review-Checklisten)
- Ein bestimmtes Modell erzwingen willst (Haiku für einfache, Opus für komplexe Aufgaben)
Denk an Custom Agents wie an Vorlagen für wiederkehrende Delegationen. Statt jedes Mal zu erklären, was der Code-Reviewer tun soll, definierst du es einmal -- und rufst es dann mit einem Wort auf.
Schritt 3 von 4Anwenden
Ein typisches Projekt-Setup könnte so aussehen:
.claude/agents/
reviewer.md # Code Review mit eingeschränkten Tools
test-writer.md # Generiert Tests basierend auf Implementierung
doc-writer.md # Erstellt/aktualisiert Dokumentation
refactorer.md # Refactoring mit spezifischen Coding Standards
Diese Agents werden ins Repository committed und stehen dem ganzen Team zur Verfügung. Jeder im Team kann mit @"reviewer (agent)" den gleichen, konsistenten Review-Prozess auslösen.
Schritt 4 von 4Reflektieren
Die Kombination aus Built-in und Custom Agents gibt dir ein flexibles Werkzeugset. Built-in Agents für den Alltag, Custom Agents für wiederkehrende, spezialisierte Aufgaben. Im nächsten Abschnitt schauen wir uns an, wie Subagents ihren Kontext managen und wie Git Worktrees für echte Isolation sorgen.