Un sous-agent Claude Code est un assistant secondaire qui exécute une tâche dans sa propre fenêtre de contexte, avec ses instructions, ses outils et parfois son propre modèle, puis rend un résumé à la conversation principale. Il sert à isoler un travail bavard, à restreindre des droits ou à confier une tâche simple à un modèle moins cher. Il ne rend pas le travail gratuit : ses requêtes sont décomptées des mêmes limites que la session qui l’a lancé.
Les noms de champs, emplacements et comportements cités ici ont été relus le 20 octobre 2026 dans la documentation officielle des sous-agents (version 2.1.296 de Claude Code) et dans la page consacrée aux coûts. L’outil évolue vite : les numéros de version mentionnés dans la documentation indiquent à partir de quand un comportement existe.
Ce qu’est un sous-agent dans Claude Code
Chaque sous-agent démarre avec une fenêtre de contexte vierge. Il ne voit ni l’historique de la conversation, ni les fichiers déjà lus, ni les skills déjà chargés. Claude rédige un message de délégation qui résume la tâche, et le sous-agent travaille à partir de ce seul message, de son propre prompt système, des fichiers CLAUDE.md du projet et d’un instantané de l’état Git. À la fin, seul son compte rendu revient dans la conversation principale.
Claude Code fournit plusieurs sous-agents intégrés. Explore est en lecture seule et sert à chercher dans un dépôt ; Plan rassemble le contexte en mode plan ; general-purpose dispose de tous les outils et traite les tâches qui mêlent exploration et modification. Explore et Plan démarrent sans les fichiers CLAUDE.md ni l’état Git, ce qui les rend plus rapides et moins coûteux. À ces intégrés s’ajoutent les sous-agents personnalisés, que chacun définit dans un fichier.
Ce mécanisme est différent d’un skill, qui ajoute des instructions dans la conversation principale, et d’un fichier CLAUDE.md, qui fixe des règles permanentes. La notion plus générale d’agent autonome, avec sa mission et son réveil planifié, est traitée dans le guide créer un agent IA.
Quand déléguer, et quand ne pas le faire
La documentation donne trois cas favorables. Le premier est la tâche qui produit beaucoup de texte dont la suite n’aura pas besoin : lancer une suite de tests, lire une documentation volumineuse, parcourir des journaux. Le sous-agent absorbe ce volume et ne rend que l’essentiel, par exemple la liste des tests en échec. Le deuxième est la recherche en parallèle sur des pistes indépendantes. Le troisième est le besoin d’imposer des restrictions d’outils ou de permissions à une partie du travail.
La conversation principale reste préférable dans d’autres situations : échanges fréquents et itératifs, phases qui partagent beaucoup de contexte (planification, écriture, tests), modification rapide et ciblée, ou besoin de réactivité. Un sous-agent qui part d’un contexte vide doit d’abord reconstituer ce qu’il ignore, ce qui prend du temps et des tokens. Pour une simple question sur un élément déjà présent dans la conversation, la documentation oriente vers la commande /btw plutôt que vers un sous-agent.
Créer un sous-agent : le fichier et ses champs
Un sous-agent personnalisé est un fichier Markdown dont l’en-tête YAML porte la configuration et dont le corps devient le prompt système. Le plus simple consiste à demander à Claude de l’écrire, puis à relire le résultat. Le fichier peut aussi être écrit à la main :
---
name: relecteur-code
description: Relit le code modifié et signale les problèmes de qualité et de sécurité. À utiliser après une modification de code.
tools: Read, Grep, Glob
model: sonnet
---
Tu es chargé de relire du code. Pour chaque problème, indique le fichier,
la ligne, le risque et une correction possible.Seuls name et description sont obligatoires. Les champs facultatifs les plus utiles sont tools (liste blanche d’outils), disallowedTools (liste noire), model, effort, permissionMode, maxTurns (nombre maximal de tours), skills (skills préchargés), mcpServers (serveurs MCP accessibles), memory (mémoire persistante), isolation: worktree (copie isolée du dépôt) et omitClaudeMd. Les noms composés s’écrivent en camelCase et doivent correspondre exactement : un champ mal orthographié est ignoré sans message d’erreur. La commande claude --debug permet de le repérer dans le journal de débogage.
L’emplacement du fichier détermine sa portée. Dans .claude/agents/ à la racine d’un projet, le sous-agent est propre à ce dépôt et peut être versionné avec lui. Dans ~/.claude/agents/, il est disponible dans tous les projets de la machine. En cas de doublon de nom, l’ordre de priorité documenté est : réglages gérés par l’organisation, option --agents en ligne de commande, projet, utilisateur, puis plugin. Claude Code détecte un fichier ajouté ou modifié en quelques secondes, sauf si le dossier agents n’existait pas au démarrage de la session : il faut alors redémarrer.
Certains fichiers sont ignorés sans avertissement dans la session : absence de name, premier --- qui n’est pas sur la première ligne, nom contenant :, description manquante ou YAML invalide. La commande claude plugin validate .claude/agents vérifie la syntaxe d’un dossier avant de lancer une session.
Choisir le modèle et limiter les outils
Le champ model accepte un alias (haiku, sonnet, opus, fable), un identifiant complet ou inherit. Claude Code résout le modèle dans cet ordre : paramètre passé par Claude au moment de l’appel, champ model du fichier, variable d’environnement CLAUDE_CODE_SUBAGENT_MODEL, puis modèle de la conversation principale. Sans indication, le sous-agent tourne donc sur le même modèle que la session. La page des coûts le rappelle : passer la session sur Opus fait aussi passer sur Opus les sous-agents qui héritent du modèle, et elle recommande model: haiku pour les tâches simples.
Le dépôt de configuration de Jeremy Degryse en donne un exemple de répartition. Sur 41 sous-agents définis au 20 octobre 2026, 17 tournent sur Opus 5.5, 17 sur Sonnet 4.6 et 6 sur Haiku 4.5 ; le dernier n’impose pas de modèle. Haiku y est réservé aux tâches mécaniques (recherche, comptage, extraction, reformatage), Sonnet à la rédaction et aux audits courants, Opus à l’arbitrage et aux décisions qui engagent.
Pour les outils, tools fonctionne comme une liste blanche et disallowedTools comme une liste noire ; quand les deux sont présents, la liste noire est appliquée d’abord. Un sous-agent chargé de relire du code n’a pas besoin de Write ni de Edit. Par défaut, un sous-agent peut lui-même en lancer d’autres, jusqu’à trois niveaux sous la conversation principale ; retirer l’outil Agent de sa liste l’en empêche. Une session bloque aussi tout nouveau lancement au-delà de 20 sous-agents actifs simultanément, limite réglable par CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.
Ce que coûte un sous-agent
La documentation est explicite : chaque sous-agent envoie ses propres requêtes, décomptées des mêmes limites d’usage que la conversation principale. Déléguer économise du contexte, pas du quota. L’économie réelle vient de deux leviers : un modèle moins cher pour le sous-agent, et un compte rendu court pour la conversation principale. Depuis un abonnement Pro, Max, Team ou Enterprise, la commande /usage attribue une part de la consommation récente aux sous-agents, aux skills et aux serveurs MCP.
Le second levier est souvent sous-estimé. Tout ce qu’un sous-agent renvoie entre dans le contexte de la conversation principale et y reste. Ce contexte est relu à chaque tour suivant. Une mesure consignée dans le même dépôt, le 22 août 2026, porte sur une session de 1 258 tours : environ 20 millions de tokens facturés pour 2,2 millions de tokens produits. L’essentiel du coût venait du contexte relu par la session principale, pas du texte généré. La documentation fait la même mise en garde : plusieurs sous-agents qui rendent chacun un résultat détaillé peuvent consommer beaucoup de contexte.
La parade documentée dans ce dépôt consiste à faire écrire le résultat complet dans un fichier et à limiter la réponse du sous-agent à quelques lignes : le chemin du fichier, un verdict, et l’information nécessaire pour décider. La conversation principale ne lit ensuite dans le fichier que ce qui sert. La fiche de l’ouvrier de délestage, qui tourne sur Haiku, formule la règle ainsi : « Ton résultat va dans un fichier. Ta réponse, elle, tient en quatre lignes. »
Erreurs fréquentes
Une description vague. Claude choisit le sous-agent d’après son champ description. « Aide pour le code » ne lui dit pas quand déléguer ; « relit le code modifié et signale les problèmes de sécurité, à utiliser après une modification » le dit. La documentation recommande aussi des descriptions courtes : au-delà de 15 000 tokens cumulés pour les sous-agents personnalisés, Claude Code affiche un avertissement au démarrage. Le détail va dans le prompt système, qui ne se charge que lorsque le sous-agent s’exécute.
Des outils trop larges. Omettre tools donne au sous-agent tous les outils disponibles. Pour une tâche de lecture, une liste blanche réduite limite à la fois les erreurs et les actions imprévues.
Un retour sans limite. Un sous-agent à qui l’on ne précise pas le format de sortie peut renvoyer l’intégralité de ce qu’il a lu. Indiquer dans le prompt système la forme attendue, et sa longueur maximale, évite de réintroduire dans la conversation principale le volume que la délégation devait écarter.
Un message de délégation incomplet. Le sous-agent ne connaît que ce message et ses propres instructions. Une règle qui doit s’appliquer à sa tâche, comme « ne pas toucher au dossier vendor/ », doit y être reprise, en particulier pour Explore, Plan et les sous-agents configurés avec omitClaudeMd, qui ne lisent pas le CLAUDE.md du projet.
Trop d’agents qui se recouvrent. Deux sous-agents aux descriptions proches rendent la délégation automatique imprévisible. Le tri périodique des instructions, décrit dans le guide trier ses instructions, s’applique aussi au dossier agents. Les échecs de coordination entre agents ont par ailleurs été documentés par Anthropic, comme le rapportait cette actualité.
Les autres guides de la série sont regroupés sur la page Claude Code, dont le comparatif Codex et Claude Code.