Les subagents de Claude Code sont des assistants à qui la session principale confie une seule tâche. Chacun s’exécute dans sa propre fenêtre de contexte, avec son propre prompt système, sa liste d’outils et son modèle, et seule sa réponse finale revient dans la conversation principale. Vous définissez un subagent sous forme de fichier Markdown dans .claude/agents/, et Claude l’utilise automatiquement quand la tâche correspond à sa description, ou quand vous le demandez par son nom.
Cet article couvre le fonctionnement des subagents, le format du fichier, les champs tools et model, la façon de les appeler, et la frontière entre un subagent et un agent séparé qui tourne à côté du premier. Les faits viennent de la documentation officielle des subagents. Pour la version en un paragraphe, voyez l’entrée du glossaire sur les subagents.
Comment fonctionnent les subagents
Quand Claude décide de déléguer, il appelle l’outil Agent (appelé Task avant la version 2.1.63) avec un court brief. Le subagent démarre avec un contexte vierge. Il reçoit son propre prompt système, le message de délégation, votre CLAUDE.md, l’état de git et les skills que vous avez préchargés pour lui. Il ne voit pas l’historique de la conversation principale.
Il traite ensuite la tâche avec les outils autorisés et renvoie un seul résultat. Tout ce qu’il a lu en chemin, comme des dizaines de fichiers, de longues sorties de grep ou des journaux de tests, reste dans son propre contexte. C’est la raison principale d’utiliser des subagents : la conversation principale reçoit un résumé, pas le bruit.
Quelques limites à connaître :
- Les subagents peuvent lancer leurs propres subagents, sur trois niveaux au maximum par défaut.
- Jusqu’à 20 peuvent tourner en même temps par défaut.
- Leurs requêtes comptent dans les mêmes limites d’utilisation que la session principale.
- Un subagent peut s’exécuter au premier plan, où l’agent principal attend, ou en arrière-plan pendant que l’agent principal continue.
Les subagents intégrés
Claude Code fournit quelques subagents utilisables sans rien écrire :
| Subagent | Outils | Usage typique |
|---|---|---|
| Explore | Lecture seule | Chercher et lire dans toute la base de code, en profondeur rapide, moyenne ou très approfondie |
| Plan | Lecture seule | Recherche en mode plan |
| General-purpose | Tous les outils | Tâches en plusieurs étapes qui demandent à la fois de la recherche et des modifications |
Explore est celui que vous verrez le plus. Quand Claude doit trouver où quelque chose est défini ou comment une fonctionnalité traverse plusieurs fichiers, il le confie souvent à Explore pour que les vidages de fichiers n’atterrissent pas dans votre contexte principal.
Où vivent les fichiers de subagents
Les subagents sont des fichiers Markdown avec un frontmatter YAML. Claude Code les charge depuis plusieurs endroits, et quand deux portent le même nom, celui qui est le plus haut dans cette liste l’emporte :
| Emplacement | Portée |
|---|---|
| Réglages gérés | Toute l’organisation, définis par les administrateurs |
Option --agents (JSON) | Une session |
.claude/agents/ | Un projet, partagé via git |
~/.claude/agents/ | Tous vos projets |
Le dossier agents/ d’un plugin | Partout où le plugin est installé |
Les subagents de projet dans .claude/agents/ sont ceux à commiter, pour que toute l’équipe partage le même relecteur ou le même exécuteur de tests.
Le format du fichier de subagent
Seuls name et description sont obligatoires. Le corps après le frontmatter est le prompt système du subagent.
---
name: code-reviewer
description: Reviews code changes for bugs, security issues and readability. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer. When called:
1. Run git diff to see the recent changes.
2. Read the changed files and the code around them.
3. Report problems by priority: bugs, security, then readability.
4. For each problem, give the file, the line and a concrete fix.
Do not edit files. Report only.La description compte plus qu’il n’y paraît. C’est ce que Claude lit pour décider de déléguer ou non : dites donc ce que fait le subagent et quand l’utiliser. Des formules comme « à utiliser après avoir écrit du code » aident Claude à le choisir de lui-même.
Le champ tools
tools est une liste d’autorisation. Avec tools: Read, Grep, Glob, Bash, le relecteur ci-dessus peut lire et lancer des commandes mais ne peut pas modifier de fichiers. Si vous omettez tools, le subagent hérite de tous les outils de la session principale, y compris les outils MCP. Il existe aussi disallowedTools quand il est plus simple de dire ce qu’il faut retirer que ce qu’il faut garder.
Gardez la liste aussi courte que la tâche le permet. Un relecteur n’a pas besoin d’Edit. Un chercheur n’a pas besoin de Bash. Moins d’outils, c’est moins de surprises et une mission plus claire.
Le champ model
model accepte un alias (sonnet, opus, haiku), un identifiant complet de modèle, ou inherit pour utiliser le modèle de la session principale. Quand le subagent est appelé, Claude Code choisit le modèle dans cet ordre : un modèle passé avec cet appel, puis le champ model du fichier, puis la variable d’environnement CLAUDE_CODE_SUBAGENT_MODEL, puis le modèle de la session principale.
C’est ici que les subagents peuvent vraiment économiser de l’argent. Les recherches larges dans les fichiers et la lecture de journaux demandent rarement le modèle le plus puissant. Mettez-les sur Haiku et gardez la session principale sur le plus gros modèle pour les décisions. L’article sur la consommation de tokens de Claude Code présente d’autres moyens de réduire les dépenses.
Autres champs utiles
| Champ | Ce qu’il fait |
|---|---|
permissionMode | Mode de permission du subagent, par exemple plan ou acceptEdits |
skills | Skills à charger dans le contexte du subagent au démarrage |
mcpServers | Serveurs MCP que le subagent peut utiliser |
hooks | Hooks qui s’appliquent pendant l’exécution de ce subagent |
memory | Mémoire persistante à la portée utilisateur, projet ou locale |
maxTurns | Limite haute du nombre de tours du subagent |
background | Exécuter en arrière-plan par défaut |
isolation: worktree | Exécuter dans un worktree git temporaire |
effort | Effort de raisonnement du subagent |
Comment appeler un subagent
Il y a trois façons :
- Laisser Claude décider. Si la demande correspond à la description d’un subagent, Claude délègue de lui-même.
- Le demander par son nom. « Utilise le subagent code-reviewer pour vérifier mon dernier commit. » Vous pouvez aussi le mentionner avec @ depuis le menu.
- Lancer toute une session sous son identité.
claude --agent code-reviewerdémarre une session qui utilise le prompt, les outils et le modèle de ce subagent.
Pour une session ponctuelle, vous pouvez passer des subagents en JSON sans créer de fichiers :
claude --agents '{
"code-reviewer": {
"description": "Reviews code changes. Use after edits.",
"prompt": "You are a senior code reviewer. Report bugs and fixes, do not edit.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
}
}'Pour empêcher Claude d’utiliser un subagent précis, ajoutez-le à la liste deny de vos permissions, par exemple Agent(Explore).
Subagents ou agents parallèles séparés
Les subagents et les agents parallèles répartissent tous deux le travail, mais ils résolvent des problèmes différents.
| Subagents | Agents parallèles séparés | |
|---|---|---|
| Qui les lance | La session principale de Claude | Vous |
| Ce que vous voyez | Le résultat final, dans le chat principal | La session complète de chaque agent |
| Contexte | Neuf à chaque tâche, jeté ensuite | De longue durée, un par agent |
| Fichiers | Le même dossier de travail, sauf isolation: worktree | En général un worktree git chacun |
| Votre intervention en cours de tâche | Aucune, c’est l’agent principal qui lui parle | Vous pouvez orienter chacun |
| Idéal pour | Recherche, revue, exploration, tâches courtes et ciblées | Fonctionnalités, refactorings, longues tâches qui finissent dans une branche |
Utilisez un subagent quand l’agent principal a besoin d’une réponse pour continuer : « trouve tous les appelants de cette fonction », « relis ce diff », « résume ces journaux ». Le travail est court, son résultat est ce qui compte, et vous n’avez pas besoin de le regarder.
Utilisez des agents séparés quand chaque morceau est un vrai travail en soi : une fonctionnalité, une migration, une suite de tests. Vous voulez voir ce que chacun fait, répondre à ses questions et relire ses changements comme une branche. C’est la configuration décrite dans agents de code parallèles et exécuter plusieurs agents Claude Code, chaque agent dans son propre worktree git.
Les deux se combinent bien. Un agent séparé peut toujours utiliser des subagents pour ses propres recherches et revues. Une bonne règle par défaut : des agents séparés pour le travail que vous confieriez à une personne, et des subagents pour les courses que ces agents effectuent. Pour des équipes plus grandes, l’article sur l’équipe d’agents IA couvre les rôles et les passages de relais, et l’entrée sur l’orchestration multi-agents présente l’idée générale.
Claude Code a aussi une fonctionnalité distincte appelée agent teams, où plusieurs sessions Claude travaillent ensemble. Ce n’est pas la même chose que les subagents, et cela sort du cadre de cet article.
Des conseils pour des subagents qui marchent
- Une mission par subagent. « Relecteur » et « exécuteur de tests » marchent mieux que « assistant ».
- Écrivez la description pour Claude. Dites quand l’utiliser, pas seulement ce que c’est.
- Limitez les outils. Des subagents en lecture seule pour la recherche et la revue, des outils de modification seulement quand c’est nécessaire.
- Choisissez le modèle exprès. Haiku pour la recherche et les résumés, un modèle plus puissant pour la conception et les corrections délicates.
- Demandez un rapport court. Le résultat va dans le contexte principal : dites donc au subagent de renvoyer des conclusions, pas des vidages de fichiers.
- Versionnez vos subagents de projet.
.claude/agents/dans git donne les mêmes assistants à tout le monde.
Comment AgentVera montre les subagents
AgentVera est une application de bureau pour exécuter côte à côte de nombreux agents de code, Claude Code, Codex et d’autres. Elle gère les subagents de deux façons.
Vous pouvez les voir. Dans le volet d’un agent Claude Code, le bouton « Subagents » ouvre une vue en direct des subagents lancés par cet agent et de ce qu’ils font en ce moment. Chacun affiche son état (Running, Done, Error, Stopped), s’il s’exécute « in background », l’« Assigned task » reçue et son « Report ». Pendant que certains travaillent, une ligne « {count} subagents running — show » apparaît pour que vous ne les manquiez pas. La visite du projet et la carte du code a aussi une chronologie des subagents avec le type, l’état, le nombre d’outils et la durée. Les deux lisent des transcriptions locales et ne concernent pour l’instant que les agents Claude Code.
Un Explore moins cher. Dans Settings → « Token saving », l’option « Explorer subagent » donne aux agents Claude un explorateur en lecture seule pour les recherches larges. L’analyse des fichiers tourne sur un modèle moins cher, Haiku par défaut, et seul le résultat revient dans la conversation principale. Si vous avez déjà votre propre fichier de subagent Explore, AgentVera laisse le vôtre en place. L’option se trouve à côté des smart tools, dans la même section.
Des agents séparés quand le travail est plus gros. La vue d’équipe montre jusqu’à 24 agents à la fois. Parallel team (offres Pro et Team) découpe un objectif en parties, exécute chacune dans son propre worktree et les fusionne en une seule PR. La messagerie entre agents leur permet de se poser des questions, même d’une CLI à l’autre, et la coordination des agents prévient quand deux agents touchent le même fichier. Cela vous donne le côté agents séparés du tableau ci-dessus, avec les subagents toujours disponibles dans chaque agent Claude.
Pour conclure
Les subagents sont l’outil adapté quand l’agent principal a besoin d’une réponse et que vous n’avez pas besoin de surveiller le travail : recherche, revue, exploration. Écrivez un fichier Markdown avec une description claire, une courte liste d’outils et un modèle choisi avec soin. Quand le travail est assez gros pour mériter sa propre branche et votre attention, lancez plutôt un agent séparé.
Pour aller plus loin :
- Subagent (glossaire)
- Agents de code parallèles
- Visite du projet et carte du code
- Parallel team
- Agent Claude Code
Pour essayer AgentVera, commencez par la page d’accueil.