Orchestrer des équipes de sessions Claude Code

​

Quand utiliser les équipes d’agents

• 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

​

Activer les équipes d’agents

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

​

Démarrer votre première équipe d’agents

Je conçois un outil CLI qui aide les développeurs à suivre les commentaires TODO dans
leur base de code. Créez trois coéquipiers pour explorer cela sous différents angles :
un sur l'UX, un sur l'architecture technique, un jouant l'avocat du diable.

• Flèches haut et bas : sélectionner un coéquipier
• Entrée : ouvrir la transcription du coéquipier sélectionné et lui envoyer un message directement
• Échap : effacer la sélection. Pendant que vous consultez la transcription d’un coéquipier, Échap interrompt le tour actuel de ce coéquipier

​

Contrôler votre équipe d’agents

​

Choisir un mode d’affichage

• In-process : tous les coéquipiers s’exécutent dans votre terminal principal. Utilisez les touches fléchées haut et bas dans le panneau d’agent pour sélectionner un coéquipier, puis appuyez sur Entrée pour l’afficher et tapez pour lui 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.

{
  "teammateMode": "auto"
}

claude --teammate-mode auto

• 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

Générez 4 coéquipiers pour refactoriser ces modules en parallèle. Utilisez Sonnet pour
chaque coéquipier.

1. Le modèle que votre invite de génération nomme pour ce coéquipier.
2. Pour un coéquipier généré à partir d’une définition de sous-agent, le model de la définition, où inherit sélectionne le modèle du chef.
3. CLAUDE_CODE_SUBAGENT_MODEL, lorsqu’il est défini sur autre chose que inherit.
4. Le modèle actuel du chef.

• Alias de famille tel que opus : sur l’API Anthropic et Claude Platform sur AWS, Claude Code exécute le coéquipier sur la version la plus récente de cette famille que la liste d’autorisation permet. Sur les fournisseurs avec des ID de modèle spécifiques au fournisseur, où la substitution ne fonctionne pas, un alias bloqué revient comme toute autre valeur bloquée selon la puce suivante
• Toute autre valeur bloquée, y compris un alias de famille sur les fournisseurs où la substitution ne fonctionne pas, ou un alias dont la famille n’a pas de version autorisée : Claude Code exécute le coéquipier sur le modèle du chef à la place. Si vous définissez CLAUDE_CODE_SUBAGENT_MODEL, Claude Code essaie d’abord ce modèle, selon ces mêmes règles

​

Exiger que les coéquipiers planifient avant de mettre en œuvre

Générez un coéquipier architecte pour refactoriser le module d'authentification.

​

Parler directement aux coéquipiers

• Mode in-process : utilisez les touches fléchées haut et bas dans le panneau d’agent pour sélectionner un coéquipier, puis appuyez sur Entrée pour afficher sa session et tapez pour lui envoyer un message. Appuyez sur x sur un coéquipier sélectionné pour l’arrêter. 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

• 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

Demandez au coéquipier chercheur d'arrêter

​

Appliquer des portes de qualité avec des hooks

• 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.
• TaskCreated : s’exécute lorsqu’une tâche est en cours de création. Quittez avec le code 2 pour empêcher la création et envoyer des commentaires.
• 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

​

Comment Claude démarre les équipes d’agents

​

Architecture

• Configuration d’équipe : ~/.claude/teams/{team-name}/config.json
• Liste de tâches : ~/.claude/tasks/{team-name}/

​

Utiliser les définitions de subagents pour les coéquipiers

Lancez un coéquipier utilisant le type d'agent security-reviewer pour auditer le module d'authentification.

• tools : Claude Code limite le coéquipier aux outils de la liste tools de la définition. Pour un coéquipier en processus, Claude Code ajoute SendMessage à cette liste, et dans une session qui dispose des outils Task il ajoute également TaskCreate, TaskGet, TaskList et TaskUpdate.
• model : Claude Code utilise le model de la définition dans l’un ou l’autre mode d’affichage lorsque votre prompt de lancement n’en nomme pas un. Consultez comment Claude Code choisit le modèle d’un coéquipier.
• Body : pour un coéquipier en processus, Claude Code ajoute le body de la définition à son prompt système par défaut en tant qu’instructions supplémentaires. Pour un coéquipier en volet divisé, Claude Code utilise le body à la place de son prompt système par défaut.
• skills : Claude Code n’applique pas les skills de la définition à un coéquipier dans l’un ou l’autre mode d’affichage. Le coéquipier charge les skills à partir de vos paramètres de projet et d’utilisateur.
• mcpServers : pour un coéquipier en volet divisé, Claude Code applique les mcpServers de la définition selon les règles pour ce champ, qui couvrent également une session démarrée avec --agent. Un coéquipier en processus ignore le champ et charge les serveurs MCP à partir de vos paramètres de projet et d’utilisateur.

​

Permissions

​

Messages entre agents

• Il traite une approbation relayée par un autre agent comme une entrée non fiable plutôt que comme une confirmation de votre part.
• Il examine chaque message avant que Claude Code ne le livre, qu’il s’agisse d’un message brut ou d’un message de protocole structuré tel qu’une demande d’arrêt ou une réponse d’approbation de plan. Un message qu’il bloque n’atteint jamais le destinataire.

​

Contexte et communication

• 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 et inclut sa réponse finale dans la notification. Un coéquipier dont le tour se termine sur une erreur API notifie le chef qu’il a échoué et inclut le texte d’erreur.
• Liste de tâches partagée : les agents qui disposent des outils Task peuvent voir l’état des tâches et revendiquer le travail disponible.
• Messagerie des coéquipiers : envoyer un message à un coéquipier spécifique par son nom. Pour atteindre tout le monde, envoyez un message par destinataire.

​

Utilisation des tokens

​

Exemples de cas d’usage

​

Exécuter un examen de code parallèle

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

​

Enquêter avec des hypothèses concurrentes

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

​

Meilleures pratiques

​

Donner aux coéquipiers suffisamment de contexte

Générez un coéquipier examinateur de sécurité avec le prompt : « Examinez le module d'authentification
à src/auth/ pour les vulnérabilités de sécurité. Concentrez-vous sur la gestion des tokens, la gestion
des sessions et la validation des entrées. L'application utilise des tokens JWT stockés dans
des cookies httpOnly. Signalez tout problème avec les évaluations de gravité. »

​

Choisir une taille d’équipe appropriée

• 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

Attendez que vos coéquipiers complètent leurs tâches avant de procéder

​

Commencer par la recherche et l’examen

​

Éviter les conflits de fichiers

​

Surveiller et diriger

​

Dépannage

​

Les coéquipiers n’apparaissent pas

• En mode in-process, les coéquipiers apparaissent dans le panneau d’agent sous l’entrée de prompt. Utilisez les touches fléchées haut et bas pour en sélectionner un, puis appuyez sur Entrée pour l’afficher.
• Une ligne de coéquipier qui a disparu après être restée inactive a été masquée, non arrêtée. Les lignes inactives se masquent 30 secondes après que le panneau entier devienne inactif et réapparaissent au prochain tour du coéquipier. Quand plus de trois coéquipiers sont inactifs, leurs lignes excédentaires s’effondrent en une seule ligne N idle agents que Entrée développe. Envoyez un message au coéquipier par son nom pour ramener une ligne masquée.
• 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 :
  which tmux
  
• Pour iTerm2, vérifiez que le CLI it2 est installé et que l’API Python est activée dans les préférences d’iTerm2.

​

Claude crée des coéquipiers au lieu de sous-agents

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

• Fichiers de paramètres de priorité supérieure : les paramètres de projet, les paramètres locaux et une charge utile --settings s’appliquent après les paramètres utilisateur, donc une entrée env qui définit la variable à 1 dans l’un d’eux gagne. Voir Priorité des paramètres.
• Paramètres gérés : les paramètres gérés s’appliquent après toute autre source. Si votre organisation active les équipes d’agents là-bas, demandez à votre administrateur de modifier la valeur gérée.

​

Trop de demandes de permission

​

Les agents s’arrêtent prématurément

• Donnez-leur des instructions supplémentaires directement
• Générez un coéquipier de remplacement pour continuer le travail

​

Sessions tmux orphelines

tmux ls
tmux kill-session -t <session-name>

​

Limitations

• Pas de reprise de session avec les coéquipiers in-process : /resume et /rewind ne restaurent pas les coéquipiers in-process. Après la reprise d’une session, le chef peut tenter d’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 : une session a exactement une équipe, limitée à cette session. Vous ne pouvez pas créer d’équipes nommées supplémentaires ou partager une équipe entre les sessions.
• Pas d’équipes imbriquées : les coéquipiers ne peuvent pas générer leurs propres coéquipiers. Seul le chef peut gérer l’équipe.
• Pas de sous-agents d’arrière-plan à partir de coéquipiers in-process : les propres sous-agents d’un coéquipier in-process s’exécutent au premier plan, car le travail d’arrière-plan d’un coéquipier ne peut pas survivre au processus du chef. Claude Code retourne une erreur quand un coéquipier génère un sous-agent dont la définition définit background: true. Une demande run_in_background: true d’un coéquipier échoue également, soit avec une erreur, soit en s’exécutant silencieusement au premier plan, comme décrit dans comment Claude Code choisit le premier plan ou l’arrière-plan. Les sous-agents lancés à partir de la conversation principale suivent la valeur par défaut d’arrière-plan.
• Le chef est fixe : la session principale 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 : les coéquipiers commencent avec le mode de permission décrit sous Permissions. Vous pouvez modifier le mode de permission d’un coéquipier individuel après la génération, mais vous ne pouvez pas définir les modes de permission 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

• 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
• Messagerie entre vos propres sessions : la messagerie inter-sessions permet à Claude de transmettre les résultats entre les sessions que vous exécutez vous-même
• 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