# Claude Code Subagents: erstellen und richtig einsetzen

URL: https://agentvera.dev/de/blog/claude-code-subagents/ · Veröffentlicht: 2026-10-23

Was Claude Code Subagents sind, wie du einen in .claude/agents schreibst, was die Felder tools und model bewirken und wann getrennte parallele Agenten besser passen.

**Kurz gesagt:**

- Ein Subagent läuft in einem eigenen Kontextfenster mit eigenem Prompt, eigenen Tools und eigenem Modell, und nur seine Endantwort geht zurück in die Hauptkonversation.
- Subagents sind Markdown-Dateien in .claude/agents/, bei denen nur name und description Pflicht sind; ohne tools bekommt der Subagent alle Tools der Hauptsession.
- Subagents passen zu kurzen Aufgaben wie Suche und Review, getrennte parallele Agenten zu Features und langen Aufgaben, die in einem eigenen Branch enden.

Claude Code Subagents sind Helfer, denen die Haupt-Session von Claude Code eine einzelne Aufgabe übergibt. Jeder läuft in einem eigenen Kontextfenster, mit eigenem System-Prompt, eigener Tool-Liste und eigenem Modell, und nur seine Endantwort kehrt in die Hauptkonversation zurück. Du definierst einen Subagent als Markdown-Datei in `.claude/agents/`, und Claude nutzt ihn automatisch, wenn die Aufgabe zu seiner Beschreibung passt, oder wenn du ihn beim Namen verlangst.

Dieser Beitrag behandelt, wie Subagents funktionieren, das Dateiformat, die Felder `tools` und `model`, wie du sie aufrufst und die Grenze zwischen einem Subagent und einem getrennten Agenten, der neben dem ersten läuft. Die Fakten stammen aus den offiziellen [Subagent-Docs](https://code.claude.com/docs/en/sub-agents "Claude Code subagents docs"). Die Kurzfassung in einem Absatz findest du im [Glossar-Eintrag zu Subagents](/de/glossary/subagent/ "Subagent").

## Wie Subagents funktionieren

Entscheidet Claude zu delegieren, ruft es das Agent-Tool auf (vor Version 2.1.63 hieß es Task) und gibt einen kurzen Auftrag mit. Der Subagent startet mit frischem Kontext. Er bekommt seinen eigenen System-Prompt, die Delegationsnachricht, deine `CLAUDE.md`, den Git-Status und alle Skills, die du für ihn vorgeladen hast. Den Verlauf der Hauptkonversation sieht er nicht.

Dann arbeitet er die Aufgabe mit seinen erlaubten Tools ab und liefert ein Ergebnis. Alles, was er unterwegs gelesen hat, etwa Dutzende Dateien, lange grep-Ausgaben oder Testprotokolle, bleibt in seinem eigenen Kontext. Das ist der Hauptgrund für Subagents: Die Hauptkonversation bekommt eine Zusammenfassung, nicht das Rauschen.

Ein paar Grenzen, die du kennen solltest:

- Subagents können eigene Subagents starten, standardmäßig bis zu drei Ebenen tief.
- Standardmäßig können bis zu 20 gleichzeitig laufen.
- Ihre Anfragen zählen auf dieselben Nutzungslimits wie die Hauptsession.
- Ein Subagent kann im Vordergrund laufen, wobei der Hauptagent wartet, oder im Hintergrund, während der Hauptagent weitermacht.

## Eingebaute Subagents

Claude Code liefert ein paar Subagents mit, die du nutzen kannst, ohne etwas zu schreiben:

| Subagent | Tools | Typischer Einsatz |
| --- | --- | --- |
| Explore | Nur Lesen | Suchen und Lesen im ganzen Codebestand, in den Tiefen quick, medium oder very thorough |
| Plan | Nur Lesen | Recherche im Plan-Modus |
| General-purpose | Alle Tools | Mehrstufige Aufgaben, die Recherche und Änderungen brauchen |

Explore begegnet dir am häufigsten. Muss Claude finden, wo etwas definiert ist oder wie ein Feature über Dateien hinweg funktioniert, gibt es das oft an Explore ab, damit die Dateiinhalte nicht in deinem Hauptkontext landen.

## Wo Subagent-Dateien liegen

Subagents sind Markdown-Dateien mit YAML-Frontmatter. Claude Code lädt sie von mehreren Orten, und haben zwei denselben Namen, gewinnt der weiter oben in dieser Liste:

| Ort | Geltungsbereich |
| --- | --- |
| Verwaltete Einstellungen | Organisationsweit, von Admins gesetzt |
| `--agents`-Flag (JSON) | Eine Session |
| `.claude/agents/` | Ein Projekt, über Git geteilt |
| `~/.claude/agents/` | Alle deine Projekte |
| Der Ordner `agents/` eines Plugins | Überall, wo das Plugin installiert ist |

Projekt-Subagents in `.claude/agents/` solltest du einchecken, damit das ganze Team denselben Reviewer oder Test-Runner nutzt.

## Das Dateiformat eines Subagents

Nur `name` und `description` sind Pflicht. Der Text nach dem Frontmatter ist der System-Prompt des Subagents.

```markdown
---
name: code-reviewer
description: Reviews code changes for bugs, security issues and readability. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When called:

1. Run git diff to see the recent changes.
2. Read the changed files and the code around them.
3. Report problems by priority: bugs, security, then readability.
4. For each problem, give the file, the line and a concrete fix.

Do not edit files. Report only.
```

Die `description` ist wichtiger, als sie aussieht. Sie liest Claude, wenn es entscheidet, ob es delegiert, also sag, was der Subagent tut und wann er zu nutzen ist. Formulierungen wie „use after writing code“ helfen Claude, ihn von selbst aufzugreifen.

### Das Feld tools

`tools` ist eine Allowlist. Mit `tools: Read, Grep, Glob, Bash` kann der Reviewer oben lesen und Befehle ausführen, aber keine Dateien bearbeiten. Lässt du `tools` weg, erbt der Subagent jedes Tool der Hauptsession, einschließlich MCP-Tools. Es gibt auch `disallowedTools`, wenn es einfacher ist zu sagen, was entfernt wird, als was bleibt.

Halte die Liste so kurz, wie die Aufgabe es erlaubt. Ein Reviewer braucht kein Edit. Ein Recherche-Agent braucht kein Bash. Weniger Tools bedeuten weniger Überraschungen und eine klarere Aufgabe.

### Das Feld model

`model` akzeptiert einen Alias (`sonnet`, `opus`, `haiku`), eine vollständige Modell-ID oder `inherit`, um das Modell der Hauptsession zu nutzen. Wird der Subagent aufgerufen, wählt Claude Code das Modell in dieser Reihenfolge: ein mit dem Aufruf übergebenes Modell, dann das Feld `model` der Datei, dann die Umgebungsvariable `CLAUDE_CODE_SUBAGENT_MODEL`, dann das Modell der Hauptsession.

Hier können Subagents echtes Geld sparen. Breite Dateisuchen und das Lesen von Logs brauchen selten das stärkste Modell. Lege sie auf Haiku und lass die Hauptsession für die Entscheidungen auf dem größeren Modell. Der Beitrag zum Claude Code Token-Verbrauch zeigt weitere Wege, Kosten zu senken.

### Weitere nützliche Felder

| Feld | Was es tut |
| --- | --- |
| `permissionMode` | Berechtigungsmodus für den Subagent, zum Beispiel plan oder acceptEdits |
| `skills` | Skills, die beim Start in den Kontext des Subagents geladen werden |
| `mcpServers` | MCP-Server, die der Subagent nutzen kann |
| `hooks` | Hooks, die gelten, solange dieser Subagent läuft |
| `memory` | Dauerhafter Speicher auf User-, Projekt- oder lokaler Ebene |
| `maxTurns` | Obergrenze für die Turns des Subagents |
| `background` | Standardmäßig im Hintergrund laufen |
| `isolation: worktree` | In einem temporären Git-Worktree laufen |
| `effort` | Reasoning-Aufwand für den Subagent |

## So rufst du einen Subagent auf

Es gibt drei Wege:

1. **Claude entscheiden lassen.** Passt die Anfrage zur Beschreibung eines Subagents, delegiert Claude von selbst.
2. **Beim Namen verlangen.** „Use the code-reviewer subagent to check my last commit.“ Du kannst ihn auch aus dem Menü mit @ erwähnen.
3. **Eine ganze Session als ihn laufen lassen.** `claude --agent code-reviewer` startet eine Session, die Prompt, Tools und Modell dieses Subagents nutzt.

Für eine einmalige Session kannst du Subagents als JSON übergeben, ohne Dateien anzulegen:

```bash
claude --agents '{
  "code-reviewer": {
    "description": "Reviews code changes. Use after edits.",
    "prompt": "You are a senior code reviewer. Report bugs and fixes, do not edit.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
```

Damit Claude einen bestimmten Subagent nicht nutzt, nimm ihn in die Deny-Liste deiner Berechtigungen auf, zum Beispiel `Agent(Explore)`.

## Subagents oder getrennte parallele Agenten

Subagents und parallele Agenten teilen beide Arbeit auf, lösen aber unterschiedliche Probleme.

| | Subagents | Getrennte parallele Agenten |
| --- | --- | --- |
| Wer sie startet | Die Haupt-Session von Claude | Du |
| Was du siehst | Das Endergebnis, im Haupt-Chat | Die komplette Session jedes Agenten |
| Kontext | Frisch pro Aufgabe, danach verworfen | Langlebig, einer pro Agent |
| Dateien | Derselbe Arbeitsordner, außer bei `isolation: worktree` | Meist je ein Git-Worktree |
| Dein Eingriff mitten in der Aufgabe | Keiner, der Hauptagent spricht mit ihm | Du kannst jeden lenken |
| Gut für | Suche, Review, Recherche, kurze fokussierte Aufgaben | Features, Refactorings, lange Aufgaben, die in einem Branch enden |

Nutze einen Subagent, wenn der Hauptagent eine Antwort braucht, um weiterzumachen: „finde alle Aufrufer dieser Funktion“, „prüfe diesen Diff“, „fasse diese Logs zusammen“. Die Arbeit ist kurz, ihr Ergebnis zählt, und du musst nicht zusehen.

Nutze getrennte Agenten, wenn jedes Stück echte Arbeit für sich ist: ein Feature, eine Migration, eine Testsuite. Du willst sehen, was jeder tut, seine Fragen beantworten und seine Änderungen als Branch prüfen. Dieses Setup beschreiben [parallele Coding-Agenten](/de/blog/parallel-coding-agents/ "Parallele Coding-Agenten") und [mehrere Claude Code Agenten ausführen](/de/blog/run-multiple-claude-code-agents/ "Mehrere Claude Code Agenten ausführen"), mit jedem Agenten in einem eigenen [Git-Worktree](/de/blog/git-worktree-parallel-agents/ "Git-Worktree für parallele Agenten").

Beides lässt sich gut mischen. Ein getrennter Agent kann für seine eigenen Suchen und Reviews trotzdem Subagents nutzen. Ein guter Standard: getrennte Agenten für Arbeit, die du einer Person zuweisen würdest, und Subagents für die Botengänge, die diese Agenten erledigen. Für größere Teams behandelt der Beitrag zum KI-Agenten-Team Rollen und Übergaben, und der Eintrag zur Multi-Agent-Orchestrierung die allgemeine Idee.

Claude Code hat außerdem eine eigene Funktion namens Agent Teams, in der mehrere Claude-Sessions zusammenarbeiten. Das ist nicht dasselbe wie Subagents und liegt außerhalb dieses Beitrags.

## Tipps für Subagents, die funktionieren

- **Eine Aufgabe pro Subagent.** „Reviewer“ und „Test-Runner“ funktionieren besser als „Helfer“.
- **Schreibe die Beschreibung für Claude.** Sag, wann er zu nutzen ist, nicht nur, was er ist.
- **Begrenze die Tools.** Schreibgeschützte Subagents für Recherche und Review, Bearbeitungs-Tools nur dort, wo nötig.
- **Wähle das Modell bewusst.** Haiku für Suche und Zusammenfassungen, ein stärkeres Modell für Design und knifflige Fixes.
- **Bitte um einen kurzen Bericht.** Das Ergebnis landet im Hauptkontext, also sag dem Subagent, er soll Erkenntnisse liefern, keine Dateiinhalte.
- **Checke deine Projekt-Subagents ein.** `.claude/agents/` in Git heißt, alle bekommen dieselben Helfer.

## So zeigt AgentVera Subagents

AgentVera ist eine Desktop-App, die viele Coding-Agenten, Claude Code, Codex und andere, nebeneinander ausführt. Sie geht auf zwei Arten mit Subagents um.

**Du kannst sie sehen.** Im Bereich eines Claude Code Agenten öffnet der Button „Subagents“ eine Live-Ansicht der Subagents, die dieser Agent gestartet hat, und was sie gerade tun. Jeder zeigt seinen Status (Running, Done, Error, Stopped), ob er „in background“ läuft, die „Assigned task“, die er bekam, und seinen „Report“. Arbeiten gerade welche, erscheint eine Zeile „{count} subagents running — show“, damit du sie nicht übersiehst. Die [Projekttour und Code-Karte](/de/features/project-tour-and-code-map/ "Projekttour und Code-Karte") hat außerdem eine Subagent-Zeitleiste mit Typ, Status, Tool-Anzahl und Dauer. Beide lesen lokale Transkripte und sind vorerst für Claude Code Agenten.

**Ein günstigeres Explore.** Unter Settings → „Token saving“ gibt die Option „Explorer subagent“ Claude Agenten einen schreibgeschützten Explorer für breite Suchen. Das Durchsuchen von Dateien läuft auf einem günstigeren Modell, standardmäßig Haiku, und nur das Ergebnis kehrt in die Hauptkonversation zurück. Hast du schon eine eigene Explore-Subagent-Datei, lässt AgentVera deine unangetastet. Die Option steht im selben Abschnitt wie die Smart Tools.

**Getrennte Agenten, wenn die Arbeit größer ist.** Die [Team-Ansicht](/de/features/team-view/ "Team-Ansicht") zeigt bis zu 24 Agenten gleichzeitig. [Parallel team](/de/features/parallel-team/ "Parallel team") (Pläne Pro und Team) teilt ein Ziel in Teile auf, führt jeden in einem eigenen Worktree aus und führt sie in einem PR zusammen. Mit Agent-Messaging stellen sich Agenten gegenseitig Fragen, auch über CLIs hinweg, und die Agent-Koordination warnt, wenn zwei Agenten dieselbe Datei anfassen. Das ist die Seite der getrennten Agenten aus der Tabelle oben, wobei Subagents in jedem Claude Agenten weiter verfügbar sind.

## Fazit

Subagents sind das richtige Werkzeug, wenn der Hauptagent eine Antwort braucht und du der Arbeit nicht zusehen musst: Suche, Review, Recherche. Schreibe eine Markdown-Datei mit klarer Beschreibung, kurzer Tool-Liste und bewusst gewähltem Modell. Ist die Arbeit groß genug für einen eigenen Branch und deine Aufmerksamkeit, nimm stattdessen einen getrennten Agenten.

Mehr dazu:

- [Subagent (Glossar)](/de/glossary/subagent/ "Subagent")
- [Parallele Coding-Agenten](/de/blog/parallel-coding-agents/ "Parallele Coding-Agenten")
- [Projekttour und Code-Karte](/de/features/project-tour-and-code-map/ "Projekttour und Code-Karte")
- [Parallel team](/de/features/parallel-team/ "Parallel team")
- [Claude Code Agent](/de/agents/claude-code/ "Claude Code in AgentVera")

Um AgentVera auszuprobieren, beginne auf der [Startseite](/de/ "AgentVera").

## Häufige Fragen

**Was ist ein Subagent in Claude Code?** Ein Subagent ist ein Helfer, den die Haupt-Session von Claude Code für eine einzelne Aufgabe startet. Er läuft in einem eigenen Kontextfenster mit eigenem System-Prompt, eigenen Tools und eigenem Modell, und nur sein Endergebnis kehrt in die Hauptkonversation zurück.

**Wie erstelle ich einen Claude Code Subagent?** Lege eine Markdown-Datei in .claude/agents/ in deinem Projekt an, oder in ~/.claude/agents/ für alle Projekte. Das YAML-Frontmatter braucht name und description; der Hauptteil ist der System-Prompt. Optionale Felder sind unter anderem tools, model, permissionMode und isolation.

**Welches Modell nutzt ein Subagent?** Das Feld model akzeptiert einen Alias wie sonnet, opus oder haiku, eine vollständige Modell-ID oder inherit. Ist es nicht gesetzt, nutzt der Subagent das Modell der Hauptsession, es sei denn, die Umgebungsvariable CLAUDE_CODE_SUBAGENT_MODEL sagt etwas anderes.

**Sparen Subagents Tokens?** Sie halten den Hauptkontext sauber, weil Dateiinhalte und Suchausgaben im Subagent bleiben. Sie machen die Arbeit nicht kostenlos: Subagent-Anfragen zählen auf dieselben Nutzungslimits, also spart es am meisten, breite Suchen an ein günstigeres Modell wie Haiku zu geben.

**Wann nutze ich getrennte Agenten statt Subagents?** Wenn Aufgaben lang sind, viele Dateien ändern, unterwegs deine Prüfung brauchen oder in getrennten Branches enden sollen. Getrennte Agenten in eigenen Git-Worktrees bieten das; Subagents passen zu kurzen, fokussierten Aufgaben, deren Ergebnis der Hauptagent braucht.

---

**Über AgentVera.** AgentVera ist eine Desktop-App für macOS, Windows und Linux, entwickelt von Solviera Teknoloji. Sie führt 18 KI-Coding-Agenten (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) nebeneinander aus, pro Projekt, in echten Terminals mit den eigenen CLI-Installationen und Logins des Nutzers. Der kostenlose Plan hat unbegrenzt viele Agenten. Download: https://agentvera.dev/de/download/ · Preise: https://agentvera.dev/de/pricing/