Les subagents de Claude Code sont des assistants spécialisés auxquels Claude confie une tâche précise, chacun dans sa propre fenêtre de contexte. Selon la documentation d’Anthropic, chaque subagent a son prompt système, ses outils autorisés et ses permissions, et il se définit dans un fichier Markdown. Là où les skills Claude Code apportent une méthode, un subagent apporte un exécutant séparé, qui travaille à part puis rend un résumé.
Ce tutoriel s’adresse à ceux qui veulent déléguer des tâches sans encombrer leur conversation principale. Il montre comment écrire un premier subagent, choisir ses outils et son modèle, puis faire travailler plusieurs agents ensemble.
L’essentiel à retenir
- Un subagent est un fichier Markdown avec un en-tête YAML, rangé dans
.claude/agents/pour un projet ou dans~/.claude/agents/pour tous vos projets. - Seuls les champs
nameetdescriptionsont obligatoires. - Sur l’API d’Anthropic, l’alias
haikupointe vers Claude Haiku 5.5, sorti le 7 octobre 2026 et destiné entre autres aux tâches de subagent. - Un subagent démarre sans l’historique de la conversation : il part du message de délégation et de son propre prompt.
- Les agent teams, où plusieurs sessions se parlent directement, restent expérimentales et désactivées par défaut.
Qu’est-ce qu’un subagent dans Claude Code ?
Un subagent est un assistant IA spécialisé auquel Claude Code délègue un type de tâche, une forme simple d’IA agentique. Il tourne dans son propre contexte, avec un prompt système, des outils et des permissions qui lui sont propres.
La session principale lui résume la tâche, il travaille seul, puis renvoie son résultat. Les fichiers qu’il a lus restent dans son contexte, pas dans le vôtre.
Claude Code en fournit déjà plusieurs, que Claude utilise de lui-même, dont ces trois :
- Explore parcourt le code, en lecture seule ;
- Plan mène les recherches du mode plan, en lecture seule ;
- general-purpose prend les tâches en plusieurs étapes et peut modifier le code.
Subagent, skill, agent team : quelle différence ?
Les trois notions se croisent, mais elles ne répondent pas au même besoin :
- un skill donne une méthode appliquée dans la conversation en cours ;
- un subagent exécute une tâche dans un contexte séparé et rend un résultat ;
- une agent team réunit plusieurs sessions qui se parlent et se partagent une liste de tâches.
Selon la page consacrée aux agent teams, une session sert de chef d’équipe et les coéquipiers échangent directement, alors qu’un subagent rend compte à l’agent qui l’a lancé. La fonction s’active en passant la variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS à 1, dans l’environnement ou dans settings.json. Elle consomme nettement plus de tokens qu’une session seule, prévient Anthropic.
Attention
D’après la documentation, une fois les agent teams activées, un subagent auquel Claude donne un nom se lance comme coéquipier dans une session interactive. Une équipe peut donc se former sans que vous l’ayez demandé. Remettre la variable à 0 rétablit le comportement habituel.
Prérequis et emplacement des fichiers
Il suffit d’avoir Claude Code installé, un projet ouvert dans le terminal et un éditeur de texte. Pour utiliser Haiku 5.5, la documentation demande Claude Code v2.1.293 ou plus récent.
L’emplacement du fichier fixe la portée du subagent :
.claude/agents/pour le projet, à versionner avec le code ;~/.claude/agents/pour tous vos projets ;- l’option
--agents, pour un subagent limité à la session ; - le dossier
agents/d’un plugin.
À nom égal, un subagent de projet l’emporte sur celui de votre dossier personnel, et l’option --agents passe avant les deux.
Tutoriel : créer son premier subagent
L’exemple suivant crée un relecteur de code en lecture seule, sur un modèle léger. Chaque champ vient de la documentation officielle des subagents.
Étape 1 : créer le fichier Markdown
Créez le dossier .claude/agents/ à la racine du projet, puis un fichier relecteur-code.md avec ce contenu :
---
name: relecteur-code
description: Relit le code modifié et signale les problèmes de qualité et de sécurité. Use proactively after code changes.
tools: Read, Glob, Grep
model: haiku
---
Tu es relecteur de code. Quand on t’appelle, lis les fichiers modifiés,
puis rends une liste de remarques précises : le fichier, la ligne,
le problème et la correction proposée.
L’en-tête entre les deux lignes --- configure le subagent ; le reste devient son prompt système. Selon la documentation, Claude Code détecte un fichier ajouté ou modifié en quelques secondes, sans redémarrage.
Une exception compte ici : la surveillance ne couvre que les dossiers qui existaient au lancement de la session. Si vous venez de créer .claude/agents/, redémarrez Claude Code pour charger ce premier fichier.
Étape 2 : rédiger le nom et la description
Le nom est un identifiant unique, sans deux-points. La description dit à Claude quand déléguer : c’est elle qui déclenche l’appel automatique. La documentation conseille d’y glisser une formule comme « use proactively ».
Mieux vaut aussi rester court. Au-delà de 15 000 tokens de descriptions cumulées, hors subagents intégrés, Claude Code affiche un avertissement au démarrage. Le détail va dans le prompt système, chargé seulement quand le subagent travaille.
Étape 3 : limiter les outils
Le champ tools liste les outils autorisés. Sans lui, le subagent hérite de tous les outils disponibles. Ici, Read, Glob, Grep l’autorise à lire et à chercher, jamais à écrire.
Le champ disallowedTools retire au contraire des outils de la liste héritée. Pour donner à un subagent un serveur MCP absent de la conversation principale, la documentation prévoit le champ mcpServers.
Étape 4 : choisir le modèle
Le champ model accepte haiku, sonnet, opus, fable, un identifiant complet ou inherit, qui reprend le modèle de la conversation. Sans ce champ, Claude Code se rabat sur la variable CLAUDE_CODE_SUBAGENT_MODEL si elle est définie, puis sur le modèle de la conversation principale. Un modèle que Claude précise au moment de l’appel passe avant tout le reste.
La documentation conseille Haiku pour réduire les coûts. Sur l’API d’Anthropic, l’alias haiku désigne Claude Haiku 5.5, qu’Anthropic destine aux tâches à fort volume, dont celles des subagents. Sa page indique un prix d’API de 0,10 $ par million de tokens en entrée et 0,50 $ en sortie, pour les prompts jusqu’à 100 000 tokens.
Pour une relecture comme celle de l’exemple, c’est un choix cohérent. Pour un raisonnement long, la documentation de Claude Code oriente plutôt vers opus, l’alias des tâches de raisonnement complexes.
Étape 5 : appeler le subagent
Claude délègue de lui-même quand une demande correspond à la description. Pour forcer l’appel, nommez le subagent dans le prompt :
Utilise le subagent relecteur-code pour relire les changements du module d’authentification
La mention @agent-relecteur-code fonctionne aussi. Le compte rendu revient ensuite dans votre conversation, sans le détail des fichiers lus. Pour qu’une session entière prenne les outils et le modèle du subagent, la documentation donne la commande claude --agent relecteur-code.
Comment orchestrer plusieurs subagents
La documentation décrit trois façons de combiner des subagents. La première isole les opérations qui produisent beaucoup de sortie, comme une suite de tests : le subagent lit tout et ne renvoie que les tests en échec, avec leurs messages d’erreur.
La deuxième est la recherche en parallèle, quand les pistes ne dépendent pas les unes des autres :
Analyse les modules authentification, base de données et API en parallèle avec des subagents séparés
Claude lance un subagent par module, puis fait la synthèse. Par défaut, une session accepte 20 subagents simultanés, une limite que change la variable CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.
La troisième est l’enchaînement : chaque subagent rend son résultat à Claude, qui transmet le contexte utile au suivant.
Utilise le subagent relecteur-code pour trouver les problèmes de performance, puis le subagent correcteur pour les corriger
Ce prompt suppose un fichier correcteur.md doté des outils d’écriture.
Un subagent peut aussi lancer ses propres subagents, jusqu’à trois niveaux sous la conversation principale par défaut. La variable CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH change cette profondeur, et la valeur 1 coupe l’imbrication. Pour un seul subagent, il suffit de laisser l’outil Agent hors de son champ tools ou de l’ajouter à disallowedTools.
Un subagent en cours passe en arrière-plan avec Ctrl+B, ce qui vous rend la main pendant qu’il travaille.
Les limites et les erreurs fréquentes
Déléguer n’est pas toujours rentable. Pour un échange en plusieurs allers-retours ou une modification rapide, la documentation conseille de rester dans votre conversation, car un subagent repart de zéro.
Quatre erreurs découlent directement de ce fonctionnement :
- un subagent introuvable : son dossier
agentsn’existait pas au lancement de la session, un redémarrage le charge ; - un subagent jamais appelé : sa description ne dit pas quand l’utiliser ;
- une consigne ignorée : il ne voit pas l’historique, le contexte doit figurer dans son prompt ou la demande ;
- un champ sans effet : les noms respectent la casse et un champ inconnu est ignoré sans message.
Autre point important : l’alias haiku ne désigne pas le même modèle partout. Selon la documentation de Claude Code, il pointe vers Haiku 4.5 sur Amazon Bedrock, Google Cloud, Microsoft Foundry et Claude Platform on AWS. Pour figer le modèle, la documentation conseille son identifiant complet, comme claude-haiku-5-5.
Les subagents de Claude Code servent donc surtout si vous revenez souvent sur les mêmes tâches : relecture, tests, exploration d’un gros dépôt. Un ou deux subagents bien décrits suffisent pour commencer. Les agent teams, plus coûteuses et encore expérimentales, se réservent plutôt aux chantiers où plusieurs agents doivent discuter entre eux.

