Les équipes d'agents Claude Code

Problème : Un gros refactor touche l'API, les migrations de base de données, la couverture de tests et la doc. Une seule session Claude Code avance de façon linéaire. Les sous-agents peuvent se répartir le travail, mais ils ne parlent qu'à l'agent principal. Ils ne s'échangent pas de notes, ne se challengent pas, et ne se coordonnent pas directement. Dès que tes agents IA ont besoin de collaborer vraiment, les sous-agents atteignent leurs limites.

Gain rapide : Active Agent Teams et décris l'équipe que tu veux dans un seul prompt :

# Add to your environment or settings.json
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Ensuite dis à Claude :

Create an agent team to refactor the payment module. Spawn three teammates:
one for the API layer, one for the database migrations, one for test coverage.
Have them coordinate through the shared task list.

Un lead démarre, trois coéquipiers s'installent dans leurs périmètres respectifs, et ils partagent une liste de tâches plus une boîte de réception. Chacun gère son couloir. Pas de collision. Pas de silence.

Note sur la terminologie : La fonctionnalité ici, c'est Agent Teams, le système expérimental intégré à Claude Code et livré par Anthropic. Si tu veux monter toi-même une configuration builder-validator avec l'outil Task, ça se trouve dans l'orchestration d'équipes avec des chaînes builder-validator. Les deux te permettent du travail multi-agent. Sous le capot, ils fonctionnent complètement différemment.

Cette distinction, c'est tout le sens de cette page. Si un agent principal peut coordonner des spécialistes et collecter leurs réponses, commence par Agent Fundamentals et Agent Patterns. Lis cette page quand les coéquipiers eux-mêmes ont besoin de se parler, de se challenger, et de se coordonner sans tout faire passer par un seul fil parent.

Ce qu'est vraiment Agent Teams

Agent Teams est un mode expérimental qui fait tourner plusieurs sessions Claude Code sur le même projet, ensemble. Une session devient le lead. Le lead distribue les tâches, maintient le travail aligné, et regroupe les résultats. Chaque autre coéquipier tourne dans sa propre fenêtre de contexte et peut envoyer des messages à n'importe quel autre coéquipier directement.

Ce qui diffère des sous-agents, c'est le canal de communication. Un sous-agent vit dans une session parent et ne peut renvoyer sa réponse qu'à ce parent. Les découvertes en cours de tâche restent bloquées. La coordination entre deux sous-agents passe toujours par l'agent principal. Agent Teams supprime ce saut. Les coéquipiers se DM, récupèrent des tâches sur une liste partagée, et débattent des problèmes en temps réel. Tu peux rejoindre la session de n'importe quel coéquipier toi-même sans demander la permission au lead.

Une image utile : les sous-agents sont des freelances à qui tu envoies des boulots séparés. Une équipe Agent Teams, c'est un groupe dans la même salle, chacun sur sa partie, qui se synchronise en discutant. C'est la différence entre une file de missions et un vrai groupe de travail.

Pourquoi ça compte maintenant

Anthropic a lancé Agent Teams en expérimental avec la sortie d'Opus 4.6, et ça marque une vraie avancée pour le travail agentique. Des développeurs indépendants assemblaient des setups similaires depuis des mois en utilisant des projets comme OpenClaw et des scripts d'orchestration faits main. Claude Code a maintenant le pattern intégré nativement.

Trois raisons pour lesquelles ça change la donne :

1. Intégré vaut mieux que rajouté. Les listes de tâches partagées, la boîte de réception, et le cycle de vie des coéquipiers font partie de Claude Code lui-même. Rien d'externe. Rien de fragile.

2. Le multi-agent grandit. Les développeurs qui construisent de l'expérience avec les équipes d'agents maintenant vont avoir une vraie longueur d'avance au fur et à mesure que les outils évoluent. L'écart entre "utilise Claude Code" et "fait tourner des équipes Claude Code" va s'élargir.

3. Les projets complexes ont besoin de dialogue, pas juste de fork. Diviser les tâches te donne du travail en parallèle. Agent Teams te donne du travail en parallèle plus de la coordination en direct, où les coéquipiers échangent du contexte, challengent les décisions, et arrivent à de meilleures réponses ensemble.

Quand utiliser Agent Teams

Faire tourner une équipe coûte de vrais tokens et ajoute de la coordination en plus d'une session unique. C'est le plus pertinent quand chaque coéquipier peut posséder une tranche distincte du travail mais bénéficie quand même du chat de groupe.

Cas d'usage forts

• Recherche et revue : Des coéquipiers différents creusent différents angles d'un problème, puis comparent les notes et pointent les failles dans les découvertes des autres
• Nouveaux modules ou fonctionnalités : Chaque coéquipier prend un composant sans chevauchement de fichiers
• Débogage avec des hypothèses concurrentes : Chaque coéquipier teste une théorie différente en parallèle et essaie activement d'invalider les autres
• Coordination inter-couches : Un changement qui traverse le frontend, le backend et les tests, avec un coéquipier par couche
• Débat et consensus : Plusieurs coéquipiers défendent des positions opposées sur un choix architectural et convergent vers la plus solide
• Inventaire ou classification à grande échelle : Les coéquipiers se répartissent un grand jeu de données et traitent leurs tranches indépendamment

Pour des templates de prompts et plus de 10 scénarios couvrant marketing, recherche et tâches hors-dev, voir Agent Teams Use Cases and Prompt Templates.

Quand les équipes valent le coût

Les équipes d'agents ne sont pas juste "plus d'agents". C'est une couche de coordination, et cette couche ne vaut d'être payée que quand la collaboration elle-même change le résultat.

Les équipes valent généralement le coup quand :

• chaque coéquipier peut posséder un couloir distinct
• les découvertes dans un couloir vont changer ce qu'un autre coéquipier doit faire
• comparer les points de vue fait partie du travail
• le boulot serait vraiment plus lent ou moins bon si tout passait par un seul fil principal

Les équipes ne valent généralement pas le coup quand :

• un seul agent pourrait finir le travail proprement
• le travail est surtout séquentiel
• tout le monde éditerait les mêmes fichiers
• tu as juste besoin de plusieurs sorties indépendantes et d'un résumé

Ce dernier cas, c'est là où les sous-agents gagnent encore. Si les agents n'ont pas besoin de se parler, ne paie pas pour un système conçu autour du dialogue.

Quand passer son chemin

Travail séquentiel, éditions sur les mêmes fichiers, ou tout ce qui a des dépendances serrées : une session unique ou un pattern de sous-agents coûte moins et tourne plus proprement. Si les agents n'ont pas besoin de se parler, la couche de coordination est une pure surcharge. Pour des éditions parallèles vraiment indépendantes, /batch est plus simple et gère l'isolation des worktrees pour toi. Les workflows async couvrent les runs parallèles basiques sans la couche de collaboration par-dessus. Pour les pièges courants et comment les éviter, voir nos bonnes pratiques pour les équipes d'agents.

Sous-agents vs Agent Teams : choisir le bon outil

Les deux parallélisent le travail. Ils opèrent à des couches différentes. La question qui décide : tes agents ont-ils vraiment besoin de se parler entre eux ?

Les sous-agents conviennent quand tu veux des agents rapides et ciblés qui remontent un résultat. Les équipes conviennent quand ces agents doivent partager du contexte, se challenger, et gérer leur propre coordination. Sur les grands projets, combine les deux : planifie d'abord pour définir les rôles et les périmètres, puis lance une équipe pour l'exécution.

Sur comment les sous-agents sont routés au départ, voir les bonnes pratiques des sous-agents.

Étape par étape : ta première équipe

En utilisation réelle, les coéquipiers apparaissent en 20 à 30 secondes et commencent à produire des résultats dans la première minute. Un run à 3 coéquipiers brûle environ 3 à 4 fois les tokens d'une session unique faisant le même travail en séquence. Sur les tâches complexes, le gain de temps couvre facilement ça.

Étape 1 : Active la fonctionnalité

Définis la variable d'environnement dans ton shell :

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Ou mets-la dans ton settings.json pour qu'elle persiste entre les sessions :

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

Étape 2 : Décris le travail et l'équipe

Utilise du texte simple. Sois précis sur qui fait quoi :

Create an agent team to review our authentication system. Spawn three teammates:
- Security reviewer: audit for vulnerabilities, check token handling
- Performance analyst: profile response times, identify bottlenecks
- Test coverage checker: verify edge cases, find untested paths
Have them share findings and coordinate through the task list.

Ce que mettre dans le brief d'équipe

Le premier prompt d'équipe compte plus que la plupart des gens le pensent. Un brief vague crée une collaboration vague.

Un bon brief d'équipe inclut :

• l'objectif global
• les rôles des coéquipiers
• les périmètres fichiers ou systèmes
• sur quoi les coéquipiers doivent se coordonner
• ce qui compte comme terminé

Exemple :

Create an agent team to ship the billing refactor.

Team:
- API teammate: own route handlers and webhook flow
- Data teammate: own schema, migrations, and backfills
- Test teammate: own integration coverage and failure cases

Coordination points:
- align on the event model before code changes
- flag any contract mismatch immediately
- do not edit the same file without discussing it first

Done means:
- migrations apply cleanly
- webhook flow still passes
- billing test suite is green

Ce prompt donne à l'équipe des rôles, des périmètres, des points de communication et une ligne d'arrivée. Sans ça, "se coordonner" veut généralement dire "beaucoup parler".

Étape 3 : Regarde l'équipe se former, dirige si nécessaire

Claude transforme ta session en lead, crée les coéquipiers, et dépose les tâches sur la liste partagée. Claude peut aussi suggérer une équipe de lui-même s'il pense que ta demande s'y prête. Dans tous les cas, le volant reste entre tes mains.

Utilise les raccourcis clavier pour observer et diriger : Shift+Haut/Bas pour choisir un coéquipier, Ctrl+T pour la liste de tâches, Entrée pour entrer dans une session, Échap pour interrompre.

Étape 4 : Nettoyage

Une fois le travail terminé, arrête l'équipe :

Ask all teammates to shut down, then clean up the team.

Lance toujours le nettoyage via le lead. Les coéquipiers s'arrêtent d'abord parce que le lead ne nettoie pas tant qu'un coéquipier est encore actif.

Pour les détails avancés sur les modes d'affichage, le mode délégué, l'approbation de plan, les hooks, l'attribution des tâches, et les coûts en tokens, voir Agent Teams Advanced Controls.

Architecture : comment les pièces s'assemblent

Quatre composants constituent une équipe :

L'équipe et sa config sont stockées localement sur disque :

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

Chaque coéquipier a sa propre fenêtre de contexte. Au démarrage, un coéquipier charge le même contexte de projet que n'importe quelle session Claude Code normale : ton CLAUDE.md, les serveurs MCP, et les skills. Il lit aussi le prompt de démarrage du lead. Ce qu'il n'hérite pas, c'est l'historique de conversation du lead.

La communication passe par la livraison automatique des messages, les notifications d'inactivité, la liste de tâches partagée, les messages directs (un seul coéquipier), et les diffusions (tout le monde à la fois, à utiliser avec soin car le coût augmente avec la taille de l'équipe).

Les coéquipiers héritent des paramètres de permission du lead au démarrage. Tu peux changer le mode d'un coéquipier spécifique après le démarrage, pas au moment du démarrage.

Pour tirer plus de ton CLAUDE.md dans une configuration en équipe, piloter le comportement de l'équipe et garder les coûts en tokens raisonnables, voir Agent Teams Advanced Controls.

Aller plus loin

Cette page est le hub. Trois guides complémentaires vont plus loin sur des points spécifiques :

• Advanced Controls : Modes d'affichage, mode délégué, approbation de plan, hooks de contrôle qualité, attribution des tâches, gestion des coûts en tokens, et optimisation de CLAUDE.md pour les équipes
• Use Cases and Prompt Templates : Plus de 10 scénarios réels avec des prompts prêts à copier pour la revue de code, le débogage, les fonctionnalités full-stack, les décisions d'architecture, les campagnes marketing, et un parcours d'apprentissage progressif
• Best Practices and Troubleshooting : Pratiques éprouvées, comportement du mode plan, guide de dépannage, limitations actuelles, et corrections récentes de v2.1.33 à v2.1.45
• End-to-End Workflow : Le pipeline complet en 7 étapes du brain dump à la production : planification, chaînes de contrats, exécution par vagues, et validation post-build

Si tu veux que le travail interactif soit encore plus fluide pendant qu'une équipe tourne, jette un œil au Fast Mode pour des réponses Opus 4.6 2,5x plus rapides.

Coordination à grande échelle

Au fur et à mesure que tes équipes grossissent, la vraie question ne devient plus "puis-je paralléliser ça ?" mais "comment gérer vraiment l'orchestration ?". Trois patterns ont du poids à grande échelle :

1. Templates de prompts de démarrage réutilisables. Garde une petite bibliothèque de formats de prompts pour tes compositions les plus courantes (équipe de revue, équipe de build, équipe de recherche). Chacun définit les rôles, les périmètres fichiers, et les critères de fin pour que rien ne soit reconstruit à chaque session. Pour le workflow dans lequel ces templates s'insèrent, voir le guide end-to-end workflow.

2. Presets de permissions. Pré-approuve tes opérations les plus courantes dans les paramètres de permission avant de démarrer l'équipe. Sinon, une nouvelle équipe se noie dans les demandes d'approbation pendant les dix premières minutes.

3. CLAUDE.md comme contexte d'exécution partagé. Un CLAUDE.md bien ciblé avec les périmètres des modules, les commandes de vérification et le contexte opérationnel réduit drastiquement le coût d'exploration par coéquipier. Trois coéquipiers qui lisent un CLAUDE.md clair, c'est bien moins cher que trois coéquipiers qui explorent indépendamment la codebase.

Le spectre multi-agent

Agent Teams se trouve à une extrémité d'une gamme de patterns multi-agents dans Claude Code. Savoir où chacun se situe aide à choisir :

Combine-les selon les besoins. Lance une équipe pour la phase d'exploration collaborative, puis passe aux paires builder-validator quand tu arrives à l'implémentation et que tu as besoin de vrais contrôles qualité. Les sessions d'équipes longues vivent et meurent selon les mêmes stratégies de contexte que n'importe quel workflow multi-agent.

L'expérience avec les équipes d'agents se capitalise au fur et à mesure que les outils multi-agents progressent. Commence avec une tâche de revue cette semaine. Le coût est faible, et ta façon de voir le travail complexe va changer une fois que tu verras des coéquipiers se coordonner vraiment.