Claude Code Subagents: Parallele Tasks mit Worktree-Isolation

In Teil 1 der Claude-Code-Serie ging es um Permissions, Rules und Skills — die drei Hebel, die Claude Code vom Spielzeug zum Team-Werkzeug machen. Das reicht für Solo-Devs und kleine Teams. Sobald eine Aufgabe größer wird — eine User Story mit Backend, Frontend und anschließendem Code-Review, ein Feature mit mehreren Stories parallel — stößt der Haupt-Claude an seinen Kontext-Horizont. Das ist der Moment für Claude Code Subagents.

Subagents sind eigenständige Claude-Prozesse mit eigenem Kontext, eigenen Permissions und einer eigenen System-Prompt-Definition. Mit dem richtigen Orchestrierungs-Pattern lassen sich mehrere Stories parallel implementieren, ohne dass die Agents sich gegenseitig in die Quere kommen. Dieser Teil 2 der Serie zeigt, wie das in unserem eigenen Setup konkret aussieht.

Was Subagents sind — und was sie nicht sind

Ein Subagent ist eine Markdown-Datei mit Frontmatter unter .claude/agents/{name}.md (projektspezifisch) oder ~/.claude/agents/{name}.md (global). Wird der Subagent über das Agent-Tool aufgerufen, startet Claude Code einen neuen Prozess mit:

• Eigenem Kontext. Keine Konversations-Historie aus der Haupt-Session — der Subagent startet fresh mit seinem Prompt.
• Eigener System-Prompt-Definition. Aus dem Body der Markdown-Datei.
• Eigenen Permissions. Optional via allowed-tools-Frontmatter beschränkbar (z. B. nur Read, Grep, Bash).
• Eigenem Modell-Aufruf. Jeder Subagent-Run ist eine eigenständige API-Abrechnung.

Was Subagents nicht sind: keine Threads, keine Funktionen, keine parallel laufenden Sessions desselben Modells im selben Kontext. Sie sind eher mit Microservices vergleichbar als mit Threads — eigenständige Einheiten mit klar definierter Schnittstelle und keinem geteilten Zustand.

Minimal-Anatomie

Eine Subagent-Definition besteht aus drei Teilen — Frontmatter, System-Prompt-Body, optionale Strukturierung:

---
name: code-reviewer
description: Reviews code changes against project conventions and quality standards.
allowed-tools: Read, Grep, Glob, Bash
---

You are a code reviewer. Your job is to ...

## First Steps
1. Read CLAUDE.md ...
2. ...

## Output Format
- Findings grouped by severity
- ...

Die description ist nicht Kosmetik — sie ist das Trigger-Signal, das der Haupt-Claude verwendet, um zu entscheiden, ob ein Subagent für einen Task passt, wenn er nicht explizit aufgerufen wird.

Drei Gründe, warum Subagents lohnen

Subagents sind nicht für jeden Task die richtige Antwort. Aber wo sie passen, lösen sie Probleme, die mit der Haupt-Session schmerzhaft umständlich sind.

1. Context-Isolation. Der Haupt-Claude trägt nach einer halben Stunde Arbeit viel Kontext mit sich: gelesene Files, vorherige Tool-Aufrufe, Konversations-Historie. Das ist meist hilfreich — aber nicht für jede Sub-Aufgabe. Ein Such-Agent, der nach einem Symbol fahndet, profitiert null von dem geladenen Kontext und kostet umgekehrt Tokens für jeden Suchschritt. Ein Subagent macht den Job mit minimalem Kontext und gibt das Ergebnis kompakt zurück.

2. Parallelisierung. Ein Backend-Task und ein Frontend-Task, die beide eine User Story bedienen, können theoretisch nacheinander laufen: sobald die Backend-API existiert, baut das Frontend dagegen. Mit Subagents, die unabhängige Worktrees benutzen, laufen beide parallel — die Backend-API-Spec ist der Vertrag, das Frontend baut gegen den vereinbarten Endpoint, beide pushen am Ende auf main. Halbe Wand-Zeit für die gleiche Liefermenge.

3. Spezialisierung. Ein Backend-Subagent kennt nur Backend-Patterns, nur Backend-Permissions (dotnet build, dotnet test), kein Frontend-Tooling, keine Versuchung, “schnell mal” am React-Code zu schrauben. Ein Code-Reviewer-Subagent darf nur lesen — keine Modifikations-Tools, keine Möglichkeit, im Review “schnell zu fixen”. Die Beschränkung ist ein Quality-Gate, keine Limitierung.

Pattern — spezialisierte Worker-Agents

Unser eigenes Setup für .NET/React-Projekte: vier spezialisierte Subagents, plus ein Orchestrator-Skill.

~/.claude/agents/
├── dev-backend.md        # .NET-Backend-Implementierung einer Story
├── dev-frontend.md       # React/TS-Frontend-Implementierung einer Story
├── dev-wpf.md            # WPF-Desktop-Implementierung
└── code-reviewer.md      # Read-only Review gegen CLAUDE.md-Konventionen

Jede dieser Agent-Definitionen folgt der gleichen Grundstruktur:

1. First Steps. Was der Agent zuerst tun muss: CLAUDE.md lesen, relevante Architektur-Sektionen lesen, git pull origin main, das Issue aus GitHub lesen.

2. Scope Boundary. Was der Agent nicht tun darf. Beispiel aus unserer dev-backend.md:

   You MUST NOT create or modify any frontend files (TypeScript, React, styles, frontend routes). Touch any frontend directories. Install frontend npm packages or run frontend commands. If the story requires frontend changes, report it back — the orchestrator will handle it.

3. Implementation Workflow. Plan → Implement → Build & Test → Commit.

4. Finalize. Squash → Rebase → Push direkt auf main. Bei Push-Konflikt: re-fetch, re-rebase, re-push.

Die Scope-Boundary ist der wichtigste Teil — ohne sie editieren parallele Agents fröhlich an Code, der nicht ihrer Spezialisierung entspricht, und provozieren Merge-Konflikte, die niemand sauber auflösen kann.

Worktree-Isolation — das kritische Pattern bei Parallelität

Sobald zwei oder mehr Subagents gleichzeitig am gleichen Repo arbeiten, gibt es ein Problem: zwei Prozesse, ein Working Directory, eine .git-Datenbank. Wer editiert was, wer committed welchen Stand, wessen unsaubere Datei landet in wessen Commit?

Die Lösung ist eine Git-Funktion, die viele Devs noch nie aktiv genutzt haben: git worktree. Ein Worktree ist ein zusätzliches Working Directory, das dasselbe .git-Repo teilt, aber auf einem anderen Branch oder Commit checked-out ist. Mehrere Worktrees können parallel existieren, jeder mit eigenem Dateisystem-Stand.

Claude Code unterstützt das nativ. Beim Spawn eines Subagents:

Agent({
  subagent_type: "dev-backend",
  isolation: "worktree",
  prompt: "Implementiere Story #142 ..."
})

Der isolation: "worktree"-Parameter sorgt dafür, dass der Subagent in einem eigenen, temporären Worktree arbeitet. Das Haupt-Repo bleibt unberührt, parallel laufende Subagents haben ihre eigenen Working Directories.

Cleanup-Verhalten:

• Macht der Subagent keine Änderungen, wird der Worktree am Ende automatisch entfernt.
• Macht der Subagent Änderungen, bleibt der Worktree liegen (mit Pfad und Branch-Name im Agent-Result), damit der Orchestrator die Arbeit inspizieren kann.

In unserem Pattern pushen die Subagents am Ende direkt auf main (siehe nächste Sektion); der Worktree-Cleanup passiert beim Orchestrator- Abschluss.

Orchestrierungs-Skill — der Eintrittspunkt

Subagents kann man manuell aufrufen. Das skaliert nicht. Spätestens bei einem Feature mit drei Backend-Stories und zwei Frontend-Stories will man:

• automatisch parallel spawnen, was parallel laufen kann
• automatisch sequenzieren, was voneinander abhängt
• Ergebnisse einsammeln und konsolidiert berichten

Genau dafür gibt es Skills als Orchestrierungs-Layer. Ein typischer /dev-Skill (gekürzt):

---
name: dev
description: Implements user stories from GitHub Issues by spawning
  specialized backend or frontend agents in parallel with worktree isolation
---

You are a development orchestrator. Your job is to analyze user stories,
plan execution order, and spawn specialized agents to implement them.
You do NOT implement code yourself.

## Phase 0 — Context
Read CLAUDE.md to determine GitHub owner/repo. Ask the user for an issue
number — single story or feature (with sub-stories).

## Phase 1 — Story Analysis
Read the issue. Determine type from labels:
- `backend` → spawn `dev-backend`
- `frontend` → spawn `dev-frontend`

For a feature with multiple stories:
- Parse `Depends on #N` from each story body
- Build a dependency graph
- Group into phases: phase 1 = no dependencies, phase 2 = depends on
  phase 1 only, ...

## Phase 2 — Execution
For each phase, spawn worker agents in parallel using the Agent tool:
- subagent_type: matching agent
- isolation: "worktree"
- prompt: assignment block with issue details

Was dieser Skill konkret leistet:

• Story-Splitting. Aus einem Feature-Issue werden die Sub-Stories ausgelesen, nach Backend/Frontend klassifiziert.
• Dependency-Graph. Aus Depends on #N-Markern im Story-Body wird ein Graph gebaut, der entscheidet, welche Stories parallel laufen dürfen.
• Phase-Ausführung. Phase 1 = alle Backend-Stories ohne Vorgänger, parallel. Phase 2 = Frontend-Stories, deren Backend in Phase 1 fertig ist, plus Backend-Stories mit Vorgängern aus Phase 1.
• Result-Konsolidierung. Nach jeder Phase wird geprüft, welche Agents erfolgreich waren, welche gefailt sind, und ob das nächste Phase-Level starten kann.

Das ist nicht magisch — es ist klassische Build-Pipeline-Logik, in einen KI-Workflow gegossen. Aber gerade deswegen funktioniert es: bekannte Patterns, klare Phasen, deterministisches Verhalten.

Trade-offs — wann Subagents nicht lohnen

Subagents sind kein Free-Lunch. Vier Kosten, die ehrlich auf dem Tisch liegen müssen:

1. Context-Cost pro Spawn. Jeder Subagent zahlt einmal für den Aufbau seines Kontextes: CLAUDE.md, Rules, Issue, gegebenenfalls Architektur-Dokumente. Bei einem Task, der in dreißig Minuten erledigt ist, ist dieser Aufbau-Overhead größer als der Nutzen der Isolation.

2. Coordination-Overhead. Der Orchestrator muss spawnen, Results empfangen, Fehler abfangen, eventuell retry-loopen. Das ist Code (im Skill), der gewartet werden muss.

3. Debugging schwerer. Drei parallele Logs sind schwerer zu folgen als ein chronologischer Stream. Wenn etwas schiefgeht, muss der Orchestrator das so reporten, dass der Mensch sofort weiß, welcher Agent stolperte und woran.

4. Höhere Token-Last. Mehr Agents, mehr Kontext, mehr API-Calls. Wenn das Budget pro Story gemessen wird, ist Single-Agent oft günstiger.

Wann Single-Agent reicht:

• Kleine Bugfixes, einzelne Refactorings
• Tasks, die unter dreißig Minuten dauern
• Exploration ohne klare Sub-Tasks

Wann Subagents sich lohnen:

• User Stories mit klarer Backend/Frontend-Trennung
• Features mit mehreren parallel-fähigen Sub-Stories
• Code-Review als separater Quality-Gate (Read-only Subagent, das nichts schreibt)
• Long-running Investigations, bei denen der Sub-Task den Hauptkontext nicht “vergiften” soll

Drei Pattern aus unserer Praxis

Drei Dinge, die wir erst beim zweiten Anlauf richtig hinbekommen haben:

Pattern 1: Scope-Boundary explizit machen. Im ersten Versuch hatten unsere Worker-Agents keine harten “MUST NOT”-Regeln. Folge: Der dev-backend-Agent hat fröhlich am React-State-Management mitgeschraubt, weil sein Story-Prompt nebenbei eine Frontend-Implikation hatte. Der parallel laufende dev-frontend-Agent hat dieselben React-Files editiert. Merge-Konflikt im Worktree, beide Pushs scheitern. Heute stehen in jedem Worker-Agent harte Scope-Boundaries (MUST NOT-Listen mit konkreten Pfaden und Tools).

Pattern 2: Direkt-auf-main statt PR-Flow. Erster Versuch: Feature-Branch pro Agent, am Ende PRs mergen. Das skaliert nicht — bei fünf parallelen Agents hat man fünf PRs, die sich gegenseitig ins Gehege kommen. Heute: jeder Agent macht Squash + Rebase auf main, pusht direkt. Bei Push-Konflikt: re-fetch, re-rebase, re-push. Das hat einen Preis (kein PR-Review für die Agent-Commits, weil keiner mehr da ist) und braucht entsprechend andere Quality-Gates — dafür kommen Hooks und Code-Reviewer-Subagents ins Spiel.

Pattern 3: Phase-Graph statt freier Parallelität. Anfangs hatten wir den Orchestrator “spawne alles, was theoretisch unabhängig ist” ausführen lassen. Folge: Frontend-Agents liefen los, bevor ihre Backend-Endpoints existierten — und scheiterten. Heute parsen wir Depends on #N-Marker und spawnen Phasen-weise. Phase 1 = nur Stories ohne offene Dependency, Phase 2 = Stories, deren Dependencies in Phase 1 abgeschlossen wurden.

Fazit

Subagents sind das, was Claude Code von einem Solo-Tool zur Team-Plattform skaliert. Drei Hebel sind wesentlich:

• Spezialisierte Worker-Agents mit harten Scope-Boundaries und klarem Workflow
• Worktree-Isolation als technische Voraussetzung für echte Parallelität ohne File-Konflikte
• Orchestrierungs-Skill als Eintrittspunkt, der Stories klassifiziert, Phasen baut und Agents koordiniert

Wer das sauber aufsetzt, implementiert Features mit drei bis fünf parallelen Stories in einem Bruchteil der Zeit, die Single-Agent-Setups brauchen — bei gleicher oder besserer Qualität, weil jeder Worker spezialisiert ist.

Im nächsten Teil der Serie geht es um Hooks — Shell-Skripte, die vor oder nach Tool-Calls automatisch laufen. Damit lassen sich harte Quality-Gates bauen: Linter-Pflicht vor Commit, Format-Check vor Push, Test-Trigger bei kritischen Pfaden. Das schließt die Klammer von Permissions, Rules und Skills aus Teil 1 über Subagents und Orchestrierung hin zu automatisierten Sicherheits- Schienen.

---

Wer 2026 über die Auswahl eines KI-fähigen Software-Partners nachdenkt — wir haben dazu sechs Kriterien aufgeschrieben. Wenn Sie Claude Code (oder ein vergleichbares Tool) in Ihrem Team produktiv aufsetzen wollen und einen Sparringspartner suchen, der das schon mehrfach durchgezogen hat — buchen Sie gerne ein kostenloses Erstgespräch.

Tech42 baut individuelle Software mit modernen KI-Tools im Engineering-Alltag — nicht als Marketing-Begriff, sondern als Teil unseres Stacks. Wie sich die Senior-Entwickler-Rolle dabei generell verschiebt, beschreibt unser Artikel Wie KI die moderne Softwareentwicklung verändert.