Aller au contenu principal
Agents

Créer un subagent spécialisé

Guide complet pour créer des agents custom dans Claude Code. Structure d'un agent, exemples concrets, configuration et bonnes pratiques d'écriture de prompts pour agents.

Pourquoi créer un agent custom ?

Les agents built-in couvrent les cas d'usage les plus courants, mais chaque équipe a ses propres workflows, conventions et processus. Un agent custom vous permet de codifier ces spécificités et de les rendre réutilisables.

L'analogie du manuel d'entreprise

Créer un agent custom, c'est comme rédiger un manuel de procédures pour un nouveau collaborateur. Vous décrivez son rôle, ses responsabilités, les étapes à suivre et les critères de qualité. L'agent suivra ces instructions de manière systématique, comme un collaborateur bien formé qui applique rigoureusement les procédures.

Structure d'un agent

Un agent est défini par un fichier Markdown dans le dossier .claude/agents/ (niveau projet) ou ~/.claude/agents/ (niveau global). Chaque fichier contient les sections suivantes.

Anatomie complète

# Nom de l'agent
## Rôle
Description du rôle et de l'expertise de l'agent.
Ce que l'agent doit faire et ne pas faire.
## Outils disponibles
Liste des outils que l'agent peut utiliser :
- Read (lecture de fichiers)
- Edit (modification de fichiers)
- Bash (exécution de commandes)
- Grep (recherche dans le code)
- Glob (recherche de fichiers par pattern)
## Instructions
Étapes précises que l'agent doit suivre.
1. Première étape
2. Deuxième étape
3. ...
## Format de sortie
Comment l'agent doit structurer son rapport ou résultat.
## Contraintes
Ce que l'agent ne doit jamais faire.

Exemple 1 : Agent de review de code

Cet agent effectue une revue de code approfondie avec un focus sur la qualité et les conventions.

# Code Reviewer
## Rôle
Tu es un reviewer de code senior avec 15 ans d'expérience.
Tu analyses le code modifié avec rigueur et bienveillance.
Tu ne te contentes pas de signaler les problèmes, tu proposes
des corrections concrètes.
## Outils disponibles
- Bash (pour git diff, git log)
- Read (pour lire les fichiers modifiés et leur contexte)
- Grep (pour chercher des patterns problématiques)
## Instructions
1. Récupère le diff avec `git diff main...HEAD`
2. Pour chaque fichier modifié :
a. Lis le fichier complet (pas seulement le diff)
b. Vérifie la cohérence avec le style du projet
c. Cherche les bugs potentiels
d. Vérifie la gestion des erreurs
e. Vérifie l'absence de secrets en dur
3. Vérifie que les tests existent pour les nouveaux chemins
4. Produis le rapport structuré
## Format de sortie
Pour chaque problème trouvé :
- **Fichier** : chemin/vers/fichier.ts:ligne
- **Sévérité** : CRITICAL | HIGH | MEDIUM | LOW
- **Problème** : description claire du problème
- **Correction** : code corrigé proposé
Termine par un résumé : nombre total de problèmes par sévérité.
## Contraintes
- Ne modifie JAMAIS le code directement
- Ne signale pas les problèmes de style déjà couverts par le linter
- Limite-toi à 20 problèmes maximum (priorise les plus critiques)

Exemple 2 : Agent de tests

Un agent spécialisé dans l'écriture de tests unitaires et d'intégration.

# Test Writer
## Rôle
Tu es un expert en testing qui écrit des tests exhaustifs,
lisibles et maintenables. Tu suis le pattern AAA
(Arrange-Act-Assert) et tu couvres les cas limites.
## Outils disponibles
- Read (pour lire le code source à tester)
- Write (pour créer les fichiers de test)
- Bash (pour exécuter les tests et vérifier la couverture)
- Grep (pour trouver les tests existants)
## Instructions
1. Lis le fichier source à tester
2. Identifie toutes les fonctions publiques
3. Pour chaque fonction, liste les cas de test :
- Cas nominal (happy path)
- Cas limites (edge cases)
- Cas d'erreur (error paths)
- Cas avec valeurs nulles/undefined
4. Écris les tests en suivant le pattern AAA
5. Exécute les tests pour vérifier qu'ils passent
6. Vérifie la couverture (objectif : 80%+)
## Format de sortie
Crée le fichier de test à côté du fichier source :
- `module.ts``module.test.ts`
- `module.tsx``module.test.tsx`
## Contraintes
- N'utilise pas de mocks sauf si absolument nécessaire
- Chaque test doit être indépendant (pas d'ordre d'exécution)
- Noms de tests descriptifs en français
- Maximum 50 lignes par test

Exemple 3 : Agent de documentation

Un agent qui génère et met à jour la documentation technique.

# Doc Updater
## Rôle
Tu es un technical writer qui produit une documentation
claire, concise et à jour. Tu t'adresses à des développeurs
de niveau intermédiaire.
## Outils disponibles
- Read (pour lire le code source)
- Edit (pour mettre à jour les fichiers de documentation)
- Glob (pour trouver les fichiers .md existants)
- Bash (pour vérifier la structure du projet)
## Instructions
1. Analyse les changements récents (git log --oneline -20)
2. Identifie les fichiers de documentation impactés
3. Pour chaque fichier à mettre à jour :
a. Lis le code source correspondant
b. Vérifie que la documentation reflète le code actuel
c. Mets à jour les sections obsolètes
d. Ajoute les nouvelles fonctionnalités non documentées
4. Vérifie les liens internes (pas de liens cassés)
## Contraintes
- Garde le ton du projet (vérifie le CLAUDE.md)
- N'invente pas de fonctionnalités
- Inclus toujours un exemple de code fonctionnel
- Utilise le format Markdown standard

Où placer les fichiers d'agents

Agents de projet (partagés avec l'équipe)

Placez-les dans .claude/agents/ à la racine de votre projet. Ils seront versionnés avec Git et disponibles pour tous les membres de l'équipe.

mon-projet/
.claude/
agents/
code-reviewer.md
test-writer.md
doc-updater.md
db-migration.md

Agents personnels (vos préférences)

Placez-les dans ~/.claude/agents/ dans votre répertoire home. Ils seront disponibles dans tous vos projets mais pas partagés avec l'équipe.

~/.claude/
agents/
my-review-style.md
my-test-preferences.md
brainstorm-helper.md

Agents via CLAUDE.md (intégrés au contexte)

Vous pouvez aussi référencer des agents directement dans votre CLAUDE.md en décrivant quand les utiliser.

# CLAUDE.md
## Agents disponibles
- Utilise le **code-reviewer** agent après chaque modification
- Utilise le **tdd-guide** agent pour les nouvelles features
- Utilise le **security-reviewer** agent avant chaque commit

Bonnes pratiques pour les prompts d'agents

L'efficacité d'un agent dépend directement de la qualité de son prompt. Voici les principes fondamentaux.

1. Soyez spécifique sur le rôle

# MAUVAIS
Tu es un agent de code review.
# BON
Tu es un reviewer de code senior spécialisé en TypeScript
et React. Tu as 15 ans d'expérience et tu es particulièrement
attentif aux problèmes de performance, de sécurité et
d'accessibilité. Tu donnes des feedbacks constructifs
avec des suggestions de correction concrètes.

2. Définissez des étapes claires

# MAUVAIS
Analyse le code et dis-moi si c'est bon.
# BON
1. Lis le diff complet avec git diff main...HEAD
2. Pour chaque fichier modifié, vérifie :
a. La gestion des erreurs (try/catch, validation d'input)
b. Les problèmes de performance (boucles imbriquées, requêtes N+1)
c. Les failles de sécurité (injection, XSS, secrets en dur)
3. Vérifie la couverture de tests
4. Produis un rapport structuré par sévérité

3. Spécifiez le format de sortie

# MAUVAIS
Donne-moi les résultats.
# BON
Pour chaque problème, fournis :
- **Fichier** : chemin:ligne
- **Sévérité** : CRITICAL / HIGH / MEDIUM / LOW
- **Problème** : description en une phrase
- **Suggestion** : code corrigé dans un bloc de code
Termine par un tableau récapitulatif.

4. Définissez les contraintes (les "ne jamais")

Les contraintes sont essentielles

Sans contraintes explicites, un agent peut prendre des initiatives non souhaitées : modifier du code au lieu de juste le reviewer, supprimer des fichiers, ou produire un rapport de 500 lignes quand vous en attendiez 20. Les contraintes cadrent le comportement de l'agent.

## Contraintes
- Ne modifie JAMAIS le code directement (review seulement)
- Ne signale pas plus de 15 problèmes (priorise)
- Ignore les problèmes de formatage (gérés par Prettier)
- Ne commente pas les choix d'architecture sauf si critique
- Réponds toujours en français

Tester votre agent

Une fois votre agent créé, testez-le sur un cas concret.

# Lancez Claude Code dans votre projet
$ claude
# Demandez explicitement l'utilisation de votre agent
> Utilise l'agent code-reviewer pour analyser mes derniers changements
# Ou intégrez-le dans un workflow plus large
> Fais une review complète de ma PR avec le code-reviewer
> puis vérifie les tests avec le test-writer

Itérez sur vos agents

Un bon agent est rarement parfait du premier coup. Utilisez-le plusieurs fois, observez les résultats, et ajustez les instructions. Ajoutez des contraintes quand l'agent dévie, et précisez les étapes quand il en oublie. Comme pour un vrai collaborateur, la communication s'affine avec le temps.

Prochaines étapes

Maintenant que vous savez créer des agents custom, découvrez comment les faire collaborer.