Sous-agents Claude Code : déléguer sans perdre le contexte

Un sous-agent Claude Code exécute une tâche à part, dans sa propre fenêtre de contexte, et ne renvoie qu'un résumé à votre session. C'est la meilleure parade quand une suite de tests ou une exploration de dépôt crache des milliers de lignes que vous ne relirez jamais. Il part pourtant sans rien savoir de votre discussion : ce que la consigne de délégation ne dit pas, il l'ignore, et il ne peut pas vous poser de question pour combler le trou.

Ce tutoriel s'adresse aux développeurs qui ont déjà fait leur prise en main de Claude Code. Il s'appuie sur la documentation officielle relevée le 12 novembre 2026, avec la version 2.1.322 installée sur notre serveur, et sur une mesure faite chez nous. Nous avons analysé les journaux des 219 sous-agents lancés par nos sessions de développement entre le 12 août et le 5 novembre 2026, sur 160 sessions et 12 projets. Nous en tirons une règle simple. Un sous-agent rentabilise son coût fixe sur les tâches bavardes et bien délimitées, et le perd sur tout ce qui demande des allers-retours.

Ce qu'un sous-agent Claude Code reçoit au démarrage

Un sous-agent démarre avec son propre prompt système, la consigne rédigée par Claude, vos fichiers CLAUDE.md et un instantané du statut git, sans l'historique de votre conversation. La documentation des sous-agents détaille ce qui n'arrive jamais jusqu'à lui : les skills déjà invoquées, les fichiers déjà lus, votre style de sortie et la mémoire automatique de la session principale. Sa fenêtre de contexte dépend de son propre modèle. Déléguer à un modèle plus petit lui donne donc une fenêtre plus petite.

Deux exceptions changent la donne. Les agents intégrés Explore et Plan démarrent sans CLAUDE.md ni statut git, pour rester rapides et peu coûteux. À l'inverse, un fork hérite de toute la conversation : même prompt système, mêmes outils, même modèle et même historique. Il réutilise le cache de prompt de la session principale, ce qui le rend moins cher qu'un sous-agent neuf quand la tâche a besoin du même contexte.

Nos journaux montrent ce que pèse ce bagage de départ. Nous avons relevé, pour chaque sous-agent, la taille du contexte envoyé à sa toute première requête, avant la moindre action.

Un sous-agent general-purpose démarre chez nous avec 92 500 jetons en médiane, contre 21 200 pour Explore, alors que leurs consignes font quelques milliers de caractères dans les deux cas. L'écart vient des CLAUDE.md, du statut git et des définitions d'outils qu'Explore ne charge pas. Notre CLAUDE.md global est volontairement chargé en règles d'exploitation, et chaque sous-agent le recharge. Pour un agent qui reçoit tout ce qu'il lui faut dans sa consigne, le champ omitClaudeMd: true, disponible depuis la version 2.1.271, supprime ce poids. Les fichiers de politique gérés par l'organisation restent chargés.

Créer un sous-agent : le fichier, la portée et les champs qui comptent

Un sous-agent est un fichier Markdown avec un en-tête YAML, placé dans .claude/agents/ pour un projet ou dans ~/.claude/agents/ pour toutes vos sessions. Seuls name et description sont obligatoires, et le corps du fichier devient le prompt système. Le sous-agent ne reçoit pas le prompt système de Claude Code, seulement le sien et quelques détails d'environnement comme le dossier de travail.

---
name: lanceur-tests
description: Lance la suite de tests et ne rapporte que les échecs. À utiliser après chaque modification de code.
tools: Bash, Read, Grep
model: haiku
omitClaudeMd: true
maxTurns: 15
---

Tu lances la commande de test indiquée dans la consigne.
Tu rends uniquement les tests en échec, un par ligne, avec le message
d'erreur et le fichier concerné. Si tout passe, tu réponds « 0 échec ».

La description décide de la délégation automatique : Claude la lit pour savoir quand passer la main. Une formule comme « à utiliser après chaque modification de code » pousse à la délégation proactive. Gardez-la courte, car toutes les descriptions restent en contexte, et Claude Code affiche un avertissement au démarrage quand celles de vos sous-agents personnalisés dépassent 15 000 jetons au total.

Quand deux définitions portent le même nom, la plus prioritaire gagne : réglages gérés de l'organisation, puis l'option --agents de la ligne de commande, puis le projet, puis l'utilisateur, puis les plugins. Les dossiers sont lus de façon récursive et l'identité vient uniquement du champ name. Cinq champs couvrent l'essentiel des besoins réels :

• tools ou disallowedTools pour restreindre les outils, par exemple un relecteur en lecture seule ;
• model pour router une tâche simple vers haiku, ou inherit pour suivre la session ;
• permissionMode pour fixer le mode de permission propre à l'agent ;
• isolation: worktree pour travailler sur une copie du dépôt, nettoyée si l'agent ne modifie rien ;
• skills et mcpServers pour donner à l'agent un savoir-faire ou un outil que la session principale n'a pas besoin de porter.

Le champ skills injecte au démarrage le contenu complet des skills Claude Code listées, et pas seulement leur description. Le champ mcpServers accepte un serveur déjà configuré ou une définition propre à l'agent, connectée à son lancement et coupée à sa fin. Cette seconde forme évite que les schémas d'outils d'un serveur encombrent la conversation principale, un sujet que nous avons mesuré dans notre guide des serveurs MCP branchés à Claude Code. Pour un essai ponctuel, claude --agents accepte la même définition en JSON, valable pour la seule session ; en mode -p, il accepte aussi le chemin d'un fichier JSON depuis la version 2.1.281.

Écrire la consigne de délégation, là où la plupart des délégations ratent

La consigne de délégation est le seul pont entre votre conversation et le sous-agent : elle doit porter l'objectif, le périmètre, le format de retour et le critère d'arrêt. Anthropic en a fait l'expérience sur son propre système de recherche. Son retour d'ingénierie publié en juin 2025 explique que chaque sous-agent a besoin d'un objectif, d'un format de sortie, d'indications sur les outils et les sources, et de limites claires. Sans description détaillée, les agents dupliquent le travail ou laissent des trous. Avec des consignes courtes du type « fais une recherche sur la pénurie de semi-conducteurs », ils interprétaient mal la tâche ou lançaient les mêmes recherches que d'autres agents.

Le piège tient à la mécanique de Claude Code. Même quand vous mentionnez un sous-agent avec @, c'est Claude qui rédige sa consigne à partir de votre message. La mention garantit quel agent tourne, pas ce qu'il reçoit. Si votre message reste vague, la consigne le sera aussi. Et le sous-agent n'a pas l'outil qui lui permettrait de vous poser une question, puisque AskUserQuestion fait partie des outils retirés à tous les sous-agents. Une ambiguïté se résout donc par une supposition.

Chez nous, les consignes envoyées aux sous-agents general-purpose font environ 3 000 caractères en médiane, soit une page. Ce volume n'a rien d'excessif : il contient ce que la session principale a déjà établi et que le sous-agent ne doit pas redécouvrir. Les règles de votre CLAUDE.md suivent la même logique. La documentation recommande de reformuler dans la consigne toute règle qui doit absolument atteindre le sous-agent, du type « ignore le dossier vendor », plutôt que de compter sur son chargement. Nous suivons cette trame :

Objectif : trouver pourquoi l'export CSV des factures double les lignes
depuis le commit a41f2c9. Ne corrige rien.
Déjà établi : le bug ne touche que les clients multi-sites ; la requête
SQL de facture_export.py renvoie le bon nombre de lignes.
Périmètre : app/exports/ et tests/exports/. N'ouvre pas vendor/.
Retour attendu : la cause en trois phrases, le fichier et la ligne,
puis la commande qui reproduit le bug. Pas de résumé de ta démarche.
Arrêt : dès que la cause est prouvée par un test qui échoue.

Le critère d'arrêt compte autant que l'objectif. Sans lui, un sous-agent d'exploration continue de lire des fichiers bien après avoir trouvé la réponse, et chaque lecture alourdit son contexte. Le champ maxTurns sert de garde-fou : à la limite, Claude Code rend la sortie marquée comme partielle, et Claude peut reprendre le sous-agent pour qu'il termine.

Déléguer ou garder la main : les cas tranchés

Déléguez une tâche qui produit beaucoup de sortie et se résume en quelques lignes ; gardez dans la session principale tout ce qui demande des allers-retours. La documentation range dans la seconde catégorie les tâches itératives, les phases qui partagent beaucoup de contexte comme planifier, implémenter et tester, les petites corrections ciblées et les cas où la latence compte. Un sous-agent qui n'est pas un fork part de zéro et doit d'abord rassembler son contexte.

Nos journaux montrent le cas idéal avec Explore. En médiane, un sous-agent Explore a enchaîné 26 requêtes et 45 appels d'outils, souvent lancés en parallèle, et son contexte est monté jusqu'à 129 400 jetons. Il a rendu un rapport d'environ 18 500 caractères, soit quelques milliers de jetons. Le reste a disparu avec lui, et c'est exactement ce qu'on lui demande. Le même travail mené dans la session principale l'aurait encombrée pour toute la suite.

La relecture de code mérite une mention. Un relecteur lancé en sous-agent n'a pas vu les compromis qui ont produit le code, et c'est sa force : il juge le diff tel qu'un collègue le lirait. Nous lançons ainsi une relecture à contexte frais avant chaque livraison sensible ; un agent limité à Read, Grep et Glob la garde en lecture seule. Pour une simple question sur ce qui est déjà dans la conversation, la commande /btw répond sans outil et sans polluer l'historique, ce qui est plus léger qu'un sous-agent. Pour un prompt réutilisable qui doit tourner dans le contexte principal, une skill convient mieux.

Ce que coûtent les sous-agents et comment réduire la facture

Chaque sous-agent envoie ses propres requêtes, décomptées sur les mêmes limites d'usage que votre conversation principale : déléguer allège votre contexte sans rien retirer à votre consommation. Anthropic chiffre l'écart dans son analyse de son système de recherche multi-agents : un agent consomme environ 4 fois plus de jetons qu'une conversation simple, et un système multi-agents environ 15 fois plus. En échange, son système multi-agents avec Opus 4 en chef et Sonnet 4 en sous-agents a dépassé un agent Opus 4 seul de 90,2 % sur son évaluation interne de recherche. Sur le test BrowseComp, le volume de jetons expliquait à lui seul 80 % de la variance des performances.

Ce surcoût ne se justifie donc que pour des tâches à forte valeur. Les mêmes principes valent hors de Claude Code, pour les systèmes multi-agents que l'on construit dans un produit. La documentation des coûts annonce d'ailleurs environ 7 fois plus de jetons pour les équipes d'agents dont les coéquipiers tournent en mode plan.

Le coût fixe se répète à chaque requête, et c'est le point que nos mesures font ressortir. Un sous-agent general-purpose a chez nous fait trois requêtes en médiane et traité 294 900 jetons d'entrée, cache compris. Les 92 500 jetons de départ sont renvoyés à chaque tour. Le cache de prompt en réduit le prix sur l'API, mais ils restent présents dans chaque requête. Trois leviers agissent directement :

• Le modèle. Sur l'API, Haiku 5.5 coûte 0,10 $ par million de jetons d'entrée pour les prompts jusqu'à 100 000 jetons, contre 4 $ pour Opus 5.5. Au-delà de ce seuil, Haiku 5.5 passe à 0,50 $, et un sous-agent qui démarre à 92 500 jetons le franchit vite.
• Le bagage de départ. omitClaudeMd: true retire les CLAUDE.md utilisateur, projet et local, et un CLAUDE.md allégé profite aussi à toutes les sessions.
• Le forçage global. CLAUDE_CODE_SUBAGENT_MODEL fixe un modèle par défaut ; ajouté à CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, il s'impose à tous les sous-agents, Explore compris, hors forks, depuis la version 2.1.257.

Le prix n'est pas le seul critère. Le guide des modèles confirme que l'alias haiku désigne Haiku 5.5 sur l'API Anthropic, mais une version antérieure chez certains autres fournisseurs. Un sous-agent chargé de juger du code mérite un modèle plus fort que celui qui filtre des journaux.

Arrière-plan, forks et imbrication : les réglages qui surprennent

Par défaut, un sous-agent lancé depuis la conversation principale tourne en arrière-plan, et en session interactive Claude ne peut pas l'attendre tant que le mode fork est actif. Ce mode est activé par défaut depuis la version 2.1.302, et depuis la 2.1.232 dans le terminal interactif. Pour que Claude puisse attendre un rapport avant de continuer, passez CLAUDE_CODE_FORK_SUBAGENT à 0 dans les réglages, relancez Claude Code, puis demandez-lui d'attendre. En mode claude -p et dans l'Agent SDK, Claude peut attendre de lui-même.

Un sous-agent en arrière-plan dispose d'un jeu d'outils réduit. Il garde ses outils MCP, mais seulement vingt outils intégrés, dont Read, Bash, Edit, WebFetch et Skill. Ses demandes de permission remontent dans votre session principale avec son nom. Attention à la portée de votre réponse : une autorisation accordée pour le reste de la session s'applique à toute la session, conversation principale comprise.

L'imbrication est permise par défaut jusqu'à trois niveaux sous la conversation principale. La variable CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH règle cette profondeur, et la valeur 1 coupe l'imbrication. Pour un relecteur qui doit rester simple, retirez Agent de ses outils. Une autre limite plafonne à 20 le nombre de sous-agents qui tournent en même temps ; au-delà, le lancement échoue avec Concurrent subagent limit reached. Il n'existe en revanche aucune limite au nombre total de sous-agents sur une session.

Un sous-agent terminé se reprend avec tout son historique. Claude lui envoie un message par son identifiant ou son nom via l'outil SendMessage, sans relancer une nouvelle instance. Explore et Plan font exception : ils ne rendent pas d'identifiant et ne se reprennent pas, d'où l'intérêt d'un agent personnalisé pour un travail à poursuivre. Les journaux sont rangés dans ~/.claude/projects/, sous un dossier subagents/ par session, et supprimés après 30 jours par défaut, selon le réglage cleanupPeriodDays. C'est dans ces fichiers que nous avons fait nos mesures.

Les pièges qui font perdre une après-midi

Le piège le plus sournois ne laisse aucune trace à l'écran : Claude Code ignore un champ d'en-tête mal orthographié et saute un fichier mal formé sans rien signaler dans la session. Les noms de champs suivent le camelCase, et max_turns ou disallowed-tools n'ont aucun effet. Depuis la version 2.1.296, lancez claude --debug et cherchez does not recognize or apply dans le journal de débogage pour trouver le champ fautif. Un fichier est écarté s'il n'a pas de name, si son --- d'ouverture n'est pas sur la première ligne, si le nom contient : ou si le YAML ne se lit pas. La commande claude plugin validate .claude/agents repère les en-têtes illisibles avant une session.

Quatre autres comportements documentés prennent souvent les équipes de court :

• une entrée comme Bash(git push *) dans disallowedTools retire tout l'outil Bash ; pour bloquer une seule commande, placez la règle dans permissions.deny ;
• le permissionMode d'un agent est ignoré quand la session principale tourne en bypassPermissions, acceptEdits ou en mode auto : l'agent prend le mode de la session ;
• les sous-agents fournis par un plugin ignorent hooks, mcpServers et permissionMode, par sécurité ;
• le premier fichier créé dans un nouveau dossier agents exige un redémarrage, alors que les modifications suivantes sont prises en compte en quelques secondes.

Le dernier piège tient à l'organisation plus qu'à la technique. Une équipe qui multiplie les sous-agents finit avec des descriptions qui se chevauchent, et Claude délègue alors au hasard. Nous conseillons peu d'agents, chacun avec une description qui dit quand l'utiliser et ce qu'il rend. La commande /tasks indique sur quel modèle tourne chaque sous-agent, utile pour vérifier qu'un réglage a bien pris. Quand ces délégations deviennent un produit, avec des agents qui tournent pour vos clients et pas seulement pour vos développeurs, le sujet relève de notre équipe spécialisée en agents IA.

FAQ sur les sous-agents Claude Code

Quelle différence entre un sous-agent et une équipe d'agents ?

Un sous-agent vit à l'intérieur d'une seule session : il reçoit une tâche, travaille dans son contexte et rend un résumé à la conversation qui l'a lancé. Une équipe d'agents réunit plusieurs sessions Claude Code : une session cheffe distribue les tâches, et les coéquipiers communiquent directement entre eux. Cette fonction est désactivée par défaut et s'active avec CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Elle consomme nettement plus, puisque chaque coéquipier garde sa propre fenêtre de contexte jusqu'à son arrêt.

Comment forcer Claude Code à utiliser mon sous-agent ?

Mentionnez-le avec @ dans votre message : la mention garantit que cet agent précis tourne pour la tâche. Pour toute une session, lancez claude --agent nom, et le fil principal prend alors les restrictions d'outils et le modèle de l'agent. Pour un projet entier, le réglage agent de .claude/settings.json fait la même chose. La délégation automatique, elle, dépend surtout de la description.

Les sous-agents fonctionnent-ils avec un abonnement Claude ?

Oui, ils tournent avec un abonnement comme avec une clé d'API. Leurs requêtes sont décomptées sur les mêmes limites d'usage que la conversation principale. Plusieurs sous-agents en parallèle peuvent donc épuiser un quota plus vite que prévu. Sur les forfaits Pro, Max, Ultra, Team et Enterprise, la commande /usage attribue aux sous-agents leur part de la consommation récente. Pour monter en compétence sur ces réglages, notre formation Claude Code les traite en atelier.

Où retrouver ce qu'a fait un sous-agent ?

Pendant qu'il tourne, la commande /tasks liste les sous-agents avec leur modèle, et la touche Entrée ouvre leur transcription. Un sous-agent terminé avec succès y reste listé 30 secondes. Ensuite, sa transcription complète se trouve dans ~/.claude/projects/, dans le dossier subagents/ de la session, sous la forme d'un fichier agent- suivi de son identifiant. Ces fichiers survivent à la compaction de la conversation principale.

Un sous-agent peut-il modifier mon code ?

Oui, si ses outils le permettent : un agent general-purpose ou un agent personnalisé sans restriction peut éditer, écrire et lancer des commandes. Explore et Plan sont en lecture seule. Pour isoler ses modifications, ajoutez isolation: worktree : l'agent travaille alors dans une copie du dépôt, partie par défaut de votre branche principale, et la copie est supprimée s'il n'a rien changé. Vous relisez ensuite ses modifications avant de les fusionner.