Subagents und Automatisierung in Claude Code

1. Was ein Subagent technisch ist

Ein Subagent in Claude Code ist eine eigenständige Agent-Instanz mit eigenem Kontextfenster, eigenem Systemprompt und einer eingeschränkten Auswahl an Werkzeugen. Der Hauptagent delegiert eine klar umrissene Teilaufgabe an den Subagenten, wartet auf dessen Ergebnis und arbeitet danach mit einer kompakten Zusammenfassung weiter, statt mit dem vollständigen Verlauf der Teilaufgabe. Das unterscheidet einen Subagenten fundamental von einer einfachen Funktion: Ein Subagent trifft eigene Entscheidungen, ruft eigenständig Werkzeuge auf und kann iterativ vorgehen, bevor er ein Ergebnis zurückgibt.

Technisch gesehen läuft ein Subagent im selben Claude-Code-Prozess, besitzt aber einen getrennten Konversationsverlauf. Das bedeutet: Dateien, die der Subagent liest, Suchergebnisse, die er durchforstet, und Zwischenschritte, die er ausprobiert, belasten nicht das Kontextfenster des Hauptagenten. Nur das, was der Subagent explizit als Ergebnis zurückmeldet, fließt in den Hauptkontext zurück. Diese Trennung ist der zentrale technische Mechanismus, auf dem alle praktischen Vorteile von Subagents aufbauen.

2. Warum isolierte Kontextfenster das eigentliche Problem lösen

Das Kontextfenster eines Sprachmodells ist eine begrenzte Ressource, und bei komplexen Mehrschritt-Aufgaben füllt es sich schneller, als man denkt. Wer in einem einzigen Agent-Kontext zehn Dateien liest, drei Testläufe durchführt und eine lange Diskussion über Architekturentscheidungen führt, verliert Kapazität für die eigentliche Aufgabe. Modelle neigen außerdem dazu, bei sehr langen, überfrachteten Kontexten weniger präzise zu werden, weil relevante Informationen zwischen irrelevanten Zwischenschritten verschwinden.

Ein Subagent kappt diese Kette gezielt. Die Rechercheaufgabe "finde alle Stellen, an denen ein bestimmtes Legacy-Interface verwendet wird" kann Dutzende Dateien lesen und trotzdem nur drei Sätze Ergebnis an den Hauptagenten zurückgeben. Der Hauptagent bleibt dadurch fokussiert auf die eigentliche Entscheidung: was mit diesem Ergebnis zu tun ist. Diese Isolation ist besonders wertvoll bei explorativen Aufgaben, deren Ausgang zu Beginn nicht feststeht und die potenziell viel "Rauschen" produzieren, bevor sie zu einem klaren Ergebnis kommen.

# Example: main agent delegates an exploratory codebase question
# to a subagent instead of reading dozens of files itself

# Only this request stays visible in the main context:
"Find all controller classes that still use the old
ObjectManager::create() pattern instead of constructor
injection, and list the file paths."

# The subagent searches independently:
#   - app/code/**/*.php
#   - reads candidate files in full
#   - filters false positives (comments, tests)
#
# Result in the main context: only the final file list,
# not the dozens of files read along the way

3. Parallele Recherche über eine große Codebasis

Der klassische Anwendungsfall für Subagents ist die parallele Recherche über mehrere unabhängige Bereiche einer Codebasis. Bei einem Magento-Modul mit Frontend-Templates, Backend-Models und einer JavaScript-Komponente lassen sich drei Subagents gleichzeitig starten: einer analysiert die phtml-Templates auf Barrierefreiheitsprobleme, einer prüft die PHP-Klassen auf PHPStan-Verstöße, ein dritter durchsucht die Alpine.js-Komponenten auf inkonsistente Event-Namen. Weil die drei Bereiche keine Abhängigkeiten zueinander haben, gewinnt die Parallelisierung reale Zeit, nicht nur Übersichtlichkeit.

Wichtig ist, dass die Teilaufgaben tatsächlich unabhängig sind. Sobald ein Subagent das Ergebnis eines anderen braucht, bevor er sinnvoll arbeiten kann, verpufft der Parallelisierungsvorteil und der Koordinationsaufwand steigt ohne Gegenwert. In der Praxis bewährt sich die Faustregel, Recherche-Aufgaben nach Datei- oder Modulgrenzen zu schneiden, nicht nach Themen, die sich überschneiden. Eine gute Aufgabenteilung führt dazu, dass jeder Subagent sein Ergebnis unabhängig liefern kann, ohne auf einen anderen zu warten.

{
  "task_group": "module_audit",
  "subagents": [
    {
      "name": "template-review",
      "scope": "app/design/frontend/**/*.phtml",
      "goal": "Check accessibility and CSP-compliant inline scripts",
      "tools": ["Read", "Grep"]
    },
    {
      "name": "phpstan-scan",
      "scope": "app/code/Mironsoft/**/*.php",
      "goal": "Identify and categorize PHPStan level 5 violations",
      "tools": ["Read", "Bash"]
    },
    {
      "name": "alpine-consistency",
      "scope": "app/design/frontend/**/web/js/**/*.js",
      "goal": "Check event naming conventions across Alpine components",
      "tools": ["Read", "Grep"]
    }
  ],
  "note": "All three subagents are independent and can run in parallel"
}

4. Isolierte Code-Review-Durchläufe als Subagent-Muster

Ein zweiter bewährter Anwendungsfall ist der isolierte Review-Durchlauf. Wenn derselbe Agent, der Code geschrieben hat, diesen Code auch reviewt, neigt er dazu, seine eigenen Annahmen und blinden Flecken zu wiederholen, weil der Kontext bereits mit der Implementierungslogik gefüllt ist. Ein Subagent, der ohne dieses Vorwissen startet und nur den fertigen Diff sieht, bewertet Code näher an der Perspektive eines echten Reviewers, der die Entstehungsgeschichte nicht kennt.

In der Praxis bedeutet das: Der Hauptagent implementiert eine Änderung, committet sie nicht sofort, sondern startet einen Subagenten mit der alleinigen Aufgabe, den Diff kritisch zu prüfen, auf Randfälle, Sicherheitslücken und Abweichungen von Projektkonventionen zu achten. Dieser Subagent bekommt keinen Zugriff auf die vorherige Konversation, sondern nur den Diff und relevante Projektregeln wie CLAUDE.md. Das erzwingt eine echte zweite Perspektive statt einer bloßen Bestätigung der eigenen Arbeit.

# Typical flow: implementation and review as separate subagent roles

# 1. Main agent implements the feature and produces a diff
git diff --staged > /tmp/pending-change.diff

# 2. A fresh subagent gets ONLY the diff and project rules,
#    no knowledge of the prior implementation conversation.
#    Task: "Review this diff for security issues,
#    missing PHPDoc blocks, and violations of CLAUDE.md."

# 3. Result: a list of concrete findings, not a blanket approval
#    - missing @throws annotation on line 42
#    - addFieldToFilter() with int instead of ['eq' => $value] array form

# 4. Main agent decides which findings to fix before committing

5. Subagents konfigurieren: Markdown-Definitionen und Tool-Scope

Subagents werden in Claude Code als Markdown-Dateien mit YAML-Frontmatter definiert, typischerweise unter .claude/agents/. Jede Definition legt Name, Beschreibung, erlaubte Werkzeuge und einen spezialisierten Systemprompt fest. Ein Subagent für Sicherheitsreviews braucht typischerweise nur Lesezugriff und Grep, während ein Subagent für Refactoring-Aufgaben auch Schreibrechte und Bash-Zugriff benötigt. Diese Einschränkung ist kein Nebeneffekt, sondern ein bewusstes Sicherheitsfeature: Ein Review-Subagent, der versehentlich Dateien ändern könnte, widerspricht dem Zweck einer unabhängigen Prüfung.

Die Beschreibung in der Frontmatter entscheidet maßgeblich darüber, wann der Hauptagent den Subagenten automatisch aktiviert. Eine präzise Formulierung wie "Nutze diesen Agenten für isolierte Sicherheitsreviews von PHP-Diffs, bevor Code committed wird" führt zu zuverlässigerer automatischer Delegation als eine vage Beschreibung wie "hilft bei Code". Wer Subagents in einem Team einsetzt, sollte diese Definitionen versionieren und im Repository ablegen, damit alle Entwickler dieselben spezialisierten Rollen zur Verfügung haben.

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: >
  Use this agent for isolated security review of PHP diffs
  before code is committed. Does not implement changes,
  only reports findings.
tools:
  - Read
  - Grep
  - Bash
model: sonnet
---

# The subagent's system prompt follows here as markdown text,
# e.g. review criteria, known vulnerability patterns,
# and the instruction to only report findings,
# never to make changes itself

6. Orchestrierung: wie der Hauptagent Subagents einsetzt

Der Hauptagent entscheidet situativ, ob eine Aufgabe an einen Subagenten delegiert wird oder nicht. Diese Entscheidung basiert auf der Aufgabenbeschreibung im Prompt, den registrierten Subagent-Definitionen und dem eingeschätzten Umfang der Teilaufgabe. Bei mehreren unabhängigen Teilaufgaben kann der Hauptagent mehrere Subagents in einer einzigen Anfrage parallel starten, was in der Praxis den größten Zeitgewinn bringt, weil die Subagents nicht nacheinander, sondern gleichzeitig arbeiten.

Nach Abschluss eines Subagent-Laufs erhält der Hauptagent ausschließlich die finale Textantwort, nicht den vollständigen Werkzeugverlauf des Subagenten. Das zwingt zu einer Disziplin bei der Formulierung von Subagent-Aufgaben: Die Aufgabenstellung muss so präzise sein, dass die Rückmeldung ohne weiteren Kontext verständlich und verwertbar ist. Ein Subagent, der nur "fertig" zurückmeldet, ohne konkrete Ergebnisse zu benennen, macht die Isolation wertlos, weil der Hauptagent dann erneut nachfragen oder selbst nachprüfen muss.

# Simplified illustration of how a main agent might reason about
# whether to dispatch independent subtasks to subagents in parallel

def should_delegate(subtasks: list[str], shared_state: bool) -> bool:
    """
    Decide whether subtasks should run as parallel subagents.
    Returns False if subtasks depend on shared, mutable state.
    """
    if shared_state:
        # Tight coupling means constant back-and-forth, no isolation benefit
        return False
    return len(subtasks) > 1

subtasks = [
    "Audit phtml templates for accessibility issues",
    "Scan PHP classes for PHPStan level 5 violations",
    "Check Alpine.js components for event naming consistency",
]

if should_delegate(subtasks, shared_state=False):
    # Dispatch all three subagents in a single request, run concurrently
    results = dispatch_subagents(subtasks)
else:
    # Fall back to sequential work in the main agent context
    results = [run_inline(task) for task in subtasks]

7. Wann Subagents unnötige Komplexität erzeugen

Nicht jede Aufgabe profitiert von einem Subagenten, und die Versuchung, Subagents als generelles Organisationsprinzip einzusetzen, führt häufig zu mehr Aufwand statt weniger. Eine einzelne Datei ändern, einen simplen Bugfix umsetzen oder eine kurze Frage zur Codebasis beantworten braucht keinen separaten Agent-Kontext. Der Koordinationsaufwand, eine Aufgabe zu formulieren, auf das Ergebnis zu warten und es zu interpretieren, übersteigt hier den Nutzen der Kontextisolation bei weitem.

Ein zuverlässiges Signal für die Entscheidung: Wenn die Teilaufgabe voraussichtlich weniger Kontext braucht, als sie für die Delegation selbst kostet, lohnt sich kein Subagent. Ebenso problematisch sind Aufgaben mit starken gegenseitigen Abhängigkeiten, bei denen ständig Informationen zwischen Subagent und Hauptagent hin- und herfließen müssten. In solchen Fällen entsteht durch die Isolation künstliche Reibung, weil jede Rückfrage einen neuen Delegationszyklus auslöst, statt dass der Agent einfach im laufenden Kontext weiterarbeitet.

8. Kosten, Latenz und Kontextverlust als reale Kehrseite

Subagents sind kein kostenloser Mechanismus. Jeder Subagent-Aufruf startet eine eigene Modellinferenz mit eigenem Tokenverbrauch, und bei paralleler Ausführung mehrerer Subagents summieren sich diese Kosten schnell. Wer zehn Subagents für eine Aufgabe startet, die auch ein einzelner Agent in wenigen Schritten hätte lösen können, zahlt für die Parallelisierung einen Tokenpreis, der den Zeitgewinn nicht immer rechtfertigt. Bei latenzkritischen, interaktiven Workflows kann das Warten auf mehrere Subagent-Ergebnisse zudem länger dauern als ein einzelner, sequenzieller Durchlauf, wenn die Koordination selbst Zeit kostet.

Die zweite reale Kehrseite ist Informationsverlust. Weil nur die finale Textantwort eines Subagenten in den Hauptkontext zurückfließt, gehen Zwischenschritte, Unsicherheiten und alternative Lösungswege verloren, die der Hauptagent möglicherweise gebraucht hätte, um eine fundierte Entscheidung zu treffen. Ein Subagent, der eine Annahme trifft, ohne sie explizit zu kommunizieren, kann den Hauptagenten in eine falsche Richtung lenken, ohne dass dieser die Grundlage der Annahme überprüfen kann. Diese Intransparenz ist ein bewusster Tradeoff für Kontexteffizienz, keine kostenlose Optimierung.

9. Subagents im direkten Vergleich zu Einzelagent-Workflows

Die Entscheidung zwischen Einzelagent und Subagent-Delegation hängt von der Struktur der Aufgabe ab, nicht von deren wahrgenommener Komplexität allein. Die folgende Übersicht fasst zusammen, wann welcher Ansatz in der Praxis die bessere Wahl ist.

In der Praxis bewährt sich ein einfacher Test vor jeder Entscheidung: Lässt sich die Teilaufgabe in einem einzigen, klaren Satz formulieren, und ist ihr Ergebnis unabhängig von anderen laufenden Teilaufgaben verwertbar? Wenn beides zutrifft, ist ein Subagent meist die richtige Wahl. Wenn die Aufgabe ständige Rückfragen erfordert oder direkt auf den bestehenden Konversationsverlauf angewiesen ist, bleibt ein einzelner Agent die robustere und günstigere Lösung.

10. Zusammenfassung

Subagents in Claude Code lösen ein konkretes Problem: Komplexe Mehrschritt-Aufgaben überladen ein einzelnes Kontextfenster mit Zwischenschritten, die für die eigentliche Entscheidung irrelevant sind. Ein Subagent kapselt eine fokussierte Teilaufgabe in einem eigenen Kontext und liefert nur das verwertbare Ergebnis zurück. Das lohnt sich besonders bei paralleler Recherche über unabhängige Bereiche einer Codebasis und bei isolierten Code-Review-Durchläufen, die eine echte zweite Perspektive statt einer Bestätigung der eigenen Arbeit brauchen.

Gleichzeitig ist Delegation kein Automatismus für bessere Ergebnisse. Jeder Subagent-Aufruf kostet zusätzliche Tokens und Zeit, und die Isolation verschluckt Zwischeninformationen, die der Hauptagent manchmal gebraucht hätte. Für einfache, eng verzahnte oder sequenziell abhängige Aufgaben bleibt ein einzelner Agent die robustere und günstigere Wahl. Die Kunst liegt darin, Aufgaben so zu schneiden, dass Delegation echten Mehrwert bringt, statt Komplexität ohne Gegenwert zu erzeugen.

11. FAQ: Subagents und Automatisierung in Claude Code