Claude Code Subagents :
orchestrez vos agents IA
Déléguez recherche, analyse et refactoring à des agents spécialisés. Chaque subagent travaille dans son propre contexte avec ses propres outils.
Les subagents Claude Code sont des assistants IA spécialisés qui travaillent dans leur propre fenêtre de contexte, avec leur propre prompt système et accès aux outils. Quand Claude rencontre une tâche qui match la description d’un subagent, il délègue automatiquement et récupère uniquement le résumé des résultats.
Cette architecture préserve votre contexte principal en gardant les logs, fichiers et recherches hors de votre conversation. Les subagents permettent aussi de router des tâches vers des modèles plus rapides et moins coûteux comme Haiku.
Sur un projet de migration Next.js, j’ai demandé à Claude d’analyser 200 fichiers pour trouver les composants qui utilisaient une ancienne API. Ma fenêtre de contexte a explosé en 3 minutes, saturée de logs et de contenus de fichiers. J’ai dû recommencer la conversation à zéro.
Depuis, j’utilise systématiquement les subagents pour ce type de tâche exploratoire. Le subagent fait le travail d’analyse dans son propre contexte, et ne me retourne que la synthèse. Dans ce guide, je vous montre comment créer vos propres subagents spécialisés pour automatiser vos workflows récurrents.
Qu’est-ce qu’un subagent dans Claude Code ?
Un subagent est un assistant IA spécialisé qui opère dans sa propre fenêtre de contexte, séparée de votre conversation principale. Il possède son propre prompt système, son propre accès aux outils, et ses propres permissions. Quand Claude délègue une tâche à un subagent, celui-ci travaille de manière autonome et retourne uniquement un résumé des résultats.
Cette séparation des contextes est fondamentale pour préserver la qualité de votre conversation principale. Sans subagents, une recherche dans 50 fichiers remplirait votre contexte de contenus inutiles pour la suite. Avec un subagent, seule la synthèse pertinente est ajoutée à votre conversation.
Les subagents sont particulièrement utiles pour trois cas d’usage : l’exploration de code où vous ne savez pas encore ce que vous cherchez, les tâches répétitives que vous lancez régulièrement avec les mêmes instructions, et le routage vers des modèles spécialisés selon le type de tâche.
Claude décide automatiquement quand utiliser un subagent en fonction de sa description. Si vous avez un subagent décrit comme expert en tests unitaires, Claude le sollicitera naturellement quand vous parlerez de tests. Cette automatisation rend l’utilisation transparente une fois les subagents configurés.
Comment créer un subagent custom ?
Les subagents custom se définissent dans des fichiers Markdown avec un frontmatter YAML. Le fichier contient la description, le prompt système, les outils autorisés, et les options d’isolation. Placez ces fichiers dans .claude/agents/ pour un projet spécifique ou dans ~/.claude/agents/ pour tous vos projets.
La description est critique car c’est elle qui déclenche l’utilisation du subagent. Soyez précis sur les cas d’usage. Une description vague comme analyste de code sera utilisée trop souvent. Une description comme analyse les fichiers de migration SQL pour détecter les breaking changes est beaucoup plus ciblée.
Le prompt système définit le comportement du subagent. C’est l’équivalent des instructions système que vous donneriez à Claude. Incluez les contraintes, le format de réponse attendu, et les patterns à suivre. Plus le prompt est précis, plus le subagent sera efficace.
Le champ tools liste les outils accessibles au subagent. Vous pouvez restreindre l’accès pour limiter les actions possibles. Par exemple, un subagent d’analyse peut avoir accès à Read et Grep mais pas à Edit ni Bash. Cette granularité renforce la sécurité.
Comment router les tâches vers des modèles spécifiques ?
Le champ model dans le frontmatter permet de router un subagent vers un modèle différent de votre session principale. C’est une optimisation importante pour les coûts et les performances. Tous les modèles ne sont pas nécessaires pour toutes les tâches.
Pour une recherche simple dans des fichiers, Haiku suffit largement et coûte une fraction du prix d’Opus. Pour une analyse complexe de code ou une génération créative, Opus reste préférable. Adaptez le modèle au niveau de raisonnement requis.
Le routing par modèle est aussi utile pour les tâches de traduction, de formatage, ou de parsing. Ces tâches mécaniques ne nécessitent pas la puissance de raisonnement d’Opus. Un subagent Haiku dédié à la traduction sera plus rapide et moins coûteux.
Attention cependant : le modèle doit être capable de respecter le prompt système. Un prompt complexe avec beaucoup de règles fonctionne mieux avec Sonnet ou Opus. Testez vos subagents avec différents modèles pour trouver le bon équilibre entre coût et qualité.
Un subagent d’analyse travaille dans son propre contexte pendant que la conversation principale reste propre
Isolation des subagents avec worktrees
Par défaut, les subagents travaillent dans le même répertoire que votre session principale. Cela peut poser problème si un subagent modifie des fichiers que vous êtes en train d’éditer. L’option isolation: worktree résout ce conflit en donnant au subagent son propre checkout git.
Avec l’isolation worktree, le subagent crée un worktree temporaire, effectue ses modifications, et le nettoie automatiquement à la fin de sa tâche si aucun changement n’a été fait. Si des modifications existent, Claude vous demande si vous voulez les conserver.
Cette isolation est particulièrement utile pour les subagents qui font du refactoring ou qui testent des modifications avant proposition. Le subagent peut expérimenter librement sans risquer de casser votre travail en cours.
Pour activer l’isolation, ajoutez isolation: worktree dans le frontmatter de votre subagent. Vous pouvez aussi demander à Claude pendant une session : utilise des worktrees pour tes agents. Cette option s’appliquera aux subagents suivants.
Voici quand activer l’isolation worktree pour vos subagents :
- Refactoring exploratoire : le subagent teste des modifications sans impacter votre travail
- Génération de code : les fichiers créés n’apparaissent pas dans votre checkout
- Tests de modifications : le subagent peut exécuter les tests dans son environnement isolé
- Analyses parallèles : plusieurs subagents travaillent sur les mêmes fichiers sans conflit
- Rollback facile : si le résultat ne convient pas, le worktree est simplement supprimé
Subagents vs Agent Teams : quelle différence ?
Les subagents et les agent teams sont deux mécanismes de parallélisation différents dans Claude Code. La distinction principale est le niveau d’autonomie et de coordination entre les agents.
Les subagents fonctionnent au sein d’une seule session. Claude délègue des tâches et récupère les résultats dans votre conversation courante. Vous restez le point de coordination central. C’est idéal pour des tâches ponctuelles ou exploratoires.
Les agent teams sont des sessions Claude complètes qui communiquent entre elles via une liste de tâches partagée. Un agent lead coordonne le travail et distribue les sous-tâches. C’est plus adapté aux projets complexes qui nécessitent une coordination autonome sur la durée.
En pratique, commencez par les subagents. Si vous vous retrouvez à gérer manuellement la coordination entre plusieurs subagents récurrents, passez aux agent teams. La plupart des workflows n’en ont pas besoin.
Subagents
Délégation au sein d’une session. Vous coordonnez. Idéal pour les tâches ponctuelles.
Agent Teams
Sessions qui communiquent entre elles. Claude coordonne. Pour projets complexes.
Worktrees
Isolation git manuelle. Vous créez les sessions. Contrôle total sur le parallélisme.
Contrôler les permissions et outils des subagents
Chaque subagent peut avoir un ensemble d’outils restreint par rapport à votre session principale. C’est une mesure de sécurité importante : un subagent d’analyse n’a pas besoin de pouvoir exécuter des commandes Bash ou modifier des fichiers.
Listez les outils autorisés dans le champ tools du frontmatter. Les outils disponibles incluent Read, Write, Edit, Bash, Glob, Grep, et les outils MCP que vous avez configurés. Omettez les outils que le subagent ne doit pas utiliser.
La restriction des outils a aussi un effet sur la consommation de tokens. Un subagent avec moins d’outils disponibles a un prompt système plus léger, ce qui laisse plus de place pour le contenu utile dans sa fenêtre de contexte.
Pensez aussi aux permissions de fichiers. Un subagent peut avoir accès à certains patterns de fichiers seulement. C’est configurable dans les settings de votre projet pour un contrôle granulaire.
Bonnes pratiques pour des subagents efficaces
La description du subagent doit être ultra-spécifique. Plus elle est précise, mieux Claude saura quand l’utiliser. Évitez les descriptions génériques comme assistant de code. Préférez analyse les fichiers de configuration Webpack pour identifier les optimisations de bundle.
Gardez le prompt système concis mais complet. Un prompt trop long consomme le contexte du subagent avant même qu’il commence à travailler. Concentrez-vous sur les règles essentielles et le format de réponse attendu.
Testez vos subagents avec différents modèles pour trouver l’équilibre coût/qualité optimal. Haiku est souvent suffisant pour des tâches d’extraction et de recherche. Reservez Opus pour les raisonnements complexes.
Utilisez l’isolation worktree dès que le subagent modifie des fichiers. Le coût en performance est négligeable et la sécurité apportée est considérable. Vous éviterez les conflits de fichiers qui sont difficiles à débugger.
Exemples de subagents prêts à l’emploi
Voici quelques patterns de subagents que j’utilise régulièrement sur mes projets. Ils sont adaptables à vos besoins spécifiques. Le plus important est de comprendre le pattern et de l’adapter à votre stack technique.
Le subagent de documentation parse le code et génère des docstrings ou des README. Il utilise Read et Grep pour analyser, et peut optionnellement utiliser Write pour créer les fichiers de documentation. Je le fais tourner sur Haiku car la génération de doc est relativement mécanique.
Le subagent de sécurité analyse le code à la recherche de vulnérabilités communes : injections SQL, XSS, secrets hardcodés, dépendances obsolètes. Il produit un rapport avec niveau de criticité. Celui-ci tourne sur Sonnet pour un meilleur raisonnement.
Le subagent de tests génère des tests unitaires pour les fonctions existantes. Il analyse la signature et le comportement, puis propose des cas de test. Je l’utilise avec Opus car la génération de bons tests nécessite une compréhension fine du code.
Questions fréquentes sur les subagents Claude Code
Quelle est la différence entre un subagent et un agent team ?
Les subagents fonctionnent au sein d’une seule session Claude Code. Claude délègue des tâches spécifiques et récupère les résultats dans votre conversation courante. Vous restez le point de coordination central et décidez quand lancer chaque subagent. C’est idéal pour des tâches ponctuelles ou exploratoires qui ne nécessitent pas de communication entre agents.
Les agent teams sont des sessions Claude complètes et séparées qui communiquent entre elles via une liste de tâches partagée. Un agent lead coordonne le travail et distribue les sous-tâches automatiquement. C’est plus adapté aux projets complexes qui nécessitent une coordination autonome sur plusieurs heures ou jours, avec des agents spécialisés par domaine.
Comment créer un subagent custom dans Claude Code ?
Créez un fichier Markdown dans .claude/agents/ pour un projet spécifique ou dans ~/.claude/agents/ pour tous vos projets. Le fichier commence par un frontmatter YAML avec les champs description, model, tools, et optionnellement isolation. Après le frontmatter, écrivez le prompt système qui définit le comportement du subagent.
La description est critique car elle détermine quand Claude utilise le subagent. Soyez précis : analyse les fichiers de migration SQL pour détecter les breaking changes est meilleur que analyste SQL. Claude matche la description avec vos requêtes pour décider de la délégation automatique.
Comment router un subagent vers un modèle moins cher ?
Ajoutez le champ model: haiku ou model: sonnet dans le frontmatter de votre subagent. Par défaut, les subagents utilisent le même modèle que votre session principale. Le routing explicite permet d’économiser des tokens sur les tâches qui ne nécessitent pas la puissance de raisonnement d’Opus.
Haiku est idéal pour les tâches mécaniques : recherche dans les fichiers, extraction de patterns, formatage, traduction. Sonnet convient pour l’analyse de code et la synthèse. Réservez Opus (implicite si pas de model spécifié) pour les raisonnements complexes comme la génération de tests ou le refactoring architectural.
Comment isoler un subagent dans un worktree ?
Ajoutez isolation: worktree dans le frontmatter de votre subagent. Claude créera automatiquement un worktree git temporaire pour chaque exécution du subagent. Les modifications faites par le subagent n’impactent pas votre checkout principal.
L’isolation est recommandée pour les subagents qui modifient des fichiers : refactoring, génération de code, tests de modifications. Le worktree est nettoyé automatiquement si aucune modification n’a été effectuée. Si des changements existent, Claude vous demande si vous voulez les conserver ou les supprimer.
Quels outils donner à un subagent d’analyse ?
Pour un subagent d’analyse pure qui ne modifie rien, limitez les outils à Read, Grep, et Glob. Ces trois outils suffisent pour explorer le codebase et extraire les informations pertinentes. Exclure Write, Edit et Bash garantit que le subagent ne peut pas modifier votre projet accidentellement.
Si le subagent doit exécuter des commandes pour collecter des informations (comme npm list ou git log), ajoutez Bash mais avec prudence. Vous pouvez restreindre les commandes autorisées dans les settings du projet. Pour un subagent de documentation qui crée des fichiers, ajoutez Write uniquement dans les répertoires appropriés.
Comment voir ce qu’un subagent fait en temps réel ?
Par défaut, Claude résume le travail du subagent et vous montre uniquement les résultats pertinents. Pour voir le détail des actions, utilisez la commande /verbose qui active le mode verbeux. Vous verrez alors chaque outil appelé par le subagent et ses résultats intermédiaires.
Le mode verbeux est utile pour débugger un subagent qui ne produit pas les résultats attendus. Vous pouvez identifier où il se trompe dans son raisonnement ou quels fichiers il analyse. Une fois le subagent au point, désactivez le mode verbeux pour garder votre contexte propre.
Peut-on faire communiquer deux subagents entre eux ?
Les subagents au sein d’une même session ne communiquent pas directement entre eux. Chaque subagent reçoit sa tâche de Claude, travaille de manière autonome, et retourne ses résultats à Claude. C’est Claude qui synthétise et orchestre les résultats de plusieurs subagents si nécessaire.
Si vous avez besoin de communication directe entre agents, utilisez plutôt les agent teams. Dans ce mode, plusieurs sessions Claude peuvent s’envoyer des messages via une liste de tâches partagée. Un agent peut créer une tâche pour un autre agent et recevoir le résultat asynchronement.
Les subagents consomment-ils mon quota de tokens ?
Oui, les subagents consomment des tokens comme n’importe quelle interaction avec Claude. Chaque subagent a sa propre fenêtre de contexte qui compte dans votre usage. Cependant, le routing vers Haiku ou Sonnet peut réduire significativement les coûts par rapport à Opus.
L’avantage des subagents est qu’ils préservent le contexte de votre session principale. Sans subagent, les résultats de recherche rempliraient votre contexte principal. Avec un subagent, seul le résumé est ajouté. Vous économisez donc des tokens sur la durée de votre session principale.
Comment partager mes subagents avec mon équipe ?
Placez vos fichiers de subagents dans .claude/agents/ à la racine de votre projet et commitez-les dans git. Tous les membres de l’équipe qui clone le projet auront automatiquement accès aux mêmes subagents. C’est la méthode recommandée pour standardiser les workflows d’équipe.
Pour des subagents personnels que vous voulez utiliser sur tous vos projets, placez-les dans ~/.claude/agents/. Ces subagents sont locaux à votre machine et ne sont pas partagés. Utile pour vos préférences personnelles ou des configurations spécifiques à votre environnement.
Que se passe-t-il si un subagent échoue ?
Si un subagent rencontre une erreur ou n’arrive pas à compléter sa tâche, il retourne un message d’erreur à Claude. Claude analyse l’erreur et peut soit retenter avec une approche différente, soit vous demander de l’aide. Le contexte de votre session principale n’est pas impacté par l’échec.
Les erreurs courantes incluent les fichiers inaccessibles, les timeouts sur de grosses analyses, ou les outils non autorisés. Vérifiez le frontmatter de votre subagent pour vous assurer qu’il a accès aux outils nécessaires. Activez le mode verbeux pour diagnostiquer précisément où le subagent échoue.
