Claude Code Subagents
le guide complet des agents Claude 2026

Claude Code classique fonctionne de façon séquentielle : une tâche à la fois, un seul agent avec un contexte global. Les subagents introduisent la parallélisation (plusieurs agents tournent simultanément) et la spécialisation (chaque agent a un prompt système dédié à son rôle précis).

Concrètement, sur un projet full-stack, Claude Code classique ferait d’abord le backend, puis le frontend, puis les tests — en séquence. Avec les subagents, les trois se développent en parallèle, chacun dans son périmètre défini par les permissions dans le frontmatter YAML.

La troisième différence, souvent sous-estimée, est la limitation du contexte par agent. Chaque subagent travaille sur un sous-ensemble du code, donc son contexte est plus petit et plus focalisé. Résultat : moins d’hallucinations, meilleure cohérence, moins de modifications non souhaitées hors périmètre.

Les subagents sont disponibles à partir du plan Claude Pro à environ 20 euros par mois. Vous n’avez pas besoin de Claude Max pour utiliser les subagents — cette information circule sur certains forums mais est incorrecte depuis la mise à jour de fin 2025.

En revanche, utiliser plusieurs subagents simultanément consomme plus de messages qu’une session Claude Code classique. Si vous faites des sessions longues avec 3 ou 4 subagents actifs en parallèle, vous pouvez atteindre les limites de Claude Pro plus rapidement. C’est la principale raison pour laquelle certains power users passent à Claude Max.

Pour la plupart des cas d’usage professionnels avec 2 à 3 subagents sur des sessions de 1 à 2 heures, Claude Pro est suffisant. Je recommande de tester avec Pro d’abord et de monter sur Max uniquement si vous constatez régulièrement des limitations.

Trois réflexes dans l’ordre. D’abord, vérifier le prompt système du subagent dans son fichier Markdown : dans 80% des cas, l’agent dévie parce que sa mission n’est pas assez précise ou contient des ambiguïtés. Reformulez plus directivement, en précisant explicitement ce que l’agent ne doit PAS faire.

Ensuite, vérifier les permissions dans le frontmatter YAML. Si le subagent modifie des fichiers hors périmètre, restreignez les outils autorisés et les patterns de fichiers dans la section deny. Les permissions sont la barrière technique qui empêche les dérives.

Enfin, isolez le subagent en le faisant tourner seul sur une session test avant de le réintégrer dans le workflow multi-agents. Claude Code génère des logs détaillés par agent dans .claude/logs/ — ces logs sont très utiles pour tracer exactement ce qui s’est passé lors d’une dérive.

Paradoxalement, les subagents fonctionnent encore mieux sur du legacy que sur du greenfield. Sur un projet existant, les frontières entre composants sont déjà définies par l’architecture en place. Vous configurez des subagents hyper-spécialisés qui respectent ces frontières : un pour le module auth legacy, un pour le nouveau module payments, un pour les tests.

Sur du greenfield, la flexibilité peut inverser l’effet. Les agents ont tendance à empiéter sur les périmètres voisins quand les frontières ne sont pas encore établies par l’architecture. Sans structure existante à respecter, les conflits de compétences entre agents sont plus fréquents.

Ma recommandation : les subagents sont quasi-obligatoires sur les projets legacy et monorepos complexes. Sur du greenfield, commencez en Claude Code classique pour établir l’architecture, puis introduisez les subagents une fois les frontières stables — généralement après les deux premières semaines de développement.

Claude Code fonctionne principalement en ligne de commande, mais s’intègre avec VS Code et JetBrains via des extensions officielles. Les subagents fonctionnent identiquement dans ces intégrations — les fichiers de configuration dans .claude/agents/ sont lus automatiquement quel que soit le point d’entrée.

L’intégration VS Code est particulièrement soignée : vous voyez les agents actifs dans un panneau dédié, les logs de chaque subagent s’affichent en temps réel dans des onglets séparés, et vous pouvez interrompre un subagent spécifique sans arrêter les autres. C’est le setup que j’utilise sur mes projets clients.

Pour les équipes qui utilisent d’autres éditeurs (Cursor, Windsurf, etc.), les subagents fonctionnent également via la CLI, mais sans l’interface visuelle de VS Code. Les fichiers de configuration restent les mêmes, seule l’expérience de monitoring change.

Il n’y a pas de limite technique documentée au nombre de subagents configurés dans un projet, mais en pratique, au-delà de 5 à 6 subagents actifs simultanément, la coordination devient complexe à gérer et les bénéfices de la parallélisation diminuent.

Les équipes qui ont poussé la configuration à l’extrême rapportent des problèmes de coordination au-delà de 4 agents simultanés : les agents peuvent modifier le même fichier au même moment, créant des conflits, ou attendre les livrables d’un autre agent sans signal clair de complétion.

Pour la grande majorité des projets, 3 subagents sont le sweet spot : backend, frontend, tests. C’est suffisant pour paralléliser l’essentiel du travail sans créer de complexité de coordination. Si votre projet a des modules vraiment distincts (mobile + web + API + infra), vous pouvez monter à 4 ou 5, mais documentez précisément les dépendances dans CLAUDE.md.

Les subagents ont accès au contexte global du projet (via CLAUDE.md et les fichiers partagés) mais maintiennent un contexte de conversation séparé. Ils peuvent lire les mêmes fichiers mais leurs historiques de conversation sont indépendants.

Cette architecture est délibérée : elle permet la spécialisation (chaque agent a son propre fil de pensée sur son périmètre) tout en assurant la cohérence (tous lisent le même contrat d’interface et le même CLAUDE.md). Le CLAUDE.md est le document de coordination central que tous les agents lisent en priorité.

Un point pratique important : les subagents ne se ‘parlent’ pas directement entre eux. La coordination passe par les fichiers du projet. Si le subagent backend écrit une API, le subagent frontend la découvre en lisant le code, pas via une communication directe. Concevez votre workflow en tenant compte de cette contrainte.

Le fichier CLAUDE.md est le cerveau de la coordination multi-agents. Pour un setup avec subagents, je recommande une structure en 4 sections : architecture du projet (pour que chaque agent comprenne l’ensemble), contrats d’interface (les APIs entre composants), règles de coordination (qui fait quoi, quels fichiers sont partagés) et conventions de code (pour homogénéiser le style entre agents).

La section contrats d’interface est la plus critique. Si le subagent backend sait exactement quels endpoints il doit exposer et sous quel format, et que le subagent frontend sait exactement ce qu’il peut consommer, les deux peuvent travailler en parallèle sans bloquer l’un l’autre. C’est le principe du contrat-first development appliqué aux agents IA.

Gardez le CLAUDE.md sous 500 lignes. Un fichier trop long dilue l’attention des agents et ils finissent par ignorer les sections moins importantes. Mieux vaut un contrat court et précis qu’un document exhaustif que personne ne lit vraiment.

Les subagents tels que décrits dans ce guide sont une fonctionnalité spécifique à Claude Code, l’outil CLI d’Anthropic. Ils ne sont pas directement disponibles via l’API Claude standard (/v1/messages) qui expose des appels de complétion individuels.

Vous pouvez recréer un comportement similaire via l’API en orchestrant plusieurs appels parallèles avec des system prompts différents, mais vous devez gérer vous-même la coordination, les permissions et le partage de contexte. C’est ce que font des frameworks comme LangChain ou AutoGen, qui ont leur propre implémentation du multi-agent.

Pour les développeurs qui veulent des subagents dans leurs propres applications, l’approche recommandée en 2026 est d’utiliser le protocole MCP (Model Context Protocol) d’Anthropic qui permet d’orchestrer plusieurs modèles avec des outils spécialisés. C’est plus flexible que les subagents Claude Code mais demande plus de configuration.

La mesure la plus fiable est le temps elapsed wall clock sur une même feature développée avec et sans subagents, sur des projets comparables. Dans mon expérience, le gain est de 30 à 60% sur les tâches parallélisables — features full-stack, refactoring multi-modules, migrations de stack.

Sur les tâches non-parallélisables (debugger un bug spécifique, écrire un algorithme complexe, concevoir une architecture), les subagents n’apportent pas de gain mesurable. Inutile de les invoquer sur ces cas. La valeur vient de la parallélisation, pas de la spécialisation seule.

Le meilleur indicateur à suivre dans votre équipe : le ratio de features livrées par sprint avant et après l’adoption des subagents, sur des sprints de complexité comparable. Attendez 6 à 8 sprints pour avoir des données statistiquement significatives — les 2 ou 3 premiers sprints sont perturbés par la courbe d’apprentissage de la configuration.