À retenir
- Un sous-agent = contexte isolé — chaque invocation démarre une fenêtre propre, le rapport remonte à la session principale sans la polluer
- La
descriptionest le seul levier de la délégation automatique — vague = jamais invoqué ; « À utiliser quand… » = délégation fiable - Économie de 66 %+ sur les tâches de routine en routant vers Haiku 4.5 (1 $/MTok input) plutôt que Sonnet (3 $/MTok)
- Sub-agents ≠ Skills ≠ MCP : trois couches complémentaires à ne pas confondre — le tableau de décision est dans cet article
- En juillet 2026 (v2.1.219), les sous-agents imbriqués jusqu'à profondeur 3 sont disponibles, et
/code-reviewtourne nativement en agent de fond
Un développeur freelance raconte la même histoire : au bout de la 3e heure sur une session Claude Code complexe, les réponses deviennent floues. Le modèle oublie les décisions prises une heure plus tôt. Il recommence la session, perd son contexte, et recommence encore. Ce n'est pas un bug — c'est la nature des fenêtres de contexte. Les sub agents Claude Code sont la réponse structurelle à ce problème, et leur adoption reste encore marginale dans les équipes françaises alors que la documentation officielle Anthropic les documente depuis juillet 2025.
Cet article couvre ce que les tutoriels classiques esquivent : les erreurs de configuration qui font que la délégation automatique ne se déclenche jamais, le calcul concret des économies de tokens par modèle, et le tableau de décision sub-agents vs Skills vs MCP que personne ne présente en un seul endroit.
Qu'est-ce qu'un sub agent Claude Code ?
Un sous-agent Claude Code est une instance Claude isolée et spécialisée, disposant de sa propre fenêtre de contexte, de son propre prompt système, d'outils autorisés scopés et de permissions distinctes de la session principale. La session principale lui délègue une tâche ; il l'exécute sans polluer le contexte existant et retourne uniquement son rapport final.
Techniquement, c'est un fichier Markdown dans .claude/agents/<nom>.md (portée projet, versionné dans le repo) ou ~/.claude/agents/<nom>.md (portée utilisateur, personnel). La session principale délègue une tâche à ce sous-agent, qui exécute son travail de façon isolée, puis retourne uniquement son rapport final.
Selon Sathish Raju (Medium, avril 2026) : « les sous-agents ne rendent pas Claude plus intelligent. Ils préservent la qualité du contexte existant. » C'est exactement ça — une question d'hygiène du contexte, pas de puissance brute.
.claude/agents/.💡 Bon à savoir : Un sous-agent n'a pas accès au contexte de la session principale — c'est volontaire. Il repart de zéro à chaque invocation. C'est ce qui garantit des rapports propres et reproductibles, mais c'est aussi pourquoi les tâches nécessitant la continuité des décisions d'architecture sont mieux traitées dans la session principale.
Le frontmatter YAML : chaque champ compte
Le contenu d'un sous-agent se divise en deux parties : le frontmatter YAML (configuration) et le corps (prompt système). Le corps, c'est votre domaine — écrivez des instructions claires. Le frontmatter, c'est là que la plupart des configurations échouent.
name (obligatoire)
description (critique)
model (levier coût)
tools / disallowedTools
background
isolation: worktree
Deux champs moins connus mais puissants depuis la v2.1.219 (releasebot.io, juillet 2026) : maxTurns pour capfer le nombre d'itérations (évite les agents qui spiralent) et permissionMode: bypassPermissions pour l'autonomie complète — à manier avec précaution.
💡 Bon à savoir : Omettre
disallowedToolssur un agent de lecture/audit est l'erreur la plus courante en production. Sans cette restriction explicite, un sous-agentdependency-auditorpeut modifierpackage.jsonou supprimer des fichiers. Listez toujoursEdit,WriteetBashdansdisallowedToolspour les agents read-only.
Le vrai problème : pourquoi la délégation automatique ne se déclenche pas
La description dans le frontmatter YAML est le seul déclencheur de la délégation automatique — et une description vague empêche systématiquement la délégation. Voici le scénario classique : vous créez un sous-agent code-reviewer, vous demandez à Claude de « faire une revue de code », et Claude le fait lui-même sans jamais invoquer l'agent.
Ce comportement est documenté par la communauté HackerNews dès juillet 2025 et la cause est toujours la même : la description est trop vague.
Claude analyse le champ description de chaque sous-agent pour décider si la tâche en cours correspond à une délégation. Une description générique comme helps with code review ne déclenche jamais de match fiable.
La formule qui fonctionne en production : commencez la description par « À utiliser quand… » suivi de deux ou trois déclencheurs nommés. C'est la règle documentée par Stéphane Robert (blog, mis à jour juillet 2026) et confirmée par systemprompt.io (mars 2026).
Sub-agents vs Skills vs MCP : le tableau de décision
Trois abstractions coexistent dans Claude Code, chacune avec un rôle précis — et les confondre génère des architectures fragiles. C'est le gap que tous les articles de la SERP évitent.
La règle de systemprompt.io est la plus claire : « Un sous-agent est QUI fait le travail. Un serveur MCP est QUELS outils il a. Un skill est QUELLES instructions il suit. »
Les sous-agents peuvent utiliser des serveurs MCP — les MCP ne peuvent pas utiliser des sous-agents. C'est une relation d'inclusion, pas de concurrence. L'architecture cible recommandée par systemprompt.io : Skills au niveau 3 (connaissances d'équipe) → Sous-agents spécialisés au niveau 2 (Haiku ou Sonnet selon la complexité) → MCP au niveau 1 (connexions externes).
Pour aller plus loin sur l'utilisation avancée de Claude Code dans un projet réel, consultez notre guide complet Claude Code 2026.
Choisir le bon modèle : Haiku, Sonnet ou Opus ?
Le choix du modèle est le levier économique le plus sous-utilisé des sous-agents Claude Code. Selon les tarifs officiels Anthropic (juillet 2026), la différence entre Haiku et Opus sur des tâches de routine atteint 5x sur le coût d'entrée — sans gain de qualité mesurable pour la majorité des cas.
Le calcul concret : une revue de code de 500 lignes génère typiquement environ 10 000 tokens en entrée + 2 000 tokens en sortie. Avec Sonnet 5 : environ 0,04 $ (tarif introductif jusqu'au 31/08/2026). Avec Haiku 4.5 : environ 0,02 $. Sur 100 revues par mois, la différence dépasse 2 $ par développeur — négligeable en apparence, mais selon l'équipe de systemprompt.io, après un mois de suivi de leur usage interne, 60 % des tokens Opus étaient dépensés sur des tâches que Haiku aurait traitées de façon identique (auto-déclaration de leur équipe sur 8 plugins et 34+ skills).
La règle de décision : si votre sous-agent ne fait que lire et résumer (audit, documentation, lint), commencez par Haiku. Passez à Sonnet si la qualité du raisonnement est insuffisante. Réservez Opus aux agents de sécurité critique ou d'architecture — jamais pour les tâches de routine.
Créer votre premier sous-agent en 5 étapes
Choisir la portée
Projet partagé → .claude/agents/nom.md (versionné dans le repo, disponible pour toute l'équipe). Usage personnel → ~/.claude/agents/nom.md (portable entre projets). Pour débuter, commencez par la portée projet.
Écrire le frontmatter YAML
Le minimum viable : name, description (avec « À utiliser quand… »), model (commencez par haiku), tools (listez uniquement ce dont l'agent a besoin), disallowedTools (bloquez Edit et Write pour les agents de lecture/audit).
Rédiger le prompt système
Le corps du fichier est le prompt système de votre agent. Soyez précis sur : (a) le format de sortie attendu (sections, nombre max de points), (b) ce que l'agent NE doit PAS faire, (c) les fichiers ou patterns à cibler en priorité.
Tester en invocation manuelle d'abord
Demandez explicitement à Claude de « déléguer à l'agent X ». Vérifiez que le rapport est au bon format et que l'agent n'a pas modifié de fichiers inattendus. Affinez le prompt système avant de passer à la délégation automatique.
Affiner la description pour la délégation automatique
Une fois le comportement validé manuellement, reformulez la description avec des déclencheurs précis. Testez en demandant naturellement la tâche sans mentionner l'agent — Claude doit déléguer automatiquement.
Workflows par profil : qui bénéficie de quoi
Les sous-agents ne s'improvisent pas de la même façon selon votre contexte. Voici les patterns documentés en production, selon Sathish Raju (Medium) et Michael Hofer (LinkedIn Pulse, août 2025).
Équipe DevOps / sécurité
Développeur fullstack
Data engineer
Équipe produit sur un monorepo
La parallélisation — via background: true — apporte un gain mesurable surtout pour des tâches réellement indépendantes : recherches multi-domaines, audits de sécurité sur plusieurs modules. Depuis la v2.1.219, les sous-agents peuvent eux-mêmes spawner des sous-agents jusqu'à une profondeur de 3. La limite en production est de 20 sous-agents concurrents (cap par défaut CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, v2.1.217) et de 15 agents par workflow dynamique (workflowSizeGuideline).
Pour comprendre comment structurer ces workflows dans un projet complet, notre article sur la sécurité et les bonnes pratiques Claude Code couvre les règles de permission et les risques d'escalade à éviter. Pour structurer votre apprentissage Claude Code de façon progressive — des premiers pas jusqu'aux architectures multi-agents — notre guide de formation détaille les prérequis et la montée en compétence recommandée.
Quand NE PAS utiliser un sous-agent
C'est la section que les tutoriels omettent — et qui est pourtant la plus utile pour éviter les erreurs coûteuses. Les sous-agents sous-performent systématiquement pour le codage direct : chaque invocation repart de zéro sans connaissance des décisions prises dans la session principale.
Selon la documentation officielle Anthropic, un système multi-agents consomme 4 à 7 fois plus de tokens qu'une session standard pour les sous-agents classiques — l'isolation du contexte devient un handicap quand la tâche requiert la continuité des décisions d'architecture.
L'alternative à considérer pour les tâches de codage complexe avec isolation maximale : plusieurs sessions Claude avec des git worktrees distincts. Chaque session dispose d'un contexte plein sur sa branche, sans la multiplication du coût en tokens propre aux architectures multi-agents.
💡 Bon à savoir : Selon Michael Hofer (LinkedIn Pulse, août 2025), les tâches de recherche et d'exploration bénéficient d'un gain de +90 % de performance avec les sous-agents par rapport à une session standard — tandis que les tâches de codage complexe avec dépendances croisées dégradent les résultats. Le bon outil dépend entièrement de la nature de la tâche.
Sources et références
- Créer des sous-agents personnalisés — Documentation officielle Claude Code (2026) — Architecture, champs YAML, sous-agents natifs
- Pricing — Anthropic (2026) — Tarifs API Claude Haiku 4.5, Sonnet 5, Opus 5
- Best practices for Claude Code — Anthropic (2026) — Skills vs Sub-agents vs MCP, règles de décision
- Claude Code Updates v2.1.219 — releasebot.io (juillet 2026) — Sous-agents imbriqués profondeur 3, workflowSizeGuideline
- Compare Skills vs Subagents vs MCP Servers — systemprompt.io (mars 2026) — Tableau de décision, architecture en couches, suivi usage tokens Opus (auto-déclaration équipe)
- Claude Code : subagents pour isoler le contexte — Stéphane Robert (mise à jour juillet 2026) — Patterns de description, erreurs fréquentes
- Understanding Claude Code Sub-Agents: When NOT to Use Them — Michael Hofer, LinkedIn Pulse (août 2025) — Benchmarks recherche +90 %, limite 20 concurrents
- Claude Code Subagents: The Complete Guide — Sathish Raju, Medium (avril 2026) — Workflows métiers, permissionMode, maxTurns
FAQ
Qu'est-ce qu'un sub agent Claude Code ?
Un sous-agent Claude Code est une instance Claude isolée et spécialisée, disposant de sa propre fenêtre de contexte, de son propre prompt système, d'un ensemble d'outils scopés et d'un modèle IA dédié (Haiku, Sonnet ou Opus). La session principale lui délègue une tâche ; il l'exécute sans polluer le contexte existant et retourne uniquement son rapport final. Techniquement, c'est un fichier Markdown avec frontmatter YAML dans .claude/agents/<nom>.md.
Quelle différence entre un sous-agent et un skill Claude Code ?
Un skill est un fichier Markdown injecté comme instructions supplémentaires dans la session courante — sans contexte isolé, sans modèle dédié, sans outils scopés. C'est de la connaissance réutilisable (conventions, standards). Un sous-agent est une instance Claude séparée avec une fenêtre de contexte fraîche et une configuration propre. Règle simple : skill = quelles instructions suivre ; sous-agent = qui fait le travail dans une session dédiée.
Comment forcer la délégation automatique vers un sous-agent ?
La description dans le frontmatter YAML est le seul déclencheur de la délégation automatique. Claude analyse ce champ pour décider de déléguer. La formule qui fonctionne : commencer par « À utiliser quand… » suivi de deux ou trois cas concrets. Exemple : « À utiliser quand on demande une revue de sécurité, un audit de vulnérabilités ou une analyse des zones d'entrée utilisateur. » Une description générique comme « helps with code review » ne déclenche jamais de délégation fiable.
Quel modèle choisir pour un sous-agent : Haiku, Sonnet ou Opus ?
Haiku 4.5 (1 $/MTok input) pour les tâches de lecture, d'audit et de documentation de routine. Sonnet 5 (2 $/MTok, tarif introductif jusqu'au 31/08/2026) pour le refactoring ciblé, les tests et les analyses qui nécessitent du raisonnement. Opus 5 (5 $/MTok) uniquement pour les décisions d'architecture critique ou les revues de sécurité à enjeu élevé. En production, l'équipe de systemprompt.io a constaté sur leur usage interne que 60 % des tokens facturés en Opus auraient pu passer en Haiku sans perte de qualité perceptible — commencez par Haiku et montez si nécessaire.
Peut-on partager des sous-agents entre développeurs d'une même équipe ?
Oui — c'est exactement la valeur des agents projet. Les fichiers dans .claude/agents/ (portée projet) se versionent dans le repo git et sont disponibles pour tous les développeurs qui clonent le projet. Les agents dans ~/.claude/agents/ (portée utilisateur) sont personnels et portables entre vos projets. La convention recommandée : les sous-agents partagés doivent avoir une description actionnable, un tools au minimum nécessaire, et un format de sortie imposé dans le prompt système.
Les sous-agents peuvent-ils créer d'autres sous-agents ?
Depuis la version 2.1.219 de Claude Code (juillet 2026), oui — les sous-agents imbriqués jusqu'à une profondeur de 3 sont supportés. La variable d'environnement CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 permet de désactiver cette fonctionnalité. La limite par défaut est de 15 agents par workflow dynamique (workflowSizeGuideline) et 20 sous-agents concurrents en parallèle (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, v2.1.217).
Quelle est la différence entre sub agent et MCP dans Claude Code ?
Un serveur MCP (Model Context Protocol) définit quels outils Claude peut utiliser — c'est un pont vers des données ou actions externes (base de données, API, filesystem). Un sous-agent définit qui fait le travail — c'est une instance Claude avec sa propre configuration. Les deux sont complémentaires : un sous-agent peut utiliser des serveurs MCP pour accéder à des données externes, tandis qu'un MCP ne peut pas lui-même invoquer un sous-agent.
Conclusion : la discipline qui fait la différence
Les sub agents Claude Code ne sont pas une fonctionnalité avancée réservée aux experts — c'est une réponse architecturale à un problème que tout développeur qui utilise Claude Code plus de 2 heures par jour rencontre. La barrière n'est pas technique : un fichier Markdown avec 6 champs YAML suffit. La barrière est de discipline : écrire une description actionnable, choisir le bon modèle, restreindre les outils, imposer un format de sortie.
Selon l'INSEE (enquête TIC 2025, publiée juillet 2026), 18 % des entreprises françaises utilisent l'IA — trois fois plus qu'en 2023. Le marché des outils agentiques comme Claude Code est en train de passer du stade « early adopters » au stade « mainstream ». La formation aux workflows agentiques structurés — orchestration, gestion du contexte, optimisation des coûts — devient une compétence différenciante concrète.
The Intelligence Academy propose une formation Claude Code dédiée aux workflows agentiques — sous-agents, MCP, orchestration — ainsi qu'une formation Code with AI plus complète couvrant l'ensemble de l'outillage IA pour développeurs. Les deux sont finançables CPF, animées par des praticiens qui utilisent ces outils en production.