Agent-Typen & Konfiguration

Wissen

Die drei Built-in Subagents

Capability-Level

Klicke auf eine Ebene

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. Schnell und günstig. 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 (Haiku, read-only)

Der Explore-Agent ist dein schneller Recherche-Assistent. Er läuft auf dem günstigeren Haiku-Modell und hat nur lesende Werkzeuge: Read, Grep, Glob und Bash (read-only). Das macht ihn ideal für schnelle Codebase-Suchen.

"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.

iAutomatische Delegation

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`

!tools vs. disallowedTools

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

*Praxis-Tipp

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

Welcher Built-in Subagent eignet sich am besten für eine schnelle Suche nach allen API-Endpunkten im Projekt?

Verstehen

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.

Du erstellst einen Custom Agent für automatisierte Test-Erstellung. Welche Konfiguration ist am sinnvollsten?

Anwenden

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.

Reflektieren

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.