Agents personnalisés

Le problème: Le comportement Claude Code par défaut ne correspond pas à la façon dont ton équipe travaille vraiment. Peut-être que tu veux un relecteur qui connaît le style maison. Ou un spécialiste de déploiement câblé à ton infrastructure.

Gain rapide: Monter ton premier slash command prend moins de deux minutes. Commence par ça :

mkdir -p .claude/commands

Puis crée .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

Puis appelle-le avec /project:code-review dans Claude Code.

Comment les commandes personnalisées changent ton workflow

La logique: Un slash command personnalisé est un prompt sauvegardé et réutilisable. Tu l'appelles, Claude lit les instructions dedans, et ton spécialiste est au boulot. Des experts consultants, à portée d'une touche.

Ils règlent aussi le problème du "c'était quoi déjà ce prompt". Plutôt que de retaper de longues instructions à chaque session, tu les gares dans un fichier. Le fichier porte l'expertise accumulée de ton équipe.

Trois routes vers un agent personnalisé :

1. Slash Commands (.claude/commands/) : Lance manuellement avec /project:command-name
2. Définitions d'agents (.claude/agents/) : Rôles de sub-agents définis en YAML qui restent disponibles et se spawnent seuls pendant l'orchestration
3. Instructions CLAUDE.md : Comportements toujours chargés qui façonnent chaque tour de conversation

Commands vs Agents: Les deux résolvent des jobs différents. Un slash command est un prompt sauvegardé que tu déclenches à la demande pour un workflow connu. Une entrée .claude/agents/ monte un sub-agent persistant que l'outil Task peut amener seul. Les commands ressemblent à des outils posés sur un établi. Les fichiers d'agents ressemblent à des coéquipiers déjà pointés.

Les deux partagent le même modèle de portée :

Tout sous le chemin du projet est commité dans git et partagé avec toute l'équipe. Le chemin utilisateur reste sur ta machine et te suit d'un repo à l'autre.

Séparation des préoccupations: Le même principe qui fait que les petits modules battent les monolithes s'applique aux prompts. Une command centrée sur une seule checklist de sécurité attrape plus de problèmes qu'un "review this code" générique.

Créer des commandes personnalisées efficaces

Commence simple: Trouve le problème qui revient sans cesse sur ton bureau. Écris la command pour ça.

Crée .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.

Lance /project:security-audit quand tu veux un balayage de sécurité.

Arguments dynamiques: Une command peut lire des arguments via $ARGUMENTS :

Crée .claude/commands/review-file.md :

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

Invoque avec /project:review-file src/auth/login.ts.

CLAUDE.md : Comportement d'agent toujours actif

Pour les règles que tu veux actives dans chaque session, mets-les dans le CLAUDE.md de ton projet :

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

Rien à invoquer. Claude tire CLAUDE.md au démarrage de la session et applique les règles à chaque tour après ça.

Project vs User Commands :

• .claude/commands/ - Commité dans git pour toute l'équipe
• ~/.claude/commands/ - Privé à ta machine uniquement

Définitions de sub-agents persistants avec .claude/agents/

Les sub-agents que l'orchestrateur doit spawner seul vivent dans .claude/agents/. Chaque fichier est du Markdown avec un bloc YAML en haut. L'identité, les capacités, et les instructions sont toutes dans ce bloc.

Contrairement à un slash command qui attend une touche, ces définitions restent en veille. L'outil Task les voit pendant l'orchestration. Dès que Claude décide qu'une tâche veut un spécialiste, il spawne le bon avec son contexte et ses contraintes déjà câblés.

Syntaxe du frontmatter YAML

Chaque fichier dans .claude/agents/ commence par un en-tête YAML qui dit à Claude comment l'agent doit se comporter. La référence des champs :

---
# 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"
---

Tout ce qui est sous le bloc YAML est du Markdown simple, qui contient le prompt système que l'agent utilise. Structurellement, ça ressemble à un slash command. La vraie différence : l'orchestrateur peut voir ce fichier seul et spawner l'agent sans invocation manuelle.

Un exemple pratique

Voici un agent concret, construit autour de contrôles qualité pré-commit. Le fichier va dans .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.

Quand l'orchestrateur repère une tâche de validation, cette définition est récupérée seule. Parce qu'allowedTools exclut Edit et Write, l'agent ne peut physiquement pas toucher ta codebase. L'inspection est le seul move qu'il a. Cette limite est la raison pour laquelle le pattern tient.

Les fichiers dans ce dossier récupèrent aussi ton CLAUDE.md au passage, donc les conventions de projet et les standards de code viennent avec sans aucun câblage supplémentaire.

Pour plus de détails sur le comportement des sub-agents, notamment les runs parallèles, le passage en arrière-plan via Ctrl+B, et la qualité d'invocation, le guide des fondamentaux des agents va plus loin.

Exemples de commandes courantes

Optimiseur de base de données (.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

Rédacteur de documentation (.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.

Erreurs courantes quand on construit des agents personnalisés

En surface, un agent personnalisé ça n'a l'air de rien. Définis-en un mal et le coût c'est des tokens gaspillés et des résultats instables.

Erreur 1 : Portée trop large. Un agent à qui on dit de scanner "cette codebase pour tous les problèmes" retourne des observations superficielles réparties sur tout à la fois. Pointe ce même agent sur l'injection SQL, restreins-le aux fichiers liés à la base de données, et il va remonter de vrais bugs. Resserre la portée. Approfondit le creusage.

Erreur 2 : Format de sortie flou. Laisse la forme du rapport ouverte et elle dérive d'une run à l'autre. Une passe te donne des bullets. La suivante donne de la prose. Cloue-le avec quelque chose d'ambigu comme : For each finding, provide: file path, line number, severity, and a one-line fix.

Erreur 3 : Accès en écriture sur un relecteur. Quand le job de l'agent est l'inspection, épingle son allowedTools sur Read, Grep, et Bash. Dès que tu donnes Edit à un relecteur, il dérive vers la correction de code plutôt que le signalement. Ça efface la raison pour laquelle le validator était séparé.

Erreur 4 : Répéter les règles CLAUDE.md dans les commandes. CLAUDE.md est déjà chargé quand une command tourne. Reformuler ces règles dans chaque fichier de command grignote juste des tokens de contexte. Une command doit affiner le comportement, pas reformuler la baseline universelle. Si "utiliser des requêtes paramétrées" est dans CLAUDE.md, ta command de base de données n'a pas besoin de cette ligne.

Quand utiliser chaque approche

Choisir entre slash commands, fichiers d'agents, skills, et CLAUDE.md se résume à deux choses. Ce qui déclenche le comportement, et combien de temps il doit persister.

La ligne pratique est celle-ci. Tout prompt détaillé que tu as tapé trois fois mérite d'être sauvegardé comme slash command. Tout spécialiste que l'orchestrateur doit invoquer seul appartient à .claude/agents/. Tout le reste atterrit dans CLAUDE.md comme comportement universel, ou dans un skill pour la connaissance de domaine qui se charge en différé. Le guide des skills couvre cette dernière route en détail.

Prompter pour des rôles spécialisés

T'as pas toujours besoin d'un fichier sauvegardé. Parfois un prompt direct suffit :

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

Suffisant pour une fois. Dès que tu remarques que tu l'as tapé deux fois, extrait-le dans une command sauvegardée.

Prochaines actions

Il est temps de construire ton premier spécialiste. Prends le point de douleur le plus bruyant aujourd'hui :

• Qualité de code: Transforme les règles maison en une command de relecteur, en s'appuyant sur le guide des fondamentaux des agents
• Focus sécurité: Écris un scanner de vulnérabilités ancré dans les notes de design des sub-agents
• Workflow d'équipe: Mets en place un pattern de collaboration en utilisant le playbook de distribution de tâches

Les commandes sauvegardées s'accumulent en valeur plus tu vis avec. Pousse-les dans le repo. Partage-les dans l'équipe. Construis une bibliothèque qui capture la façon dont ton groupe ship du code.