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ôleDescription du rôle et de l'expertise de l'agent.Ce que l'agent doit faire et ne pas faire.## Outils disponiblesListe 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 étape2. Deuxième étape3. ...## Format de sortieComment l'agent doit structurer son rapport ou résultat.## ContraintesCe 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ôleTu 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 proposesdes 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)## Instructions1. 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 projetc. Cherche les bugs potentielsd. Vérifie la gestion des erreurse. Vérifie l'absence de secrets en dur3. Vérifie que les tests existent pour les nouveaux chemins4. Produis le rapport structuré## Format de sortiePour 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ôleTu 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)## Instructions1. Lis le fichier source à tester2. Identifie toutes les fonctions publiques3. 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/undefined4. Écris les tests en suivant le pattern AAA5. Exécute les tests pour vérifier qu'ils passent6. Vérifie la couverture (objectif : 80%+)## Format de sortieCré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ôleTu es un technical writer qui produit une documentationclaire, concise et à jour. Tu t'adresses à des développeursde 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)## Instructions1. Analyse les changements récents (git log --oneline -20)2. Identifie les fichiers de documentation impactés3. Pour chaque fichier à mettre à jour :a. Lis le code source correspondantb. Vérifie que la documentation reflète le code actuelc. Mets à jour les sections obsolètesd. Ajoute les nouvelles fonctionnalités non documentées4. 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.mdtest-writer.mddoc-updater.mddb-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.mdmy-test-preferences.mdbrainstorm-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
# MAUVAISTu es un agent de code review.# BONTu es un reviewer de code senior spécialisé en TypeScriptet React. Tu as 15 ans d'expérience et tu es particulièrementattentif aux problèmes de performance, de sécurité etd'accessibilité. Tu donnes des feedbacks constructifsavec des suggestions de correction concrètes.
2. Définissez des étapes claires
# MAUVAISAnalyse le code et dis-moi si c'est bon.# BON1. Lis le diff complet avec git diff main...HEAD2. 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 tests4. Produis un rapport structuré par sévérité
3. Spécifiez le format de sortie
# MAUVAISDonne-moi les résultats.# BONPour 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 codeTermine 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.
- Agent Teams : Faire travailler plusieurs agents ensemble sur un même projet
- Top agents par cas d'usage : Les meilleurs agents par catégorie
- Orchestration avancée : Patterns d'orchestration multi-agents