Claude Code Agent Teams : Le Guide Qui M'a Pris des Semaines

Claude Code Agent Teams : Le Guide Qui M'a Pris des Semaines

L'agent QA a trouvé onze bugs. Onze. Dès la première passe. Je venais de regarder deux autres agents — un développeur front-end et un développeur back-end — passer quatre minutes à construire une landing page pour une startup d'AI fictive appelée Neuroflow. Texte, animations, palettes de couleurs, mise en page responsive, API endpoints. Tout tournait en parallèle, chaque agent travaillant dans sa propre session Claude Code pendant que je regardais le terminal se diviser en panneaux codés par couleur. L'agent front-end a soumis son travail. L'agent back-end a soumis son travail. Puis l'agent QA a démoli le travail des deux. Des hover states manquants. Un API endpoint renvoyant des données dans un format que le front-end n'attendait pas. Un ratio de contraste de couleur qui échouait aux standards WCAG. Une animation qui se déclenchait avant le chargement du contenu, provoquant un flash de texte non stylé. Voici la partie qui m'a cloué sur place : je n'ai rien eu à faire. L'agent QA a signalé ses découvertes, tagué les agents responsables, et les deux développeurs ont pris en charge les corrections immédiatement. À la deuxième passe, QA a tout approuvé. La landing page finale avait l'air d'avoir été travaillée pendant une semaine par une petite équipe de design. C'est le moment où j'ai compris ce que sont réellement les Claude Code agent teams. Pas une fonctionnalité. Pas un paramètre qu'on active. Une façon fondamentalement différente de construire du logiciel avec l'AI — une où les agents ne se contentent pas d'exécuter des tâches, mais collaborent, débattent et se tiennent mutuellement responsables. Et arriver à ce moment a nécessité des semaines d'expérimentation douloureuse que je m'apprête à condenser dans cet article. Car voici ce que personne ne vous dit sur les agent teams : la fonctionnalité est facile à activer. La faire produire des résultats comme ceux que je viens de décrire ? C'est là que la plupart des gens échouent. La différence entre un agent team bien orchestré et un brasier chaotique de tokens se résume à la façon dont vous promptez, comment vous structurez les rôles, et comment vous gérez la dizaine de choses qui peuvent mal tourner. J'ai brûlé plus de tokens pour comprendre tout ça que je ne voudrais l'admettre. Voici le guide que j'aurais voulu avoir quand j'ai commencé.

Pourquoi les Agent Teams existent (et pourquoi les Sub Agents ne suffisent pas)

Si vous avez utilisé les sub agents de Claude Code, vous connaissez déjà le principe : lancer des agents indépendants, les laisser travailler en parallèle, récupérer les résultats. Rapide, économique, efficace pour des tâches délimitées. J'utilise encore les sub agents quotidiennement pour des choses comme « analyse ce codebase et liste chaque API endpoint » ou « écris des tests unitaires pour ce module ». Ils sont parfaits quand le travail est isolé. Le problème apparaît dès que le travail n'est pas isolé. J'ai appris ça de la manière coûteuse en construisant une application de dashboard. Un sub agent s'occupait du front-end en React. Un autre construisait l'API Express. Un troisième écrivait la couche base de données. Les trois tournaient simultanément — et les trois ont pris des décisions indépendantes qui se contredisaient. L'agent front-end s'attendait à des réponses paginées. L'agent API renvoyait tout dans un seul payload. L'agent base de données a construit des queries optimisées pour un pattern de pagination qu'aucun des autres agents ne connaissait. Trois pièces brillantes de logiciel qui ne pouvaient pas communiquer entre elles. J'ai passé plus de temps à les assembler que les agents n'en avaient mis à les construire. Les sub agents sont parallèles mais sourds. Ils ne peuvent pas se poser de questions mutuellement. Ils ne peuvent pas négocier un contrat d'API. Ils ne peuvent pas dire « attention, j'ai changé le format de réponse pour l'endpoint /users ». Chacun opère dans un context window scellé, rapporte à l'agent principal, et c'est tout. L'agent principal devient un goulot d'étranglement — chaque morceau de coordination doit passer par lui. Les agent teams résolvent ça avec une architecture complètement différente. Trois composants font que ça fonctionne : Le chef d'équipe — votre session principale Claude Code. Il comprend la vision d'ensemble, décompose la mission, attribue les domaines et coordonne l'intégration. Pensez à lui comme le tech lead qui n'écrit pas tout le code mais s'assure que tout le monde construit le même produit. Les coéquipiers — des instances Claude Code séparées, chacune avec son propre context window complet. Ils tournent en parallèle et possèdent des domaines spécifiques. L'agent front-end ne pense qu'aux problématiques front-end. L'agent back-end se concentre entièrement sur la logique API. Aucune pollution de contexte entre eux. La messagerie directe — et c'est la différence cruciale. Les coéquipiers peuvent communiquer entre eux sans tout router par le chef d'équipe. L'agent front-end peut demander directement à l'agent back-end : « Quel format utilise la réponse /users ? » L'agent back-end répond. Le travail continue. Aucun goulot d'étranglement. Quand j'ai vu ça fonctionner pour la première fois, la comparaison qui m'est venue à l'esprit n'était pas technique — elle était organisationnelle. Les sub agents, c'est comme envoyer des e-mails à trois freelances dans trois pays différents. Les agent teams, c'est comme mettre ces freelances dans un canal Slack commun. Même talent, capacité de coordination radicalement différente. Mais plus de coordination signifie aussi plus de complexité, plus de tokens et plus de façons de tout faire foirer. La configuration compte énormément — et la plupart des guides que j'ai lus passent à côté des parties qui déterminent réellement le succès ou l'échec.

Configurer les Agent Teams : La configuration qui fonctionne vraiment

Les agent teams sont expérimentaux en mars 2026 et désactivés par défaut. Anthropic a publié ceci en preview de recherche avec Claude Code v2.1.32, ce qui vous dit deux choses : c'est assez puissant pour être publié, et assez brut pour qu'ils veuillent que vous sachiez dans quoi vous vous engagez. Étape 1 : Activez la fonctionnalité. Ouvrez le settings.local.json de votre projet (ou votre fichier de paramètres global Claude Code) et ajoutez ceci :

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

Redémarrez Claude Code. C'est tout pour la configuration technique. Le feature flag donne à Claude l'accès aux outils de coordination d'équipe — créer des coéquipiers, assigner des tâches, envoyer des messages inter-agents et gérer une liste de tâches partagée. Étape 2 : Installez tmux (fortement recommandé). Vous n'avez pas strictement besoin de tmux, mais faire tourner des agent teams sans tmux, c'est comme conduire sans tableau de bord. Tmux vous permet de voir la session terminal de chaque agent simultanément — codée par couleur selon le rôle, mise à jour en temps réel. Sur macOS :

brew install tmux

Quand les agent teams sont actifs et tmux est installé, Claude Code divise automatiquement votre terminal en panneaux pour chaque coéquipier. Vous pouvez regarder l'agent front-end écrire du JSX dans un panneau pendant que l'agent back-end configure des routes Express dans un autre. C'est véritablement fascinant et pratiquement utile — vous pouvez repérer les échecs de coordination au moment où ils surviennent plutôt que de les découvrir dans le résultat final. Étape 3 : Entraînez votre projet Claude Code. C'est l'étape que la plupart des tutoriels sautent, et c'est celle qui a fait la plus grande différence pour moi. Avant de lancer votre premier agent team, importez la documentation des agent teams dans le contexte de votre projet. J'ai récupéré les concepts clés de la documentation agent teams d'Anthropic dans le fichier CLAUDE.md de mon projet — spécifiquement les sections sur les règles de propriété de fichiers, les protocoles de communication et la gestion des dépendances de tâches. Pourquoi est-ce important ? Quand Claude génère des coéquipiers, chacun démarre avec un contexte vierge. Ils ne connaissent pas automatiquement les bonnes pratiques de coordination d'agent teams. Mais si ces pratiques sont dans votre CLAUDE.md, chaque coéquipier les lit à l'initialisation. La différence de qualité de coordination est immédiate et spectaculaire. Voici la section que j'ai ajoutée à mon CLAUDE.md :

## Agent Team Rules
- Each teammate owns specific files. Never modify files owned by another agent.
- Always communicate API contracts before implementation begins.
- QA agent must receive final output from all other agents before running checks.
- Save progress to temporary files after each major milestone.

Quatre lignes. Elles préviennent environ 80 % des échecs de coordination que j'ai rencontrés pendant mes deux premières semaines. Étape 4 : Pré-approuvez les commandes courantes. Les coéquipiers d'agent team héritent des permissions de la session principale. Par défaut, ils se mettent en pause et demandent la permission à chaque fois qu'ils veulent exécuter une commande shell, écrire un fichier ou exécuter du code. Avec trois agents qui tournent simultanément, vous passerez toute votre session à cliquer sur « Approuver » au lieu de les regarder travailler. Dans les paramètres de votre projet, pré-approuvez les commandes dont vos agents auront besoin. Lectures de fichiers, écritures, commandes npm, lanceurs de tests — tout ce que votre projet exige. Les commandes spécifiques dépendent de votre stack, mais le principe est universel : supprimez le goulot d'étranglement des permissions avant de commencer, sinon vos agents « parallèles » passeront la moitié de leur temps à vous attendre.

Le Playbook de Prompts : Comment dire aux agents quoi construire

C'est ici que la plupart des gens se trompent. Ils activent les agent teams, tapent « construis-moi une appli de to-do » et se demandent pourquoi le résultat est fragmenté. La stratégie de prompts pour les agent teams est fondamentalement différente du prompting d'un agent solo, et l'écart entre un prompt médiocre et un excellent se manifeste dans le coût en tokens, la qualité du résultat et l'overhead de coordination. J'ai testé des dizaines de structures de prompts au cours des dernières semaines. Voici le pattern qui produit systématiquement les meilleurs résultats. L'anatomie d'un prompt efficace pour agent teams :

Create a team of [number] agents using [model]:
1. [Role Name] — responsible for [specific domain].
   Owns files in: [directory or file pattern].
   Deliverables: [exact outputs expected].
2. [Role Name] — responsible for [specific domain].
   Owns files in: [directory or file pattern].
   Deliverables: [exact outputs expected].
3. [Role Name] — responsible for [specific domain].
   Owns files in: [directory or file pattern].
   Deliverables: [exact outputs expected].
Communication rules:
- [Agent A] must share [specific artifact] with [Agent B] before [specific action].
- [Agent C] reviews all deliverables before the team reports completion.
Final deliverables: [list everything the team should produce].
Goal: [one sentence describing the end state].

Laissez-moi expliquer pourquoi chaque élément compte. L'attribution explicite des rôles empêche les chevauchements. Quand vous dites « développeur front-end responsable de tous les composants UI, du style et des interactions côté client », l'agent sait exactement ce qui lui appartient et — tout aussi important — ce qui ne lui appartient pas. Sans limites claires, j'ai vu deux agents décider tous les deux qu'ils devaient gérer la validation des formulaires, produisant des implémentations contradictoires dans des fichiers différents. La propriété de fichiers empêche les conflits d'écrasement. Celui-ci m'a coûté des heures avant que je comprenne. Si deux agents pensent tous les deux posséder app.js, l'un écrasera le travail de l'autre. Chaque agent doit savoir quels fichiers lui appartiennent. « L'agent front-end possède tous les fichiers dans /src/components/ et /src/styles/. » « L'agent back-end possède tous les fichiers dans /src/api/ et /src/models/. » Aucune ambiguïté. Aucun conflit. Les règles de communication explicites empêchent le problème du freelance sourd. La phrase la plus efficace que j'aie jamais mise dans un prompt d'agent team est celle-ci : « L'agent back-end doit partager le contrat d'API endpoints avec l'agent front-end avant que l'un ou l'autre ne commence l'implémentation. » Cette seule phrase élimine la catégorie de bugs où les agents construisent sur des hypothèses incompatibles. Sans elle, ils commenceront à coder immédiatement — en parallèle, à pleine vitesse, vers des destinations différentes. Les livrables créent la responsabilité. « Livrer une application fonctionnelle » est vague. « Livrer une application fonctionnelle, un rapport de tests QA couvrant tous les parcours utilisateur critiques, et un README documentant les API endpoints » est spécifique. Quand les agents savent qu'ils seront évalués sur des résultats précis, le chef d'équipe répartit le travail différemment — et l'agent QA a des critères clairs pour sa revue. Voici un prompt réel que j'ai utilisé pour le projet de landing page Neuroflow :

Create a team of 3 using Sonnet:
1. Front-End Developer — responsible for HTML structure, CSS styling,
   animations, and responsive design. Owns all .html and .css files.
   Deliverables: Complete, responsive landing page with hero section,
   features grid, pricing table, and footer.
2. Back-End Developer — responsible for JavaScript functionality,
   form handling, and any API mock endpoints. Owns all .js files.
   Deliverables: Working contact form, smooth scroll navigation,
   and dynamic pricing toggle.
3. QA Agent — responsible for testing all interactive elements,
   checking cross-browser compatibility, and verifying responsive
   breakpoints. Owns the /tests directory.
   Deliverables: Test report listing all issues found, severity ratings,
   and verification that fixes resolve each issue.
Communication rules:
- Front-End and Back-End must agree on element IDs and class names
  before implementation begins.
- QA reviews all work after initial build, sends issues back to
  responsible agents, and re-verifies after fixes.
Goal: A polished, production-quality landing page for Neuroflow,
an AI startup, that passes QA review with zero critical issues.

Ce prompt m'a pris trois itérations pour être au point. La première version ne spécifiait pas la propriété des fichiers — deux agents ont édité le même fichier HTML et écrasé le travail l'un de l'autre. La deuxième version n'incluait pas la règle de communication sur les IDs d'éléments — l'agent JavaScript a construit des event handlers ciblant des classes qui n'existaient pas dans le HTML. La troisième version, ci-dessus, a produit le résultat onze-bugs-puis-zéro-bugs que j'ai décrit en introduction. Trois à cinq agents est le sweet spot. J'ai expérimenté avec des équipes plus grandes — sept agents sur un projet ambitieux — et l'overhead de coordination est devenu écrasant. Les agents passaient plus de temps à s'échanger des messages qu'à écrire du code. La facture de tokens était astronomique. Pour la plupart des projets, un agent front-end, un agent back-end et un agent QA couvrent tout. Ajoutez un quatrième pour l'infrastructure ou le DevOps si le projet l'exige. N'allez au-delà de cinq que si vous avez véritablement cinq domaines de travail indépendants nécessitant une exécution parallèle.

Agent Teams vs. Sub Agents : Le cadre de décision que j'utilise vraiment

J'ai utilisé les deux approches sur suffisamment de projets pour avoir un modèle mental clair de quand utiliser laquelle. Ce n'est pas théorique — c'est né de l'observation de factures de tokens qui grimpaient quand je choisissais mal. Utilisez les sub agents quand :

• La tâche est ciblée et délimitée. « Analyse ce fichier. » « Écris des tests pour cette fonction. » « Génère la documentation pour cette API. »
• Les tâches sont véritablement indépendantes. Pas de décisions partagées, pas de contrats d'API à négocier, pas de fichiers que plusieurs agents pourraient toucher.
• La vitesse et le coût comptent plus que la coordination. Les sub agents sont nettement moins chers car ils éliminent complètement l'overhead de communication.
• Vous avez besoin d'un résultat rapide renvoyé à votre session principale. Les sub agents sont fire-and-forget — lancer, obtenir le résultat, continuer. Utilisez les agent teams quand :
• Le projet a plusieurs domaines spécialisés qui doivent collaborer. Un front-end React, une API Node.js et un schéma PostgreSQL ne sont pas indépendants — les décisions dans l'un affectent les autres.
• La qualité nécessite du feedback itératif. Le pattern de l'agent QA que j'ai décrit — où un agent révise et renvoie le travail pour correction — ne fonctionne qu'avec les agent teams. Les sub agents ne peuvent pas faire de boucles de qualité aller-retour.
• Vous avez besoin d'exécution parallèle AVEC coordination. Les sub agents vous donnent l'exécution parallèle. Les agent teams vous donnent l'exécution parallèle plus la communication. Le « plus la communication » coûte plus cher mais prévient les cauchemars d'intégration qui dévorent des heures de correction manuelle.
• Le projet est assez complexe pour justifier l'overhead. Mon seuil approximatif : si le projet prendrait plus de 15 minutes à un agent solo, les agent teams commencent à avoir du sens. En dessous, vous payez une taxe de coordination sur un problème qui n'en a pas besoin. N'utilisez jamais les agent teams pour :
• Les tâches simples ou séquentielles. Si une chose doit se faire avant la suivante, le parallélisme n'aide pas — il nuit.
• Les tâches nécessitant un historique de conversation unifié. Chaque coéquipier a son propre contexte. Il n'y a pas de mémoire partagée des conversations précédentes.
• Les projets avec des fichiers fortement partagés. Si chaque agent doit éditer index.html, vous allez avoir des problèmes quelle que soit la précision avec laquelle vous assignez la propriété.
• L'exploration et la planification. J'ai fait cette erreur tôt — utiliser des agent teams pour « rechercher et planifier » l'architecture d'un projet. Les agents ont dépensé tout leur budget à discuter des possibilités au lieu de construire quoi que ce soit. Utilisez un agent solo pour la planification, puis faites intervenir l'équipe pour l'exécution. La différence de coût est réelle et significative. Un agent solo peut brûler 45 000 tokens sur une appli de gestion de tâches. La même appli construite par un agent team peut atteindre 150 000-200 000 tokens — trois à quatre fois plus — car la communication inter-agents n'est pas gratuite. Chaque message entre coéquipiers consomme des tokens des deux côtés. Le cycle de revue-et-correction QA seul peut doubler la consommation totale. Pour mon travail, le calcul donne ceci : les agent teams produisent une sortie de meilleure qualité sur les projets complexes, mais le coût en tokens est 3 à 5 fois plus élevé. Je ne recours aux agent teams que lorsque la différence de qualité justifie suffisamment la dépense — projets clients, applications en production, tout ce où les bugs d'intégration coûteraient plus à corriger manuellement que les tokens supplémentaires ne coûtent à prévenir.

Les erreurs qui m'ont coûté des milliers de tokens

Je veux être honnête sur les échecs car ils m'ont appris plus que les succès. Voici les erreurs que j'ai commises pour que vous puissiez les éviter. Erreur 1 : Ne pas assigner la propriété des fichiers. Mes trois premières sessions d'agent team ont produit du code qui avait l'air correct dans le terminal de chaque agent et était complètement cassé une fois combiné. Deux agents créaient tous les deux un fichier utils.js. Un agent modifiait package.json pendant qu'un autre était en train de le lire. Le chef d'équipe essayait d'intégrer le tout et trouvait des changements conflictuels éparpillés dans le projet. La correction était d'une simplicité embarrassante : dire à chaque agent exactement quels fichiers et répertoires lui appartiennent. « Tu peux tout lire, mais tu n'écris que dans les fichiers de ton répertoire. » J'ai probablement perdu 300 000 tokens à apprendre cette leçon au fil de plusieurs sessions ratées. Erreur 2 : Laisser les agents communiquer librement sans structure. La messagerie inter-agents sans restriction semble géniale en théorie. En pratique, trois agents avec une communication libre vont passer un temps alarmant à discuter au lieu de construire. J'ai regardé un agent back-end et un agent front-end avoir un échange de sept messages sur la meilleure façon de gérer le formatage des dates avant que l'un ou l'autre n'ait écrit une seule ligne de code. Maintenant, je définis des checkpoints de communication explicites : « Partage le contrat d'API avant l'implémentation. Signale la complétion à QA après l'implémentation. N'échange pas de messages pendant l'implémentation sauf si tu es bloqué. » Cela a réduit la consommation de tokens d'environ 40 % sans réduire la qualité du résultat. Erreur 3 : Utiliser le mauvais modèle pour le mauvais rôle. Faire tourner chaque agent sur Opus 4.6 semble rassurant — c'est le modèle le plus puissant, donc tout devrait mieux fonctionner, non ? En pratique, le coût est sidérant et l'amélioration de qualité pour les tâches d'exécution est marginale. Mon attribution actuelle de modèles :

• Chef d'équipe : Opus 4.6 — il prend des décisions architecturales et coordonne des dépendances complexes. Le premium en vaut la peine.
• Agents développeurs (front-end, back-end) : Sonnet — rapide, performant et environ 5 fois moins cher par token qu'Opus. Pour écrire du code dans des limites bien définies, Sonnet performe de manière quasi identique.
• Agent QA : Sonnet ou même Haiku pour les projets plus simples — il suit des patterns de test, il n'invente pas des architectures. Le modèle le moins cher capable d'exécuter la logique de test de manière fiable. Cette approche par paliers a réduit mes coûts d'agent team d'environ 60 % par rapport à l'utilisation d'Opus partout. Erreur 4 : Ne pas pré-approuver les permissions. Avec trois agents tournant en parallèle, chacun nécessitant une approbation pour les opérations sur fichiers et les commandes shell, je suis devenu le goulot d'étranglement. Les agents restaient inactifs 30 à 60 secondes en attendant que je clique sur « Approuver » dans chaque panneau. Multipliez ça par des dizaines d'opérations par agent, et un projet qui devrait prendre cinq minutes s'étire à vingt — non pas parce que les agents sont lents, mais parce que je ne peux pas cliquer assez vite. Pré-approuvez tout ce dont vos agents ont besoin dans vos paramètres de projet ou locaux. La différence de productivité est énorme. Erreur 5 : Faire tourner des équipes sans agent QA. Mes premiers agent teams étaient composés de deux développeurs et aucun QA. La sortie était rapide mais truffée de problèmes d'intégration — des IDs qui ne correspondaient pas, des event handlers cassés, du CSS qui conflictuait entre les composants. Je faisais le QA moi-même, ce qui annulait l'intérêt d'avoir une équipe. L'ajout d'un agent QA dédié a changé la donne. Il attrape les problèmes d'intégration qui me prendraient 10-15 minutes à trouver manuellement, et la boucle revue-correction-vérification se fait sans mon intervention. L'agent QA coûte peut-être 20 000 tokens supplémentaires par session. Le temps qu'il me fait gagner vaut dix fois ça. Si vous préférez que quelqu'un configure ces configurations d'agent team de zéro — prompts optimisés, attributions de modèles, workflows QA, toute l'infrastructure — j'accepte ce type de missions. Vous pouvez voir ce que j'ai construit sur fiverr.com/s/EgxYmWD.

Patterns avancés : Approbation de plan, Monitoring Tmux et Persistance de contexte

Une fois les bases en place, trois fonctionnalités avancées feront passer votre workflow d'agent teams de bon à véritablement puissant. Mode d'approbation de plan Par défaut, les coéquipiers d'agent team se contentent de... démarrer. Ils reçoivent leur mission et commencent à exécuter immédiatement. Le mode d'approbation de plan ajoute un checkpoint : chaque agent génère un plan et attend l'approbation avant d'écrire le moindre code. L'approbateur peut être vous, le chef d'équipe, ou un agent réviseur désigné. Je l'utilise de manière sélective. Pour les projets où je connais bien l'architecture, je laisse les agents exécuter librement — la vitesse compte plus que le contrôle. Pour les terrains inconnus ou les projets clients où les erreurs sont coûteuses, l'approbation de plan me donne une porte de révision sans ralentir toute l'équipe à une exécution séquentielle. Chaque agent soumet son plan en parallèle. Je révise tous les plans simultanément. Puis ils exécutent tous en parallèle. L'overhead total est généralement inférieur à deux minutes, et ça prévient le type de divergence architecturale qui nécessite une reconstruction complète. Monitoring Tmux J'ai mentionné tmux plus tôt pour le découpage de terminal, mais le workflow de monitoring mérite plus de détails. Quand les agent teams tournent avec tmux, chaque agent obtient un panneau dédié avec un en-tête codé par couleur montrant son rôle. Vous pouvez :

• Regarder tous les agents travailler simultanément
• Cliquer dans le panneau d'un agent pour envoyer un message direct
• Observer le flux de messages entre agents en temps réel
• Repérer les problèmes bloquants avant qu'ils ne cascadent La capacité de messagerie directe est particulièrement précieuse. Si je vois l'agent front-end partir dans une direction que je sais ne marchera pas, je peux sauter dans son panneau et le rediriger sans affecter les autres agents. « Hé, utilise CSS Grid pour cette mise en page au lieu de Flexbox — les composants imbriqués auront besoin d'un alignement bidimensionnel. » L'agent s'adapte, et l'agent back-end continue de travailler sans être perturbé. Ce genre d'intervention chirurgicale n'est pas possible avec les sub agents. Il faudrait annuler le sub agent, réécrire le prompt et relancer — en perdant tout le travail déjà effectué. Persistance de contexte via des fichiers temporaires Les agent teams ont une vulnérabilité qui m'a touché deux fois : si un agent plante ou que la session tombe, tout travail non écrit sur le disque est perdu. Le context window de l'agent s'évapore, et le chef d'équipe n'a pas de copie du travail en cours. Ma solution de contournement : instruire les agents de sauvegarder leur progression dans des fichiers temporaires après chaque étape importante. « Après avoir complété le composant header, sauvegarde ta progression dans /tmp/frontend-checkpoint-1.md avec un résumé de ce qui est fait et de ce qui reste. » Si un agent meurt en pleine session, l'agent de remplacement lit le fichier de checkpoint et reprend là où le précédent s'est arrêté au lieu de repartir de zéro. Ça ajoute peut-être 5 % à votre consommation de tokens et m'a sauvé de deux redémarrages complets d'équipe. Le premier redémarrage, avant que j'implémente les checkpoints, m'a coûté environ 180 000 tokens de travail dupliqué.

Le modèle mental qui fait tout se mettre en place

Après des semaines d'expérimentation, j'ai trouvé une façon de penser les agent teams qui prédit quand ils fonctionneront bien et quand ils échoueront. Elle vient du management d'équipe réel, pas de la théorie de l'AI. Les agent teams suivent les mêmes règles que les équipes d'ingénierie humaines : La loi de Brooks s'applique. Ajouter plus d'agents à un projet augmente l'overhead de communication de manière quadratique. Trois agents ont trois canaux de communication. Cinq agents en ont dix. Sept agents en ont vingt et un. Le coût de coordination ne croît pas linéairement — il explose. Gardez les équipes petites. Trois à cinq agents. Pas plus. La loi de Conway s'applique. La structure de votre agent team sera reflétée dans la structure du code qu'ils produisent. Si vous avez un agent front-end et un agent back-end, vous obtiendrez un front-end et un back-end clairement séparés. Si vous avez un agent qui gère « UI et API » ensemble, vous obtiendrez du code fortement couplé. Concevez la structure de votre équipe pour qu'elle corresponde à l'architecture que vous voulez. Le mythe du mois-homme s'applique. Deux agents ne produisent pas deux fois plus vite qu'un seul pour chaque tâche. Sur certaines tâches — séquentielles, fortement couplées, nécessitant un contexte partagé — deux agents sont plus lents qu'un seul à cause de l'overhead de coordination. Les agent teams excellent quand le travail est véritablement parallélisable avec des frontières de domaine claires. L'implication pratique : avant de lancer un agent team, esquissez le projet sous forme de graphe de dépendances. Si vous avez trois flux de travail indépendants ou plus qui doivent finalement s'intégrer, les agent teams ont du sens. Si le travail est fondamentalement séquentiel ou que tout dépend de tout, utilisez un agent solo. J'ai commencé à me poser une question simple avant chaque projet : « Pourrais-je expliquer ça à trois freelances séparés dans trois pièces séparées et obtenir un résultat cohérent ? » Si oui, agent teams. Si non, agent solo ou sub agents avec une intégration soigneuse.

Ce que je construis actuellement — et ce qui arrive ensuite

En ce moment, j'utilise les agent teams pour presque chaque projet ayant plus de deux points d'intégration. Le workflow s'est stabilisé en un pattern : je planifie avec une session solo Opus, je configure la propriété des fichiers et les règles de communication, puis je lance une équipe de 3-4 agents Sonnet pour l'exécution pendant qu'un agent QA surveille la sortie. Les résultats parlent à travers le processus, pas à travers le battage médiatique. Mes landing pages reviennent plus propres parce que l'agent QA attrape des choses que je manquerais à 2h du matin. Mes builds full-stack s'intègrent du premier coup parce que les agents négocient les contrats d'API avant d'écrire du code. Mes sessions de debugging sont plus rapides parce que je peux avoir trois agents qui testent trois hypothèses différentes simultanément au lieu de les tester séquentiellement. La fonctionnalité n'est pas parfaite. La stabilité des sessions peut être capricieuse — j'ai eu des agents qui se déconnectaient en pleine tâche sur de longues sessions. Le coût en tokens est véritablement élevé pour les projets complexes. Et la précision de prompts requise signifie qu'il y a une courbe d'apprentissage plus raide que ce que la documentation d'Anthropic laisse entendre. Mais voici ce qui m'a convaincu que c'est l'avenir du développement assisté par l'AI, pas juste une fonctionnalité : le pattern de collaboration lui-même. Regarder un agent QA trouver des bugs, les envoyer au développeur responsable, recevoir les corrections et vérifier les résolutions — le tout sans mon intervention — ce n'est pas juste de l'automatisation. C'est une équipe. Une équipe qui se trouve être composée d'AI, mais une équipe néanmoins, avec les mêmes dynamiques de communication, de responsabilité et d'amélioration itérative de la qualité qui rendent les équipes d'ingénierie humaines efficaces. Les outils deviendront moins chers et plus stables. Les modèles deviendront plus rapides et plus intelligents. Mais le pattern — des agents spécialisés collaborant à travers une communication structurée sur des objectifs partagés — ce pattern est permanent. L'apprendre maintenant signifie que vous construisez une compétence qui se démultiplie avec chaque amélioration qu'Anthropic déploie. Si vous faites encore tout passer par un agent solo et vous demandez pourquoi les projets complexes ressemblent à pousser un rocher en haut d'une colline, essayez ceci : prenez votre prochain projet multi-composants, définissez trois rôles avec une propriété de fichiers claire, ajoutez un agent QA, et écrivez une règle de communication. Juste une. « Convenez du contrat d'API avant d'écrire du code. » Et observez ce qui se passe.

Foire aux questions

Comment activer les Claude Code agent teams ?

Ajoutez "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" à l'objet env dans le fichier settings.local.json de votre projet et redémarrez Claude Code. Vous avez besoin de Claude Code v2.1.32 ou ultérieur, disponible avec les forfaits Pro (20 $/mois) ou Max (100-200 $/mois).

Combien d'agents dois-je utiliser dans une équipe ?

Trois à cinq agents est le sweet spot pour la plupart des projets. Au-delà de cinq, l'overhead de communication inter-agents croît de manière quadratique et les coûts en tokens escaladent. Une équipe efficace typique comprend un agent front-end, un agent back-end et un agent QA. Pour un regard plus approfondi sur la sélection de modèles par rôle, consultez mon guide des Claude agent teams.

Quelle est la différence entre les agent teams et les sub agents ?

Les sub agents tournent indépendamment, complètent une tâche et renvoient les résultats à l'agent principal — ils ne peuvent pas communiquer entre eux. Les agent teams disposent d'une liste de tâches partagée, de messagerie directe inter-agents et d'un chef d'équipe qui coordonne le travail parallèle avec des boucles de feedback itératives. Les sub agents sont moins chers et plus rapides ; les agent teams produisent une sortie de meilleure qualité sur les projets complexes et multi-domaines.

Les agent teams coûtent-ils plus de tokens qu'un agent solo ?

Oui, significativement. Une tâche qui coûte 45 000 tokens avec un agent solo coûte typiquement 150 000-200 000 tokens avec un agent team en raison de l'overhead de communication inter-agents. Réduisez les coûts en utilisant Sonnet ou Haiku pour les agents d'exécution et en réservant Opus uniquement pour le chef d'équipe.

Les coéquipiers d'agent team peuvent-ils accéder à mes fichiers de projet et outils ?

Tous les coéquipiers héritent des permissions de la session principale, y compris l'accès au système de fichiers, l'exécution de commandes, les serveurs MCP et les skills. Vous ne pouvez pas accorder des niveaux de permission différents à différents coéquipiers — ils partagent tous la même configuration d'accès.

Travaillons ensemble

Vous cherchez à construire des systèmes d'AI, automatiser des workflows ou faire évoluer votre infrastructure technologique ? Ce serait un plaisir de vous aider.

• Fiverr (développements sur mesure et intégrations) : 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