Claude Code Agents: Autonome Sub-Agenten verstehen

Subagents sind das Power-Feature für komplexe Workflows. Statt alles selbst zu machen, delegiert Claude Aufgaben an spezialisierte Assistenten - jeder mit eigenem Kontext und eigenen Fähigkeiten.

Was sind Subagents?

Ein Subagent ist ein isolierter KI-Assistent innerhalb von Claude Code. Jeder Subagent hat:

• Eigenen Kontext: Separate Conversation History
• Spezifische Tools: Nur die Tools, die er braucht
• Fokussierte Aufgabe: Ein klarer System-Prompt
• Eigene Permissions: Unabhängige Zugriffsrechte

Warum das wichtig ist:

Ohne Subagents läuft alles im Hauptkontext. Bei einer grossen Recherche-Aufgabe füllt sich der Kontext mit Informationen, die Sie für die eigentliche Arbeit nicht brauchen.

Mit Subagents:

1. Claude erkennt: "Das ist eine Recherche-Aufgabe"
2. Claude delegiert an den Explore-Agent
3. Explore arbeitet in seinem eigenen Kontext
4. Nur das Ergebnis kommt zurück in den Hauptkontext

Built-in Subagents

Claude Code bringt drei eingebaute Subagents mit:

Explore

Zweck: Read-only Codebase-Exploration Modell: Übernimmt vom Parent (bei API-Nutzung max. Opus) Tools: Read-only Tools (z.B. Lesen, Suchen, Dateilisten)

User: Wie funktioniert die Auth in diesem Projekt?

Claude: [delegiert an Explore]

Explore: [durchsucht Codebase]
         [analysiert Auth-Module]
         [erstellt Zusammenfassung]

Claude: Die Authentifizierung funktioniert so: ...

Ideal für:

• "Finde alle Stellen, wo X verwendet wird"
• "Erkläre mir die Architektur von Y"
• "Welche Files sind von Z betroffen?"

Für günstige Exploration können Sie einen eigenen Explore-ähnlichen Agent mit model: haiku anlegen.

Plan

Zweck: Architektur-Recherche für Plan Mode Modell: Übernimmt vom Parent Tools: Read-only Tools

Wird automatisch genutzt, wenn Sie /plan verwenden oder komplexe Architektur-Fragen stellen.

General-purpose

Zweck: Komplexe Multi-Step Tasks Modell: Übernimmt vom Parent Tools: Alle verfügbaren Tools

Für Aufgaben, die zu komplex für den Hauptkontext sind, aber volle Tool-Zugriffe brauchen.

Eigene Subagents erstellen

Verzeichnisstruktur

.claude/agents/
├── debugger.md
├── reviewer.md
└── db-analyst.md

Oder für persönliche Agents:

~/.claude/agents/
├── my-helper.md
└── security-scanner.md

Agent-Datei Aufbau

---
name: debugger
description: Debugging-Spezialist für Fehleranalyse und Bug-Fixes
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---

Du bist ein erfahrener Debugger. Deine Stärke ist systematische
Fehleranalyse und Root-Cause-Identification.

## Vorgehen

1. **Fehler verstehen**: Error Message, Stack Trace analysieren
2. **Reproduzieren**: Minimalen Reproduktionsfall finden
3. **Isolieren**: Betroffenen Code eingrenzen
4. **Hypothesen**: Mögliche Ursachen auflisten
5. **Testen**: Hypothesen systematisch prüfen
6. **Fixen**: Minimalen Fix implementieren
7. **Verifizieren**: Tests schreiben, Regression prüfen

## Debugging-Techniken

- Console.log strategisch platzieren
- Git bisect für Regression
- Minimal Reproduction Case
- Divide and Conquer

Arbeite methodisch und dokumentiere deine Findings.

Frontmatter-Felder

Permission Modes

Praktische Beispiele

Code Reviewer Agent

---
name: code-reviewer
description: Führt Code Reviews durch. Nutze bei PR-Reviews oder vor Merges.
tools: Read, Grep, Glob
model: sonnet
permissionMode: plan
---

Du bist ein Senior Code Reviewer mit Fokus auf Qualität und Sicherheit.

## Review-Checkliste

### Sicherheit
- [ ] Input Validation
- [ ] SQL Injection
- [ ] XSS Prevention
- [ ] Authentication/Authorization
- [ ] Sensitive Data Exposure

### Performance
- [ ] N+1 Queries
- [ ] Unnecessary Loops
- [ ] Memory Leaks
- [ ] Caching Opportunities

### Maintainability
- [ ] Code Duplication
- [ ] Clear Naming
- [ ] Single Responsibility
- [ ] Test Coverage

## Output

Erstelle einen strukturierten Review mit:
- Severity (Critical/High/Medium/Low/Info)
- Location (File:Line)
- Issue Description
- Suggested Fix

Schliesse mit einer Empfehlung: APPROVE, REQUEST_CHANGES, oder DISCUSS.

Database Analyst Agent

---
name: db-analyst
description: Analysiert Datenbank-Schemas und optimiert Queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: ".claude/hooks/validate-readonly-query.sh"
---

Du bist ein Datenbank-Experte. Du analysierst Schemas, optimierst
Queries und identifizierst Performance-Probleme.

## Wichtig

- NUR SELECT Queries ausführen
- NIEMALS Daten modifizieren
- Bei Unsicherheit: nachfragen

## Analyse-Bereiche

1. **Schema-Analyse**: Tabellen, Relationen, Indizes
2. **Query-Optimierung**: EXPLAIN ANALYZE, Index-Nutzung
3. **Performance**: Slow Queries, Missing Indexes
4. **Data Quality**: Null Values, Constraints

Security Scanner Agent

---
name: security-scanner
description: Scannt Code auf Sicherheitslücken (OWASP Top 10)
tools: Read, Grep, Glob
model: opus
permissionMode: plan
---

Du bist ein Security-Experte, spezialisiert auf Application Security.

## OWASP Top 10 Checkliste

1. **Injection**: SQL, NoSQL, OS Command, LDAP
2. **Broken Authentication**: Session Management, Credentials
3. **Sensitive Data Exposure**: Encryption, Storage
4. **XXE**: XML External Entities
5. **Broken Access Control**: Authorization, IDOR
6. **Security Misconfiguration**: Headers, Defaults
7. **XSS**: Reflected, Stored, DOM-based
8. **Insecure Deserialization**: Object Manipulation
9. **Using Components with Known Vulnerabilities**: Dependencies
10. **Insufficient Logging**: Audit Trail, Detection

## Reporting

Für jedes Finding:
- Severity: Critical/High/Medium/Low
- CWE Number
- Location
- Description
- Proof of Concept (wenn sicher)
- Remediation

CLI-defined Agents

Für temporäre Agents können Sie JSON via CLI übergeben:

claude --agents '{
  "quick-helper": {
    "description": "Schnelle Hilfe für einfache Fragen",
    "prompt": "Du beantwortest kurze Fragen knapp und präzise.",
    "tools": ["Read"],
    "model": "haiku"
  }
}'

Foreground vs Background

Seit Claude Code v2.1.198+ laufen Subagents standardmässig im Hintergrund. Foreground nutzen Sie, wenn das Ergebnis sofort im selben Turn gebraucht wird.

Background Execution (Default)

• Agent läuft parallel zur Hauptkonversation
• Permission-Prompts erscheinen in der Hauptsession (seit v2.1.186; zuvor wurden sie oft auto-denied)
• MCP-Tools bleiben im Background verfügbar; eingebaute Tools werden gefiltert
• Sie können weiterarbeiten, während der Agent läuft

Shortcut: Ctrl+B um einen laufenden Task in den Background zu verschieben.

Wann Background ideal ist:

• Lange Recherche-Aufgaben
• Unabhängige Analysen
• Während Sie an etwas anderem arbeiten

Foreground Execution

• Agent blockiert die Hauptkonversation, bis er fertig ist
• Permission-Prompts werden direkt durchgereicht
• Ergebnis steht sofort im selben Turn zur Verfügung

Claude: Ich delegiere an den Debugger-Agent...

[Debugger arbeitet]

Debugger: Der Fehler liegt in auth.ts:42. Soll ich fixen?

User: Ja, bitte.

Agents mit Hooks kombinieren

Agents können eigene Hooks haben. Hook-Scripts erhalten Tool-Details als JSON über stdin (nicht als Umgebungsvariablen wie $FILE):

---
name: safe-editor
description: Editiert Files mit automatischem Backup
tools: Read, Edit, Write
hooks:
  PreToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: ".claude/hooks/backup.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "npm run lint --fix"
---

Du editierst Files sicher mit automatischem Backup und Linting.

Beispiel .claude/hooks/backup.sh:

#!/bin/bash
FILE_PATH=$(jq -r '.tool_input.file_path // empty')
[ -n "$FILE_PATH" ] && [ -f "$FILE_PATH" ] && cp "$FILE_PATH" "$FILE_PATH.bak"

Agents mit Skills

Agents können Skills laden:

---
name: documentation-writer
description: Erstellt und aktualisiert Dokumentation
tools: Read, Write
skills:
  - documentation-style
  - api-docs-template
---

Du schreibst Dokumentation nach unseren Standards.
Nutze die geladenen Skills für Formatierung und Templates.

Best Practices

1. Klare Descriptions

Die description bestimmt, wann Claude delegiert:

# Schlecht
description: Hilft bei Code-Problemen

# Gut
description: Debugging-Spezialist für Runtime-Errors und Test-Failures.
             Nutze bei Fehlermeldungen, Stack Traces oder unerwartetem Verhalten.

2. Minimale Tool-Sets

Geben Sie Agents nur die Tools, die sie brauchen:

# Code Reviewer braucht keine Schreibrechte
tools: Read, Grep, Glob

# Debugger braucht Edit für Fixes
tools: Read, Edit, Bash, Grep, Glob

3. Passende Modelle

• Haiku: Schnelle, günstige Exploration (z.B. eigener Explore-ähnlicher Agent)
• Sonnet: Standard für die meisten Agents
• Opus: Komplexe Analysen, Security Reviews
• inherit: Modell vom Parent übernehmen (Default der Built-ins)

4. Documentation

Dokumentieren Sie Ihre Agents für das Team:

## Verfügbare Agents

| Agent | Zweck | Trigger |
|-------|-------|---------|
| debugger | Bug-Analyse | Fehlermeldungen, Stack Traces |
| reviewer | Code Review | PR-Reviews, vor Merge |
| db-analyst | DB-Analyse | Schema-Fragen, Query-Optimierung |

Fazit

Subagents sind Ihre spezialisierten Teammitglieder in Claude Code. Der Explore-Agent für Recherche, ein Debugger für Fehleranalyse, ein Reviewer für Code-Qualität.

Starten Sie mit den Built-in Agents und erstellen Sie eigene, wenn Sie wiederkehrende spezialisierte Aufgaben haben.

---

Weiterführende Artikel:

• Claude Code: Der komplette Überblick - Alle Features
• Claude Code Skills erstellen - Workflow-Module
• Claude Code Hooks konfigurieren - Event-Automatisierung
• CLAUDE.md Best Practices - Projekt-Konfiguration

Sie möchten spezialisierte Agents für Ihr Team entwickeln? Hedinger-Digital unterstützt bei Konzeption und Implementierung - Softwareentwicklung bei Hedinger-Digital. Und wenn Sie klären möchten, wo KI-Agenten ausserhalb der Entwicklung Zeit sparen: KI-Beratung für KMU.