Agent Teams vs sous-agents : la différence concrète
Les sous-agents travaillent indépendamment et renvoient leur résultat à l'agent principal une fois terminés. Ils ne se parlent pas entre eux. L'agent principal attend, compile, et passe à la suite.
Les Agent Teams fonctionnent différemment. L'agent principal crée une équipe avec un chef de projet et plusieurs agents spécialisés. Ces agents partagent une liste de tâches commune et peuvent communiquer directement entre eux, sans passer par l'agent principal. Un agent peut envoyer son travail à un autre, demander une révision, ou signaler un blocage.
C'est cette communication directe qui rend les Agent Teams utiles sur des projets complexes. Un développeur front-end qui attend une réponse de l'API back-end peut simplement la demander à l'agent back-end, en temps réel. L'agent QA peut renvoyer du travail aux deux autres s'il trouve des problèmes. Le cycle continue jusqu'à ce que le résultat soit satisfaisant.
En pratique, cette architecture reproduit le fonctionnement d'une vraie équipe de développement : chaque membre a sa spécialité, communique avec les autres quand il a besoin d'une information, et soumet son travail à la relecture avant validation finale. C'est le pattern multi-agent appliqué directement dans votre terminal.
Comment activer les Agent Teams
Les Agent Teams sont désactivées par défaut dans Claude Code car c'est une fonctionnalité expérimentale. Pour les activer, vous devez ajouter une variable dans le fichier settings.json de votre projet.
La façon la plus simple : allez dans la documentation officielle Claude Code sur les Agent Teams, copiez le bloc JSON fourni, et demandez à Claude Code de le placer dans les paramètres locaux de votre projet. Il crée automatiquement le dossier .claude avec un fichier settings.local.json contenant la configuration.
Avant de commencer à construire, une étape utile : donnez à Claude Code l'URL de la documentation officielle sur les Agent Teams et demandez-lui de créer un fichier de référence en Markdown dans un dossier docs. Il lira la documentation, la stockera localement, et pourra s'y référer pendant qu'il construit vos agents sans avoir à la recharger à chaque fois.
Comment promter une Agent Team efficacement
Le format de prompt qui fonctionne bien suit ce schéma : d'abord un objectif global, ensuite la définition de l'équipe, et enfin les livrables attendus.
L'objectif global est important parce que les agents démarrent sans contexte. Ils reçoivent uniquement ce que la session principale leur envoie. Si vous leur expliquez ce vers quoi l'équipe entière travaille, ils comprennent mieux leur rôle et pourquoi ils ont des coéquipiers.
Exemple de structure :
- Objectif : construire une application full stack avec une API REST et un front React, testée et fonctionnelle sur localhost
- Équipe : créer une équipe de 3 agents avec Sonnet. Le premier est développeur back-end, il fait ceci. Le deuxième est développeur front-end, il fait cela. Le troisième est un agent QA, il vérifie tout une fois que les deux premiers ont terminé et renvoie le travail si nécessaire.
- Livrables : une application qui tourne, un rapport de tests, un document récapitulant ce qui a été construit et comment le faire tourner
Dans les descriptions de chaque agent, précisez explicitement à qui il doit envoyer son travail une fois terminé. Ne supposez pas que les agents devineront. "Quand tu as fini, envoie ton résultat au développeur front-end" est bien plus efficace que de laisser cette coordination implicite.
Ce qu'il faut éviter
- Des agents qui partagent les mêmes fichiers : ils risquent d'écraser le travail les uns des autres
- Des livrables flous : définissez exactement ce que vous attendez en sortie
- Des équipes de plus de 5 agents : chaque agent supplémentaire multiplie le coût et la complexité
- L'absence de contexte initial : rappelez-vous, les agents démarrent sans historique
Ce que les agents savent dès le départ
Les agents héritent des permissions de la session principale. Si vous avez activé le mode bypass ou autorisé certaines commandes bash, tous les agents de l'équipe bénéficient des mêmes droits automatiquement.
Ils ont également accès à tous vos fichiers de projet, à vos serveurs MCP configurés et à vos Claude Skills. Vous n'avez pas besoin de reconfigurer quoi que ce soit pour chaque agent.
Ce qu'ils n'ont pas, en revanche, c'est l'historique de la conversation. Ils commencent à zéro à chaque fois, ce qui est exactement pourquoi le contexte initial dans votre prompt est si important.
Le mode approbation de plan
Vous pouvez activer un mode où chaque agent doit soumettre son plan avant d'exécuter quoi que ce soit. L'agent principal valide le plan, et seulement après, l'agent passe à l'action. Vous pouvez aussi vous mettre vous-même comme validateur si vous voulez garder la main sur chaque étape, mais dans la plupart des cas, laisser l'agent principal gérer ça est plus fluide.
Voir les agents travailler avec tmux
Depuis l'extension VS Code, vous voyez les mises à jour de l'agent principal mais pas ce que font les autres agents en temps réel. Si vous voulez une visibilité complète, lancez Claude Code depuis un terminal avec tmux.
Avec tmux, chaque agent apparaît dans son propre panneau avec une couleur distincte. Vous voyez ce que chacun pense et fait en temps réel. Vous pouvez aussi envoyer des messages directement à un agent spécifique sans passer par l'agent principal, approuver des actions ou lui donner des informations supplémentaires.
Sur Windows, il faut passer par une configuration spécifique pour utiliser tmux, mais Claude Code peut vous guider pas à pas dans la mise en place.
Cette visibilité en temps réel est particulièrement utile pour le débogage. Si un agent prend une mauvaise direction ou tourne en boucle, vous le repérez immédiatement et pouvez intervenir avant qu'il ne consomme trop de tokens inutilement.
Les trois règles de base
Chaque agent a son propre territoire. Attribuez des fichiers distincts à chaque agent. Ils peuvent s'envoyer des résultats, mais chacun travaille sur ses propres fichiers. Si deux agents modifient le même fichier, l'un écrasera le travail de l'autre.
Les agents se parlent directement. Ils n'ont pas besoin de passer par l'agent principal pour communiquer. Un agent peut envoyer un message à un autre via l'outil send_message. C'est cette communication directe qui crée les boucles de révision utiles, comme un agent QA qui renvoie du travail aux développeurs.
Ils travaillent en parallèle, pas en séquence. Si votre processus est linéaire (étape 1 puis étape 2 puis étape 3 sans interaction entre les étapes), les Agent Teams ne sont probablement pas le bon outil. Elles sont faites pour des tâches qui se déroulent simultanément et qui ont besoin de se coordonner en cours de route.
Erreurs fréquentes et correctifs
Les agents s'arrêtent constamment pour demander des permissions. Autorisez les commandes dont ils ont besoin dans les paramètres de votre projet. Ça évite les interruptions à répétition.
Les livrables ne sont pas cohérents entre eux. Vérifiez que les agents n'écrivent pas dans les mêmes fichiers. Attribuez un propriétaire à chaque fichier.
Un agent ne fait rien. Vous avez probablement oublié de lui assigner une tâche ou une dépendance explicite dans votre prompt. Chaque agent doit avoir quelque chose à faire et savoir quand commencer.
Le coût explose. Réduisez le nombre d'agents. Trois agents bien ciblés donnent souvent de meilleurs résultats que six agents dont la moitié se retrouve à attendre.
Des agents perdent du travail en cours de session. Dites-leur de stocker leurs résultats intermédiaires dans des fichiers temporaires qu'ils peuvent relire si besoin.
Quand utiliser une Agent Team, quand s'en passer
Utiliser une Agent Team si :
- Votre projet couvre plusieurs domaines distincts (front, back, tests, documentation)
- Ces parties peuvent avancer en parallèle
- Les agents ont besoin de se transmettre du travail et de réagir les uns aux autres
- Vous avez besoin d'un niveau de qualité élevé avec plusieurs cycles de révision
Utiliser des sous-agents à la place si :
- Votre processus est séquentiel et chaque étape dépend de la précédente
- Vous avez besoin d'un seul historique de conversation ou d'un seul contexte
- Tous les agents travailleraient sur les mêmes fichiers
- La tâche est simple et ne justifie pas le coût supplémentaire
Une Agent Team avec 3 agents coûte environ 3 fois plus qu'une session simple. Avec 5 agents, c'est 5 fois plus. Ce n'est pas une raison de les éviter, mais c'est une raison de ne les utiliser que quand la complexité du projet le justifie vraiment.
Arrêter proprement une Agent Team
Quand l'agent principal envoie une demande d'arrêt aux agents, ceux-ci ne s'éteignent pas immédiatement. Ils peuvent signaler qu'ils ont encore du travail à terminer et demander plus de temps. Ce n'est qu'une fois qu'ils confirment qu'ils sont prêts que la session se ferme proprement.
Ne forcez pas l'arrêt. Si vous coupez une session avant que les agents aient sauvegardé leur travail, vous risquez de perdre des fichiers ou de laisser le projet dans un état instable. Attendez la confirmation de chaque agent avant de fermer.
Si un agent semble bloqué pendant l'arrêt, vous pouvez lui envoyer un message directement via tmux pour lui demander de terminer sa tâche en cours et de sauvegarder. Dans la plupart des cas, l'arrêt complet prend moins d'une minute.
Les Agent Teams de Claude Code sont une des fonctionnalités les plus puissantes disponibles aujourd'hui pour automatiser des projets complexes. Elles sont plus coûteuses et plus lentes qu'une session simple, mais elles produisent un niveau de qualité et de coordination difficile à atteindre autrement. Trois à cinq agents bien configurés, avec des territoires clairs et des objectifs précis, suffisent dans la grande majorité des cas.
