Claude Code Subagents und Worktrees: wann was

Claude Code Subagents teilen Arbeit innerhalb einer Session. Jeder läuft in einem eigenen Kontextfenster, erledigt eine Aufgabe und liefert eine Zusammenfassung. Worktrees trennen Dateiänderungen: Jede Session bekommt eine eigene Kopie des Repositorys und einen eigenen Branch. Unsere Regel aus der täglichen Arbeit mit parallelen Agenten: Subagents lesen nur, und jede Änderung bekommt ihren eigenen Worktree, ihre eigene Session und ihren eigenen Pull Request.

KI schreibt heute unseren gesamten Code, und ein Senior steht dafür ein, was in Produktion geht. Mit parallelen Agenten laufen mehrere Aufgaben gleichzeitig, ohne sich in die Quere zu kommen. Unten steht, wann wir was nutzen, der Befehl dahinter und was unterwegs kaputtging.

Was sind Claude Code Subagents?

Ein Subagent ist ein Helfer, den Claude in Ihrer Session startet. Die Claude Code Dokumentation sagt es in einem Satz: „Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.“ Jeder Subagent hat also ein eigenes Kontextfenster, einen eigenen System-Prompt, eigene Tools und Berechtigungen.

Genau darum geht es. Der Subagent liest einen Stapel Dateien, und in Ihre Hauptkonversation kommt ein Absatz zurück. Eigene Subagents definieren Sie in .claude/agents/: Name, Beschreibung, Tools und Modell. Claude wählt sie nach der Beschreibung aus, oder Sie rufen einen beim Namen.

Der Preis ist derselbe Absatz. Sie sehen, was der Subagent meldet, nicht was er gelesen hat. Hat er etwas übersehen, steht das nicht in der Zusammenfassung.

Subagents oder Worktrees: wofür was?

Sie lösen verschiedene Probleme. Subagents schützen Ihren Kontext. Worktrees schützen Ihre Dateien. Die Worktree-Dokumentation beschreibt einen Worktree als eigenes Arbeitsverzeichnis mit eigenen Dateien und eigenem Branch, das sich Historie und Remote mit dem Haupt-Checkout teilt.

Warum lesen unsere Subagents nur?

Wir haben es in das Briefing geschrieben, das jede Coding-Session bekommt:

Only you write code. Subagents only read (explore the repo, run a long test suite and return just the failures).

Code schreibt nur die Hauptsession. Subagents lesen nur: Sie erkunden das Repository oder lassen eine lange Testsuite laufen und melden nur die Fehler. Beim Schreiben von Dokumenten und bei Browser-QA ist die Grenze noch strenger: „Do it yourself, no subagents.“ Recherche ist das Gegenteil. Dort skaliert das Briefing die Subagents mit der Aufgabe: einer für einen einzelnen Fakt, ein paar für einen Vergleich, einer pro Punkt bei einer breiten Übersicht. Jeder schreibt seine Ergebnisse in eine Datei und gibt nur den Pfad zurück.

Claude Code kann Subagents auch schreiben lassen. Mit isolation: worktree bekommt ein Subagent einen eigenen temporären Worktree. Wir bleiben trotzdem bei einem Schreiber pro Aufgabe. Ein Reviewer folgt einem Diff und einem Gedankengang. Mehrere Schreiber an einer Aufgabe bedeuten mehrere Diffs, die jemand im Kopf zusammenführen muss.

Wie läuft bei uns ein Issue in einem Worktree?

Eine Aufgabe ist ein Worktree, ein Branch, eine Claude Code Session und ein Pull Request. Die Orchestrator-Session bleibt auf main im Haupt-Checkout und wechselt dort nie den Branch. Jede Änderung startet mit einem Befehl von wizrd, unserem internen Claude-Code-Plugin und CLI (nicht öffentlich):

wizrd task start <repo> "<brief>"

Was der Befehl macht:

1. Worktree. wizrd worktree new legt ihn in einem Worktree-Verzeichnis pro Rechner an. Env-Dateien werden aus dem Haupt-Checkout verlinkt, Abhängigkeiten nach Lockfile installiert.
2. Kontext. Ein Service, der im Repository eines Kunden liegt, bekommt einen Worktree dieses Repositorys mit dem Service an seinem Submodul-Pfad. So lädt jede CLAUDE.md nach oben. Skills und Agents der Repositorys darüber kommen per --add-dir dazu.
3. Session. Im Worktree startet claude --bg im Hintergrund. Wir verfolgen sie in claude agents und schreiben ihr per Nachricht zwischen Sessions, wenn sie etwas braucht.
4. PR. Die Session committet, pusht und öffnet einen Pull Request aus ihrem Branch. Nach dem Merge entfernt wizrd worktree prune den Worktree.

Ein Issue, das wir unserem KI-Agenten geben, läuft genauso, in der Schleife aus Harness Engineering in der Praxis: vom Issue zum PR. Derselbe Worktree-Code läuft auf dem Laptop eines Menschen und auf dem Rechner des Agenten. Wie der Agent vor der Arbeit einen Plan schreibt, steht in Claude Code Plan Mode.

Wann verschwenden Subagents Tokens?

Jeder Subagent startet mit frischem Kontext. Er sieht nicht, was Ihre Hauptsession schon gelesen hat, und liest es neu. Fragen Sie mehrere Subagents zum selben Modul, liest jeder es von vorn.

Worauf wir achten:

• Die Aufgabe ist klein. Eine Suche braucht keinen Helfer. Die Zusammenfassung kostet mehr als die Antwort.
• Die Aufgaben überschneiden sich. „Wie funktioniert der Login“ und „wo wird die Session geprüft“ schicken zwei Subagents in dieselben Dateien.
• Sie brauchen die Details. Ein Review, das genaue Zeilen zitieren muss, gelingt besser dort, wo diese Zeilen im Kontext bleiben.

Die Lösung sind meist weniger Subagents, nicht klügere.

Ehrlich gesagt: Den Token-Verbrauch pro Subagent messen wir nicht. Wir verfolgen Runden und aktive Zeit pro Aufgabe, und dort zeigt sich Verschwendung. Ein Fan-out lohnt sich für uns klar bei breiter Recherche mit unabhängigen Fragen und bei Arbeit, die den Aufrufer überfluten würde. Unser Skill für Meeting-Protokolle läuft als Fork (context: fork), damit ein langes Transkript nie in den Kontext des Aufrufers gelangt.

Was ging bei Worktrees kaputt?

Die Trennung ist der leichte Teil. Kaputt geht die Einrichtung. Diese Fälle lohnt es sich zu kennen:

• Eine fortgesetzte Aufgabe bekam ihren Worktree nicht. Ihr Branch war noch in einem älteren Worktree-Verzeichnis ausgecheckt, also schlug git worktree add fehl. Heute nutzt die CLI den Worktree, der den Branch schon hat, und ein Worktree-Verzeichnis pro Rechner ist fest vorgegeben, für Menschen und Agent.
• Die Env-Einrichtung war zu hilfsbereit. Sie verlinkte Env-Dateien in leere Submodul-Ordner und erzeugte .env-Dateien mit Platzhaltern aus Beispielen. Heute verlinkt sie nur, was der Haupt-Checkout wirklich hat.
• Ein Aufgaben-Branch verschob einen Submodul-Zeiger. In einem Repository aus Repositorys ändert das still, was alle anderen auschecken. Heute lässt unser Gate jeden Aufgaben-Branch scheitern, der einen verschiebt. Zeiger bewegen sich nur über einen eigenen Sync.
• Parallele Sessions in einem Checkout. Zwei Sessions, die im selben Ordner Branches wechseln, zerstören gegenseitig ihre nicht committete Arbeit. Deshalb bleibt der Haupt-Checkout auf main, und niemand baut dort.

Der letzte Punkt ist der Grund, warum es Worktrees überhaupt gibt. Die ersten drei sind der Grund, warum wir sie in einen Befehl gepackt haben, statt git worktree add von Hand zu tippen.

Wie starten Sie im eigenen Repository?

Unsere CLI brauchen Sie nicht. Die Grundlagen deckt Claude Code ab:

Dann kommen die Checks dazu, mit denen sich parallele Arbeit sicher reviewen lässt: Tests, Typen und ein CI-Gate, das auf jedem Branch grün sein muss. Hooks, die gefährliche Befehle stoppen, stecken in unserem öffentlichen Claude Code Production Starter. Was in die Regeln gehört, die jede Session liest, steht in CLAUDE.md und AGENTS.md: Regeln für KI-Code im Team.

Ist Ihr Repository bereit für parallele Agenten?

Das echte Limit ist das Review. Unser Dispatcher startet keine neue Agenten-Aufgabe, solange Agenten-PRs auf Menschen warten. Mehr parallele Agenten als Reviewer machen nur die Warteschlange länger.

Parallele Agenten im Repository Ihres Teams?

Das richten wir direkt im Repository eines Teams ein, im Rahmen von AI-native SDLC für Entwicklerteams: Worktrees, Regeln, Hooks und die Checks, die Agenten-PRs reviewbar machen. Fehlen Ihnen eher Hände als Setup? Sehen Sie sich einen Senior-Entwickler für Ihr Team an. Seit 2023 haben wir 15+ Produktionsprojekte geliefert.

Wir melden uns innerhalb von zwei Arbeitstagen und wählen gemeinsam, was wir zuerst lösen.

Wenn Sie lieber zuerst sprechen möchten, buchen Sie ein 15-Minuten-Meeting mit Filip.

Wie viele Agenten lässt Ihr Team heute gleichzeitig laufen, und wer reviewt ihre Arbeit?

Häufige Fragen

Was ist ein Subagent in Claude Code?

Ein Helfer, den Claude in Ihrer Session startet. Er läuft in einem eigenen Kontextfenster mit eigenem Prompt, eigenen Tools und Berechtigungen, erledigt eine Aufgabe und liefert eine Zusammenfassung. Die Hauptkonversation bleibt klein.

Was ist der Unterschied zwischen Subagents und Worktrees?

Subagents teilen Arbeit innerhalb einer Session und schützen deren Kontext. Worktrees trennen Dateiänderungen: Jede Session bekommt eine eigene Kopie der Dateien und einen eigenen Branch. Wir nutzen Subagents zum Lesen und einen Worktree für jede Änderung.

Können Subagents parallel Code schreiben?

Ja. Mit isolation: worktree gibt Claude Code jedem einen eigenen temporären Worktree. Wir bleiben trotzdem bei einem Schreiber pro Aufgabe, weil ein Reviewer einem Diff und einem Gedankengang viel besser folgt als mehreren.

Wie starte ich Claude Code in einem Worktree?

Mit claude --worktree <name>. Claude Code legt den Worktree unter .claude/worktrees/ auf einem neuen Branch an. Nehmen Sie .claude/worktrees/ in .gitignore auf und listen Sie die Env-Dateien, die ein frischer Checkout braucht, in .worktreeinclude.

Wann verschwenden Subagents Tokens?

Wenn ihre Aufgabe klein ist oder sich mit einer anderen überschneidet. Jeder Subagent startet mit frischem Kontext und liest erneut, was die Hauptsession schon gelesen hat. Ein Fan-out lohnt sich bei breiter Recherche mit unabhängigen Fragen.