Custom Agents

Problem: Das Standard-Verhalten von Claude Code passt nicht dazu, wie dein Team tatsächlich arbeitet. Vielleicht willst du einen Reviewer, der den Hausstil kennt. Oder einen Deploy-Spezialisten, der in deine Infrastruktur eingebunden ist.

Schneller Einstieg: Deinen ersten Slash-Command aufzustellen dauert weniger als zwei Minuten. Fang damit an:

mkdir -p .claude/commands

Dann erstelle .claude/commands/code-review.md:

Review the recent code changes for quality and security:
 
1. Run git diff to see recent changes
2. Focus on modified files only
 
Review checklist:
 
- Code is readable and well-named
- No duplicated logic
- Proper error handling exists
- No exposed secrets or credentials
- Performance considerations addressed
 
Provide feedback by priority: Critical → Warnings → Suggestions

Dann ruf es mit /project:code-review innerhalb von Claude Code auf.

Wie Custom Commands deinen Workflow verändern

Verständnis: Ein benutzerdefinierter Slash-Command ist ein gespeicherter, wiederverwendbarer Prompt. Ruf ihn auf, Claude liest die Anweisungen darin, und dein Spezialist ist im Einsatz. Experten-Berater, einen Tastendruck entfernt.

Sie lösen auch das "Was war nochmal dieser Prompt"-Problem. Statt lange Anweisungen jede Sitzung neu zu tippen, parkst du sie in einer Datei. Die Datei trägt das angesammelte Expertenwissen deines Teams.

Drei Wege zu einem Custom Agent:

1. Slash Commands (.claude/commands/): Manuell ausgelöst mit /project:command-name
2. Agent Definitions (.claude/agents/): YAML-definierte Sub-Agenten-Rollen, die auf Abruf bereitstehen und während der Orchestrierung selbst spawnen
3. CLAUDE.md Anweisungen: Immer geladene Verhaltensweisen, die jeden Turn des Gesprächs formen

Commands vs. Agents: Die beiden lösen verschiedene Jobs. Ein Slash-Command ist ein gespeicherter Prompt, den du bei Bedarf für einen bekannten Workflow auslöst. Ein .claude/agents/-Eintrag stellt einen persistenten Sub-Agenten auf, den das Task-Tool selbstständig einbinden kann. Commands fühlen sich wie Tools auf einer Werkbank an. Agenten-Dateien fühlen sich wie Teammates an, die bereits eingestempelt haben.

Beide teilen dasselbe Scoping-Modell:

Alles unter dem Projektpfad wird zu git committed und mit dem ganzen Team geteilt. Der User-Pfad bleibt auf deinem Laptop und folgt dir von Repo zu Repo.

Separation of Concerns: Das gleiche Prinzip, das kleine Module über sprawlige siegen lässt, gilt für Prompts. Ein Command, der um eine einzige Security-Checkliste gebaut ist, fängt mehr Probleme als ein allgemeines "review this code" je wird.

Effektive Custom Commands erstellen

Einfach starten: Find das eine Problem, das immer wieder auf deinem Teller landet. Schreib den Command dafür.

Erstelle .claude/commands/security-audit.md:

You are a security expert. Scan this codebase for vulnerabilities.
 
Check for:
 
- SQL injection vulnerabilities
- XSS attack vectors
- Authentication bypass issues
- Exposed API keys or secrets
- OWASP Top 10 violations
 
For each finding, provide:
 
1. Vulnerability description
2. Risk level (Critical/High/Medium/Low)
3. Specific fix recommendation
4. Code example of the fix
 
Start by searching for common vulnerability patterns in the codebase.

Führ /project:security-audit aus, wann immer du einen Sicherheits-Sweep willst.

Dynamische Argumente: Ein Command kann Argumente über $ARGUMENTS lesen:

Erstelle .claude/commands/review-file.md:

Review this specific file for issues: $ARGUMENTS
 
Focus on: code quality, potential bugs, security concerns.

Aufruf mit /project:review-file src/auth/login.ts.

CLAUDE.md: Immer aktives Agenten-Verhalten

Für Regeln, die in jeder Sitzung aktiv sein sollen, pack sie in die CLAUDE.md deines Projekts:

## Code Review Standards
 
When reviewing code, always check:
 
- All functions have error handling
- No console.log statements in production code
- API endpoints validate input parameters
- Database queries use parameterized statements
 
## Commit Message Format
 
Use conventional commits: type(scope): description
Types: feat, fix, docs, refactor, test, chore

Nichts aufzurufen. Claude zieht CLAUDE.md rein, wenn die Sitzung startet, und wendet die Regeln auf jeden Turn danach an.

Projekt vs. User Commands:

• .claude/commands/ - Ins git committed für das ganze Team
• ~/.claude/commands/ - Privat für deine Maschine

Persistente Sub-Agenten-Definitionen mit .claude/agents/

Sub-Agenten, die der Orchestrator selbstständig spawnen soll, leben unter .claude/agents/. Jede Datei ist Markdown mit einem YAML-Block oben. Identität, Fähigkeiten und Anweisungen sitzen alle in diesem Block.

Im Gegensatz zu einem Slash-Command, der auf einen Tastendruck wartet, stehen diese Definitionen auf Bereitschaft. Das Task-Tool sieht sie während der Orchestrierung. Sobald Claude entscheidet, dass ein Task einen Spezialisten will, spawnt es den richtigen mit seinem Kontext und seinen Einschränkungen bereits verdrahtet.

YAML-Frontmatter-Syntax

Jede Datei unter .claude/agents/ beginnt mit einem YAML-Header, der Claude sagt, wie der Agent sich verhalten soll. Die Feldreferenz:

---
# Required
name: "security-auditor" # Agent identity (used in Task invocations)
 
# Optional
model: "claude-sonnet-4-5" # Override the default model
allowedTools: # Restrict which tools this agent can use
  - Read
  - Grep
  - Bash
description: "Scans code for vulnerabilities and OWASP violations"
---

Alles unterhalb des YAML-Blocks ist normales Markdown, das den System-Prompt enthält, mit dem der Agent läuft. Strukturell sieht es genauso aus wie ein Slash-Command. Der eigentliche Unterschied: Der Orchestrator kann diese Datei selbst sehen und den Agenten ohne manuellen Aufruf spawnen.

Ein Beispiel aus der Praxis

Hier ist ein konkreter Agent, der rund um Pre-Commit-Qualitätsgates gebaut ist. Die Datei geht nach .claude/agents/quality-engineer:

---
name: "quality-engineer"
allowedTools: ["Read", "Grep", "Bash"]
description: "Validates code against project standards before commits"
---
 
You are a quality engineer. Your job is to validate, never to modify.
 
## Validation Protocol
 
1. Read the files that changed (use git diff --name-only)
2. For each file, check:
   - Imports resolve correctly (grep for the import targets)
   - No console.log/print statements left in production code
   - Functions under 50 lines
   - All exported functions have JSDoc or docstring
3. Run the test suite: `npm test -- --bail`
4. Report pass/fail with specific line numbers for failures
 
Never edit files. Never suggest fixes. Only report what you find.

Wenn der Orchestrator einen Validierungs-Task erkennt, wird diese Definition von selbst aufgegriffen. Weil allowedTools Edit und Write auslässt, kann der Agent deine Codebase physisch nicht anfassen. Inspektion ist der einzige Zug, den er hat. Diese Grenze ist der ganze Grund, warum das Muster hält.

Dateien in diesem Ordner nehmen deine CLAUDE.md beim Reinkommen auch mit, also kommen Projektkonventionen und Coding-Standards ohne zusätzliche Klempnerarbeit mit.

Für mehr darüber, wie sich Sub-Agenten verhalten, einschließlich paralleler Runs, Backgrounding via Ctrl+B und Aufrufqualität, geht der Agent-Fundamentals-Guide tiefer.

Häufige Command-Beispiele

Database Optimizer (.claude/commands/db-optimize.md):

You are a database performance expert.
 
Analyze the database queries in this codebase:
 
1. Find slow or inefficient queries
2. Check for missing indexes
3. Review schema design
 
For each issue, provide:
 
- The problematic query or schema
- Why it's a problem
- Optimized version with explanation

Documentation Writer (.claude/commands/write-docs.md):

Write documentation for: $ARGUMENTS
 
Include:
 
- Purpose and overview
- Setup instructions
- Usage examples
- Common troubleshooting
 
Target audience: developers new to this project.
Write in clear, concise language.

Häufige Fehler beim Bauen von Custom Agents

Auf der Oberfläche sieht ein Custom Agent nach nichts aus. Scope ihn schlecht, und die Kosten sind vergwendete Token und flackernde Ergebnisse.

Fehler 1: Scope zu breit. Ein Agent, dem gesagt wird, die "gesamte Codebase auf alle Probleme" zu scannen, liefert dünne Beobachtungen verteilt über alles auf einmal zurück. Zeig denselben Agenten auf SQL Injection, beschränk ihn auf datenbanknahe Dateien, und er wird echte Bugs aufdecken. Den Scope enger machen. Die Tiefe steigern.

Fehler 2: Loses Output-Format. Lass die Report-Form offen und sie driftet von Run zu Run. Ein Durchlauf gibt dir Bullets. Der nächste gibt Prosa. Nagle es mit etwas Eindeutigem fest wie: For each finding, provide: file path, line number, severity, and a one-line fix.

Fehler 3: Schreibzugriff auf einem Reviewer. Wenn der Job des Agenten Inspektion ist, pin allowedTools auf Read, Grep und Bash. In dem Moment, wo du einem Reviewer Edit gibst, driftet er zum Codefix statt zum Berichten. Das löscht den Grund, warum der Validator überhaupt separat war.

Fehler 4: CLAUDE.md-Regeln in Commands wiederholen. CLAUDE.md ist bereits geladen, wenn ein Command läuft. Diese Regeln in jeder Command-Datei nochmals zu sagen, frisst einfach Kontext-Token. Ein Command soll Verhalten einengen, nicht die universelle Baseline wiederholen. Wenn "parametrisierte Queries verwenden" in CLAUDE.md steht, braucht dein Datenbank-Command diese Zeile nicht auch noch.

Wann du welchen Ansatz nutzt

Die Wahl zwischen Slash-Commands, Agenten-Dateien, Skills und CLAUDE.md hängt von zwei Dingen ab. Was das Verhalten auslöst, und wie lange es anhalten soll.

Die praktische Linie läuft so. Jeder detaillierte Prompt, den du dreimal getippt hast, verdient es, als Slash-Command gespeichert zu werden. Jeder Spezialist, den der Orchestrator selbstständig aufrufen soll, gehört unter .claude/agents/. Alles andere landet in CLAUDE.md als universelles Verhalten, oder in einem Skill für Domain-Wissen, das faul lädt. Der Skills-Guide behandelt diesen letzten Weg vollständig.

Für spezialisierte Rollen prompten

Du brauchst nicht immer eine gespeicherte Datei. Manchmal reicht ein direkter Prompt:

Act as a senior security engineer. Review the authentication
flow in src/auth/ for vulnerabilities. Be thorough and paranoid.

Gut genug für ein Einzel-Ding. In dem Moment, wo du merkst, dass du es zweimal getippt hast, heb es in einen gespeicherten Command.

Nächste Schritte

Zeit, deinen ersten Spezialisten zu bauen. Wähle den lautesten Schmerzpunkt heute:

• Code-Qualität: Mach aus deinen Hausregeln einen Reviewer-Command, geleitet vom Agent-Fundamentals-Guide
• Security-Fokus: Schreib einen Schwachstellen-Scanner auf Basis der Sub-Agent-Design-Notizen
• Team-Workflow: Leg ein Kollaborationsmuster mit dem Task-Distribution-Playbook aus

Gespeicherte Commands steigern ihren Wert, je länger du mit ihnen lebst. Push sie ins Repo. Gib sie ans Team weiter. Wachse eine Bibliothek, die erfasst, wie deine Gruppe tatsächlich liefert.