Wann Subagents statt einem Agenten sinnvoll sind

1. Was Subagents in Claude Code konkret sind

Ein Subagent in Claude Code ist eine eigenständige Agenteninstanz, die für eine klar abgegrenzte Teilaufgabe gestartet wird und einen eigenen Kontext erhält, statt den kompletten Verlauf der Hauptunterhaltung zu übernehmen. Ein Hauptagent kann einen oder mehrere Subagents beauftragen, deren Ergebnis abwarten und anschließend in die eigene Antwort einbauen. Diese Trennung unterscheidet sich fundamental davon, einfach mehr Nachrichten an denselben Agenten zu schicken.

Der zentrale Unterschied zu einem einzelnen, durchgehenden Agenten liegt im Kontextmanagement: Während ein Einzelagent seinen Kontext über die gesamte Sitzung hinweg aufbaut und dadurch mit jeder weiteren Aufgabe voller wird, startet ein Subagent mit einem gezielt zusammengestellten, meist deutlich kleineren Kontext. Das macht Subagents besonders geeignet für Teilaufgaben, die viel Detailwissen benötigen, das für den Rest der Unterhaltung irrelevant ist, etwa das Durchsuchen einer großen Codebasis nach einer bestimmten Funktion.

Subagents in Claude Code lassen sich zudem mit eigenen, engeren Werkzeugrechten konfigurieren. Ein Subagent, der ausschließlich Dateien lesen soll, bekommt keinen Schreibzugriff, selbst wenn der Hauptagent selbst Schreibrechte besitzt. Diese Eigenschaft macht Subagents nicht nur zu einem Werkzeug für Kontexttrennung, sondern auch zu einem Sicherheitsmechanismus, der Berechtigungen granularer steuerbar macht als ein einzelner Agent mit einem einzigen Berechtigungsprofil.

{
  "main_agent": {
    "tools": ["read_file", "write_file", "run_tests", "grep", "list_directory"]
  },
  "subagent": {
    "name": "codebase_search_subagent",
    "tools": ["read_file", "grep", "list_directory"],
    "denied_tools": ["write_file", "run_tests"],
    "context": "fresh, no history from main agent session",
    "returns": "distilled result only, not raw file contents"
  }
}

2. Symptome dafür, dass ein einzelner Agent an Grenzen kommt

Bevor man sich für Subagents statt eines Einzelagenten entscheidet, lohnt sich ein Blick auf typische Warnsignale. Ein deutliches Symptom ist, dass die Antwortqualität mit fortschreitender Sitzung spürbar nachlässt, obwohl die Aufgabe selbst nicht schwieriger geworden ist. Das deutet darauf hin, dass der Kontext mit irrelevanten Details aus früheren Teilschritten überfrachtet ist und relevante Informationen im Rauschen untergehen.

Ein zweites Symptom sind stark schwankende Antwortzeiten innerhalb derselben Sitzung, die häufig mit wachsendem Kontext zusammenhängen, weil größere Kontextfenster mehr Verarbeitungszeit benötigen. Ein drittes Symptom zeigt sich, wenn ein Agent zwischen fachlich sehr unterschiedlichen Rollen hin und her wechseln muss, etwa zwischen tiefem Code-Verständnis und oberflächlicher Dokumentationsarbeit. Solche Rollenwechsel innerhalb eines einzigen Agenten führen häufig zu inkonsistenten Ergebnissen, weil der Agent implizit zwischen unterschiedlichen Denkmodi springen muss, ohne dass diese Grenze im Kontext klar markiert ist.

3. Kriterium eins: Kontextgröße und Themenwechsel

Das erste und wichtigste Entscheidungskriterium für Subagents ist die Frage, wie stark sich der benötigte Kontext zwischen Teilaufgaben unterscheidet. Wenn eine Teilaufgabe das Durchsuchen hunderter Dateien erfordert, deren Inhalt für die eigentliche Hauptaufgabe irrelevant ist, sollte diese Suche in einem Subagent stattfinden. Der Hauptagent erhält am Ende nur das destillierte Ergebnis, nicht die vollständigen Dateiinhalte, die er durchsucht hat.

Als Faustregel gilt: Wenn eine Teilaufgabe mehr als etwa ein Viertel des verfügbaren Kontextfensters allein für Rechercheschritte verbrauchen würde, die für nachfolgende Schritte nicht mehr gebraucht werden, sprechen die Zahlen für einen Subagent. Dieses Kriterium lässt sich objektiv prüfen, indem man abschätzt, wie viele Tokens die Zwischenschritte einer Teilaufgabe im Vergleich zum tatsächlich relevanten Ergebnis benötigen.

# Rough heuristic: estimate whether a subtask justifies a subagent
# Rule of thumb: if intermediate tokens >> final result tokens, use a subagent

estimate_subagent_benefit() {
  local intermediate_tokens="$1"
  local result_tokens="$2"
  local ratio
  ratio=$(echo "scale=1; $intermediate_tokens / $result_tokens" | bc)

  echo "Intermediate/result token ratio: ${ratio}x"
  if (( $(echo "$ratio > 5" | bc -l) )); then
    echo "Recommendation: use a subagent, discard intermediate context"
  else
    echo "Recommendation: keep it in the main agent context"
  fi
}

# Example: searching 40 files (~20000 tokens) to find one relevant function (~400 tokens)
estimate_subagent_benefit 20000 400

4. Kriterium zwei: Spezialisierung und Werkzeugzugriff

Das zweite Kriterium für Subagents betrifft die fachliche Spezialisierung einer Teilaufgabe. Manche Teilschritte profitieren von einem eigenen Systemprompt, der genau auf diese eine Rolle zugeschnitten ist, etwa ein Subagent, der ausschließlich auf Sicherheitslücken in Code prüft und dafür eine speziell formulierte Anweisung mit Fokus auf typische Schwachstellenklassen erhält. Ein solcher spezialisierter Systemprompt würde den Hauptagenten in seiner allgemeinen Rolle nur verwässern, wenn er dauerhaft Teil des Hauptkontexts wäre.

Ergänzend spielt der benötigte Werkzeugzugriff eine Rolle. Braucht eine Teilaufgabe Zugriff auf ein Werkzeug, das der Hauptagent aus Sicherheitsgründen nicht dauerhaft zur Verfügung haben sollte, etwa das Ausführen von Datenbankabfragen, ist ein Subagent mit eng begrenztem Werkzeugzugriff die sauberere Lösung. So bleibt der Hauptagent in seiner Grundkonfiguration unverändert restriktiv, während die Spezialaufgabe trotzdem erledigt werden kann.

#!/usr/bin/env bash
# Invoke a narrowly specialized subagent for a security-focused subtask
set -euo pipefail

claude --agent-config "subagents/security_reviewer.json" \
  --system-prompt "Check only for insecure deserialization, missing input \
validation and access control gaps. Ignore style and naming conventions." \
  --tools "read_file,grep" \
  --input "src/Model/Checkout/" \
  --output "reports/security-subtask.json"

echo "[main_agent] Security subagent finished, integrating distilled findings"

5. Kriterium drei: Parallelisierbarkeit der Teilaufgaben

Das dritte Kriterium ist die Frage, ob mehrere Teilaufgaben unabhängig voneinander bearbeitet werden können. Müssen etwa drei verschiedene Module einer Anwendung auf denselben Fehlertyp geprüft werden, lassen sich drei Subagents parallel starten, die jeweils ein Modul untersuchen, statt dass ein Einzelagent die Module nacheinander abarbeitet. Bei unabhängigen Teilaufgaben verkürzt sich die Gesamtlaufzeit dadurch erheblich, während bei einem Einzelagenten die Zeit linear mit der Anzahl der Module steigt.

Wichtig ist dabei die ehrliche Prüfung der Unabhängigkeit: Wenn das Ergebnis der Prüfung von Modul A das Vorgehen bei Modul B beeinflussen sollte, etwa weil ein gemeinsames Muster erst in Modul A entdeckt werden muss, ist die Aufgabe nicht wirklich unabhängig und Parallelisierung mit Subagents bringt hier keinen Vorteil, sondern nur zusätzliche Komplexität ohne Zeitgewinn.

6. Kosten und Latenz: Der Preis der Aufteilung in Subagents

Der Einsatz von Subagents ist nicht kostenlos. Jeder Subagent benötigt einen eigenen Systemprompt, muss gegebenenfalls relevanten Kontext vom Hauptagenten übernehmen und produziert ein eigenes Ergebnis, das der Hauptagent wieder einordnen muss. Bei sehr kleinen Teilaufgaben kann dieser Koordinationsaufwand größer sein als die eigentliche Einsparung durch kleineren Kontext, wodurch die Gesamtlatenz trotz kleinerer Einzelkontexte steigt statt sinkt.

Eine praktikable Regel: Subagents lohnen sich erst, wenn die eingesparte Kontextmenge im Hauptagenten den zusätzlichen Overhead für Start, Übergabe und Ergebnisintegration klar übersteigt. Für sehr kurze, einfache Nachfragen, etwa das schnelle Nachschlagen einer einzelnen Konstante, lohnt sich ein eigener Subagent in aller Regel nicht, selbst wenn das Kriterium der Themenfremdheit formal erfüllt wäre.

{
  "subagent_config": {
    "name": "security_scan_subagent",
    "trigger_condition": "task requires scanning more than 20 files for one pattern",
    "system_prompt": "Scan the given files for the specified vulnerability class only. Return findings as a compact JSON list, no prose explanation.",
    "tools": ["read_file", "grep"],
    "max_output_tokens": 2000
  },
  "estimated_cost_tradeoff": {
    "without_subagent_context_tokens": 45000,
    "with_subagent_main_context_tokens": 6000,
    "subagent_overhead_tokens": 1200,
    "net_savings_tokens": 37800
  }
}

7. Praxisbeispiel: Ein Refactoring mit und ohne Subagents

Ein anschauliches Beispiel: Ein Legacy-Modul in einer Magento-Erweiterung soll von einer alten auf eine neue Repository-Schnittstelle migriert werden. Ohne Subagents müsste der Hauptagent zunächst alle Aufrufstellen der alten Schnittstelle im gesamten Repository suchen, was bei einer großen Codebasis leicht mehrere zehntausend Tokens an Dateiinhalten in den Kontext lädt, von denen am Ende nur eine Handvoll relevanter Codezeilen tatsächlich geändert werden.

Mit Subagents übernimmt ein spezialisierter Such-Subagent das Auffinden aller Aufrufstellen und liefert dem Hauptagenten nur eine kompakte Liste mit Dateipfad und Zeilennummer zurück. Der Hauptagent, dessen Kontext dadurch schlank bleibt, kann sich anschließend vollständig auf die eigentliche Migration konzentrieren, ohne durch irrelevante Suchergebnisse abgelenkt zu werden. In diesem Fall zeigt sich der Vorteil von Subagents besonders deutlich, weil Suche und Migration fachlich klar getrennte Tätigkeiten sind.

#!/usr/bin/env bash
# Search subagent finds all call sites, main agent only migrates
set -euo pipefail

claude --agent-config "subagents/callsite_search.json" \
  --system-prompt "Find every call site of LegacyPriceRepositoryInterface. \
Return only file path and line number as a compact JSON list." \
  --tools "grep,read_file" \
  --input "app/code/Mironsoft/" \
  --output "state/callsites.json"

# Main agent context stays lean: it only receives the distilled list
echo "[main_agent] Migrating $(jq '. | length' state/callsites.json) call sites"

8. Typische Fehler bei der Entscheidung für oder gegen Subagents

Ein häufiger Fehler ist der reflexartige Einsatz von Subagents für jede Teilaufgabe, unabhängig davon, ob die drei genannten Kriterien tatsächlich zutreffen. Das führt zu unnötiger Komplexität, längeren Laufzeiten durch Koordinationsoverhead und schwerer nachvollziehbaren Abläufen, ohne dass ein realer Nutzen entsteht. Subagents sind ein gezieltes Werkzeug, kein Standardverfahren für jede Anfrage.

Der entgegengesetzte Fehler ist ebenso verbreitet: Ein Einzelagent wird über Stunden mit immer neuen, fachlich unterschiedlichen Teilaufgaben beladen, bis der Kontext so überfüllt ist, dass die Ergebnisqualität sichtbar leidet. In diesem Fall hätten frühzeitig eingesetzte Subagents für klar abgrenzbare Rechercheschritte die Kontextbelastung des Hauptagenten deutlich reduziert und die Gesamtqualität der Sitzung verbessert.

9. Einzelagent und Subagents im direkten Vergleich

Die folgende Tabelle fasst zusammen, welche Situationen für einen Einzelagenten sprechen und welche für den Einsatz von Subagents.

Die Entscheidung für oder gegen Subagents lässt sich also nicht pauschal treffen, sondern hängt von der konkreten Struktur der Aufgabe ab. Wer die drei Kriterien Kontextgröße, Spezialisierung und Parallelisierbarkeit systematisch prüft, trifft eine begründete statt eine intuitive Entscheidung.

10. Zusammenfassung

Subagents lohnen sich immer dann, wenn eine Teilaufgabe deutlich mehr Kontext verbraucht, als für das Endergebnis relevant ist, wenn sie eine eigene fachliche Spezialisierung oder engere Werkzeugrechte braucht, oder wenn mehrere Teilaufgaben unabhängig voneinander parallel bearbeitet werden können. Treffen keines dieser drei Kriterien zu, bleibt ein Einzelagent die effizientere und einfachere Wahl.

Die Entscheidung zwischen Einzelagent und Subagents ist keine Grundsatzfrage, sondern eine Frage der Aufgabenstruktur im Einzelfall. Wer die drei Kriterien konsequent anwendet und dabei auch den zusätzlichen Koordinationsoverhead ehrlich einpreist, vermeidet sowohl unnötige Komplexität als auch überladene, langsam werdende Einzelagenten.

11. FAQ: Wann Subagents statt einem Agenten sinnvoll sind