„Subagent-Kollaborationsmodus“

„Claude Code-Subagents verstehen und nutzen – parallele Exploration, Hintergrundtasks, isolierte Ausführung“

Subagent-Kollaborationsmodus¶

Stellen Sie sich vor: Sie bitten Claude, Ihnen beim Refactoring eines großen Moduls zu helfen, doch vor dem Refactoring muss es zunächst drei Dinge klären – welche bestehenden API-Schnittstellen gibt es, wie sieht das Datenbankschema aus und wie steht es um die Testabdeckung. Im normalen Modus kann Claude diese Punkte nur der Reihe nach einzeln prüfen. Aber was wäre, wenn es drei „Klone“ aussenden könnte, die gleichzeitig recherchieren?

Genau darin liegt der Reiz von Subagents.

Was sind Subagents¶

Konzept des Agent-Tools¶

Ein Subagent ist ein spezielles Tool in Claude Code, das es der Hauptsitzung ermöglicht, eigenständige Claude-Instanzen zu erstellen, die bestimmte Tasks ausführen. Man kann sich das vorstellen als „Claude hat einen Assistenten engagiert“.

Das Claude in der Hauptsitzung ist der Projektmanager, der für die Gesamtsteuerung zuständig ist. Wenn es auf Teilaufgaben stößt, die eine tiefgehende Recherche erfordern, kann es einen Subagenten starten, der sich gezielt darum kümmert, während es selbst weitere Aufgaben bearbeitet.

Unterschiede zwischen Subagenten und Hauptsitzung¶

Der entscheidendste Unterschied ist das eigenständige Kontextfenster. Subagenten haben ihren eigenen Kontextraum; ihr Explorationsprozess bläht den Kontext der Hauptsitzung nicht auf. Lediglich die Endergebnisse werden an die Hauptsitzung übergeben – es ist, als schickt man jemanden auf eine Recherche-Reise; bei der Rückkehr braucht er nur einen Bericht abzuliefern, statt den gesamten Rechercheablauf nachzuerzählen.

Vorteile des eigenständigen Kontextfensters¶

Warum ist eigenständiger Kontext so wichtig? Ein praktisches Beispiel:

Angenommen, Sie benötigen von Claude eine Analyse eines Projekts mit 200 Dateien. Wenn Sie die Dateien einzeln in der Hauptsitzung lesen, mit durchschnittlich 200 Zeilen pro Datei, allein der Dateiinhalt würde 40.000 Zeilen Kontext beanspruchen. Rechnet man Claudes Analyseprozess hinzu, ist das Kontextfenster schnell gefüllt.

Mit Subagenten verhält sich das anders. Der Subagent liest und analysiert diese Dateien in seinem eigenen Kontext und gibt am Ende nur einen Analysebericht mit ein paar Hundert Zeilen zurück. Der Kontext der Hauptsitzung wächst kaum, und Ihnen steht weiterhin reichlich Platz für die weitere Arbeit zur Verfügung.

Integrierte Subagent-Typen¶

Subagenten in Claude Code sind eigentlich keine festen „Typen“, sondern werden flexibel von der Hauptsitzung je nach Aufgabenstellung erstellt. In der Praxis nehmen Subagenten jedoch typischerweise die folgenden Rollen ein:

Explore (Codesuche und Exploration)¶

Dies ist der häufigste Anwendungsfall für Subagenten. Wenn Claude einen bestimmten Aspekt eines Projekts verstehen muss, startet es einen Explore-Subagenten:

Fähigkeiten:

• Dateien lesen (Read)
• Code durchsuchen (Grep, Glob)
• Verzeichnisstruktur anzeigen
• Code-Abhängigkeiten analysieren

Einschränkungen:

• Üblicherweise nur Read-only-Tools
• Kann keine Dateien modifizieren
• Kann keine Befehle ausführen

Typische Szenarien:

Analyze public interfaces for all services in the src/services/ directory
Find all files that reference UserService
Understand the workflow of the authentication middleware

Plan (Architekturdesign und Planung)¶

Subagenten zur Formulierung von Plänen oder Lösungsentwürfen:

Fähigkeiten:

• Alle Explore-Fähigkeiten
• Websuche (Dokumentation, Best Practices)
• Detaillierte Lösungsdokumente generieren

Typische Szenarien:

Design a cache layer architecture
Evaluate feasibility of migrating from REST to GraphQL
Formulate a database sharding strategy

General-Purpose (Allgemeine Tasks)¶

Subagenten, die konkrete Ausführungsaufgaben übernehmen, mit vollständigem Tool-Zugriff:

Fähigkeiten:

• Dateien lesen und schreiben
• Befehle ausführen
• Tests laufen lassen
• Abhängigkeiten installieren

Typische Szenarien:

Run the full test suite in the background
Generate API documentation
Execute code formatting

Wann Subagents verwenden¶

Szenario 1: Code-Suche und Verständnis¶

Wenn Sie ein unvertrautes Codebase tiefgreifend verstehen müssen, können Subagents die Exploration effizient erledigen:

I just took over this project. Please help me understand its architecture comprehensively:
1. Use a subagent to analyze the backend directory structure and core modules
2. Use a subagent to analyze the frontend component tree and state management
3. Use a subagent to analyze the database schema and entity relationships
Then synthesize information from all three areas and give me a project architecture overview.

Claude könnte drei Subagents starten, um diese Aufgaben parallel auszuführen und anschließend deren Berichte zusammenzuführen.

Szenario 2: Parallele Recherche mehrerer Lösungsansätze¶

Wenn Sie mehrere technische Lösungen vergleichen müssen, ist die Parallelfähigkeit von Subagents sehr nützlich:

I need to choose a message queue for the project. Please research the following solutions separately:
1. Redis Streams — check if our existing Redis configuration supports it
2. RabbitMQ — evaluate the cost of introducing new dependencies
3. Using PostgreSQL's LISTEN/NOTIFY directly
For each solution, analyze the pros and cons and compatibility with our project.

Szenario 3: Lange Aufgaben im Hintergrund ausführen¶

Manche Aufgaben dauern lange (z. B. Tests ausführen, Dokumentation generieren). Sie können sie in einen Subagent zur Hintergrundausführung auslagern:

Please run the full test suite in the background while I continue working on other things.
Tell me the results when the tests are done.

Claude wird einen Hintergrund-Subagent starten, um die Tests auszuführen. Sie können ohne Wartezeit mit der Hauptsitzung weiterarbeiten.

Szenario 4: Risikoreiche Operationen isolieren¶

Wenn Sie potenziell riskante Operationen ausführen müssen, können Sie einen Subagent zur Isolation nutzen:

Please try the following operations using a subagent:
1. Switch to a temporary branch
2. Try upgrading React to 19.x
3. Run the build and see how many compatibility errors there are
4. Send me the error list
Do not operate on the main branch.

Subagent-Praxistutorial¶

Beispiel 1: Mit Subagents ein unvertrautes Codebase verstehen¶

Angenommen, Sie arbeiten am ersten Tag an einem mittelgroßen Python-Projekt (etwa 50 Quelldateien) und müssen schnell dessen Struktur durchdringen.

Ihr Prompt:

It's my first day on this project. Please help me quickly build an understanding of it.
Use subagents to analyze the following areas in parallel:

1. Project structure and entry points — scan directory structure, find main entry, routing definitions, config files
2. Data models — analyze all model files and draw entity relationships
3. Business logic — analyze the services directory and understand core business workflows
4. External dependencies — analyze requirements.txt and actual imports to identify key dependencies

Finally, synthesize all the information into a project overview of no more than 500 words.

Claudes Ausführungsprozess:

Claude wird mehrere Subagents erstellen, die Aufgaben eigenständig ausführen. Jeder Subagent erkundet für sich und liefert die Ergebnisse zurück. Während des Prozesses sehen Sie Ausgaben wie:

Launching 4 subagents for parallel analysis...

[Subagent 1] Analyzing project structure...

  - Scanned 52 Python files
  - Found entry point: main.py → FastAPI app
  - Route definitions in routers/ directory (8 routing modules)
  - Config: config.py + .env

[Subagent 2] Analyzing data models...

  - Found 12 SQLAlchemy models
  - Core entities: User, Organization, Project, Task, Comment
  - Key relationships: User ← many-to-many → Organization, Project → has-many → Task

[Subagent 3] Analyzing business logic...

  - 9 service files
  - Core workflows: user management, project management, task assignment, notification system
  - Async task processing using Celery

[Subagent 4] Analyzing external dependencies...

  - 32 direct dependencies
  - Key dependencies: FastAPI, SQLAlchemy, Celery, Redis, Alembic
  - Found 2 unused dependencies (requests, beautifulsoup4)

Abschließend führt Claude die Ergebnisse aller vier Subagents zusammen und liefert Ihnen eine strukturierte Projektübersicht.

Beispiel 2: Mehrere Subagents parallel starten, um Lösungen zu vergleichen¶

Sie überlegen, wie Sie Echtzeit-Benachrichtigungen umsetzen wollen und möchten mehrere Lösungen vergleichen:

I need to add real-time notification functionality to the project. Please help me evaluate the following three solutions in parallel:

Solution A: WebSocket (using FastAPI's built-in WebSocket support)
Solution B: Server-Sent Events (SSE)
Solution C: Polling

For each solution, please analyze:
1. Compatibility with our existing architecture (check existing code)
2. Implementation complexity (approximately how many files need changes)
3. Performance and scalability
4. Client compatibility

Then give me a comparison table and your recommendation.

Claudes Vergleichsergebnisse könnten so aussehen:

All three subagents have completed analysis. Summary comparison:

| Evaluation Dimension | WebSocket | SSE | Polling |
|----------|-----------|-----|------|
| Architecture Compatibility | Need to add WebSocket routes | Can reuse existing HTTP routes | Fully compatible |
| Implementation Complexity | High (~8 files) | Medium (~4 files) | Low (~2 files) |
| Real-time Capability | Best (full duplex) | Good (server push) | Average (depends on polling interval) |
| Scalability | Needs WebSocket load balancing | Can use CDN | Simplest |
| Celery Integration | Needs additional message bridge | Can directly consume Celery events | Poll database |

**Recommendation**: Considering you're already using Celery + Redis, SSE is the best choice.
It can directly subscribe to Redis channels to get Celery events, with moderate implementation complexity,
and doesn't require additional infrastructure.

Beispiel 3: Tests mit Hintergrund-Subagent ausführen¶

Sie ändern gerade Code und möchten gleichzeitig die Testergebnisse wissen:

Please run pytest in the background and run the full test suite. I'll continue modifying code. Tell me when it's done.

Claude wird einen Hintergrund-Subagent starten, um die Tests auszuführen. Sie können mit Claude weiterarbeiten und Code ändern. Sobald die Tests abgeschlossen sind, sehen Sie eine Ergebnisbenachrichtigung:

Background tests completed. Results:

- Total: 247 tests
- Passed: 241
- Failed: 4
- Skipped: 2

Failed tests:
1. test_order_service.py::test_calculate_total_with_discount
   AssertionError: 99.99 != 100.0
2. test_user_service.py::test_create_user_duplicate_email
   IntegrityError: Test database not properly cleaned up
3. ...

Would you like me to analyze these failing tests?

Subagent-Konfiguration¶

Subagent-Verhalten über CLAUDE.md steuern¶

Obwohl Sie Subagent-Parameter nicht direkt „konfigurieren“ können, können Sie CLAUDE.md nutzen, um Claude zu leiten, wann und wie Subagents eingesetzt werden sollen:

## Subagent Usage Guidelines

### When to Use Subagents

- Tasks analyzing more than 10 files should use subagents
- When comparing multiple solutions, launch independent subagents for each
- Running tests should be executed in background subagents

### Subagent Task Description Template
When launching subagents, the task description should include:
1. Clear objectives (what to do)
2. Scope limitations (what not to do)
3. Output format (what kind of results to return)

### Subagent Result Handling
Subagent results must include:

- Analysis summary (no more than 200 words)
- Key findings list
- Related file paths
- Potential risks or issues

Verfügbare Tools für Subagents verstehen¶

Welche Tools ein Subagent nutzen kann, hängt von der Autorisierung der Hauptsession ab. In der Praxis:

• Nur-Lese-Aufgaben: In der Regel werden nur Suchtools wie Read, Grep, Glob bereitgestellt
• Ausführungsaufgaben: Schreibtools wie Bash, Write, Edit werden bereitgestellt
• Netzwerkaufgaben: Netzwerktools wie WebSearch, WebFetch werden bereitgestellt

Sie können den Tool-Umfang über natürliche Sprache implizit angeben:

Please use a subagent to analyze (read-only) the relationships of all models in the src/models/ directory.

Durch den Hinweis „read-only“ neigt Claude dazu, einen Subagent mit ausschließlich Such- und Lesefähigkeiten zu erstellen.

Hintergrundausführung¶

Subagents können im Hintergrund laufen, ohne Ihre Interaktion mit der Hauptsession zu blockieren. Wenn Sie „im Hintergrund…“ oder „asynchron…“ sagen, nutzt Claude den Parameter run_in_background:

Please help me with two things in the background:
1. Run the complete lint check
2. Check all dependencies for known security vulnerabilities
I'll continue modifying code and let me know when done.

Wenn ein Subagent im Hintergrund abgeschlossen ist, benachrichtigt das System Claude, der Ihnen dann die Ergebnisse übermittelt.

Best Practices¶

1. Subagents klare Aufgabenbeschreibungen geben¶

Der Kontext eines Subagents ist komplett neu — er weiß nicht, was Sie zuvor in der Hauptsession besprochen haben. Aufgabenbeschreibungen müssen daher in sich geschlossen sein:

Schlechte Praxis:

Use a subagent to check the issue mentioned earlier.

(Der Subagent weiß nicht, was „das zuvor erwähnte Problem“ ist)

Gute Praxis:

Use a subagent to check whether the process_refund() method in src/services/payment_service.py correctly handles concurrent refund requests.
Need to pay attention to database transaction isolation levels and use of optimistic locking.

2. Parallele Subagents zur Effizienzsteigerung nutzen¶

Wenn mehrere Aufgaben voneinander unabhängig sind, lassen Sie sie parallel ausführen:

Please execute the following tasks in parallel:
1. [Subagent A] Analyze all API call points in the frontend code
2. [Subagent B] Analyze backend API endpoints and parameter definitions
3. [Subagent C] Check if API documentation is consistent with actual interfaces

After all three tasks are complete, summarize the API inconsistencies.

3. Subagents nicht übermäßig einsetzen¶

Subagents sind kein Allheilmittel. In folgenden Szenarien ist die direkte Bearbeitung in der Hauptsession effizienter:

• Einfache Dateiansicht: Ein oder zwei Dateien lesen — einfach mit @ referenzieren
• Einfache Suchen: Ein einzelnes Stichwort suchen — die Hauptsession erledigt das schneller
• Aufgaben mit fortlaufender Interaktion: Subagents sind „einmalig“ und eignen sich nicht für Aufgaben, die mehrere Dialogrunden erfordern
• Serienaufgaben mit Abhängigkeit vom vorherigen Ergebnis: Der Einsatz von Subagents würde die Komplexität erhöhen

Faustregel: Wenn eine Aufgabe in ein oder zwei Sätzen beschrieben werden kann und kein Lesen einer großen Anzahl von Dateien erfordert, erledigen Sie sie direkt in der Hauptsession.

4. Mechanismus zur Ergebnisübergabe verstehen¶

Wenn ein Subagent seine Aufgabe abgeschlossen hat, werden die Ergebnisse in Zusammenfassungsform an die Hauptsession zurückgegeben. Das bedeutet:

• Der Original-Dateiinhalt, den der Subagent gelesen hat, wird nicht vollständig zurückübertragen (er ist zu groß)
• Nur die Analyseergebnisse und Schlüsselinformationen des Subagents werden zurückgegeben
• Wenn Sie eine bestimmte Datei ansehen möchten, die der Subagent entdeckt hat, lesen Sie sie in der Hauptsession selbst erneut

The subagent told me there's an issue on line 127 of payment_service.py.
Please show me lines 120-140 of that file.

5. Subagents für „exploratorische“ Operationen nutzen¶

Unsicher, ob ein bestimmter Ansatz machbar ist? Nutzen Sie einen Subagent zum Experimentieren, anstatt Risiken auf dem Hauptzweig einzugehen:

Please use a subagent to run an experiment:
1. Create a temporary directory /tmp/experiment
2. Copy src/models/user.py into it
3. Try replacing SQLAlchemy's declarative models with dataclasses
4. See what problems arise

Don't touch any project files.

Erweitert: Subagents mit anderen Funktionen kombinieren¶

Subagents + Plan Mode¶

Sie können Subagents auch im Plan Mode verwenden. Das ist eine leistungsstarke Kombination – nutzen Sie Subagents für tiefgehende Recherche in der Planungsphase:

(In Plan mode)
Please use subagents to help me research the following questions, then formulate a migration plan based on the research results:
1. List of all current REST API endpoints and their call frequencies
2. Which endpoints already have equivalent GraphQL implementations
3. How much the client code depends on REST APIs

Subagents + MCP-Tools¶

Wenn Sie MCP-Server konfiguriert haben (etwa Tools für Datenbankabfragen), können Subagents diese ebenfalls nutzen:

Please use a subagent to connect to the database and analyze the following:
1. Data volume for each table
2. Top 10 slow queries
3. Missing indexes
Use the database MCP tool to execute queries.

Subagents + Hooks¶

Sie können Hooks nutzen, um benutzerdefinierte Logik auszulösen, wenn Subagents bestimmte Aktionen ausführen. Zum Beispiel können Sie automatisch Benachrichtigungen senden, wenn ein Subagent Tests abgeschlossen hat:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl -X POST https://hooks.slack.com/... -d '{\"text\": \"$MESSAGE\"}'"
          }
        ]
      }
    ]
  }
}

FAQ¶

Q: Können Subagents meinen Gesprächsverlauf mit der Hauptsitzung einsehen?

A: Nein. Der Kontext eines Subagents ist völlig neu und enthält lediglich die Aufgabenbeschreibung, die Claude ihm gibt. Deshalb müssen Aufgabenbeschreibungen auch in sich abgeschlossen sein. Subagents können jedoch CLAUDE.md lesen, sodass projektweite Konventionen und Vereinbarungen auch für Subagents gelten.

Q: Können Subagents „Sub-Subagents“ starten?

A: Ja, aber eine zu starke Verschachtelung ist nicht empfehlenswert. In der Regel reicht eine Ebene an Subagents aus.

Q: Können mehrere Subagents miteinander kommunizieren?

A: Nein, nicht direkt. Wenn Subagent B von den Ergebnissen eines Subagent A abhängen soll, können Sie nur abwarten, bis A abgeschlossen ist – anschließend übergibt die Hauptsitzung die Ergebnisse an B.

Q: Verbrauchen Subagents zusätzliches API-Kontingent?

A: Ja. Subagents verwenden unabhängige Kontextfenster, und sowohl die Eingabe als auch die Ausgabe jedes Subagents verbrauchen Tokens. Da der Kontext eines Subagents jedoch meist kleiner ist (er enthält nur bestimmte Aufgaben), ist der Gesamtverbrauch oft geringer, als wenn dieselbe Arbeit in der Hauptsitzung erledigt würde.