Claude Code Subagents: Praxisleitfaden für sichere Agent-Delegation

Wenn Arbeit in Claude Code groß wird, bricht meistens nicht zuerst das Modell. Es bricht die Arbeitsaufteilung. Eine einzige Unterhaltung, die Recherche, Schreiben, Übersetzung, Codeänderung, Checks und Review für zehn lokalisierte Dateien tragen soll, wird schnell schwer. Der Agent liest dieselben Dateien mehrfach, Logs füllen den Kontext, und am Ende ist unklar, welche Datei aus welchem Grund geändert wurde.

Subagents helfen, weil sie begrenzte Aufgaben in einem getrennten Kontext erledigen. Delegation heißt hier nicht: “Ein anderer Agent macht alles.” Delegation heißt: ein kleiner Vertrag mit Ziel, erlaubten Dateien, verbotenen Dateien, Fertigkriterien und Rückgabeformat. Dieser Vertrag verhindert, dass parallele Arbeit zu doppelter Arbeit wird.

Dieser Leitfaden basiert auf dem ClaudeCodeLab-Workflow: einen japanischen Canonical-Artikel schreiben, ihn in zehn Sprachen lokalisieren, Prompt-Templates prüfen und vor der Veröffentlichung reviewen. Dasselbe Muster funktioniert für Codeänderungen, Dokumentation, Migrationen und Release-Vorbereitung.

Was ein Subagent ist

Ein Subagent ist ein spezialisierter Arbeiter, der außerhalb des Hauptkontexts läuft. Kontext ist der Arbeitsspeicher, den Claude gerade sieht: Chat, gelesene Dateien, Kommandoausgaben, Projektregeln und Zusammenfassungen. Wenn eine Aufgabe viele Suchergebnisse oder Logs erzeugt, kann ein Subagent diese Last übernehmen und nur die nützliche Zusammenfassung zurückgeben.

Die offiziellen Referenzen sind die Claude Code Seiten zu Subagents, Memory und Slash commands. Für die Praxis sind drei Punkte wichtig: Subagents starten mit isoliertem Kontext, Projekt-Agenten können in .claude/agents/ liegen, und lange Rückgaben verbrauchen trotzdem wieder Hauptkontext.

Begriff	Einfache Bedeutung
Subagent	Spezialisierter Arbeiter für Recherche, Implementierung, Übersetzung oder Review
Kontext	Aktueller Arbeitsspeicher, den Claude sieht
disjoint write set	Bearbeitbare Dateien eines Workers ohne Überschneidung mit anderen
explorer	Read-only Agent, der zuerst den Umfang kartiert
worker	Agent, der nur zugewiesene Dateien bearbeitet
handoff contract	Vertrag über Umfang, Grenzen, Fertigkriterien und Rückgabe

Wann delegieren

Subagents sind kein Selbstzweck. Eine kleine Änderung wird langsamer, wenn jeder Agent erst wieder Kontext sammeln muss. Entscheidend ist, ob Kontexttrennung wirklich hilft und ob die Schreibbereiche sauber getrennt werden können.

Arbeit	Delegieren?	Warum
Einen Artikel in zehn Sprachen lokalisieren	Ja	Jede Sprache hat eigene Dateien und klare Qualitätskriterien
Großes Codebase nach Konventionen durchsuchen	Ja	Der Hauptthread braucht die Karte, nicht jedes Suchergebnis
Einen Tippfehler korrigieren	Nein	Koordination ist teurer als die Änderung
Authentifizierung breit refactoren	Vielleicht	Zuerst explorer nutzen und Auswirkungen klären
Unklare neue Funktion planen	Noch nicht	Anforderungen zuerst im Hauptthread schärfen

Meine Regel: Delegiere nur, wenn die Aufgabe viel Zwischeninformation produziert, jeder worker auf konkrete Dateien begrenzt werden kann und das Ergebnis als Tabelle, Checkliste oder kurzer Beleg zurückkommen kann.

Grundmuster: explorer, worker, reviewer

Starte bei wichtiger Arbeit nicht mit mehreren editierenden Agents. Starte mit einem explorer. Er liest nur, findet relevante Dateien, bestehende Muster und Risiken und schlägt write sets vor. Danach bearbeiten worker getrennte Dateimengen. Zum Schluss prüft ein reviewer oder verification agent read-only.

flowchart TD
  A["Main: goal and constraints"] --> B["Explorer: read only, map scope"]
  B --> C["Main: decide disjoint write sets"]
  C --> D["Worker: canonical article or code module"]
  C --> E["Worker: localized files or separate module"]
  D --> F["Reviewer: quality, metadata, verification"]
  E --> F
  F --> G["Main: final checks and handoff"]

Diese Reihenfolge verhindert den häufigsten Fehler: mehrere Agents bearbeiten dieselben Dateien, weil der Auftrag zu breit war.

Use Case 1: Lokalisierte Artikelproduktion

Bei ClaudeCodeLab ist der sichere Ablauf: zuerst den japanischen Canonical-Artikel fertigstellen, dann den vollständigen Guide lokalisieren. Wenn der Canonical dünn ist, werden alle Übersetzungen dünn. Wenn er Beispiele, Stolperfallen, Templates und CTA enthält, können die lokalisierten Versionen Substanz behalten.

Rolle	Erlaubte Dateien	Aufgabe
ja-worker	site/src/content/blog/claude-code-subagent-patterns.mdx	Struktur, Beispiele, Prompts und CTA bauen
western-locale-worker	blog-en, blog-es, blog-fr, blog-de, blog-pt	Natürlich lokalisieren, nicht zusammenfassen
asia-locale-worker	blog-zh, blog-ko, blog-hi, blog-id	Begriffe für lokale Leser anpassen
review-agent	alle zehn Slug-Dateien, read-only	Frontmatter, Mojibake, Links, Fences und Publikationsrisiko prüfen

Prompt zum Kopieren:

Use a translation subagent for the assigned locale files only.

Source:
- Japanese canonical file: site/src/content/blog/claude-code-subagent-patterns.mdx

Allowed write set:
- site/src/content/blog-en/claude-code-subagent-patterns.mdx
- site/src/content/blog-es/claude-code-subagent-patterns.mdx

Rules:
- Do not summarize. Localize the full guide.
- Keep frontmatter valid and preserve heroImage.
- Use natural SEO terms for each language.
- Keep prompt templates copy-pasteable.
- Do not edit Japanese or other locale files.

Return:
- Files changed
- Localization choices
- Any terms that may need human review
- Checks performed

Use Case 2: Codebeispiele im Artikel prüfen

Der Autor eines Artikels und der Verification-Agent sollten nicht dieselbe Rolle haben. Der Autor erklärt den Ablauf. Der verification agent extrahiert Codeblöcke, prüft Syntax, validiert Pfade und sagt, welche Beispiele wirklich kopierbar sind.

---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

You review article drafts critically.
Check whether the draft has concrete examples, pitfalls, working prompts,
official links, internal links, and a clear CTA.
Return findings first, then a short pass/fail recommendation.

Diese Definition kann als .claude/agents/article-reviewer.md liegen. name muss eindeutig sein, und description sollte erklären, wann der Agent genutzt wird. Schreibe keine riesige Policy in den Prompt; dauerhafte Regeln gehören besser in CLAUDE.md oder eine Team-Checkliste. Siehe auch den Kontextmanagement-Guide und die CLAUDE.md Best Practices.

Use Case 3: Codeänderungen mit getrennten write sets

Dasselbe Muster funktioniert für Code. Angenommen, eine Blog-Site braucht Änderungen an Artikelkarten, OGP-Generierung und Related-Post-Logik. Die Bereiche hängen zusammen, aber die Dateien können getrennt werden.

We will use three workers with disjoint write sets.

Worker A:
- May edit: site/src/components/BlogCard.astro
- Must not edit: layouts, pages, content files
- Goal: improve card metadata rendering only

Worker B:
- May edit: site/src/pages/og/[...slug].png.ts
- Must not edit: components or article files
- Goal: verify OGP title and hero behavior

Worker C:
- May edit: site/src/lib/relatedPosts.ts
- Must not edit: components, pages, content files
- Goal: improve related-post selection without changing routes

All workers return a handoff receipt with changed files, reasoning, tests, and risks.

“Verbessere die UI parallel” ist ein schwacher Prompt. Ein starker Prompt nennt erlaubte Dateien, verbotene Dateien und die erwarteten Belege.

Use Case 4: Read-only Review und Verification

Der letzte Agent sollte oft read-only sein. Ein reviewer sucht Leserwert, SEO-Lücken, Dopplungen und fehlende Stolperfallen. Ein verification agent prüft Metadaten, Links, Befehle, Code-Fences und Build-Risiken.

Use a review subagent in read-only mode.

Scope:
- Read only these 10 localized files for slug claude-code-subagent-patterns.
- Do not edit anything.

Review checklist:
- description is 120 characters or fewer
- updatedDate is 2026-06-02
- heroImage is retained
- each locale is a full localized article, not a thin summary
- at least 3 concrete use cases are present
- pitfalls and failure modes are concrete
- code fences are balanced
- official external links and internal links are present
- CTA is natural and relevant

Return findings by severity with file paths and line numbers where possible.

Bei mehrsprachiger Veröffentlichung ist das besonders hilfreich. Ein Text kann natürlich klingen und trotzdem ein altes Datum, einen offenen Code-Fence oder keinen CTA haben. Für Codearbeit passt dazu die Claude Code Code-Review-Checkliste.

Delegations-Templates

Orchestrierungs-Prompt:

You are the orchestrator. Before using subagents, create a delegation plan.

Goal:
- [one sentence goal]

Hard constraints:
- Work only on: [exact files or directories]
- Do not edit: [out of scope]
- Preserve: [metadata, public API, routes, screenshots, etc.]
- Verification required: [commands or manual checks]

Ask explorer agents to read first. Do not start workers until write sets are disjoint.
For every worker, define:
- allowed write set
- forbidden files
- expected output
- done condition

Final response must include:
- changed files
- checks run
- remaining risks

Read-only Recherche:

Use an explorer subagent in read-only mode.

Task:
- Map the current state of [feature/article/slug].
- Find existing conventions, related files, internal links, and quality gaps.

Rules:
- Do not edit files.
- Prefer search and targeted reads over full-directory dumps.
- Return only the useful summary, not raw command output.

Return:
- Files that matter
- Existing patterns to follow
- Risks or unclear requirements
- Suggested write sets for workers

Isolierter worker:

Use a worker subagent for this isolated edit.

Allowed write set:
- [file 1]
- [file 2]

Forbidden:
- Do not edit files outside the allowed write set.
- Do not stage, commit, push, deploy, or rewrite unrelated changes.
- If the task requires another file, stop and report why.

Implementation goal:
- [specific behavior or article quality outcome]

Return a handoff receipt:
- Files changed
- Summary of changes
- Commands or checks run
- Evidence of success
- Remaining risk

Typische Fehler

Der erste Fehler ist Parallelisierung ohne Grenzen. Wenn drei worker “mach den Artikel besser” bekommen, ändern alle Titel, Intro, Beispiele und CTA. Es gibt mehr Diff, aber weniger Kontrolle.

Der zweite Fehler ist zu viel Rückgabe. Ein Subagent schützt den Hauptkontext während der Arbeit, aber sein Ergebnis kommt wieder in den Hauptthread. Fordere Entscheidungen, Tabellen und Belege an, keine vollständigen Logs.

Der dritte Fehler ist ein schwacher Vertrag. “Natürlich übersetzen” reicht nicht. Schreibe “nicht zusammenfassen”, “frontmatter erhalten”, “Stolperfallen behalten”, “lokale SEO-Begriffe nutzen” und “Formulierungen für menschliche Prüfung markieren”.

Der vierte Fehler ist Selbstvalidierung. Der reviewer soll skeptisch lesen, Anforderungen gegen Ergebnisse halten und zuerst Risiken nennen.

Der fünfte Fehler ist das Laden von Agent-Dateien zu vergessen. Dateien in .claude/agents/ sind möglicherweise erst in einer neuen Session verfügbar. Für wiederverwendbare Agents ist eine kurze Dateidefinition meist wartbarer als ein sehr langer einmaliger CLI-Prompt.

Kontextbudget

Subagents sparen nur Kontext, wenn du die Rückgabe begrenzt.

Context budget rule:
- Explorer returns at most 20 bullets and 1 table.
- Worker returns changed files, decisions, and checks only.
- Reviewer returns findings by severity, no full rewritten article.
- Logs longer than 80 lines must be summarized.
- If uncertainty remains, ask one focused question instead of dumping raw output.

Das Ergebnis darf groß sein. Der Handoff sollte kurz bleiben. Sonst füllt sich der Hauptthread mit Entwürfen, Übersetzungsnotizen und Prüf-Logs.

Kopierbarer Reviewer-Subagent

Der sicherste erste Subagent ist ein reiner Reviewer mit Leserechten. Dieses Skript erstellt .claude/agents/article-reviewer.md; der Agent darf Entwürfe prüfen und Risiken melden, aber keine Dateien ändern. Damit ergänzt du kritische Kontrolle, ohne Schreibzugriffe auszuweiten.

mkdir -p .claude/agents
cat > .claude/agents/article-reviewer.md <<'EOF'
---
name: article-reviewer
description: Reviews ClaudeCodeLab articles for originality, implementation detail, SEO, and publication risk.
tools: Read, Grep, Glob
---

Review the assigned files only. Do not edit.

Checklist:
- title and description match the search intent
- intro gives a concrete reader problem in the first three lines
- examples, pitfalls, official links, internal links, and CTA are present
- code fences are balanced and labeled
- the article is not a thin summary or duplicated from another page

Return:
- findings by severity
- pass/fail recommendation
- one highest-leverage fix
EOF

Checkliste für Delegation

# Subagent Delegation Checklist

## Before delegation
- [ ] Goal is one sentence.
- [ ] In-scope files are listed explicitly.
- [ ] Out-of-scope files and actions are listed explicitly.
- [ ] Explorer runs before worker when scope is unclear.
- [ ] Write sets do not overlap.

## During work
- [ ] Each worker edits only allowed files.
- [ ] Large outputs are summarized.
- [ ] Any need to expand scope is reported before editing.
- [ ] Prompts include done conditions.

## Review
- [ ] Reviewer runs in read-only mode.
- [ ] Metadata and links are checked.
- [ ] Code fences and commands are checked.
- [ ] Localization is full, not summarized.
- [ ] Remaining risks are written in the handoff.

Ergebnis aus der Praxis

Bei ClaudeCodeLab war der größte Gewinn nicht schnellere Übersetzung. Der größte Gewinn kam aus der Trennung von Canonical, Locale-Workern und read-only reviewer. Früher entstand leicht eine starke Sprache und neun dünne Varianten. Mit klaren Regeln gegen Zusammenfassung, festen write sets und Prüfbeleg wurde das Review konkreter.

Wenn dein Team Claude Code einführt, lehre Subagents als Arbeitsdesign, nicht als magischen Automatisierungsschalter. ClaudeCodeLab bündelt solche Delegationsverträge, Review-Rubriken und Kontextgewohnheiten in training und product templates für Teams.