Agent teams dans Claude Code : faire travailler plusieurs agents

Une équipe d'agents Claude Code, ou agent team, fait travailler plusieurs sessions Claude Code en même temps : un chef qui répartit le travail et des coéquipiers qui se parlent directement, chacun dans sa propre fenêtre de contexte. Nous l'avons testée le 15 novembre 2026 sur notre serveur de développement, avec Claude Code 2.1.323, sur un vrai bug à deux causes. L'équipe de trois coéquipiers a trouvé les deux causes en débattant. Une session seule, lancée ensuite sur une copie neuve du même code, a trouvé les mêmes en 1 min 58 s au lieu de 3 min 38 s, avec 5,5 fois moins de jetons d'entrée.

Notre position découle de cet essai. Une équipe d'agents vaut son coût quand le débat entre agents produit un résultat qu'une session seule ne trouverait pas, et elle ne fait gagner du temps que si le travail se découpe vraiment en morceaux indépendants. Ce tutoriel s'adresse aux développeurs qui utilisent déjà l'outil au quotidien. Il couvre l'activation, le lancement, la coordination par tâches et par messages, l'arrêt et les limites, avec nos mesures. La délégation à l'intérieur d'une seule session relève d'un autre mécanisme, détaillé dans notre guide des sous-agents Claude Code.

Activer les équipes d'agents dans Claude Code

Les équipes d'agents sont désactivées par défaut : on les active en passant la variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS à 1, dans le shell ou dans le bloc env du fichier settings.json. La documentation officielle des équipes d'agents les présente comme expérimentales, avec des limites connues sur la reprise de session, la coordination des tâches et l'arrêt. Le réglage persistant prend cette forme :

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

Nous conseillons plutôt l'activation au cas par cas, en lançant CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude pour la seule session qui en a besoin. La raison tient à un comportement documenté : tant que la fonction est active, un sous-agent auquel Claude donne un nom démarre comme coéquipier, sans vous demander de confirmation. Vous pouvez donc vous retrouver avec une équipe sans l'avoir demandée. Nous y revenons plus bas avec les chiffres de notre serveur.

Deuxième prérequis, la session doit être interactive. En mode non interactif avec l'option -p, Agent SDK compris, Claude ne lance aucun coéquipier, et un sous-agent nommé tourne comme un sous-agent ordinaire. Une équipe d'agents ne se branche donc pas dans une chaîne d'intégration continue. Elle se pilote depuis un terminal ouvert, par quelqu'un qui suit le travail.

Reste le mode d'affichage. Par défaut, les coéquipiers tournent dans le terminal du chef, en mode in-process, ce qui fonctionne dans n'importe quel terminal. Le mode à volets séparés donne un volet par coéquipier, mais il exige tmux ou iTerm2 avec son outil it2, et le réglage teammateMode à "auto". L'option --teammate-mode fait la même chose pour une seule session, sans apparaître dans claude --help. Notre essai a tourné en mode in-process sur un serveur Linux, sans difficulté. Si vous découvrez l'outil, notre fiche Claude Code résume ses usages, et notre méthode de travail avec hooks, skills et MCP montre comment nous l'encadrons au quotidien.

Lancer une équipe : la consigne de notre essai, pas à pas

On lance une équipe en la décrivant en langage naturel au chef : nombre de coéquipiers, noms, modèle, périmètre de chacun et condition de fin. Claude crée alors les coéquipiers et coordonne le travail d'après cette consigne. Plus elle est précise, moins le chef improvise.

Pour l'essai, nous avons écrit un mini-service d'export CSV de factures en trois fichiers Python, avec un bug décrit dans le README : des lignes en double pour les clients multi-sites, et un nombre de lignes qui grossit à chaque relance du même mois. Deux causes indépendantes étaient cachées dedans. La fonction de jointure gardait tous les sites d'un client au lieu d'un seul, et un cache global ajoutait les lignes à chaque appel au lieu de les remplacer. Le test existant échouait. La consigne envoyée au chef est reproduite ci-dessous ; seul le nom du premier coéquipier, un identifiant sans accent, y est rendu par « jointure ».

Le README décrit un bug. Crée une équipe d'agents (agent team) de trois
coéquipiers nommés jointure, cache et testeur, tous sur Sonnet. jointure
n'examine que app/data.py, cache n'examine que app/export.py, testeur
n'écrit que dans tests/ des tests qui reproduisent chaque hypothèse.
Chacun envoie son hypothèse aux deux autres par message et essaie de
réfuter celles des autres. Personne ne modifie un fichier qu'un autre
possède. Quand l'équipe est d'accord, les propriétaires corrigent leur
fichier, testeur fait passer les tests, puis tu demandes aux trois de
s'arrêter et tu me rends la synthèse.

Nommer les coéquipiers rend leurs noms prévisibles, ce qui permet ensuite de leur écrire ou de les arrêter par leur nom. Le modèle de chaque coéquipier se choisit dans cet ordre : celui que la consigne nomme, puis celui de la définition d'agent utilisée, puis la variable CLAUDE_CODE_SUBAGENT_MODEL, puis le modèle du chef. Le fichier de configuration de l'équipe a bien enregistré "model": "sonnet" pour les trois, le chef restant sur Opus 5.5.

Le déroulé a été rapide. Avant de lancer quoi que ce soit, le chef a copié l'état de départ dans son dossier de travail, de sa propre initiative, pour vérifier à la fin qu'aucun fichier hors périmètre n'avait bougé. Les trois coéquipiers ont démarré à la même seconde. Le coéquipier jointure a envoyé son hypothèse sur la fonction de jointure, cache a montré que deux appels du même mois donnaient 5 puis 10 lignes, et testeur a écrit trois tests rouges qui reproduisaient les deux effets, puis un test de garde. Chacun a ensuite écrit « D'ACCORD » sur la même liste de deux causes. Les propriétaires ont corrigé leur fichier et la suite est passée à 5 tests verts. Le chef a encore réintroduit chaque bug seul sur une copie, pour prouver que chaque test visait bien sa cause.

Le protocole n'a pas été suivi à la lettre. Le coéquipier cache a corrigé son fichier avant le « D'ACCORD » de jointure, et jointure attendait un feu vert que la consigne ne prévoyait pas : le chef a dû le débloquer. Les agents interprètent un protocole écrit en prose. Pour une règle qui compte vraiment, un hook vaut mieux qu'une phrase dans la consigne.

Chef, coéquipiers, tâches et boîtes aux lettres : ce qui tourne réellement

Une équipe tient en quatre pièces : le chef, qui est votre session principale, les coéquipiers, qui sont des instances Claude Code séparées, une liste de tâches partagée et une boîte aux lettres par agent. Le chef reste le même pendant toute la session, et une session n'a qu'une équipe, deux points listés parmi les limites officielles.

Tout vit dans votre dossier personnel, sous un nom dérivé de la session : session- suivi des huit premiers caractères de son identifiant. Selon la section architecture de la documentation, la configuration de l'équipe se trouve dans ~/.claude/teams/{équipe}/config.json, et chaque boîte aux lettres dans un fichier JSON du sous-dossier inboxes/. La liste de tâches est rangée à part, dans ~/.claude/tasks/{équipe}/, et reste sur le disque après la session. N'éditez pas la configuration à la main : Claude Code la réécrit à chaque changement d'état. Pour définir des rôles réutilisables, passez par des définitions de sous-agents, qu'un coéquipier peut reprendre.

Deux observations de notre essai complètent la documentation. Les boîtes aux lettres pesaient 2 octets, un simple [], pendant que les messages circulaient : un message est retiré du fichier une fois remis. L'historique des échanges se lit donc dans les journaux de session sous ~/.claude/projects/, où chaque coéquipier a son propre fichier. Après un /exit propre, le dossier de l'équipe a disparu, et le dossier de tâches est resté vide, car le chef avait tout coordonné par messages sans créer de tâche.

La liste de tâches partagée sert quand le travail se découpe en nombreuses unités. Une tâche passe par trois états, en attente, en cours et terminée, et peut dépendre d'autres tâches, auquel cas elle reste bloquée jusqu'à leur fin. Un coéquipier qui termine prend seul la tâche libre suivante, avec un verrou de fichier pour éviter que deux agents prennent la même. Les bonnes pratiques de taille d'équipe conseillent de 3 à 5 coéquipiers et 5 ou 6 tâches par coéquipier.

Chaque coéquipier charge le contexte du projet comme une session normale, avec les fichiers CLAUDE.md, les serveurs MCP et les skills, plus la consigne du chef. Il ne reçoit pas l'historique de la conversation du chef. Ce bagage a un poids mesurable : la première requête de chacun de nos trois coéquipiers pesait environ 77 600 jetons, et celle du chef 86 600, avant toute action. Notre CLAUDE.md global, chargé de règles d'exploitation, explique une bonne part de ce volume.

Combien coûte une équipe d'agents face à une session seule

Sur un bug à deux causes, notre équipe de trois coéquipiers a traité 6,2 millions de jetons d'entrée, contre 1,12 million pour une session seule qui a résolu le même bug, soit 5,5 fois plus, et 2,74 $ contre 1,02 $ en équivalent API. La session seule tournait sur Opus 5.5, en mode -p, avec la même demande sans la notion d'équipe. Elle a fait 14 requêtes, trouvé les deux causes, écrit deux tests ciblés et vérifié elle aussi chaque test en réintroduisant chaque bug seul.

Le détail montre d'où vient l'écart. Le chef a traité 2,03 millions de jetons en 19 requêtes, synthèse finale comprise, jointure 1,72 million en 20 requêtes, testeur 1,34 million en 15 et cache 1,11 million en 13. Chaque message reçu réveille un coéquipier pour un nouveau tour, et chaque tour renvoie ses quelque 77 600 jetons de contexte. Le débat que nous avions demandé se paie donc en requêtes, message par message. La production de texte reste faible à côté : 36 200 jetons de sortie pour l'équipe, contre 10 400 pour la session seule.

En dollars, l'écart se réduit à 2,7 fois, parce que l'essentiel de ces jetons sont des lectures de cache et que les coéquipiers tournaient sur Sonnet. Nous avons calculé l'équivalent API avec la grille de prix d'Anthropic : Opus 5.5 facture 4 $ par million de jetons d'entrée, 0,20 $ en lecture de cache et 20 $ en sortie, contre 2 $, 0,10 $ et 10 $ pour Sonnet 5.5. Nous étions sur un abonnement, donc ces dollars ne correspondent à aucune facture réelle, mais ils donnent l'ordre de grandeur pour une équipe qui passe par l'API. Les journaux confirment aussi un détail documenté : le cache des coéquipiers in-process dure cinq minutes, contre une heure pour le chef dans notre configuration. Le réglage subagentPromptCacheTtl l'allonge à une heure, avec des écritures facturées plus cher.

La page des coûts de Claude Code annonce environ 7 fois plus de jetons qu'une session standard quand les coéquipiers tournent en mode plan. Elle recommande Sonnet pour les coéquipiers, des équipes petites, des consignes courtes et l'arrêt des coéquipiers dès leur travail fini. À l'autre bout de l'échelle, Anthropic a fait écrire par 16 agents en parallèle un compilateur C de 100 000 lignes capable de compiler Linux 6.9, en près de 2 000 sessions et 20 000 $ d'API. Ce chantier reposait sur un harnais maison, chaque agent dans son propre conteneur, avec des verrous écrits dans des fichiers texte, et non sur la fonction intégrée. Il montre surtout à quelle échelle un travail vraiment parallèle rentabilise ce surcoût.

Piloter, contrôler et arrêter les coéquipiers

Vous pilotez l'équipe en parlant au chef, et vous pouvez aussi écrire directement à n'importe quel coéquipier. En mode in-process, les flèches sélectionnent un coéquipier dans le panneau sous la zone de saisie, Entrée ouvre sa session pour lui écrire, Échap interrompt son tour en cours, la touche x l'arrête et Ctrl+T affiche la liste de tâches. Depuis la vue d'un coéquipier, le texte va à ce coéquipier, mais /compact, /clear et /rewind agissent sur la conversation du chef, après confirmation.

Les permissions des coéquipiers demandent le plus d'attention. Un coéquipier démarre avec le mode de permission du chef, bypassPermissions compris, et aucun mode propre ne se fixe au lancement. Ses demandes d'autorisation remontent dans la session du chef. Pendant notre essai, la première commande Bash du chef a déclenché une demande, et la réponse « oui, et passer en mode auto » l'a placé en mode auto : les coéquipiers lancés ensuite démarrent dans ce mode. Pré-approuvez les commandes attendues avant de lancer l'équipe, par exemple avec --settings '{"permissions":{"allow":["Bash(npm *)"]}}', et relisez nos règles sur les permissions de Claude Code avant de donner un mode large à quatre agents à la fois. Un garde-fou existe entre agents : un coéquipier ne peut pas approuver une permission à votre place, ni relayer une action refusée à un autre coéquipier pour la faire passer.

Le mode plan ne fait pas office de relecture humaine. Selon la documentation du mode plan des coéquipiers, un coéquipier lancé pendant que le chef est en mode plan planifie d'abord, puis envoie une demande d'approbation au chef. Si vous n'avez pas changé son mode depuis son lancement, Claude Code approuve ce plan dès réception, sans que le chef l'examine. Pour imposer une vraie porte, les hooks d'équipe sont plus fiables. TeammateIdle se déclenche quand un coéquipier va s'arrêter, TaskCreated à la création d'une tâche, TaskCompleted quand une tâche passe à terminée. Un code de sortie 2 bloque l'action et renvoie le message d'erreur à l'agent. Ce script, déclaré dans la section hooks des réglages, refuse qu'une tâche se ferme sur des tests rouges :

#!/bin/bash
INPUT=$(cat)
SUJET=$(echo "$INPUT" | jq -r '.task_subject')
if ! python3 -m pytest -q 2>&1; then
  echo "Tests rouges, tâche non terminée : $SUJET" >&2
  exit 2
fi
exit 0

L'arrêt mérite une vérification de votre part. On demande au chef d'arrêter un coéquipier par son nom ; il envoie une demande que le coéquipier accepte ou refuse en expliquant pourquoi. Dans notre essai, le chef a envoyé les trois demandes puis a fini son tour sur « j'attends leurs confirmations », sans jamais reprendre la main de lui-même. Le fichier de configuration ne listait pourtant plus que le chef. Quand nous lui avons demandé où en était l'équipe, il a répondu qu'il ne pouvait pas prouver l'arrêt. Vérifiez donc le panneau des agents, puis fermez la session par /exit, qui nettoie le dossier de l'équipe.

Les limites qui décident de l'usage

Une équipe d'agents ne survit pas à une reprise de session, ne s'imbrique pas et garde le même chef jusqu'au bout. Ces trois limites, avec deux autres, pèsent le plus dans la décision de l'employer :

• pas de reprise : /resume et /rewind ne restaurent pas les coéquipiers in-process, et le chef peut écrire à des agents qui n'existent plus ;
• une seule équipe par session, sans partage entre sessions ;
• pas d'équipes imbriquées, seul le chef gère l'équipe ;
• un chef fixe, qu'on ne peut ni remplacer ni promouvoir ;
• un statut de tâche qui peut rester en retard et bloquer les tâches dépendantes.

La liste complète des limites ajoute d'autres contraintes, comme l'arrêt parfois lent ou l'absence de sous-agents en arrière-plan chez un coéquipier. Deux coéquipiers qui modifient le même fichier s'écrasent mutuellement : donnez à chacun un ensemble de fichiers à lui, comme dans notre consigne.

La limite la plus coûteuse chez nous ne figure pas dans cette liste, c'est l'activation globale. Nous avions activé la variable dans les réglages utilisateur de notre serveur. Entre le 17 juin et le 28 octobre 2026, 460 configurations d'équipe sont restées sur le disque, une par session ouverte avec la fonction active. 430 ne contenaient que le chef. Les 30 autres ont réellement lancé des coéquipiers, 98 au total, dont 82 de type general-purpose, le sous-agent intégré sur lequel Claude se rabat quand il ne précise aucun type. Ces chiffres laissent penser que la plupart de ces équipes sont nées de délégations nommées par Claude lui-même, transformées en coéquipiers par le réglage. Le fait que ces dossiers soient restés, alors qu'un /exit propre les efface, vient probablement de sessions fermées sans sortie normale.

Pour revenir à des sous-agents classiques, il suffit de passer la variable à 0 dans le settings.json utilisateur : la valeur l'emporte sur un export du shell, et Claude Code la relit au prochain lancement d'agent, sans redémarrage. Un réglage de projet ou un réglage géré par l'organisation peut toutefois la remettre à 1.

Quand une équipe d'agents vaut son coût

Montez une équipe quand les agents doivent se contredire ou se coordonner entre eux, et restez sur une session seule ou des sous-agents dans les autres cas. Le critère tient à la communication : un sous-agent rend un résultat à celui qui l'a lancé, alors que des coéquipiers échangent entre eux et se répartissent le travail. Le choix détaillé entre les deux mécanismes, coûts de démarrage compris, figure dans notre tutoriel sur la délégation par sous-agents.

Notre essai tombait dans la dernière ligne, et c'était voulu pour mesurer le coût. Trois fichiers et deux causes se lisent d'un seul regard : le débat n'a rien apporté que la session seule n'ait trouvé, et il a coûté 5,5 fois plus de jetons. Le cas où l'équipe gagne est celui que la documentation décrit pour les hypothèses concurrentes. Quand la cause est obscure, un agent seul tend à retenir la première explication plausible, et des enquêteurs chargés de se réfuter limitent ce biais d'ancrage.

Gardez aussi en tête la taille. Trois coéquipiers ciblés font souvent mieux que cinq dispersés, et la consigne de chacun doit porter ce que le chef sait déjà, puisqu'ils ne voient pas sa conversation. Quand ces mécanismes sortent du poste de développement pour devenir un produit, avec des agents qui travaillent pour vos clients, les principes rejoignent ceux des systèmes multi-agents IA. C'est le terrain de notre agence spécialisée en agents IA, et vous pouvez contacter Noxcod pour cadrer un montage avant d'engager vos équipes.

FAQ sur les équipes d'agents Claude Code

Les équipes d'agents fonctionnent-elles en mode -p ou dans une CI ?

Non. Lancer des coéquipiers exige une session interactive. En mode non interactif avec l'option -p, comme avec l'Agent SDK, Claude ne crée aucun coéquipier, même avec la variable activée : un sous-agent qu'il nomme tourne alors comme un sous-agent ordinaire. Pour paralléliser dans un pipeline, il faut lancer plusieurs sessions vous-même, par exemple dans des worktrees git séparés, ou passer par des sous-agents dans une seule session.

Peut-on donner un modèle différent à chaque coéquipier ?

Oui, en le nommant dans la consigne pour ce coéquipier précis. À défaut, Claude Code prend le modèle de la définition d'agent utilisée, puis la variable CLAUDE_CODE_SUBAGENT_MODEL, puis le modèle du chef. Le modèle d'un coéquipier est fixé à son lancement, et la commande /model ne s'exécute pas depuis sa vue. Notre essai a placé le chef sur Opus et les trois coéquipiers sur Sonnet.

Que se passe-t-il si deux coéquipiers modifient le même fichier ?

Le second écrase le premier, prévient la documentation sur les conflits de fichiers. Claude Code verrouille la prise des tâches pour éviter que deux agents prennent la même, mais il ne protège pas les fichiers. La parade consiste à attribuer un ensemble de fichiers à chaque coéquipier dans la consigne, comme nous l'avons fait avec jointure, cache et testeur. Pour un travail où tout le monde touche aux mêmes fichiers, une session seule reste plus sûre et moins coûteuse.

Combien de coéquipiers faut-il lancer ?

La documentation recommande de rester entre trois et cinq coéquipiers pour la plupart des travaux, et de commencer à trois quand les tâches sont nombreuses. Chaque coéquipier ajoute sa fenêtre de contexte, environ 77 600 jetons au départ dans notre configuration, puis ce bagage à chaque tour. Visez cinq ou six tâches par coéquipier, pour que le chef puisse réaffecter du travail si l'un d'eux bloque, et augmentez la taille de l'équipe seulement si les tâches avancent vraiment en parallèle.