Claude Agents: Subagenten in Claude Code erstellen

Ein Claude Agent ist in der Regel ein Subagent in Claude Code: ein spezialisierter Assistent mit eigenem Kontext, eigenem System-Prompt und eigenen Tool-Rechten, an den Claude Teilaufgaben abgibt. Er wird als Markdown-Datei unter .claude/agents/ definiert. Zurück in die Hauptsession kommt nur das Ergebnis.

Was «Claude Agent» bedeutet

Der Begriff wird für drei verschiedene Dinge verwendet:

• Subagents in Claude Code: Dateien in .claude/agents/, Thema dieses Artikels.
• Claude Agent SDK: Eine Bibliothek für Python und TypeScript, die den Agent-Loop von Claude Code in eigener Software nutzbar macht. Subagents gibt es dort ebenfalls.
• Claude Managed Agents: Ein von Anthropic gehosteter Agent-Dienst über die Claude API, mit Sandbox und Sessions für lang laufende Aufgaben. Stand September 2026 in der Beta.

Wer «Agent erstellen» sucht und nicht programmiert, meint fast immer den ersten Fall.

Was sind Subagents?

Ein Subagent ist ein isolierter Assistent innerhalb von Claude Code. Er hat:

• Eigenen Kontext: eine separate Konversation, ohne die Historie der Hauptsession
• Eigene Tools: nur, was er braucht
• Einen fokussierten System-Prompt: die Markdown-Datei
• Eigene Rechte: etwa Read-only

Der praktische Nutzen: Eine grosse Recherche füllt sonst den Hauptkontext mit Material, das für die eigentliche Arbeit nicht mehr gebraucht wird. Mit einem Subagent recherchiert dieser in seinem eigenen Kontext, und nur die Zusammenfassung landet in der Hauptsession.

Eingebaute Subagents

Explore und Plan laden weder CLAUDE.md noch den Git-Status, damit sie schlank bleiben. Dazu kommen interne Helfer wie claude-code-guide (beantwortet Fragen zu Claude Code) und statusline-setup.

Typische Explore-Aufträge:

• «Finde alle Stellen, wo X verwendet wird»
• «Erkläre die Architektur von Y»
• «Welche Dateien sind von Z betroffen?»

Für günstige Recherche legen Sie einen eigenen Agent mit model: haiku an.

Eigene Agents in .claude/agents/ erstellen

Agents liegen als Markdown-Dateien an diesen Orten. Bei gleichem Namen gewinnt die höhere Priorität:

1. Managed Settings (organisationsweit)
2. --agents beim Start (nur für die Session)
3. .claude/agents/ im Projekt (lässt sich einchecken und im Team teilen)
4. ~/.claude/agents/ (persönlich, für alle Projekte)
5. agents/ in einem aktivierten Plugin

Der interaktive Assistent hinter /agents wurde entfernt. Der Befehl verweist inzwischen darauf, Claude die Datei schreiben zu lassen oder sie direkt zu bearbeiten. Ein Prompt wie «Erstelle einen Subagent für Code Reviews, der nur lesen darf» reicht in der Praxis.

Aufbau einer Agent-Datei

---
name: debugger
description: Debugging-Spezialist für Runtime-Errors und Test-Failures. Nutze bei Fehlermeldungen, Stack Traces oder unerwartetem Verhalten.
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---

Du bist ein erfahrener Debugger. Gehe systematisch vor:

1. Fehlermeldung und Stack Trace analysieren
2. Minimalen Reproduktionsfall finden
3. Ursache eingrenzen und Hypothesen prüfen
4. Minimalen Fix umsetzen und mit einem Test absichern

Der Text unter dem Frontmatter ist der System-Prompt. Der Subagent erhält nicht den Claude-Code-Standard-Prompt, sondern nur diesen Text, dazu die CLAUDE.md-Dateien und den Git-Status.

Frontmatter-Felder

Weitere Felder wie color, initialPrompt oder omitClaudeMd sind in der Referenz beschrieben.

Welches Modell für welchen Agent

Das Modell eines Subagents wird in dieser Reihenfolge bestimmt: Angabe beim Aufruf, model im Frontmatter, Umgebungsvariable CLAUDE_CODE_SUBAGENT_MODEL, Modell der Hauptsession. Als Faustregel:

• Haiku für einfache, häufige Recherche
• Sonnet für die meisten Aufgaben
• Opus für schwierige Analysen wie Security Reviews
• inherit übernimmt das Modell der Hauptsession

Tools einschränken

Ein Reviewer braucht keine Schreibrechte, ein Debugger schon. Mit tools beschränken Sie einen Agent auf eine Positivliste, mit disallowedTools entfernen Sie einzelne Tools. Über Agent(worker, researcher) in tools legen Sie fest, welche weiteren Subagents er starten darf.

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

Agents aufrufen

• Automatisch: Claude entscheidet anhand der description.
• Explizit per @-Erwähnung: @"code-reviewer (agent)" prüfe die Auth-Änderungen erzwingt den Einsatz.
• Ganze Session als Agent: claude --agent code-reviewer. Alternativ setzt agent in den Settings einen Standard.
• Nur für eine Session: claude --agents '{...}' mit JSON. Die Felder entsprechen dem Frontmatter, der System-Prompt steht unter prompt.

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

Hintergrund, Parallelität und Verschachtelung

Subagents laufen standardmässig im Hintergrund, während Sie in der Hauptsession weiterarbeiten. Das Ergebnis kommt als Benachrichtigung. Berechtigungsabfragen erscheinen in der Hauptsession. Hintergrund-Agents haben einen reduzierten Tool-Satz, MCP-Tools bleiben verfügbar. Im Vordergrund blockiert der Agent die Konversation, dafür stehen alle Tools bereit und Rückfragen kommen direkt durch.

Mehrere Subagents können parallel arbeiten, standardmässig höchstens 20 gleichzeitig (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS). Subagents dürfen selbst Subagents starten, bis zu drei Ebenen tief. Mit CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 schalten Sie die Verschachtelung ab.

Custom-Agents lassen sich später fortsetzen: Claude nimmt dafür per SendMessage erneut Kontakt mit dem Agent auf, der seinen bisherigen Verlauf behält. Der Befehl /subtask startet zusätzlich einen Fork, der die gesamte bisherige Konversation erbt.

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 Dateien 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

Das Feld skills lädt Skills beim Start vollständig in den Kontext des Agents. Mehr zum Unterschied und zu den Formaten steht im Artikel Claude Code Skills erstellen.

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

Du schreibst Dokumentation nach den geladenen Stilvorgaben.

Wann sich ein eigener Agent nicht lohnt

• Kleine, einmalige Aufgaben: Ein Subagent startet ohne Konversationshistorie und muss sich Kontext erst wieder aufbauen. Für kurze Änderungen ist die Hauptsession schneller.
• Enge Abstimmung mit Ihnen: Was viele Rückfragen braucht, gehört in die Hauptsession. Subagents können Ihnen keine Rückfragen stellen (AskUserQuestion steht ihnen nicht zur Verfügung).
• Zu viele ähnliche Agents: Alle description-Texte belegen Kontext (zusammen sind rund 15'000 Tokens vorgesehen). Wenige, klar getrennte Agents sind übersichtlicher.
• Kosten: Jeder Subagent verbraucht eigene Tokens. Parallele Agents beschleunigen, sparen aber nichts.

Mit klaren Descriptions, minimalen Tool-Sets und passenden Modellen bleiben Agents zuverlässig. Eine gute description nennt, wann der Agent gebraucht wird, nicht nur, was er kann.

Weiterführende Artikel

• Claude Code: Der komplette Überblick mit allen Features
• Claude Code Skills erstellen für Workflow-Module
• Claude Code Hooks konfigurieren für Event-Automatisierung
• CLAUDE.md Best Practices für die Projekt-Konfiguration
• Claude Code und MCP für externe Tools

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.