Les équipes d’agents nécessitent Claude Code v2.1.32 ou ultérieur. Vérifiez votre version avec
claude --version.- Quand utiliser les équipes d’agents, y compris les meilleurs cas d’usage et comment ils se comparent aux subagents
- Démarrer une équipe
- Contrôler les coéquipiers, y compris les modes d’affichage, l’assignation de tâches et la délégation
- Meilleures pratiques pour le travail parallèle
Quand utiliser les équipes d’agents
Les équipes d’agents sont les plus efficaces pour les tâches où l’exploration parallèle ajoute une réelle valeur. Consultez les exemples de cas d’usage pour des scénarios complets. Les cas d’usage les plus solides sont :- Recherche et examen : plusieurs coéquipiers peuvent enquêter sur différents aspects d’un problème simultanément, puis partager et contester les conclusions les uns des autres
- Nouveaux modules ou fonctionnalités : les coéquipiers peuvent chacun posséder une partie distincte sans se marcher dessus
- Débogage avec hypothèses concurrentes : les coéquipiers testent différentes théories en parallèle et convergent vers la réponse plus rapidement
- Coordination inter-couches : les modifications qui s’étendent sur le frontend, le backend et les tests, chacun possédé par un coéquipier différent
Comparer avec les subagents
Les équipes d’agents et les subagents vous permettent tous deux de paralléliser le travail, mais ils fonctionnent différemment. Choisissez en fonction de la nécessité pour vos travailleurs de communiquer les uns avec les autres :
| Subagents | Équipes d’agents | |
|---|---|---|
| Contexte | Fenêtre de contexte propre ; les résultats reviennent à l’appelant | Fenêtre de contexte propre ; complètement indépendant |
| Communication | Rendre compte uniquement à l’agent principal | Les coéquipiers se messagent directement |
| Coordination | L’agent principal gère tout le travail | Liste de tâches partagée avec auto-coordination |
| Meilleur pour | Les tâches ciblées où seul le résultat compte | Le travail complexe nécessitant discussion et collaboration |
| Coût en tokens | Inférieur : les résultats sont résumés au contexte principal | Supérieur : chaque coéquipier est une instance Claude distincte |
Activer les équipes d’agents
Les équipes d’agents sont désactivées par défaut. Activez-les en définissant la variable d’environnementCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS sur 1, soit dans votre environnement shell, soit via settings.json :
settings.json
Démarrer votre première équipe d’agents
Après avoir activé les équipes d’agents, demandez à Claude de créer une équipe d’agents et décrivez la tâche et la structure d’équipe que vous souhaitez en langage naturel. Claude crée l’équipe, génère les coéquipiers et coordonne le travail en fonction de votre prompt. Cet exemple fonctionne bien car les trois rôles sont indépendants et peuvent explorer le problème sans attendre les uns les autres :Contrôler votre équipe d’agents
Dites au chef ce que vous voulez en langage naturel. Il gère la coordination d’équipe, l’assignation de tâches et la délégation en fonction de vos instructions.Choisir un mode d’affichage
Les équipes d’agents supportent deux modes d’affichage :- In-process : tous les coéquipiers s’exécutent dans votre terminal principal. Utilisez Maj+Bas pour parcourir les coéquipiers et tapez pour leur envoyer un message directement. Fonctionne dans n’importe quel terminal, aucune configuration supplémentaire requise.
- Volets divisés : chaque coéquipier obtient son propre volet. Vous pouvez voir la sortie de tout le monde à la fois et cliquer dans un volet pour interagir directement. Nécessite tmux ou iTerm2.
tmux a des limitations connues sur certains systèmes d’exploitation et fonctionne traditionnellement mieux sur macOS. L’utilisation de tmux -CC dans iTerm2 est le point d’entrée suggéré dans tmux."auto", qui utilise les volets divisés si vous êtes déjà en train de s’exécuter dans une session tmux, et in-process sinon. Le paramètre "tmux" active le mode volets divisés et détecte automatiquement s’il faut utiliser tmux ou iTerm2 en fonction de votre terminal. Pour remplacer, définissez teammateMode dans votre settings.json :
it2. Pour installer manuellement :
- tmux : installez via le gestionnaire de paquets de votre système. Consultez le wiki tmux pour les instructions spécifiques à la plateforme.
- iTerm2 : installez le CLI
it2, puis activez l’API Python dans iTerm2 → Paramètres → Général → Magie → Activer l’API Python.
Spécifier les coéquipiers et les modèles
Claude décide du nombre de coéquipiers à générer en fonction de votre tâche, ou vous pouvez spécifier exactement ce que vous voulez :Exiger l’approbation du plan pour les coéquipiers
Pour les tâches complexes ou risquées, vous pouvez exiger que les coéquipiers planifient avant de mettre en œuvre. Le coéquipier travaille en mode plan en lecture seule jusqu’à ce que le chef approuve son approche :Parler directement aux coéquipiers
Chaque coéquipier est une session Claude Code complète et indépendante. Vous pouvez envoyer un message à n’importe quel coéquipier directement pour donner des instructions supplémentaires, poser des questions de suivi ou rediriger son approche.- Mode in-process : utilisez Maj+Bas pour parcourir les coéquipiers, puis tapez pour leur envoyer un message. Appuyez sur Entrée pour afficher la session d’un coéquipier, puis Échap pour interrompre son tour actuel. Appuyez sur Ctrl+T pour basculer la liste des tâches.
- Mode volets divisés : cliquez dans le volet d’un coéquipier pour interagir directement avec sa session. Chaque coéquipier a une vue complète de son propre terminal.
Assigner et revendiquer des tâches
La liste de tâches partagée coordonne le travail dans l’équipe. Le chef crée des tâches et les coéquipiers les accomplissent. Les tâches ont trois états : en attente, en cours et terminées. Les tâches peuvent également dépendre d’autres tâches : une tâche en attente avec des dépendances non résolues ne peut pas être revendiquée jusqu’à ce que ces dépendances soient complétées. Le chef peut assigner des tâches explicitement, ou les coéquipiers peuvent les revendiquer eux-mêmes :- Le chef assigne : dites au chef quelle tâche donner à quel coéquipier
- Auto-revendication : après avoir terminé une tâche, un coéquipier choisit la prochaine tâche non assignée et non bloquée de sa propre initiative
Arrêter les coéquipiers
Pour terminer gracieusement la session d’un coéquipier :Nettoyer l’équipe
Lorsque vous avez terminé, demandez au chef de nettoyer :Appliquer des portes de qualité avec des hooks
Utilisez les hooks pour appliquer des règles lorsque les coéquipiers terminent le travail ou que les tâches se complètent :TeammateIdle: s’exécute lorsqu’un coéquipier est sur le point de devenir inactif. Quittez avec le code 2 pour envoyer des commentaires et garder le coéquipier au travail.TaskCompleted: s’exécute lorsqu’une tâche est marquée comme complète. Quittez avec le code 2 pour empêcher la complétion et envoyer des commentaires.
Comment fonctionnent les équipes d’agents
Cette section couvre l’architecture et la mécanique derrière les équipes d’agents. Si vous souhaitez commencer à les utiliser, consultez Contrôler votre équipe d’agents ci-dessus.Comment Claude démarre les équipes d’agents
Il y a deux façons de démarrer les équipes d’agents :- Vous demandez une équipe : donnez à Claude une tâche qui bénéficie du travail parallèle et demandez explicitement une équipe d’agents. Claude en crée une en fonction de vos instructions.
- Claude propose une équipe : si Claude détermine que votre tâche bénéficierait du travail parallèle, il peut suggérer de créer une équipe. Vous confirmez avant qu’il ne procède.
Architecture
Une équipe d’agents se compose de :| Composant | Rôle |
|---|---|
| Chef d’équipe | La session Claude Code principale qui crée l’équipe, génère les coéquipiers et coordonne le travail |
| Coéquipiers | Des instances Claude Code distinctes qui travaillent chacune sur des tâches assignées |
| Liste de tâches | Liste partagée d’éléments de travail que les coéquipiers revendiquent et complètent |
| Boîte aux lettres | Système de messagerie pour la communication entre agents |
- Configuration d’équipe :
~/.claude/teams/{team-name}/config.json - Liste de tâches :
~/.claude/tasks/{team-name}/
members avec le nom de chaque coéquipier, l’ID d’agent et le type d’agent. Les coéquipiers peuvent lire ce fichier pour découvrir les autres membres de l’équipe.
Permissions
Les coéquipiers commencent avec les paramètres de permission du chef. Si le chef s’exécute avec--dangerously-skip-permissions, tous les coéquipiers le font aussi. Après la génération, vous pouvez modifier les modes de coéquipiers individuels, mais vous ne pouvez pas définir les modes par coéquipier au moment de la génération.
Contexte et communication
Chaque coéquipier a sa propre fenêtre de contexte. Lorsqu’il est généré, un coéquipier charge le même contexte de projet qu’une session régulière : CLAUDE.md, MCP servers et skills. Il reçoit également le prompt de génération du chef. L’historique de conversation du chef ne se transporte pas. Comment les coéquipiers partagent les informations :- Livraison automatique de messages : lorsque les coéquipiers envoient des messages, ils sont livrés automatiquement aux destinataires. Le chef n’a pas besoin d’interroger les mises à jour.
- Notifications d’inactivité : lorsqu’un coéquipier termine et s’arrête, il notifie automatiquement le chef.
- Liste de tâches partagée : tous les agents peuvent voir l’état des tâches et revendiquer le travail disponible.
- message : envoyer un message à un coéquipier spécifique
- broadcast : envoyer à tous les coéquipiers simultanément. À utiliser avec parcimonie, car les coûts augmentent avec la taille de l’équipe.
Utilisation des tokens
Les équipes d’agents utilisent considérablement plus de tokens qu’une seule session. Chaque coéquipier a sa propre fenêtre de contexte, et l’utilisation des tokens augmente avec le nombre de coéquipiers actifs. Pour la recherche, l’examen et le travail sur les nouvelles fonctionnalités, les tokens supplémentaires en valent généralement la peine. Pour les tâches de routine, une seule session est plus rentable. Consultez les coûts des tokens des équipes d’agents pour les conseils d’utilisation.Exemples de cas d’usage
Ces exemples montrent comment les équipes d’agents gèrent les tâches où l’exploration parallèle ajoute de la valeur.Exécuter un examen de code parallèle
Un seul examinateur tend à graviter vers un type de problème à la fois. Diviser les critères d’examen en domaines indépendants signifie que la sécurité, l’impact sur les performances et la couverture de test reçoivent tous une attention approfondie simultanément. Le prompt assigne à chaque coéquipier une lentille distincte pour qu’ils ne se chevauchent pas :Enquêter avec des hypothèses concurrentes
Lorsque la cause première est peu claire, un seul agent tend à trouver une explication plausible et s’arrête. Le prompt combat cela en rendant les coéquipiers explicitement adversaires : le travail de chacun n’est pas seulement d’enquêter sur sa propre théorie mais de contester les autres.Meilleures pratiques
Donner aux coéquipiers suffisamment de contexte
Les coéquipiers chargent automatiquement le contexte du projet, y compris CLAUDE.md, MCP servers et skills, mais ils n’héritent pas de l’historique de conversation du chef. Consultez Contexte et communication pour les détails. Incluez les détails spécifiques à la tâche dans le prompt de génération :Choisir une taille d’équipe appropriée
Il n’y a pas de limite stricte au nombre de coéquipiers, mais des contraintes pratiques s’appliquent :- Les coûts des tokens augmentent linéairement : chaque coéquipier a sa propre fenêtre de contexte et consomme des tokens indépendamment. Consultez les coûts des tokens des équipes d’agents pour les détails.
- La surcharge de coordination augmente : plus de coéquipiers signifie plus de communication, de coordination de tâches et de risques de conflits
- Rendements décroissants : au-delà d’un certain point, les coéquipiers supplémentaires n’accélèrent pas le travail proportionnellement
Dimensionner les tâches de manière appropriée
- Trop petites : la surcharge de coordination dépasse le bénéfice
- Trop grandes : les coéquipiers travaillent trop longtemps sans points de contrôle, augmentant le risque d’effort gaspillé
- Juste bien : des unités autonomes qui produisent un livrable clair, comme une fonction, un fichier de test ou un examen
Attendre que les coéquipiers terminent
Parfois, le chef commence à mettre en œuvre des tâches lui-même au lieu d’attendre les coéquipiers. Si vous remarquez cela :Commencer par la recherche et l’examen
Si vous êtes nouveau aux équipes d’agents, commencez par des tâches qui ont des limites claires et ne nécessitent pas d’écrire du code : examiner une PR, rechercher une bibliothèque ou enquêter sur un bug. Ces tâches montrent la valeur de l’exploration parallèle sans les défis de coordination qui accompagnent la mise en œuvre parallèle.Éviter les conflits de fichiers
Deux coéquipiers éditant le même fichier entraîne des écrasements. Divisez le travail pour que chaque coéquipier possède un ensemble de fichiers différent.Surveiller et diriger
Vérifiez la progression des coéquipiers, redirigez les approches qui ne fonctionnent pas et synthétisez les conclusions au fur et à mesure qu’elles arrivent. Laisser une équipe s’exécuter sans surveillance pendant trop longtemps augmente le risque d’effort gaspillé.Dépannage
Les coéquipiers n’apparaissent pas
Si les coéquipiers n’apparaissent pas après avoir demandé à Claude de créer une équipe :- En mode in-process, les coéquipiers peuvent déjà être en cours d’exécution mais non visibles. Appuyez sur Maj+Bas pour parcourir les coéquipiers actifs.
- Vérifiez que la tâche que vous avez donnée à Claude était suffisamment complexe pour justifier une équipe. Claude décide s’il faut générer des coéquipiers en fonction de la tâche.
- Si vous avez explicitement demandé des volets divisés, assurez-vous que tmux est installé et disponible dans votre PATH :
- Pour iTerm2, vérifiez que le CLI
it2est installé et que l’API Python est activée dans les préférences d’iTerm2.
Trop de demandes de permission
Les demandes de permission des coéquipiers remontent au chef, ce qui peut créer des frictions. Pré-approuvez les opérations courantes dans vos paramètres de permission avant de générer les coéquipiers pour réduire les interruptions.Les coéquipiers s’arrêtent sur les erreurs
Les coéquipiers peuvent s’arrêter après avoir rencontré des erreurs au lieu de se rétablir. Vérifiez leur sortie en utilisant Maj+Bas en mode in-process ou en cliquant sur le volet en mode divisé, puis :- Donnez-leur des instructions supplémentaires directement
- Générez un coéquipier de remplacement pour continuer le travail
Le chef s’arrête avant que le travail ne soit terminé
Le chef peut décider que l’équipe est terminée avant que toutes les tâches ne soient réellement complètes. Si cela se produit, dites-lui de continuer. Vous pouvez également dire au chef d’attendre que les coéquipiers terminent avant de procéder s’il commence à faire du travail au lieu de déléguer.Sessions tmux orphelines
Si une session tmux persiste après la fin de l’équipe, elle peut ne pas avoir été complètement nettoyée. Listez les sessions et tuez celle créée par l’équipe :Limitations
Les équipes d’agents sont expérimentales. Les limitations actuelles à connaître :- Pas de reprise de session avec les coéquipiers in-process :
/resumeet/rewindne restaurent pas les coéquipiers in-process. Après la reprise d’une session, le chef peut tenter de envoyer un message aux coéquipiers qui n’existent plus. Si cela se produit, dites au chef de générer de nouveaux coéquipiers. - L’état des tâches peut être en retard : les coéquipiers échouent parfois à marquer les tâches comme complètes, ce qui bloque les tâches dépendantes. Si une tâche semble bloquée, vérifiez si le travail est réellement terminé et mettez à jour l’état de la tâche manuellement ou dites au chef de pousser le coéquipier.
- L’arrêt peut être lent : les coéquipiers terminent leur demande actuelle ou appel d’outil avant de s’arrêter, ce qui peut prendre du temps.
- Une équipe par session : un chef ne peut gérer qu’une seule équipe à la fois. Nettoyez l’équipe actuelle avant de démarrer une nouvelle.
- Pas d’équipes imbriquées : les coéquipiers ne peuvent pas générer leurs propres équipes ou coéquipiers. Seul le chef peut gérer l’équipe.
- Le chef est fixe : la session qui crée l’équipe est le chef pour sa durée de vie. Vous ne pouvez pas promouvoir un coéquipier en chef ou transférer le leadership.
- Permissions définies au moment de la génération : tous les coéquipiers commencent avec le mode de permission du chef. Vous pouvez modifier les modes de coéquipiers individuels après la génération, mais vous ne pouvez pas définir les modes par coéquipier au moment de la génération.
- Les volets divisés nécessitent tmux ou iTerm2 : le mode in-process par défaut fonctionne dans n’importe quel terminal. Le mode volets divisés n’est pas supporté dans le terminal intégré de VS Code, Windows Terminal ou Ghostty.
Prochaines étapes
Explorez les approches connexes pour le travail parallèle et la délégation :- Délégation légère : les subagents génèrent des agents auxiliaires pour la recherche ou la vérification au sein de votre session, mieux pour les tâches qui n’ont pas besoin de coordination inter-agents
- Sessions parallèles manuelles : les Git worktrees vous permettent d’exécuter plusieurs sessions Claude Code vous-même sans coordination d’équipe automatisée
- Comparer les approches : consultez la comparaison subagent vs équipe d’agents pour une répartition côte à côte
