Subagents in Claude Code

Ein Subagent ist ein spezialisierter Helfer, den Claude Code für eine bestimmte Aufgabe startet – mit eigenem Context-Fenster, eigenem System-Prompt und einer eingeschränkten Tool-Liste. Statt dass Claude im Hauptgespräch hunderte Suchergebnisse durchscrollt und deinen Context damit verstopft, übernimmt der Subagent die Arbeit isoliert und liefert nur die Zusammenfassung zurück.

Für wen ist das?

Für Entwickler, die Claude Code regelmäßig nutzen und merken: Bestimmte Side-Tasks tauchen immer wieder auf – Codebase nach einem Pattern durchsuchen, Logs analysieren, eine API-Doku überfliegen. Genau hier glänzen Subagents.

Was lernst du?

• Was Subagents sind und wie sie sich von Hooks und Skills unterscheiden
• Wann ein Subagent sich lohnt – und wann nicht
• Wie du einen Subagent als Markdown-Datei definierst
• Wie du Tool-Zugriff und Modellwahl gezielt einschränkst
• Wo Subagents im Projekt liegen und wie die Resolution-Reihenfolge funktioniert

Wann nutzen?

• Heavy-Context-Tasks: Eine große Codebase nach einem bestimmten Pattern durchsuchen
• Parallele Exploration: Den gleichen Codebereich aus mehreren Blickwinkeln untersuchen
• Wiederkehrende Side-Aufgaben: Test-Failures triagieren, Dependency-Updates prüfen, Migration-Steps verifizieren
• Isolation: Wenn ein Task seinen eigenen System-Prompt braucht (z.B. „streng nach Security-Checkliste arbeiten”)

Wann nicht?

• Bei einmaligen Fragen – formuliere einfach einen guten Prompt
• Wenn der Task im Hauptgespräch stattfinden muss, weil Folgefragen direkt anschließen
• Wenn der Output stark vom restlichen Kontext abhängt, den der Subagent nicht kennt

So funktionieren Subagents

Jeder Subagent ist eine Markdown-Datei in .claude/agents/ (Projekt-Scope) oder ~/.claude/agents/ (User-Scope). YAML-Frontmatter beschreibt, wann Claude den Subagent automatisch wählen soll; der Markdown-Body wird zum System-Prompt für den Subagent.

---
name: test-triager
description: Use when test failures need to be categorized by root cause. Reads test output and groups failures by likely cause (timing, mocks, real bugs).
tools: Read, Grep, Bash
model: sonnet
---

You are a test failure triager. When given test output:
1. Group failures by likely root cause (timing, mocks, real bugs)
2. For each group, name 1-2 representative failures
3. Return a short prioritized list — most likely real bugs first

Stay focused on triage. Do not propose fixes unless explicitly asked.

Claude liest die description automatisch und entscheidet, ob ein Subagent für die aktuelle Aufgabe passt. Eine präzise description ist der wichtigste Hebel – sie steuert, wann der Subagent tatsächlich gestartet wird.

Subagent anlegen – Schritt für Schritt

Subagents vs. Skills vs. Hooks

Drei verwandte Konzepte, die oft verwechselt werden:

• Skill: Wissen + Instruktionen, die Claude für eine bestimmte Aufgabe lädt – läuft im selben Context.
• Subagent: Eigener Helfer mit eigenem Context und eigenen Tools – gibt nur das Ergebnis zurück.
• Hook: Shell-Befehl, der vor oder nach einem Tool-Call deterministisch ausgeführt wird – kein LLM-Call.

Faustregel: Wenn die Aufgabe „nur Anleitung” braucht → Skill. Wenn sie eigenen Context braucht → Subagent. Wenn sie deterministisch und ohne LLM läuft → Hook.

Modellwahl je Subagent

Jeder Subagent darf sein eigenes Modell wählen – passend zur Schwere der Aufgabe:

• Haiku 4.5: Klassifikation, Routing, einfache Suche im Codebase
• Sonnet 4.6: Standardarbeit – Analysen, Tests triagieren, Doku überfliegen
• Opus 4.8: Komplexe Reasoning-Aufgaben, Architektur-Reviews, schwierige Bugs

Ein Triage-Subagent mit Haiku kostet Bruchteile dessen, was Opus für die gleiche Klassifikation verlangen würde – und ist schneller.

Typische Fehler

• Schwammige description: „Helps with code” ist nutzlos. Claude muss erkennen, WANN dieser Subagent passt. Schreibe „Use when test failures need to be grouped by root cause” – konkret und scoped.
• Zu viele Tools: Wenn der Subagent Read, Edit, Write, Bash, Grep, WebSearch darf, verliert er den Fokus. Liste nur, was zwingend nötig ist.
• Subagent als Generalist: Ein „Allzweck-Subagent” wird nie automatisch gewählt – er konkurriert mit dem Hauptmodell. Subagents sind Spezialkräfte.
• Output nicht definiert: Wenn du nicht sagst, in welcher Form der Subagent zurückgeben soll (Liste, Tabelle, Zusammenfassung), bekommst du Wildwuchs.
• Falsches Modell: Opus für eine Klassifikation ist Verschwendung. Sonnet für tiefes Architektur-Reasoning kann zu oberflächlich sein. Wähle bewusst.

Mini-Übung

Lege einen Subagent an, der für dich Test-Output triagiert:

1. Erstelle .claude/agents/test-triager.md in einem Projekt mit Tests
2. Schreibe eine scharfe description („Use when test failures need to be grouped by likely root cause”)
3. Begrenze Tools auf Read, Grep, Bash
4. Setze model: sonnet
5. Im System-Prompt: „Group failures by root cause, name representatives, return prioritized list”
6. Lass deine Tests fehlschlagen und bitte Claude im Hauptgespräch: „Triage the failures.” – beobachte, ob der Subagent automatisch übernimmt

Nächster Schritt

Du weißt jetzt, wann und wie du Subagents einsetzt. Als Nächstes lohnt sich der Guide Hooks einrichten – denn Hooks und Subagents ergänzen sich: deterministische Gates (Hooks) plus intelligente Spezialisten (Subagents) sind die Basis professioneller Claude-Code-Setups.