Claude Code Agent Teams : configuration, astuces et cas d'usage

Claude Code Agent Teams : configuration, astuces et cas d'usage

J'ai cramé un budget de 47 $ de tokens en dix-neuf minutes. Quatre agents, tous sur Opus 4.6, tous travaillant sur le même codebase Next.js, tous en train de modifier layout.tsx en même temps.

L'orchestrateur n'a pas signalé le conflit. L'agent front-end a écrasé le wrapper d'authentification de l'agent back-end. L'agent QA a testé une version du fichier qui n'existait plus. Et l'agent design -- celui que j'avais lancé pour "peaufiner l'interface" -- a introduit une classe Tailwind qui a cassé la grille responsive que l'agent front-end avait passé huit minutes à construire.

Dix-neuf minutes. Quarante-sept dollars. Un codebase dans un pire état qu'au départ.

C'était en février 2026. Je venais d'activer les Claude Code agent teams pour la première fois, et j'ai fait toutes les erreurs contre lesquelles la documentation te met en garde -- plus quelques-unes qu'elle ne mentionne pas. Depuis, j'ai utilisé les agent teams sur plus de trente vrais projets, des dashboards SaaS aux migrations d'API en passant par un pipeline de contenu qui alimente maintenant le blog que tu es en train de lire. La fonctionnalité est passée de "catastrophe coûteuse" à l'outil le plus puissant de mon workflow de développement.

Voici le guide que j'aurais aimé avoir quand j'ai commencé. Pas la version marketing. Pas le quickstart en trois paragraphes. Le tableau complet -- configuration, paramétrage, plus de 30 astuces durement acquises, et les six cas d'usage où les agent teams surpassent véritablement tout ce que j'ai essayé.

Ce que sont vraiment les Agent Teams (et pourquoi les sub-agents ne suffisent pas)

Avant de toucher à la moindre configuration, tu as besoin d'un modèle mental plus précis que "plusieurs agents qui travaillent ensemble." La distinction entre sub-agents et agent teams, c'est la différence entre embaucher des freelances et constituer une équipe -- et confondre les deux te coûtera de l'argent réel.

Les sub-agents sont des instances indépendantes de Claude Code lancées par ta session principale. Chacune a sa propre fenêtre de contexte. Chacune exécute sa tâche et rapporte au parent. Le détail crucial : les sub-agents ne peuvent pas communiquer entre eux. Ils remontent au orchestrateur, point. Si l'Agent A découvre que le schéma de base de données a besoin d'une nouvelle colonne, l'Agent B n'en saura rien à moins que tu ne transmettes manuellement cette information.

Les agent teams ajoutent une couche de communication par-dessus. Les coéquipiers peuvent s'envoyer des messages directement. L'agent front-end peut demander à l'agent back-end "quel format renvoie l'endpoint /users ?" et obtenir une réponse sans passer par l'orchestrateur. Un agent joue le rôle de team lead -- il coordonne, délègue, synthétise -- tandis que les coéquipiers travaillent de manière indépendante tout en restant connectés via l'échange de messages.

Voici l'analogie qui m'a fait comprendre : les sub-agents, c'est le mail. Tu envoies des instructions, ils renvoient des résultats. Les agent teams, c'est Slack. Tout le monde est dans le même canal, les messages circulent en temps réel, et le chef de projet garde le cap.

Les implications sont pratiques et immédiates. Les sub-agents fonctionnent parfaitement pour des tâches véritablement indépendantes -- lancer le linting, générer la documentation, scaffolder des tests. Pas besoin de coordination, pas de contexte partagé, pas de messages échangés. Rapide et pas cher.

Les agent teams brillent quand le travail est interdépendant. Quand le front-end a besoin de connaître le contrat d'API avant de coder les appels fetch. Quand l'agent QA a besoin de la structure réelle des composants pour écrire des tests pertinents. Quand un changement de schéma de base de données doit se propager dans la compréhension du système de chaque agent.

Je vais te montrer le processus exact de configuration juste après, mais cette distinction doit guider chaque décision que tu prends à partir de maintenant. Si tes tâches n'ont pas besoin de coordination, les agent teams sont un moyen coûteux de faire quelque chose que les sub-agents gèrent pour une fraction du prix.

La configuration complète : de zéro à une équipe opérationnelle

Les agent teams sont encore marquées comme expérimentales dans Claude Code en mars 2026. Ça veut dire que tu dois opt-in, et que le comportement de la fonctionnalité peut changer entre les versions. Voici la séquence exacte que je suis sur une installation fraîche.

Étape 1 : Activer le flag expérimental

Ouvre ton fichier de paramètres Claude Code. Sur macOS, il se trouve à ~/.claude/settings.json. Ajoute le flag expérimental pour les agent teams :

{
  "experimental": {
    "agentTeams": true
  }
}

Tu peux aussi définir la variable d'environnement CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 si tu préfères ne pas toucher au fichier de paramètres. J'utilise le fichier de paramètres parce qu'il persiste entre les sessions terminal sans polluer mon profil shell.

Étape 2 : Choisir ton mode d'affichage

Cette décision a un impact plus important sur ton workflow que tu ne le penses. Les agent teams supportent deux modes de rendu :

Le mode split-pane tmux donne à chaque coéquipier son propre panneau de terminal. Tu vois tous les agents travailler simultanément, côte à côte. Tu peux cliquer dans n'importe quel panneau et interagir directement avec cet agent spécifique. C'est ma configuration préférée pour les projets complexes -- le feedback visuel est inestimable.

Prérequis : tmux installé (brew install tmux sur macOS), et tu dois lancer Claude Code depuis l'intérieur d'une session tmux. Commence avec tmux new -s dev, puis lance Claude Code dans cette session.

Le mode in-process fait tout tourner dans une seule fenêtre de terminal. La sortie des coéquipiers apparaît en ligne, et tu interagis avec les agents via le lead. Moins de surcharge visuelle, fonctionne partout, mais plus difficile de suivre ce que fait chaque agent en temps réel.

Configure ça dans tes paramètres :

{
  "teammateMode": "tmux"
}

Les options sont "tmux", "in-process", ou "auto" (qui bascule par défaut sur tmux s'il détecte une session tmux, in-process sinon).

Un piège qui m'a eu : le mode split-pane ne fonctionne pas dans le terminal intégré de VS Code, Windows Terminal, ou Ghostty. Si tu utilises l'un de ceux-là, reste en in-process ou passe à un terminal autonome. J'utilise iTerm2, qui supporte aussi nativement les split panes via son API Python -- installe le CLI it2 et active l'API Python dans les paramètres d'iTerm2.

Étape 3 : Définir les rôles de l'équipe en langage naturel

C'est là que les agent teams divergent des frameworks d'orchestration traditionnels. Tu n'écris pas de fichiers de configuration pour chaque agent. Tu décris ton équipe à l'agent lead en français (ou anglais) courant.

Voici un vrai prompt que j'ai utilisé pour un projet SaaS récent :

I need a team of 4 agents for this project:

1. Lead (you) - Architecture decisions, task delegation, integration review
2. Frontend specialist - React, TypeScript, Tailwind, component architecture
3. Backend specialist - Node.js, Express, PostgreSQL, API design
4. QA specialist - Testing, validation, integration checks

Rules:
- Frontend and backend must agree on API contracts before building
- QA writes tests only after receiving the actual implementation
- Nobody touches files outside their domain without lead approval

L'agent lead lance les coéquipiers en fonction de ta description. Chaque coéquipier obtient sa propre fenêtre de contexte (environ 200K tokens avec Opus 4.6) et sa spécialité assignée.

Étape 4 : Assigner les modèles stratégiquement

C'est le levier de coût le plus important que tu aies. Tous les agents n'ont pas besoin d'Opus 4.6. Mon assignation standard :

Une équipe de quatre agents tous sur Opus coûte environ 4 fois ce que coûte une équipe à modèles mixtes. La différence de qualité pour les tâches d'exécution -- écrire des composants React, construire des endpoints CRUD, scaffolder des tests -- est négligeable entre Opus et Sonnet. Réserve Opus pour la réflexion qui en a réellement besoin.

Étape 5 : Planifier avant d'exécuter

C'est non négociable. Avant que l'équipe n'écrive la moindre ligne de code, utilise le mode plan pour cartographier le travail. Le mode plan est pas cher -- c'est un seul agent qui réfléchit à l'approche. Le mode exécution avec une équipe complète est cher -- c'est quatre agents qui consomment des tokens en parallèle.

Mon workflow : activer le mode plan avec l'agent lead, obtenir un découpage complet des tâches et un plan d'architecture, le relire, l'ajuster, et seulement ensuite basculer en exécution avec l'équipe complète. Ça crée un checkpoint avant d'engager de vrais tokens.

Pense-y comme ça : le mode plan, c'est le plan architectural. L'exécution de l'agent team, c'est l'équipe de construction. Tu n'enverrais pas une équipe sur un chantier sans plans. Même principe, support différent.

Plus de 30 astuces qui m'ont fait économiser des milliers de dollars en tokens

Je les collecte depuis février. Certaines viennent de mes propres erreurs coûteuses. D'autres de patterns que j'ai remarqués sur des dizaines de projets. Je les ai regroupées par catégorie parce qu'une liste plate de 30 éléments est impossible à exploiter.

Composition de l'équipe

1. Commence avec 3 agents, pas 5. L'overhead de coordination entre agents augmente de manière non linéaire. Trois agents se coordonnent efficacement. Cinq agents passent un pourcentage significatif de leurs tokens juste à communiquer entre eux. Je commence chaque projet à trois et je n'ajoute un quatrième que si la charge de travail l'exige clairement.

2. Chaque agent a besoin d'un périmètre de domaine clair. "Agent front-end" est clair. "Agent assistant" ne l'est pas. Si tu ne peux pas décrire le domaine d'un agent en une phrase, le rôle n'est pas assez bien défini et l'agent empiétera sur le territoire des autres.

3. L'agent lead doit être ton modèle le plus cher. Le lead prend les décisions architecturales, résout les conflits entre coéquipiers et maintient la vision globale du projet. Économiser ici cause des erreurs coûteuses partout ailleurs.

4. Fais correspondre la capacité du modèle à la complexité de la tâche. Écrire des tests unitaires ne nécessite pas un raisonnement de niveau Opus. Concevoir un schéma de base de données avec des relations complexes, si. Assigne les modèles en fonction de la charge cognitive du rôle, pas un "tout le monde a le meilleur modèle" systématique.

5. Ne crée pas une équipe pour du travail séquentiel. Si la Tâche B ne peut pas commencer avant que la Tâche A soit terminée, tu n'as pas besoin de deux agents -- tu as besoin d'un agent qui fait deux choses. Les agent teams sont rentables quand les tâches peuvent tourner en parallèle.

Planification des tâches

6. Limite les tâches à 5-6 par agent. J'ai trouvé que c'est le sweet spot. Moins de 3 et tu sous-utilises l'agent. Plus de 7 et l'agent perd le fil de sa propre progression, commence à refaire du travail, ou oublie des décisions antérieures.

7. Rédige les descriptions de tâches comme si tu briefais un nouveau prestataire. Inclus ce qu'il faut construire, quelles contraintes s'appliquent, quels fichiers toucher et quels fichiers éviter. Des tâches ambiguës produisent des résultats ambigus -- et ces résultats coûtent des tokens à corriger.

8. Définis des critères de succès pour chaque tâche. "Construire le système d'auth" est vague. "Construire une auth basée sur JWT avec refresh tokens, retournant un 401 pour les tokens expirés et supportant un contrôle d'accès par rôles pour admin/user/viewer" dit à l'agent exactement quand il a terminé.

9. Planifie les points d'intégration avant de répartir le travail. L'agent lead doit produire un contrat partagé -- schémas d'API, modèles de base de données, définitions de types, formats d'événements -- avant que le moindre coéquipier commence à coder. Ça élimine la majorité des problèmes d'intégration.

10. Concentre la réflexion en amont, la construction en aval. Passe 20 % de ta session sur la planification et 80 % sur l'exécution. La plupart des gens inversent ce ratio et le paient en retravail.

Communication et contexte

11. Le partage de contexte se limite à l'échange de messages. Les agents ne partagent ni mémoire ni fenêtre de contexte. Si l'Agent A découvre quelque chose que l'Agent B doit savoir, cette information doit être explicitement envoyée par message. Rien n'est automatique.

12. Alimente les coéquipiers avec le contexte critique dès le départ. Quand tu définis les rôles de l'équipe, inclus les décisions architecturales clés, la stack technique et les contraintes dans le prompt initial. Chaque token dépensé en contexte initial en économise dix en comportements d'agent confus plus tard.

13. Définis des protocoles de communication explicites. Ne laisse pas les agents s'envoyer des messages librement. Définis les points de handoff : "L'agent front-end envoie ses attentes d'API à l'agent back-end avant d'écrire les appels fetch." "L'agent back-end partage le contrat d'endpoint final avec QA avant l'écriture des tests." La structure empêche le bruit.

14. Utilise l'agent lead comme routeur, pas comme goulot d'étranglement. Le lead devrait déléguer et relire, pas relayer chaque message entre coéquipiers. La messagerie directe entre agents existe pour une raison -- si toute communication passe par le lead, tu as recréé le modèle sub-agent mais avec plus d'overhead.

15. Garde les messages entre agents concis. Un agent qui envoie l'intégralité de son output à un autre agent gaspille des tokens des deux côtés. Les messages doivent contenir des décisions, des contrats et des définitions d'interface -- pas des implémentations complètes.

Gestion des fichiers et des conflits

16. Ne laisse jamais deux agents modifier le même fichier simultanément. C'est l'erreur qui m'a coûté 47 $ en dix-neuf minutes. Les conflits de fichiers dans les agent teams sont silencieux -- il n'y a pas de dialogue de conflit de merge. Un agent écrase simplement le travail de l'autre. Assigne la propriété des fichiers explicitement.

17. Crée une carte de propriété des fichiers. Avant de lancer l'exécution, l'agent lead devrait produire un mapping clair : "L'agent front-end possède tout dans /src/components et /src/hooks. L'agent back-end possède /src/api et /src/db. QA possède /tests." Les zones grises causent des collisions.

18. Utilise un répertoire partagé de types ou de contrats. Je crée un répertoire /src/shared ou /src/contracts que les agents front-end et back-end lisent mais que seul l'agent lead peut modifier. Ça empêche la dérive des contrats.

19. Si un agent doit modifier un fichier d'un autre agent, passe par le lead. Le lead examine le changement, confirme qu'il ne crée pas de conflit, et soit fait le changement lui-même, soit autorise explicitement l'agent demandeur à procéder. Ça ajoute quelques secondes de latence mais évite des minutes de debug.

Contrôle des coûts

20. Surveille la consommation de tokens activement, pas passivement. N'attends pas la fin de la session pour vérifier ta facture. Claude Code montre la consommation de tokens en temps réel. Si un agent brûle des tokens plus vite que prévu, quelque chose ne va pas -- il est probablement coincé dans une boucle ou génère une sortie excessive.

21. Tue les agents inactifs immédiatement. Un agent qui a terminé ses tâches mais tourne encore consomme toujours des ressources. L'orchestrateur gère le nettoyage, mais j'ai vu des agents rester inactifs pendant des minutes avant d'être arrêtés. L'arrêt manuel est plus rapide et moins cher.

22. Utilise les sub-agents pour les tâches indépendantes, les teams pour les interdépendantes. Je ne le répéterai jamais assez. Faire tourner quatre agents coordonnés pour quatre tâches indépendantes, c'est comme planifier une réunion qui aurait pu être quatre emails. Utilise les sub-agents pour le travail isolé. Réserve les agent teams pour le travail qui nécessite véritablement de la coordination.

23. Regroupe les tâches liées. Au lieu de lancer un nouvel agent pour chaque petite tâche, regroupe les tâches liées sous un seul agent. Un agent qui gère "construire les trois endpoints API de gestion utilisateur" est plus efficace que trois agents qui en construisent chacun un.

24. Fais une estimation de coût avant de te lancer. Calcul rapide : une équipe de 3 agents tournant 30 minutes sur Opus 4.6 consomme environ 200K-300K tokens. Au tarif actuel, ça fait 15-25 $. Avec une équipe à modèles mixtes (un Opus, deux Sonnet), la même session revient à 6-10 $. Connais tes chiffres avant de commencer.

Suivi et pilotage

25. Fais le point toutes les 10-15 minutes. Les agent teams ne sont pas du "configure et oublie". Je vérifie la progression à intervalles réguliers, je détecte les dérives tôt, et j'ajuste les assignations de tâches si un agent est bloqué pendant qu'un autre est inactif.

26. Tu peux interagir directement avec n'importe quel coéquipier. En mode split-pane tmux, clique dans le panneau d'un agent et donne-lui des instructions directes. Tu n'es pas limité à parler à travers le lead. Quand je remarque qu'un agent spécifique part dans la mauvaise direction, j'interviens directement plutôt que de relayer la correction via l'orchestrateur.

27. Utilise les hooks pour les événements de cycle de vie. Claude Code supporte des hooks qui se déclenchent quand des coéquipiers deviennent inactifs, terminent des tâches, ou rencontrent des erreurs. J'ai branché ça sur des notifications Slack pour être pingé quand un agent termine ou se bloque -- pas besoin de surveiller le terminal en permanence.

28. Attention aux boucles infinies. Parfois, deux agents entrent dans un schéma de ping-pong -- l'Agent A pose une question à l'Agent B, l'Agent B répond avec une question en retour, et ils bouclent. Si tu vois la consommation de tokens exploser sans progrès visible, interviens immédiatement.

Cycle de vie et nettoyage

29. Les agents s'arrêtent automatiquement quand leur file de tâches se vide. L'orchestrateur gère l'arrêt, mais le timing n'est pas toujours immédiat. Si tu en as fini avec la session, dis explicitement à l'agent lead de conclure.

30. Une seule équipe par session. Un agent lead ne peut gérer qu'une seule équipe à la fois. Si tu as besoin d'une composition d'équipe différente pour un autre projet, démarre une nouvelle session.

31. Les coéquipiers ne peuvent pas créer leurs propres équipes. La hiérarchie est plate : un lead, plusieurs coéquipiers. Pas de sous-équipes, pas d'orchestration récursive. Si ton projet a besoin de ce niveau d'imbrication, tu ferais probablement mieux d'utiliser plusieurs sessions indépendantes.

32. Nettoie les processus d'agents après un crash. Si une session plante en plein milieu d'une équipe, des processus d'agents orphelins peuvent persister. Vérifie les processus obsolètes et arrête-les manuellement. Ça évite à la fois le gaspillage de ressources et les conflits potentiels quand tu lances une nouvelle session.

33. Documente ce qui a fonctionné. Après chaque session d'équipe, je passe deux minutes à noter quelles assignations de modèles, tailles d'équipe et patterns de communication ont le mieux fonctionné pour ce type de projet. Cette bibliothèque de templates me permet maintenant de lancer des équipes optimisées en moins de trois minutes.

Six cas d'usage où les Agent Teams écrasent les agents solo

La théorie c'est bien. Ce qui compte vraiment, c'est de savoir quand utiliser cet outil. Après plus de trente projets, ces six scénarios justifient systématiquement l'overhead de coordination.

1. Développement d'applications full-stack

C'est le cas d'usage canonique, et il tient vraiment ses promesses. Trois agents -- lead architecture, spécialiste front-end, spécialiste back-end -- travaillant en parallèle sur un codebase partagé. Le lead produit le contrat d'API en premier, les deux agents d'implémentation construisent en s'appuyant sur ce contrat simultanément, et les problèmes d'intégration remontent via la messagerie inter-agents plutôt qu'après coup lors du debug.

Sur un projet récent -- un dashboard multi-tenant avec contrôle d'accès par rôles et mises à jour WebSocket en temps réel -- l'agent team a livré en 35 minutes ce qui aurait pris à un agent solo environ 90 minutes. Pas parce que les agents tapent plus vite, mais parce que l'agent front-end construisait des composants pendant que l'agent back-end construisait des endpoints. Une vraie exécution parallèle sur du travail interdépendant.

La clé : le pattern "contrat d'abord" décrit dans l'astuce #9 est obligatoire ici. Sans contrat d'API partagé, les agents construisent sur des hypothèses qui divergent immédiatement.

2. Revue de code avec des prismes spécialisés

Ce cas d'usage m'a surpris par son efficacité. Assigne trois agents pour relire la même PR, chacun avec un focus différent : vulnérabilités de sécurité, goulots d'étranglement de performance, et lacunes de couverture de tests. Chaque agent examine le code à travers son prisme spécialisé et produit un rapport ciblé. L'agent lead synthétise les trois rapports en une seule revue.

Le résultat est plus approfondi que n'importe quelle revue en une seule passe, et le focus spécialisé permet à chaque agent de repérer des choses qu'un généraliste manquerait. Un agent centré sécurité a signalé un vecteur d'injection SQL dans une requête paramétrée qui semblait correcte au premier regard -- l'échappement des paramètres ne gérait pas les entrées de type tableau. Un agent centré performance a attrapé une requête N+1 cachée derrière une abstraction ORM. Aucune de ces trouvailles n'aurait émergé dans une revue standard.

Le coût d'une revue de code à trois agents tourne autour de 3-5 $ en tokens. Pour les PRs critiques, c'est une affaire.

3. Debug avec hypothèses concurrentes

Quand un bug a plusieurs causes racines possibles, l'approche traditionnelle est séquentielle : investiguer l'hypothèse A, si c'est pas ça, essayer l'hypothèse B. Les agent teams te permettent d'investiguer toutes les hypothèses simultanément.

J'avais un problème en production où les temps de réponse de l'API passaient de 200ms à 3 secondes toutes les quelques heures. Trois causes possibles : épuisement du pool de connexions à la base de données, fuite mémoire dans un worker en arrière-plan, ou throttling d'un service en amont. J'ai assigné chaque hypothèse à un agent différent et les ai laissés investiguer en parallèle. Vingt minutes plus tard, l'Agent C a trouvé le throttling en amont -- un rate limit sur une API de géocodage que personne n'avait documenté. Les deux autres agents n'ont trouvé aucune preuve pour leurs hypothèses, ce qui était tout aussi précieux parce que ça a éliminé deux jours potentiels de recherche à l'aveugle.

4. Workflows de rédaction et d'édition

Celui-ci correspond directement au pipeline de contenu que j'utilise pour ce blog. Trois agents avec des rôles distincts : chercheur (rassemble les sources, les données, les informations actuelles), rédacteur (produit le brouillon en suivant le ton et la structure de la marque), et éditeur (relit pour la qualité, la précision, la cohérence et le SEO).

Le chercheur termine en premier et transmet ses trouvailles au rédacteur. Le rédacteur produit le brouillon et le passe à l'éditeur. L'éditeur relit et renvoie des notes de révision. Ce flux séquentiel-avec-communication produit un output notablement meilleur qu'un seul agent essayant de chercher, rédiger et s'auto-relire simultanément -- parce que chaque agent se concentre sur une seule tâche cognitive sans changement de contexte.

5. Recherche et exploration en parallèle

Quand tu as besoin d'évaluer plusieurs outils, approches ou architectures avant de prendre une décision, les agent teams te permettent d'explorer tous les chemins simultanément. J'ai utilisé ça quand je comparais trois approches différentes de gestion d'état pour un projet React -- un agent testait Zustand, un autre testait Jotai, un autre testait l'API native React Context. Chaque agent a construit un petit proof-of-concept, documenté les compromis, et rapporté au lead.

La règle critique pour les tâches de recherche : garde les agents en lecture seule pendant la phase d'exploration. Laisse-les lire le code, lancer des benchmarks et écrire des prototypes jetables -- mais ne les laisse pas modifier le codebase principal tant que le lead n'a pas examiné les résultats et choisi une direction. Sinon tu te retrouves avec trois approches différentes à moitié implémentées dans ton code de production.

6. Parité fonctionnelle cross-platform

Si tu livres la même fonctionnalité sur plusieurs plateformes -- iOS et Android, web et mobile, ou même différents microservices qui doivent avoir un comportement synchronisé -- les agent teams maintiennent la parité en faisant partager à chaque agent de plateforme les détails de son implémentation avec les autres. Quand l'agent Android implémente un utilitaire de formatage de dates, il envoie un message à l'agent iOS avec la chaîne de format exacte pour que les deux plateformes produisent un output identique.

Je n'ai utilisé ça que deux fois, mais les deux fois ça a détecté des divergences qui seraient devenues des bugs visibles par l'utilisateur. L'overhead de coordination est élevé pour ce pattern, donc je ne le recommande que pour les fonctionnalités où l'incohérence entre plateformes serait un problème sérieux -- flux de paiement, sérialisation de données, tout ce où "un comportement légèrement différent sur iOS vs Android" signifie un ticket de support.

Les phases du workflow : comment une session se déroule concrètement

Pour ceux qui veulent la vision de bout en bout, voici comment une session d'agent team typique se déroule du début à la fin. Je vais utiliser un exemple réel -- la construction d'un outil interne de suivi du statut d'un pipeline de contenu.

Phase 1 -- Initialisation. J'ouvre une session tmux, je lance Claude Code, et je vérifie que le flag expérimental agents est actif. Je décris le projet à l'agent lead en détail : la stack technique (Next.js 15, Prisma, PostgreSQL), les exigences (dashboard montrant le statut du contenu, les assignations d'auteurs, les dates de publication), et les contraintes (doit s'intégrer au système d'auth existant, ne doit pas modifier le schéma de base de données partagé).

Phase 2 -- Création de l'équipe. Je dis à l'agent lead de quelle équipe j'ai besoin. Dans ce cas : un agent front-end pour l'interface du dashboard, un agent back-end pour la couche API et les requêtes base de données, et un agent QA. Le lead lance trois coéquipiers, chacun apparaissant dans son propre panneau tmux. Je peux voir les quatre agents simultanément.

Phase 3 -- Planification des tâches. Avant que quiconque n'écrive du code, l'agent lead produit un plan de tâches. Il détaille chaque livrable, assigne les tâches à des agents spécifiques, définit le contrat d'API entre front-end et back-end, et fixe les critères de tests d'intégration. Je relis ce plan, j'ajuste deux assignations de tâches qui n'avaient pas de sens, et j'approuve.

Phase 4 -- Exécution en parallèle. Les agents se mettent au travail. Le front-end commence à construire les composants du dashboard. Le back-end crée le schéma Prisma et les routes API. Je peux suivre la progression des deux agents en temps réel via les panneaux tmux. Quand l'agent front-end a besoin d'une clarification sur la forme de la réponse de l'endpoint /content, il envoie un message directement à l'agent back-end.

Phase 5 -- Suivi et pilotage. Environ douze minutes plus tard, je remarque que l'agent front-end construit un composant de filtre avancé qui n'était pas dans le cahier des charges. Je clique dans son panneau et le redirige : "Laisse les filtres avancés pour l'instant. Concentre-toi sur le tableau de statut et la vue auteur." L'agent s'ajuste immédiatement.

Phase 6 -- Intégration et QA. Une fois que les deux agents d'implémentation signalent qu'ils ont terminé, l'agent QA s'active. Il lit les composants front-end et les endpoints back-end, écrit les tests d'intégration, et les exécute. Deux échecs : un décalage de formatage de dates et une error boundary manquante. L'agent QA rapporte ça aux agents concernés, qui corrigent en moins de deux minutes.

Phase 7 -- Résumé et nettoyage. L'agent lead compile un résumé : ce qui a été construit, quels tests passent, ce qui reste en suspens. Je relis la sortie, je confirme que tout fonctionne, et je ferme la session. Temps total : 28 minutes. Coût total en tokens avec la configuration à modèles mixtes : environ 8 $.

Toute la séquence ressemblait moins à "utiliser un outil" qu'à gérer une petite équipe de dev. Ce qui, dans un sens très concret, est exactement ce que c'est.

Les vrais compromis dont personne ne parle

Je te rendrais un mauvais service si je présentais les agent teams comme universellement supérieures. Elles ne le sont pas. Voici ce que j'ai appris de leurs vraies limites après des mois d'utilisation quotidienne.

Le coût augmente linéairement, mais pas la valeur. Trois agents coûtent trois fois plus qu'un seul. Mais ils ne délivrent pas toujours trois fois la valeur. Pour les projets de complexité modérée -- la plupart des apps CRUD, la plupart des outils single-page, la plupart des scripts -- un agent solo est plus rapide, moins cher, et produit un output plus facile à débugger parce qu'un seul cerveau l'a écrit.

L'échange de messages n'est pas du partage de contexte gratuit. Les agents peuvent s'envoyer des messages, mais ces messages consomment des tokens côté envoi et côté réception. Une communication intensive entre agents peut coûter plus cher que le code lui-même. J'ai vu des sessions où 30 % de la consommation totale de tokens venait de la messagerie inter-agents.

L'orchestrateur est un point de défaillance unique. Si l'agent lead se perd dans l'état du projet -- et ça arrive -- toute l'équipe dérive. La fenêtre de contexte du lead est finie, et suivre le statut de cinq coéquipiers sur des dizaines de tâches peut submerger même Opus 4.6. C'est pourquoi je limite les équipes à 3-4 agents et les tâches à 5-6 par agent.

Débugger la sortie d'une équipe est plus dur que débugger la sortie d'un agent solo. Quand quelque chose casse dans la sortie d'un agent solo, tu sais qui l'a écrit. Quand quelque chose casse dans la sortie d'une équipe, tu dois tracer quel agent a produit le code fautif, quel contexte il avait quand il a pris cette décision, et si le message d'un autre agent a influencé le choix. Le rayon d'impact d'une erreur est plus large.

La fonctionnalité est encore expérimentale. La reprise de session n'est pas fiable. L'arrêt des coéquipiers ne se passe pas toujours proprement. L'indexation des panneaux tmux peut bugger si ta config utilise des indices de base non standards. Ce sont des aspérités, et elles valent la peine d'être tolérées pour les projets complexes -- mais elles signifient que les agent teams ne sont pas encore un outillage production-grade. C'est une fonctionnalité avancée pour les gens prêts à gérer les frictions.

Voici ma position honnête après trois mois : les agent teams sont le bon choix pour peut-être 15-20 % des projets sur lesquels je travaille. Mais pour ces 15-20 %, elles sont radicalement meilleures que l'alternative. L'art, c'est de savoir identifier ces 15-20 %.

Si tu préfères que quelqu'un construise et configure ce type de workflow multi-agents pour ton projet, j'accepte des missions d'automatisation IA sur mesure. Tu peux voir ce que j'ai réalisé sur fiverr.com/s/EgxYmWD.

Comment je m'y prendrais si je devais tout recommencer aujourd'hui

Si je pouvais revenir en février et me donner un plan d'action en cinq étapes, voici ce que je me remettrais.

Première session : agent solo, mode plan uniquement. Ne touche pas aux agent teams. Construis ton plan de projet avec une seule instance de Claude Code. Pose l'architecture, définis les contrats d'API, cartographie la structure des fichiers. Ça ne coûte quasiment rien et ça produit le plan que ton équipe exécutera.

Deuxième session : deux agents, une petite tâche. Lance un lead et un coéquipier. Donne-leur un morceau contenu et à faible risque du projet -- une seule fonctionnalité avec des limites claires. Observe comment la communication circule. Apprends l'interface tmux. Familiarise-toi avec le rythme.

Troisième session : trois agents, du vrai travail. Maintenant tu en sais assez pour être efficace. Lead sur Opus, deux coéquipiers sur Sonnet, des périmètres de domaine clairs, des contrats partagés, 5-6 tâches par agent. C'est ta configuration de production pour 90 % des projets qui méritent une équipe.

Chaque session suivante : affine tes templates. Documente quelles assignations de modèles, tailles d'équipe et patterns de communication fonctionnent pour chaque type de projet. Après dix sessions, tu auras une bibliothèque de templates d'équipe qui rend la configuration quasi instantanée.

La seule chose que je changerais : j'aurais commencé par lire la documentation officielle d'Anthropic sur les agent teams sur code.claude.com/docs/en/agent-teams au lieu d'apprendre par essais et erreurs. La doc est vraiment bien faite -- elle n'existait juste pas quand j'ai commencé à expérimenter.

Le plus grand changement dans ma façon de penser ces trois derniers mois ne concerne pas la technologie. C'est le rôle. Quand j'utilise les agent teams, j'arrête d'être un développeur qui utilise l'IA et je deviens un lead technique qui manage des développeurs IA. Les compétences qui comptent changent : rédaction d'exigences claires, décomposition de tâches, suivi de progression, planification de l'intégration. Les mêmes compétences qui font un bon engineering manager font un bon opérateur d'agent teams.

Ton terminal n'est plus un éditeur de texte. C'est un poste de commandement. Et les agents attendent les ordres.

Questions fréquemment posées

Comment activer les Claude Code agent teams ?

Ajoute "agentTeams": true à la section "experimental" de ~/.claude/settings.json, ou définis la variable d'environnement CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Tu as besoin d'un abonnement Claude Pro ou Max avec accès à Opus 4.6 pour le rôle d'agent lead.

Combien d'agents utiliser dans une équipe Claude Code ?

Commence avec 3 coéquipiers pour la plupart des projets -- un lead, deux spécialistes. Trois agents équilibrent le débit parallèle et l'overhead de coordination. Les équipes de 5 ou plus dépensent une proportion disproportionnée de tokens en messagerie inter-agents. Pour une analyse plus détaillée, consulte les astuces sur la composition d'équipe ci-dessus.

Les Claude Code agent teams coûtent-elles plus cher que les sub-agents ?

Oui. Une équipe de 3 agents utilise environ 3-4x les tokens d'une session unique faisant le même travail. Tu peux réduire les coûts en assignant des modèles moins chers (Sonnet 4.5 ou Haiku) aux coéquipiers d'exécution tout en gardant Opus sur le lead. Les agent teams ne sont rentables que quand la complexité du projet exige véritablement une coordination en temps réel.

Les coéquipiers Claude Code peuvent-ils modifier le même fichier ?

Ils le peuvent, mais ils ne le devraient absolument pas. Les agent teams n'ont pas de détection de conflits de merge -- un agent écrase silencieusement les modifications de l'autre. Assigne une propriété de fichiers explicite à chaque agent avant de lancer l'exécution, et fais passer tout changement de fichier cross-domaine par l'agent lead.

Quelle est la différence entre les agent teams et les sub-agents dans Claude Code ?

Les sub-agents sont des travailleurs isolés qui rapportent leurs résultats à la session parente -- pas de communication inter-agents. Les agent teams ajoutent l'échange de messages direct entre coéquipiers, permettant une coordination en temps réel sur des tâches interdépendantes. Utilise les sub-agents pour le travail parallèle indépendant, les agent teams pour le travail collaboratif qui nécessite un contexte partagé.

Travaillons ensemble

Tu cherches à construire des systèmes IA, automatiser des workflows, ou faire évoluer ton infrastructure technique ? Ce serait un plaisir de t'aider.

• Fiverr (builds et intégrations sur mesure) : fiverr.com/s/EgxYmWD
• Portfolio : mejba.me
• Ramlit Limited (solutions entreprise) : ramlit.com
• ColorPark (design et branding) : colorpark.io
• xCyberSecurity (services de sécurité) : xcybersecurity.io