Sous-agents Claude Code : Quand et Comment faire fonctionner des équipes d'agents

Dernière mise à jour : June 28, 2026

Un subagent Claude Code est une session Claude séparée que l'agent principal lance pour un travail ciblé, puis intègre le résultat dans votre travail. J'en ai déployé trois en parallèle la semaine dernière pour diviser un refactoring en schéma, API et tests, et ils ont terminé avant qu'une seule longue session n'ait fini de planifier. Cet article explique comment définir et déployer des subagents, les modèles d'orchestration que j'utilise pour simuler une petite équipe, et la ligne honnête où les subagents coûtent plus qu'ils ne font économiser.

Réponse rapide : qu'est-ce qu'un subagent Claude Code ?

Un subagent est une instance Claude avec sa propre fenêtre de contexte, son propre prompt système et un ensemble d'outils restreint. La session principale ne perd pas de contexte lorsqu'elle en exécute un, car le subagent travaille en isolation et ne retourne que un résumé. Considérez cela comme déléguer une tâche à un coéquipier qui n'interrompt jamais votre écran.

Le mécanisme officiel est simple. Vous déposez un fichier markdown dans .claude/agents/ avec un frontmatter YAML, et Claude Code peut l'appeler via l'outil Task lorsqu'une tâche correspond à sa description. La documentation des sub-agents est la source de vérité pour les champs, et le dépôt Claude Code suit les modifications du format.

Une définition minimale de subagent ressemble à ceci :

---
name: migration-writer
description: Writes and runs database migrations for this repo. Use for schema changes.
tools: Read, Edit, Bash
model: inherit
---
You are a migration specialist. Always check existing migrations first, never drop columns without a confirmation step, and run the migration against the local DB before reporting done.

Une fois ce fichier existant, je demande à l'agent principal : "utilise le subagent migration-writer pour ajouter la table orders" et il déploie un travailleur limité au lieu de tâtonner en ligne. La ligne model: inherit maintient le coût et la qualité au même niveau que la session principale ; fixer un modèle moins cher comme haiku sur un subagent lourd en lecture est un véritable levier lorsque vous en exécutez beaucoup.

Quand devriez-vous utiliser des subagents plutôt qu'une seule session ?

Utilisez un subagent lorsqu'une tâche est longue, riche en contexte ou nécessite un ensemble d'outils que vous ne voulez pas dans la session principale. Gardez-le dans une seule session lorsque le travail est court, étroitement lié à ce que vous faites déjà, ou nécessite des allers-retours serrés avec vous.

J'utilise les subagents pour les tâches qui autrement pollueraient mon contexte principal avec des logs, de grandes lectures ou des essais et erreurs. Un audit de l'ensemble du code qui utilise grep sur 200 fichiers est un candidat parfait, car le subagent lit tout cela et renvoie un résumé de deux paragraphes pendant que ma session principale reste propre.

Si vous êtes nouveau avec l'agent lui-même, le guide ultime Claude Code couvre les fondamentaux avant d'ajouter des subagents par-dessus.

Comment déployer des subagents dans Claude Code ?

Le déploiement se fait de deux manières. L'agent principal peut invoquer l'outil Task par lui-même lorsqu'une tâche correspond à la description d'un subagent, ou vous pouvez le nommer explicitement dans votre prompt. Je préfère le nommer, car le déploiement implicite saute parfois un agent que je voulais.

Quelques modèles que j'exécute régulièrement :

• "Utilise le subagent code-reviewer sur le diff de cette branche, puis applique ses suggestions."
• "Déploie migration-writer pour ajouter une colonne users.email_verified, et déploie test-writer pour la couvrir. Exécute les deux."
• "Lance le subagent api-docs contre src/routes/ et retourne uniquement le squelette OpenAPI."

Le subagent s'exécute dans son propre contexte, il ne peut donc pas voir votre conversation en cours à moins que vous ne passiez le détail dans le prompt. Cet isolement est l'objectif. Lorsqu'il a terminé, vous obtenez un résultat, pas un flux de bruit intermédiaire.

Modèles que j'utilise pour les flux de travail de type équipe

L'astuce est de copier la manière dont une véritable équipe divise le travail, puis de mapper chaque rôle à un subagent. Voici les modèles auxquels je reviens souvent.

Recherche, puis diffusion. Je déploie un subagent pour recueillir le contexte, lis ce résumé, puis je déploie plusieurs subagents d'implémentation contre une interface partagée. Cela reflète un chef de projet qui évalue le travail avant de distribuer les tickets.

Construire selon un contrat. Définissez d'abord l'API ou les props du composant, puis exécutez un subagent backend et un subagent frontend en parallèle contre ce contrat. Aucun ne bloque l'autre, et les conflits sont rares car ils touchent à des fichiers différents.

Revoir comme un rôle séparé. Je garde un subagent code-reviewer avec uniquement des outils de lecture. Après tout changement non trivial, je l'exécute sur le diff. Restreindre ses outils signifie qu'il ne peut littéralement pas modifier, ce qui maintient la révision honnête.

Pour les flux de travail répétables comme celui-ci, associez les subagents à Claude Code skills : un skill encode les étapes, et les subagents effectuent le travail isolé. Et si un subagent a besoin de données externes, connectez-le à un serveur MCP comme décrit dans le guide d'intégration Claude Code MCP.

Exemple concret : commandes et paiements

Le mois dernier, j'ai divisé une fonctionnalité commandes plus paiements en trois subagents contre un contrat typé. Le contrat était une seule interface TypeScript pour un Order avec status, totalCents et paymentId. J'ai déployé : un subagent backend pour implémenter la création de commande et les transitions d'état ; un subagent payments pour connecter l'appel Stripe et stocker le paymentId ; et un subagent test pour couvrir le chemin heureux et le cas limite de remboursement. Les trois ont touché à des fichiers différents, donc la fusion n'a nécessité que trois opérations propres copier-coller au lieu d'une session de résolution de conflits. L'ensemble du processus a pris 14 minutes ; le même travail dans une seule session sérielle en a coûté 41 la semaine précédente, car le contexte unique continuait de recharger la documentation Stripe.

Comment orchestrer un travail parallèle sans perdre de contexte ?

La session principale est votre coordinateur. Son rôle est de diviser le travail, de distribuer des prompts limités et de réassembler les résultats. Gardez le coordinateur léger et laissez les subagents gérer les lectures lourdes.

Une exécution parallèle typique pour moi ressemble à ceci :

1. Écrire le contrat et les limites de fichiers dans la session principale.
2. Déployer deux à quatre subagents, chacun avec une tranche et une condition de succès claire.
3. Lire chaque résumé au fur et à mesure qu'il revient, pas en cours d'exécution.
4. Fusionner dans la session principale, résolvant les coutures vous-même.
5. Exécuter le subagent test en dernier sur le résultat intégré.

Le parallélisme ne paie que lorsque les tranches sont véritablement indépendantes. Si deux subagents modifient tous schema.prisma, vous n'avez pas divisé le travail, vous avez créé un problème de fusion. Tracez des frontières au niveau des fichiers et des contrats, puis appliquez-les dans le prompt.

Quand les subagents ajoutent-ils plus de surcharge qu'ils n'en font économiser ?

Les subagents ajoutent de la latence, des tokens et un coût de coordination. Le transfert du résumé fait perdre des détails, donc tout ce qui nécessite une continuité profonde est mal adapté. Soyez honnête quant au compromis avant de les utiliser.

J'ai effectué un benchmark sur une branche de fonctionnalité : un subagent par microservice contre une seule session les parcourant dans l'ordre. Pour cinq services faiblement couplés, le parallèle a gagné environ 40 % en temps réel. Pour trois services qui partageaient un modèle de données, la session unique était plus rapide, car la fusion et la ré-explication ont absorbé les gains parallèles.

La leçon : le parallélisme récompense l'indépendance et pénalise le couplage. Si vos tranches partagent un état, ne les parallélisez pas.

Quelles sont les erreurs courantes ?

• Trop de subagents. Je limite une exécution à trois à cinq. Au-delà, le coût de coordination dépasse le gain parallèle.
• Prompts vagues. "Corriger l'auth" échoue. "Ajouter un endpoint de rafraîchissement JWT à /auth/refresh, retournant { token }, avec un test" réussit.
• Pas de critères de succès. Définissez ce que signifie terminé. "Migration appliquée localement et rollback testé" bat "gérer le schéma".
• Ensemble d'outils incorrect. Donnez à un réviseur uniquement des outils de lecture. Donnez à un agent de déploiement les commandes exactes dont il a besoin, rien de plus large.
• Ignorer les échecs. Si un subagent retourne une erreur, lisez-la. Réessayer aveuglément consomme des tokens et cache un problème réel.
• Sauter la fusion. Les subagents retournent des résultats ; vous êtes toujours propriétaire de l'intégration. Allouez du temps réel pour cela.

L'erreur la plus coûteuse est de traiter les subagents comme un parallélisme gratuit pour tout. Ce sont des travailleurs limités derrière une frontière de résumé, et cette frontière a un coût.

Résumé

Les subagents transforment Claude Code en quelque chose qui ressemble à une petite équipe : un coordinateur léger déployant des travailleurs limités qui chacun portent leur propre contexte et rapportent un résultat. Définissez-les dans .claude/agents/, déployez avec l'outil Task, et gardez votre session principale propre en poussant les lectures lourdes et les rôles répétitifs vers les subagents.

Utilisez-les lorsque le travail est long, riche en contexte ou nécessite un ensemble d'outils restreint. Évitez-les pour des tâches courtes, couplées et interactives où le transfert de résumé perd trop de détails. Tracez des frontières au niveau des fichiers et des contrats, limitez une exécution à une poignée d'agents, et budgétez toujours du temps pour fusionner les résultats vous-même.

Une vraie mise en garde : les subagents multiplient le débit, pas le jugement. Ils construiront volontiers la mauvaise chose en parallèle dans quatre contextes isolés. Le travail de coordination, la définition du contrat et la révision finale reposent toujours sur vous, donc le levier n'apparaît que lorsque les tranches sont véritablement indépendantes et que les critères de succès sont exacts. Si vous voulez un arrière-plan plus approfondi sur le protocole qui alimente beaucoup de ce câblage d'outils, le explainer MCP est une bonne lecture suivante, et la documentation Claude Code couvre des paramètres que je n'ai pas répétés ici.

Crédits images

• Une équipe de développeurs travaillant ensemble sur ordinateurs dans un bureau technologique moderne — photo par Rebrand Cities sur Pexels
• Code de programmation coloré sur un moniteur d'ordinateur — photo par inna mykytas sur Pexels
• Un développeur écrivant du code sur un ordinateur portable devant plusieurs moniteurs — photo par Christina Morillo sur Pexels
• Deux programmeurs concentrés sur le codage côte à côte dans un bureau moderne — photo par Rebrand Cities sur Pexels