Eine der mächtigsten, aber am wenigsten genutzten Funktionen von Claude Code sind Custom Agents — spezialisierte Sub-Agents, die du für bestimmte Aufgaben definierst. Statt immer wieder dieselben detaillierten Prompts zu schreiben, packst du sie in wiederverwendbare Agent-Definitionen. Ich habe mehrere für meine eigenen Projekte gebaut, und sie haben meine Arbeitsweise grundlegend verändert.
Was sind Agents im Claude-Code-Kontext?
Ein Agent ist eine vordefinierte Persona mit spezifischen Anweisungen, Tool-Zugriff und optional einem bestimmten Modell. Wenn du einen Agent aufrufst, startet Claude Code eine fokussierte Sub-Sitzung, die unter den Einschränkungen des Agents arbeitet.
Stell dir Agents als gespeicherte, spezialisierte Prompts vor — aber mit mehr Struktur. Sie wissen, welche Tools sie nutzen dürfen, was ihre Grenzen sind und wie sie ihren Fachbereich angehen sollen.
Wo Agent-Definitionen liegen
Agent-Definitionen sind Markdown-Dateien mit YAML-Frontmatter im .claude/agents/-Verzeichnis deines Projekts:
dein-projekt/
.claude/
agents/
frontend-engineer.md
test-runner.md
code-reviewer.md
content-manager.md
Jede Datei definiert einen Agent. Claude Code erkennt sie automatisch.
Format der Agent-Definition
Eine Agent-Definitionsdatei hat zwei Teile: YAML-Frontmatter für die Konfiguration und Markdown-Body für die Anweisungen.
Die Grundstruktur:
---
name: agent-name
description: Einzeilige Beschreibung
model: claude-sonnet-4-20250514 # optional
tools:
- Read
- Edit
- Write
- Bash
- Grep
- Glob
---
# Agent-Anweisungen
Deine detaillierten Anweisungen in Markdown.
Wichtige Felder
- name: Der Bezeichner, mit dem du den Agent aufrufst
- description: Eine kurze Beschreibung, die in der Agent-Liste erscheint
- model: Welches Claude-Modell verwendet wird. Schnellere Modelle für einfache, leistungsfähigere für komplexe Aufgaben
- tools: Welche Tools der Agent nutzen darf. Tool-Einschränkungen begrenzen den Handlungsspielraum
Echte Beispiele aus meinem Workflow
Hier sind tatsächliche Agent-Definitionen, die ich in meinen Projekten einsetze:
Test-Runner Agent
Dieser Agent führt Tests aus, analysiert Fehler und behebt sie.
---
name: test-runner
description: Führt Tests aus, analysiert Fehler und behebt sie
tools:
- Bash
- Read
- Edit
- Glob
- Grep
---
# Test Runner Agent
Du bist ein Test-Runner und -Fixer. Dein Ablauf:
1. Test-Suite mit dem Projektbefehl ausführen (package.json oder CLAUDE.md prüfen)
2. Wenn alle Tests bestehen: Erfolg melden und stoppen
3. Bei Fehlern: Fehlerausgabe sorgfältig analysieren
4. Fehlschlagende Testdateien und getesteten Quellcode lesen
5. Feststellen, ob der Bug im Test oder in der Implementierung liegt
6. Problem beheben und Tests erneut ausführen
7. Wiederholen, bis alle Tests bestehen
## Regeln
- Nie Tests löschen oder überspringen, um die Suite grün zu bekommen
- Implementierungsfixes bevorzugen statt Testerwartungen zu ändern
- Nach dem Fix immer erneut ausführen zur Bestätigung
Code-Reviewer Agent
Dieser Agent reviewt Code, ohne Änderungen vorzunehmen. Beachte das eingeschränkte Tool-Set — er kann nur lesen, nicht schreiben.
---
name: code-reviewer
description: Reviewt Code-Änderungen mit strukturiertem Feedback
tools:
- Read
- Bash
- Grep
- Glob
---
# Code Reviewer Agent
Du bist ein Senior Code Reviewer. Reviewe die aktuellen Änderungen
(nutze git diff) und gib strukturiertes Feedback.
## Review-Checkliste
- **Korrektheit**: Tut der Code, was beabsichtigt ist?
- **Sicherheit**: Injection-Risiken, exponierte Secrets, fehlende Validierung?
- **Performance**: Unnötige Re-Renders, fehlendes Memoization, N+1-Queries?
- **Wartbarkeit**: Klare Benennung, sinnvolle Abstraktionen, kein toter Code?
- **Tests**: Sind Änderungen durch Tests abgedeckt?
## Regeln
- KEINE Änderungen vornehmen — nur reviewen und berichten
- Wenn der Code gut ist, das auch sagen
Frontend-Engineer Agent
Ein spezialisierter Agent für React-Komponentenarbeit:
---
name: frontend-engineer
description: React-Komponentenentwicklung mit Projektkonventionen
tools:
- Read
- Edit
- Write
- Bash
- Grep
- Glob
---
# Frontend Engineer Agent
Du bist Frontend-Engineer in einem React 19 + TypeScript + Vite Projekt.
## Konventionen
- CSS Modules (.module.css) — kein Tailwind
- Alle nutzersichtbaren Texte über i18next: t(''namespace:key'')
- Übersetzungen in frontend/src/i18n/locales/{en,de}/
- Mobile-first responsives Design
Wann Agents vs. direktes Prompting?
Verwende Agents, wenn:
- Du dieselbe Art von Aufgabe wiederholst — Code reviewen, Tests ausführen, Inhalte erstellen
- Die Aufgabe spezifische Einschränkungen braucht — eingeschränkter Tool-Zugriff, bestimmtes Ausgabeformat
- Du Konsistenz willst — dieselbe Review-Checkliste, dieselben Coding-Konventionen
- Du an ein Team delegierst — Agents dokumentieren deine Workflow-Erwartungen
Verwende direktes Prompting, wenn:
- Die Aufgabe einmalig und einzigartig ist
- Du Flexibilität brauchst, um den Ansatz mittendrin zu ändern
- Die Aufgabe simpel genug ist, dass Einschränkungen Overhead erzeugen
Tipps für gute Agent-Definitionen
Sei explizit, was nicht getan werden soll
Einschränkungen sind so wichtig wie Anweisungen. „Niemals Tests löschen" ist nützlicher als „Tests sorgfältig behandeln".
Gib einen Workflow vor
Nummerierte Schritte geben dem Agent einen klaren Ausführungspfad. Ohne sie überspringt er möglicherweise Schritte oder arbeitet in ineffizienter Reihenfolge.
Schränke Tools auf die Aufgabe ein
Ein Code-Reviewer, der keine Dateien bearbeiten kann, wird weniger wahrscheinlich anfangen, Dinge zu „fixen", die er nur markieren sollte. Tool-Einschränkungen sind Leitplanken.
Teste und iteriere
Agent-Definitionen sind Code. Behandle sie so — versioniere sie, verfeinere sie bei suboptimalen Ergebnissen und teile sie mit deinem Team.
Halte sie fokussiert
Ein Agent pro Verantwortungsbereich. Ein „Mach-alles"-Agent ist einfach eine normale Claude-Code-Sitzung. Der Wert von Agents kommt durch Spezialisierung.
Agents projektübergreifend teilen
Da Agent-Definitionen einfach Dateien in .claude/agents/ sind, kannst du:
- Sie zusammen mit dem Projektcode versionieren
- Sie zwischen Projekten kopieren und anpassen
- Eine persönliche Bibliothek in deinem Home-Verzeichnis unter
.claude/agents/für globalen Zugriff aufbauen
Das große Ganze
Custom Agents in Claude Code sind eine leichtgewichtige Methode, deine Entwicklungs-Workflows in wiederverwendbare, kombinierbare Einheiten zu verpacken. Sie sitzen im Sweet Spot zwischen Ad-hoc-Prompting und schwergewichtigen Automatisierungs-Frameworks.
Fang mit einem Agent für die Aufgabe an, die du am häufigsten wiederholst. Verfeinere ihn über eine Woche. Dann bau den nächsten. Innerhalb eines Monats hast du ein personalisiertes Toolkit, das dich deutlich schneller macht — nicht weil die KI alles erledigt, sondern weil du ihr beigebracht hast, wie du die Dinge haben willst.
