Workbranch › Guides

Comment utiliser les subagents dans Claude Code

Les longues recherches et les sorties de tests verbeuses remplissent vite votre conversation Claude Code. Les subagents prennent ce travail dans un contexte séparé et renvoient un résumé. Ce guide explique ce qu'ils sont, comment créer les vôtres et quand ils valent la peine.

Mis à jour le 30 octobre 2026

Les détails ci-dessous proviennent de la documentation Claude Code d'Anthropic en octobre 2026. Claude Code évolue souvent : lancez claude update s'il manque quelque chose de ce qui est décrit ici.

Ce que sont les subagents

Quand Claude rencontre une tâche qui correspond à la description d'un subagent, il peut la lui déléguer. Le subagent part de zéro : il ne voit pas votre conversation, seulement les instructions que Claude lui transmet. Il fait son travail, par exemple lire des dizaines de fichiers ou lancer une suite de tests, et renvoie un résumé. Votre conversation principale reste courte.

Claude Code inclut des subagents intégrés, notamment :

• Explore : recherche et analyse rapides d'une base de code, en lecture seule.
• Plan : recherche en lecture seule pendant que vous êtes en mode plan.
• General-purpose : tâches en plusieurs étapes qui demandent à la fois d'explorer et de modifier.

Vous n'avez rien à configurer : Claude les utilise quand ils conviennent.

Créer votre propre subagent

1. Choisissez la portée. Pour un subagent que toute l'équipe peut utiliser dans un dépôt, créez le dossier .claude/agents/ dans le projet. Pour un subagent qui vous suit d'un projet à l'autre, utilisez ~/.claude/agents/.
2. Créez un fichier Markdown dans ce dossier, par exemple code-reviewer.md.
3. Commencez le fichier par un frontmatter entre deux lignes ---. La première ligne du fichier doit être ---.
4. Ajoutez les deux champs obligatoires : name (un identifiant unique, par exemple code-reviewer, sans deux-points) et description (quand Claude doit l'utiliser, par exemple Reviews code for quality and best practices. Use after code changes.).
5. Ajoutez éventuellement tools pour limiter ce qu'il peut utiliser, par exemple Read, Glob, Grep pour un relecteur en lecture seule, et model (un alias de modèle comme sonnet ou haiku, un identifiant de modèle complet, ou inherit).
6. Sous la ligne --- de fermeture, écrivez les instructions du subagent en langage courant : son rôle, ce qu'il doit vérifier et ce qu'il doit renvoyer.
7. Enregistrez le fichier. Claude Code prend en compte en quelques secondes les modifications dans un dossier agents existant ; si vous avez créé le dossier pendant la session, redémarrez Claude Code.

Utiliser un subagent

• Laisser Claude choisir : Claude compare votre demande à la description de chaque subagent. Des mots comme « use proactively » dans la description l'encouragent à déléguer.
• Le demander par son nom : par exemple Utilise le subagent code-reviewer pour vérifier mes dernières modifications.
• Le mentionner : tapez @ et choisissez le subagent. Cela garantit que ce subagent prend la tâche en charge.
• Pour toute une session : lancez claude --agent code-reviewer.

Quand les subagents aident, et quand ils n'aident pas

Les recommandations d'Anthropic se résument ainsi :

Bon à savoir

• Si deux subagents portent le même nom, l'emplacement prioritaire l'emporte : paramètres gérés, puis l'option --agents, puis le dossier du projet, puis votre dossier utilisateur, puis les plugins.
• Un subagent ne voit ni l'historique de votre chat ni les fichiers que Claude a déjà lus : il dépend des instructions que Claude lui donne.
• Par défaut, jusqu'à 20 subagents peuvent s'exécuter en même temps.
• Les noms de champs sont en camelCase (par exemple disallowedTools, maxTurns) et les champs non reconnus sont ignorés sans avertissement : vérifiez l'orthographe.
• Les fichiers de subagents du projet peuvent être committés, pour que toute l'équipe dispose des mêmes assistants.

Si cela ne fonctionne pas

• Claude ne trouve pas le nouveau subagent : si le dossier agents n'existait pas au démarrage de la session, redémarrez Claude Code.
• Le fichier est ignoré sans message : les causes fréquentes sont un name ou une description manquants, un YAML invalide, ou une ligne --- qui n'est pas la première. Lancez claude --debug et lisez le journal de débogage, ou lancez claude plugin validate .claude/agents pour trouver les fichiers dont le frontmatter ne s'analyse pas.
• Claude signale une erreur mentionnant des outils non résolus : quand aucune entrée de tools ne correspond à un outil réel, Claude Code ne lance généralement pas le subagent. Corrigez l'orthographe des noms d'outils.
• Mauvais modèle : lancez /tasks pour voir quel modèle chaque subagent utilise réellement.

Gardez les résultats, pas seulement le résumé

Le rapport d'un subagent atterrit dans votre session, qui disparaît de votre vue une fois fermée. Avec le plugin Workbranch pour Claude Code, dire « save this to Workbranch » classe les tâches, décisions et questions ouvertes de la session dans un projet, et la session suivante dans ce dossier démarre avec ce qui reste ouvert. Voir Workbranch pour Claude. Si une session a manqué de place, reprendre une session Claude Code explique comment y revenir.

Sources

• Use Claude Code with your Pro or Max plan (centre d'aide Claude, consulté le 30 octobre 2026)
• Create custom subagents (documentation Claude Code, consultée le 30 octobre 2026)

Questions fréquentes