Custom Agents erstellen
Level 2 | 40 Minuten
Baue eigene spezialisierte Agents für deine Workflows
Lernziele
- Die Agent-Architektur verstehen
- Vollständige Custom Agents erstellen
- Agent-Permissions und Hooks konfigurieren
- Agents in Workflows integrieren
Agent Architektur
Ein Custom Agent in Claude Code ist eine vollständig konfigurierte KI-Einheit mit eigener Identität, eigenen Fähigkeiten und eigenem Verhalten. Während Subagents temporäre Helfer sind die für einzelne Aufgaben spawnen, sind Custom Agents dauerhafte Spezialisten die du immer wieder einsetzen kannst. Die Architektur eines Custom Agents folgt einem klaren Schichtenmodell — wie ein Haus mit verschiedenen Stockwerken. Das Fundament ist der System-Prompt, der die Identität und Grundregeln definiert. Darüber liegt die Tool-Schicht, die bestimmt was der Agent tun darf. Darüber die Wissens-Schicht mit Skills und Referenzdokumenten. Und ganz oben die Interaktions-Schicht, die definiert wie der Agent mit dir und anderen Agents kommuniziert. Der System-Prompt ist das Herzstück. Er definiert WER der Agent ist (seine Rolle), WAS er tut (seine Aufgaben), WIE er arbeitet (seine Methode) und WAS ER NICHT TUT (seine Grenzen). Ein guter System-Prompt ist wie eine Stellenbeschreibung: klar, spezifisch und vollständig. Ein Senior-Security-Reviewer Agent hat einen ganz anderen System-Prompt als ein Junior-Documentation-Writer Agent. Die Tool-Schicht folgt dem Principle of Least Privilege: Jeder Agent bekommt nur die Tools die er für seine Aufgabe braucht. Ein Code-Review Agent braucht Read und Grep, aber nicht Write oder Bash. Ein Test-Runner Agent braucht Bash und Read, aber nicht Write. Diese Einschränkung erhöht nicht nur die Sicherheit, sondern hilft dem Agent auch sich auf seine Kernaufgabe zu fokussieren. Die Wissens-Schicht besteht aus Skills die dem Agent spezifisches Domänenwissen geben. Der Security-Reviewer kennt die OWASP Top 10, der Testing-Agent kennt die Test-Konventionen, der API-Agent kennt die REST-Standards. Dieses Wissen wird beim Start des Agents geladen. Die Interaktions-Schicht definiert Kommunikationsregeln: Wie ausführlich sind die Antworten? Wann fragt der Agent nach? Wie strukturiert er seine Reports? Diese Regeln sorgen für konsistentes, vorhersagbares Verhalten.
CUSTOM AGENT KOMPONENTEN
━━━━━━━━━━━━━━━━━━━━━━━━
┌─────────────────────────────────────┐
│ AGENT.md │
├─────────────────────────────────────┤
│ YAML Frontmatter │
│ ├── name, description │
│ ├── model (haiku/sonnet/opus) │
│ ├── tools (allowed tools) │
│ ├── permissions │
│ ├── hooks (on_start, on_complete) │
│ └── context_files │
├─────────────────────────────────────┤
│ Markdown Instructions │
│ ├── Rolle & Persönlichkeit │
│ ├── Aufgaben-Beschreibung │
│ ├── Workflows & Prozesse │
│ ├── Output-Formate │
│ └── Beispiele │
└─────────────────────────────────────┘Vollständiger Custom Agent
Ein vollständiger Custom Agent bringt alle Architektur-Schichten zusammen: System-Prompt, Tool-Berechtigungen, Skills und Kommunikationsregeln. Anhand eines konkreten Beispiels — einem Code-Review-Agent — siehst du wie alle Teile zusammenspielen. Der Code-Review-Agent hat einen klaren Auftrag: Er prüft Code-Änderungen auf Qualität, Sicherheit, Performance und Konsistenz mit den Projektstandards. Er liest Code, analysiert ihn, und liefert einen strukturierten Report — er ändert aber selbst keinen Code. Das ist wichtig: Die klare Abgrenzung verhindert unbeabsichtigte Seiteneffekte. Sein System-Prompt definiert die Persona: 'Du bist ein erfahrener Senior Developer der Code Reviews durchführt. Du achtest auf: Korrektheit der Logik, Error Handling, Security-Schwachstellen, Performance-Probleme, Code-Style-Verstöße und fehlende Tests. Dein Ton ist konstruktiv und lösungsorientiert — du zeigst nicht nur Probleme auf, sondern schlägst konkrete Verbesserungen vor.' Die Tool-Berechtigungen sind bewusst restriktiv: Nur Read (Dateien lesen), Grep (Code durchsuchen), und Glob (Dateien finden). Kein Write, kein Edit, kein Bash. Der Agent kann analysieren aber nicht ändern — das ist eine Sicherheitsentscheidung. Der Agent referenziert projektspezifische Skills: Den Code-Style-Skill für Konventionen, den Security-Skill für bekannte Schwachstellen-Patterns, und den Testing-Skill für die Prüfung der Test-Abdeckung. Die Kommunikationsregeln definieren das Output-Format: Jedes Finding hat eine Kategorie (Bug, Security, Performance, Style), einen Schweregrad (Critical, High, Medium, Low), eine Beschreibung, den betroffenen Code und einen Verbesserungsvorschlag. Das macht die Reports maschinenlesbar und konsistent. Der Agent wird als Markdown-Datei in .claude/agents/code-reviewer.md gespeichert. Du rufst ihn auf mit @code-reviewer oder über einen Slash-Command. In der Praxis spart so ein Agent pro Review 15-20 Minuten und liefert konsistentere Ergebnisse als ad-hoc Reviews.
# .claude/agents/pr-reviewer/AGENT.md
---
name: pr-reviewer
description: Automatisiertes PR Review mit Best Practices
model: sonnet
tools:
- Read
- Grep
- Bash
- WebFetch
permissions:
- read_files
- execute_bash
context_files:
- "CONTRIBUTING.md"
- ".eslintrc.js"
- "tsconfig.json"
hooks:
on_start: |
echo "Starting PR Review..."
git fetch origin
on_complete: |
echo "Review complete. Check output."
on_error: |
echo "Review failed. Check logs."
---
# PR Reviewer Agent
Du bist ein erfahrener Senior Developer, spezialisiert auf Code Reviews.
## Deine Rolle
- Gründlich aber konstruktiv
- Fokus auf Verbesserung, nicht Kritik
- Erkläre das WARUM hinter Feedback
- Lobe gute Patterns
## Review Prozess
### 1. PR Info laden
Permissions Deep Dive
Das Permission-System ist das Sicherheitsrückgrat von Claude Code. Es kontrolliert granular, welche Aktionen erlaubt sind — von einfachem Dateizugriff über Shell-Befehle bis hin zu MCP-Tools. Ohne das Permission-System wäre Claude Code ein unkontrollierbares Werkzeug; mit ihm hast du volle Kontrolle über jeden Aspekt. Das System arbeitet mit drei Ebenen: Allow (erlaubt ohne Nachfrage), Deny (blockiert immer), und Ask (fragt jedes Mal nach). Deny-Regeln haben IMMER Vorrang — auch wenn eine Allow-Regel das Gleiche erlaubt. Das ist eine bewusste Sicherheitsentscheidung: Verbote sind stärker als Erlaubnisse. Die Berechtigungen können auf vier Ebenen konfiguriert werden, von allgemein bis spezifisch: Enterprise-Einstellungen (gelten für das gesamte Unternehmen), User-Einstellungen (~/.claude/settings.json), Projekt-Einstellungen (.claude/settings.json im Repo), und lokale Einstellungen (.claude/settings.local.json, nicht committed). Spezifischere Ebenen überschreiben allgemeinere. Beispiele für typische Berechtigungen: 'Read' erlaubt das Lesen aller Dateien. 'Edit' erlaubt Dateiänderungen. 'Bash(npm run:*)' erlaubt alle npm-Befehle die mit 'run:' beginnen. 'mcp__github__*' erlaubt alle Tools des GitHub MCP Servers. Du kannst sehr granular steuern was erlaubt ist. Für Teams ist die Projekt-Konfiguration in .claude/settings.json besonders wertvoll: Sie wird ins Git-Repository committed und gilt automatisch für alle Teammitglieder. So stellst du sicher, dass alle die gleichen Sicherheitsregeln haben — niemand kann versehentlich die Produktionsdatenbank modifizieren. Die Datei .claude/settings.local.json ist für persönliche Übersteuerungen gedacht. Hier kannst du Berechtigungen für deine lokale Umgebung anpassen ohne die Team-Konfiguration zu ändern. Diese Datei sollte in .gitignore stehen. Mein wichtigster Rat: Starte restriktiv und erweitere die Berechtigungen nach Bedarf. Es ist einfacher eine Berechtigung hinzuzufügen als den Schaden rückgängig zu machen der durch eine zu lockere Berechtigung entstanden ist.
# Permission Levels für Agents
permissions:
# Datei-Operationen
- read_files # Dateien lesen
- write_files # Dateien schreiben
- delete_files # Dateien löschen (vorsichtig!)
# Bash Execution
- execute_bash # Beliebige Bash Commands
- execute_safe_bash # Nur safe Commands (ls, cat, etc.)
# Git Operationen
- git_read # git status, log, diff
- git_write # git add, commit
- git_push # git push (gefährlich!)
# Netzwerk
- web_fetch # HTTP Requests
- mcp_access # MCP Server nutzen
# System
- env_access # Environment Variables lesen
# Beispiel: Minimale Permissions für Read-Only Agent
permissions:
- read_files
- execute_safe_bash
- git_readHooks System
Hooks sind der deterministische Gegenpol zum intelligenten KI-Agent. Während Claude als KI entscheidet ob und wie es etwas tut, laufen Hooks GARANTIERT ab wenn ein bestimmtes Event eintritt. Kein Ermessensspielraum, kein Vergessen, keine Abweichung — pure Automatisierung. Stell dir Hooks vor wie Alarm-Systeme in einem Haus: Unabhängig davon ob der Bewohner aufpasst, löst der Rauchmelder bei Rauch immer aus. Genauso löst ein Hook bei einem bestimmten Claude Code Event immer die definierte Aktion aus — egal was Claude gerade tut oder denkt. Hooks reagieren auf Lifecycle-Events: SessionStart (Session beginnt), UserPromptSubmit (du sendest eine Nachricht), PreToolUse (bevor ein Tool genutzt wird), PostToolUse (nachdem ein Tool genutzt wurde), Notification (Claude sendet eine Benachrichtigung), Stop (Session endet), und weitere. Für jedes Event kannst du einen oder mehrere Shell-Befehle definieren. Der häufigste Einsatzzweck: Code-Formatting nach jeder Dateiänderung. Statt darauf zu hoffen dass Claude den Formatter aufruft, definierst du einen PostToolUse-Hook der bei jedem Edit oder Write automatisch prettier oder eslint ausführt. Das Ergebnis: Dein Code ist IMMER formatiert, egal was Claude macht. Der zweitbeliebteste Einsatz: Sicherheitsschutz. Ein PreToolUse-Hook auf Bash prüft ob der auszuführende Befehl gefährlich ist (rm -rf, DROP TABLE, etc.) und blockiert ihn bevor er ausgeführt wird. Das ist eine harte Sicherheitsbarriere die auch bei Prompt Injection funktioniert. Seit Version 2.1.0 gibt es auch Agent-basierte Hooks: Statt eines einfachen Shell-Befehls entscheidet ein kleines Claude-Modell ob der Hook auslösen soll. Das ermöglicht intelligentere Entscheidungen — z.B. 'Löse den Lint-Hook nur bei TypeScript-Dateien aus, nicht bei Markdown'. Das ist ein Hybrid aus Determinismus und Intelligenz. Hooks werden in der Settings-Datei konfiguriert, nicht als separate Dateien. Sie können global, pro Projekt oder lokal definiert werden.
# Available Hooks für Agents
hooks:
# Lifecycle Hooks
on_start: |
echo "Agent starting"
# Setup-Logik hier
on_complete: |
echo "Agent completed successfully"
# Cleanup, Notifications
on_error: |
echo "Agent encountered error: $ERROR"
# Error handling, Rollback
# Tool Hooks
before_edit: |
# Vor jeder Datei-Änderung
git stash
after_edit: |
# Nach jeder Datei-Änderung
npm run lint --fix
before_bash: |
# Vor jedem Bash Command
echo "Executing: $COMMAND"
# Validation Hooks
validate_output: |
# Output prüfen bevor Return
if [[ -z "$OUTPUT" ]]; then
exit 1
fiAgent in Workflows einbinden
Ein fertig konfigurierter Agent entfaltet seine volle Wirkung erst wenn er nahtlos in deine täglichen Workflows integriert ist. Ein Agent der nur über direkte Ansprache funktioniert wird schnell vergessen. Ein Agent der automatisch bei bestimmten Events aktiv wird, verändert deine Arbeitsweise fundamental. Der einfachste Integrationsweg ist über Slash-Commands. Du erstellst einen Command der den Agent aufruft, z.B. /review der den Code-Review-Agent startet, oder /security der den Security-Audit-Agent triggert. So brauchst du nur einen kurzen Befehl und der Agent erledigt den Rest. Für automatische Integration nutzt du Hooks. Ein Hook kann einen Agent bei bestimmten Events starten: Bei jedem Git-Commit den Review-Agent ausführen, bei jeder neuen Datei den Style-Check-Agent starten, bei Session-Ende den Documentation-Agent die Änderungen dokumentieren lassen. In CI/CD-Pipelines verwendest du den Headless Mode. Der Agent wird über 'claude -p' mit einem spezifischen Prompt aufgerufen und liefert das Ergebnis als Text oder JSON zurück. Das ist perfekt für automatische Code-Reviews bei Pull Requests, Nightly-Security-Scans oder automatische Test-Generierung. Für Team-Workflows definierst du die Agent-Konfigurationen im .claude/agents/ Verzeichnis und committst sie ins Repository. Jedes Team-Mitglied hat dann automatisch Zugriff auf die gleichen Agents. Kombiniert mit standardisierten Slash-Commands entsteht ein konsistenter Team-Workflow den alle nutzen können. Ein fortgeschrittenes Pattern: Agent-Chains. Der Output eines Agents wird zum Input des nächsten. Erst analysiert der Explore-Agent das Problem, dann plant der Architecture-Agent die Lösung, dann implementiert der Coding-Agent den Plan, und schließlich testet der Testing-Agent das Ergebnis. Diese Chain kann komplett automatisiert ablaufen. Mein Praxis-Tipp: Starte mit einem einzelnen Agent für deine häufigste Aufgabe. Wenn er sich bewährt hat, erstelle den zweiten. Iterativ aufbauen ist besser als alles auf einmal zu automatisieren.
# .claude/skills/deploy-workflow/SKILL.md
---
name: deploy-workflow
description: Kompletter Deployment-Workflow
invocation: user
triggers: ["deploy", "release"]
---
# Deploy Workflow
## Agents die genutzt werden
1. test-runner - Alle Tests ausführen
2. pr-reviewer - Final Review
3. deploy-agent - Deployment ausführen
## Workflow
### Phase 1: Validation
💡 Agent Design Best Practices 1. Single Responsibility - Ein Agent, ein Zweck 2. Least Privilege - Nur nötige Permissions 3. Clear Instructions - Detaillierte Markdown-Docs 4. Error Handling - on_error Hooks nutzen 5. Idempotent - Agent kann mehrfach laufen 6. Testable - Agent-Output sollte prüfbar sein