Claude Code Team Agents : Orchestrer une Équipe d'IA en Parallèle

Mis à jour le 3 mars 2026

Les sub-agents, c'est de la délégation simple. Les Team Agents, c'est une équipe entière d'IA qui travaille en parallèle sur ton projet. Un leader qui coordonne, des workers qui exécutent, des tâches partagées, de la messagerie entre agents. C'est l'orchestration multi-agents — et c'est la fonctionnalité la plus avancée de Claude Code.

Imagine que tu dois implémenter une feature full-stack : des composants UI, une API backend, et des tests d'intégration. Au lieu de tout faire séquentiellement — front, puis back, puis tests — tu lances une équipe de 3 agents. Chacun prend une partie. Ils avancent en même temps, se coordonnent via une task list partagée, et le leader supervise l'ensemble. Le temps total ? Divisé par 3, ou presque. C'est ça, l'orchestration multi-agents.

C'est quoi un Team Agent

Un Team Agent est un système multi-agents où plusieurs instances de Claude Code travaillent simultanément, coordonnées par un leader. Chaque agent a son propre contexte, ses propres outils, et communique avec les autres via messagerie et task lists partagées.

La distinction avec les sub-agents est fondamentale. Un sub-agent, c'est une instance unique que Claude Code lance pour déléguer une sous-tâche. Le sub-agent fait son travail, retourne le résultat, et disparaît. C'est une relation parent-enfant simple, séquentielle. Le sub-agent n'a pas conscience des autres sub-agents. Il n'y a pas de communication latérale.

Un Team Agent, c'est un tout autre paradigme. Tu as un leader (le chef d'équipe) et plusieurs workers (les exécutants). Chaque worker est une session Claude Code complète avec son propre contexte, sa propre mémoire, ses propres outils. Ils tournent en parallèle — véritablement en même temps — et se coordonnent via deux mécanismes : une task list partagée et un système de messagerie directe.

En termes concrets : un sub-agent, c'est comme envoyer un collègue faire une course pendant que tu attends. Un team agent, c'est comme avoir une équipe de 3-4 développeurs qui bossent simultanément sur des parties différentes du même projet, avec un chef de projet qui distribue les tâches et synchronise tout le monde.

Le leader crée l'équipe avec le tool TeamCreate, distribue les tâches avec TaskCreate, et les workers les exécutent. Quand un worker finit, il envoie un message au leader avec SendMessage. Le leader peut alors assigner de nouvelles tâches ou décider que le travail est terminé. C'est un cycle de coordination continu, pas une délégation ponctuelle.

Le pattern Leader + Workers

Le pattern central des Team Agents, c'est le pattern Leader + Workers. Comprends-le bien, parce que c'est sur ce modèle que toute l'orchestration repose.

Étape 1 : Le leader crée l'équipe

Tout commence par le leader. Quand tu demandes à Claude Code une tâche complexe qui justifie une équipe (on verra les critères plus bas), il crée une team avec TeamCreate. Cette commande lance plusieurs sessions Claude Code en parallèle, chacune avec un rôle défini. Le leader donne un nom à l'équipe et définit les workers nécessaires.

Étape 2 : Le leader crée et assigne les tâches

Avec TaskCreate, le leader définit les tâches à accomplir. Chaque tâche a un titre, une description, et un owner (le worker assigné). Le leader peut aussi utiliser TaskUpdate pour modifier une tâche existante — changer son statut, réassigner, ajouter des détails. C'est le leader qui a la vision d'ensemble du projet.

Étape 3 : Les workers exécutent

Chaque worker récupère ses tâches assignées et les exécute de manière autonome. Un worker frontend va créer des composants React. Un worker backend va implémenter des endpoints API. Un worker tester va écrire des tests. Ils travaillent en parallèle, chacun dans son propre contexte, sans interférer avec les autres.

Étape 4 : Communication au leader

Quand un worker termine une tâche, il envoie un message au leader via SendMessage. Le message contient le résultat, les fichiers modifiés, les éventuels problèmes rencontrés. Le leader reçoit le message et peut réagir : valider, demander des corrections, ou assigner la tâche suivante.

Étape 5 : Le leader ajuste et redistribue

C'est là que la coordination prend tout son sens. Le leader analyse les résultats des workers, identifie les dépendances (le tester a besoin que le backend soit fini avant de tester les endpoints), et redistribue le travail en conséquence. Il peut créer de nouvelles tâches, modifier les priorités, ou débloquer un worker qui attendait.

Étape 6 : Les workers passent en idle entre les tours

Un point important : les workers passent en état idle entre leurs tâches. C'est normal. Un worker qui a fini sa tâche et envoyé son message attend que le leader lui assigne du nouveau travail. Ce n'est pas un bug, c'est le fonctionnement attendu. L'idle state permet au leader de garder le contrôle de la coordination.

Étape 7 : Shutdown

Quand toutes les tâches sont terminées, le leader envoie un shutdown_request à chaque worker via SendMessage. Le worker peut approuver (il s'arrête proprement) ou refuser (s'il est en train de finir quelque chose). Une fois tous les workers arrêtés, le leader compile les résultats et te donne le rapport final.

La Task List partagée

La task list, c'est le point de synchronisation central de l'équipe. Sans elle, les agents seraient des instances isolées sans moyen de savoir ce qui se passe ailleurs. Avec elle, ils ont une vue partagée de l'avancement du projet.

Où vivent les tâches

Les tâches sont stockées dans ~/.claude/tasks/{nom-de-l-equipe}/. Chaque équipe a son propre répertoire de tâches. Quand tu lances une nouvelle team, un nouveau répertoire est créé automatiquement. Les tâches sont des fichiers JSON que chaque agent peut lire et modifier.

Les états d'une tâche

Chaque tâche passe par un cycle de vie simple :

• pending — La tâche est créée mais personne ne l'a encore prise. Elle attend d'être assignée ou réclamée par un worker.
• in_progress — Un worker travaille dessus. Les autres agents voient que cette tâche est en cours et par qui.
• completed — Le travail est fait. Le worker a marqué la tâche comme terminée et envoyé le résultat au leader.

Création et mise à jour

N'importe quel agent peut créer une tâche avec TaskCreate. En pratique, c'est surtout le leader qui crée les tâches, mais un worker peut aussi en créer s'il découvre qu'un travail supplémentaire est nécessaire. La mise à jour se fait avec TaskUpdate : changer le statut, modifier la description, réassigner à un autre worker.

Blocage et déblocage

Une tâche peut être marquée comme bloquée — par exemple, le tester ne peut pas écrire les tests d'intégration tant que les endpoints backend n'existent pas. Quand la dépendance est résolue, le leader ou le worker concerné débloque la tâche. Ce mécanisme évite qu'un worker tourne dans le vide en essayant de travailler sur quelque chose qui n'est pas encore possible.

La règle d'or

Après avoir terminé chaque tâche, un worker devrait vérifier la task list avec TaskList pour voir s'il y a de nouvelles tâches assignées, des tâches débloquées, ou des changements de priorité. C'est ce comportement qui maintient la coordination fluide dans l'équipe.

La messagerie inter-agents

La task list gère la coordination des tâches. La messagerie gère la coordination humaine — les discussions, les questions, les signalements. Les deux sont complémentaires.

SendMessage — messages directs

Le tool SendMessage permet à n'importe quel agent d'envoyer un message direct à un autre agent de l'équipe. Le message est livré automatiquement. Le destinataire le reçoit dans son contexte et peut y répondre. C'est le canal principal de communication entre le leader et les workers.

Cas d'usage typiques : un worker signale qu'il a terminé sa tâche, un worker demande une clarification au leader, le leader donne des instructions complémentaires, un worker signale un blocage technique.

Broadcast — annonces globales

Le broadcast envoie un message à tous les agents de l'équipe en même temps. C'est utile pour les annonces qui concernent tout le monde : changement de priorité, décision architecturale, information contextuelle importante. Mais attention — chaque broadcast consomme des tokens sur chaque agent destinataire. Utilise-le avec parcimonie.

L'état idle est normal

Un agent qui attend un message est en état idle. C'est le fonctionnement normal, pas un problème. Le worker a fini sa tâche, a envoyé son rapport au leader, et attend les prochaines instructions. Pendant ce temps, il ne consomme pas de tokens. L'idle state est le mécanisme qui permet au pattern Leader + Workers de fonctionner : sans pause, les workers tourneraient en boucle sans direction.

Le protocole de shutdown

Quand le travail est terminé, le leader envoie un shutdown_request au worker via SendMessage. Le worker reçoit le message et peut répondre de deux manières :

• Approbation — Le worker confirme qu'il peut s'arrêter. Il fait ses dernières sauvegardes et se termine proprement.
• Refus — Le worker indique qu'il est encore en train de finir quelque chose de critique. Le leader attend et retente plus tard.

Ce protocole évite de couper un agent en plein milieu d'une opération d'écriture de fichier ou d'une commande système. C'est un arrêt gracieux, pas un kill brutal.

Quand utiliser des Team Agents

Les Team Agents sont puissants, mais ils ne sont pas la bonne solution pour tout. Chaque agent est une session complète qui consomme des tokens et du contexte. Utilise-les quand c'est justifié, pas par réflexe.

Bon usage : tâches parallélisables

La règle d'or : si le travail peut véritablement être fait en parallèle, une team a du sens. Voici les cas classiques :

• Feature full-stack — Frontend (composants, pages, styles), backend (API, base de données, logique métier), et tests (unitaires, intégration) peuvent avancer en même temps. 3 workers, un leader qui coordonne.
• Refactoring large-scale — Quand tu dois refactorer 10+ fichiers répartis dans des modules indépendants, tu peux assigner chaque module à un worker différent. Le leader s'assure que les interfaces entre modules restent compatibles.
• Tâches multi-domaines — Migration de base de données + mise à jour de l'API + adaptation du frontend. Trois domaines, trois workers, un leader qui gère les dépendances.
• Audit + correction — Un worker fait l'audit de sécurité, un autre corrige les vulnérabilités identifiées, un troisième vérifie que les corrections n'ont rien cassé.

Mauvais usage : ne pas en abuser

Les teams ne sont PAS adaptées pour :

• Tâches séquentielles — Si chaque étape dépend de la précédente, une team n'apporte rien. Tu payes 3 agents pour un travail qui ne peut pas être parallélisé. Utilise un seul agent ou des sub-agents à la place.
• Modifications simples — Modifier 1-2 fichiers ne justifie pas une équipe. Un seul agent fait ça très bien.
• Tâches exploratoires — Explorer un codebase, comprendre une architecture, planifier une approche. C'est du travail de réflexion qui se fait mieux avec un seul agent concentré.
• Budget limité — Une team de 3 agents coûte ~3x plus qu'un seul agent. Si ton budget tokens est serré, privilégie un agent unique bien configuré.

Le critère décisif : est-ce que les parties du travail sont véritablement indépendantes ? Si oui, team. Si non, un seul agent avec des sub-agents suffit. Pour un panorama complet de ces choix, le guide complet Claude Code détaille toute la hiérarchie de délégation.

Exemple concret : refactoring multi-modules

Passons à un cas réel. Tu as un projet Next.js avec trois modules indépendants : un module d'authentification, un module de facturation, et un module de notifications. Chacun utilise une ancienne convention de nommage que tu veux moderniser. Les modules n'ont pas de dépendances entre eux — parfait pour une team.

Le leader analyse et planifie

Tu demandes à Claude Code : "Refactore les trois modules auth, billing et notifications pour utiliser la nouvelle convention camelCase. Utilise une équipe." Le leader analyse le codebase, identifie les fichiers de chaque module, et crée la team.

// Le leader crée l'équipe
TeamCreate({ name: "refactoring-team", workers: ["auth-dev", "billing-dev", "notif-dev"] })

// Le leader crée les tâches
TaskCreate({
  title: "Refactor module auth",
  description: "Renommer toutes les fonctions et variables en camelCase dans src/auth/",
  owner: "auth-dev"
})
TaskCreate({
  title: "Refactor module billing",
  description: "Renommer toutes les fonctions et variables en camelCase dans src/billing/",
  owner: "billing-dev"
})
TaskCreate({
  title: "Refactor module notifications",
  description: "Renommer toutes les fonctions et variables en camelCase dans src/notifications/",
  owner: "notif-dev"
})

Les workers exécutent en parallèle

Chaque worker reçoit sa tâche et commence immédiatement. Le worker auth-dev parcourt src/auth/, identifie toutes les fonctions et variables à renommer, et applique les changements. En même temps, billing-dev fait la même chose dans src/billing/, et notif-dev dans src/notifications/. Les trois travaillent simultanément, sans se gêner, parce que les modules sont indépendants.

Communication au leader

Quand auth-dev termine, il envoie un message :

SendMessage({
  to: "leader",
  content: "Module auth refactoré. 23 fichiers modifiés, 47 renommages. Aucun conflit détecté. Tests existants mis à jour."
})

Le leader reçoit le message, note que auth-dev est disponible. billing-dev finit ensuite, puis notif-dev. Le leader a le statut de chaque tâche en temps réel via la task list partagée.

Le leader vérifie et finalise

Une fois les trois tâches terminées, le leader crée une dernière tâche : vérifier que les imports entre modules fonctionnent toujours (au cas où un module importerait une fonction d'un autre). Il peut assigner cette vérification à n'importe quel worker disponible, ou la faire lui-même.

TaskCreate({
  title: "Vérification cross-modules",
  description: "Vérifier que les imports entre auth, billing et notifications sont cohérents après refactoring",
  owner: "auth-dev"
})

Une fois la vérification passée, le leader envoie les shutdown_requests et te présente le résultat final : 3 modules refactorés en parallèle, avec un rapport détaillé des changements.

Ce scénario illustre la force des Team Agents : un travail qui aurait pris 30 minutes séquentiellement est fait en ~12 minutes en parallèle. Le coût en tokens est plus élevé, mais le gain de temps est réel. Pour les projets en entreprise où le temps est le facteur critique, c'est un avantage considérable — et c'est un pattern qu'on retrouve dans les déploiements Claude Code en équipe.

Si tu utilises déjà Claude Code en mode headless pour la CI/CD, les Team Agents s'intègrent naturellement dans des pipelines automatisés où plusieurs tâches de review, test et déploiement tournent en parallèle.

Pour ceux qui débutent et veulent d'abord maîtriser les fondamentaux avant de passer au multi-agents, le guide Claude Code pour entrepreneurs est le meilleur point de départ. Et si tu combines Claude Code avec n8n pour des solutions complètes, les Team Agents ouvrent la porte à des architectures d'automatisation encore plus puissantes.

Meydeey — Architecte IA & Automatisation

+110 entrepreneurs formés au Vibe Coding et à l'automatisation IA avec N8N. Fondateur du Labo IA.