Guide complet de Claude Agent Teams

Introduction

Si vous avez utilisé les Subagents de Claude Code, vous avez probablement trouvé le développement parallèle déjà assez puissant. Mais les Subagents ont une limitation : ils ne peuvent que rapporter leurs résultats à l'Agent principal, sans pouvoir communiquer entre eux.

Agent Teams change complètement la donne. Imaginez : un Agent se charge de l'audit de sécurité, un autre de l'optimisation des performances, un troisième de la couverture de tests — non seulement ils travaillent en parallèle, mais ils peuvent aussi dialoguer directement, se challenger mutuellement et parvenir à un consensus. C'est la valeur fondamentale d'Agent Teams.

Comprendre Agent Teams

L'architecture d'Agent Teams ressemble à une véritable équipe de développement :

┌─────────────────────────────────────────────────────────┐
│                    Vous (utilisateur)                     │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                    Team Lead                             │
│        (Instance Claude principale, coordinateur)        │
└─────────────────────────────────────────────────────────┘
         │              │              │
         ▼              ▼              ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ Teammate 1  │  │ Teammate 2  │  │ Teammate 3  │
│ Audit sécu. │◄─►│ Optim. perf.│◄─►│ Couv. tests │
└─────────────┘  └─────────────┘  └─────────────┘
         │              │              │
         └──────────────┼──────────────┘
                        ▼
              ┌─────────────────┐
              │ Liste de tâches │
              │    partagée     │
              └─────────────────┘

Différences avec les Subagents

En résumé : les Subagents sont des sous-traitants envoyés exécuter des tâches, tandis qu'Agent Teams est une équipe projet collaborant dans la même pièce.

Pourquoi Agent Teams fonctionne

L'intuition fondamentale : la spécialisation apporte la concentration.

Lorsqu'un seul Agent traite des tâches complexes à plusieurs étapes, le contexte gonfle continuellement, nécessitant fréquemment un /clear pour réinitialiser. Agent Teams permet à chaque Teammate de conserver un domaine de spécialisation étroit, un contexte propre et des performances plus stables.

Activer Agent Teams

Agent Teams est actuellement une fonctionnalité expérimentale, désactivée par défaut. Vous devez l'activer manuellement :

Méthode 1 : Variable d'environnement

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Méthode 2 : settings.json (recommandée, persistante)

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

Utilisation de base

Créer votre première Agent Team

Une fois activée, il suffit de demander à Claude en langage naturel de créer une équipe :

Crée une agent team pour examiner la PR #142.
Génère trois examinateurs :
- Un spécialisé dans les problèmes de sécurité
- Un qui vérifie l'impact sur les performances
- Un qui valide la couverture des tests
Qu'ils examinent chacun et rapportent leurs découvertes.

Mots-clés : Utilisez "create an agent team" ou "spawn an agent team". Si vous dites simplement "spawn agents", cela peut confondre Subagent et Agent Teams.

Modes d'affichage

Agent Teams prend en charge deux modes d'affichage :

Le mode par défaut est auto : si vous êtes dans tmux, il utilise les split panes, sinon le mode in-process.

Configuration du mode d'affichage :

{
  "teammateMode": "in-process"
}

Spécification pour une seule session :

claude --teammate-mode in-process

Raccourcis clavier courants

Delegate Mode (important)

Le Delegate Mode est l'une des fonctionnalités les plus importantes d'Agent Teams :

Pourquoi le Delegate Mode est-il nécessaire :

Sans cette restriction, le Lead a souvent tendance à « accaparer le travail » — alors que trois Teammates attendent de travailler, le Lead commence à coder lui-même. Avec le Delegate Mode activé, le Lead est contraint de jouer un rôle de pur chef de projet, se limitant à gérer les tâches, communiquer avec les Teammates et examiner les résultats.

# Après le lancement de l'équipe, appuyez immédiatement sur Shift+Tab pour activer

Cas pratiques

Cas 1 : Revue de code parallèle

Un seul examinateur a tendance à approfondir un seul type de problème. En séparant les dimensions d'examen en domaines indépendants, la sécurité, les performances et la couverture des tests reçoivent tous une attention égale :

Crée une agent team pour examiner cette PR. Génère trois examinateurs :
- Examinateur sécurité : vérifie l'authentification, l'autorisation, les vulnérabilités d'injection
- Examinateur performance : analyse la complexité algorithmique, les requêtes de base de données, les stratégies de cache
- Examinateur tests : valide la couverture des tests, les cas limites, la gestion d'erreurs

Qu'ils examinent chacun puis discutent des problèmes trouvés entre eux.

Cas 2 : Débogage par hypothèses concurrentes

Lorsque la cause première est inconnue, un Agent unique a tendance à s'arrêter dès qu'il trouve une explication apparemment plausible. Laisser les Teammates se challenger mutuellement évite ce problème :

L'utilisateur signale que l'application se ferme après l'envoi d'un message,
au lieu de maintenir la connexion.

Génère 5 agent teammates pour investiguer différentes hypothèses.
Qu'ils discutent entre eux, tentent de réfuter les théories des autres,
comme un débat scientifique. Mettez à jour le rapport d'investigation
avec les conclusions ayant fait l'objet d'un consensus.

Mécanisme clé : La structure de débat. Plusieurs enquêteurs indépendants tentent activement de réfuter les théories des autres — les hypothèses qui survivent ont plus de chances d'être la véritable cause première.

Cas 3 : Production de contenu en masse

Application typique pour des tâches non techniques — transformer une entrée en plusieurs sorties :

Crée une agent team pour transformer ce script vidéo en contenu pour quatre plateformes :
- Rédacteur d'article LinkedIn
- Rédacteur de thread Twitter
- Rédacteur de newsletter
- Rédacteur d'article de blog

Emplacement du script : /content/scripts/video-20.md

Chaque Teammate crée de manière indépendante tout en maintenant la cohérence du contenu.

Cas 4 : Groupe d'assurance qualité

Un contrôle qualité de site de blog, déployant 5 Agents testant différents aspects en parallèle :

Crée une agent team pour un contrôle qualité complet du blog :
- Agent 1 : Test des pages principales (accueil, à propos, contact)
- Agent 2 : Test des pages d'articles (rendu, navigation, métadonnées SEO)
- Agent 3 : Vérification des liens (liens internes, liens externes, liens morts)
- Agent 4 : Validation SEO (titres, descriptions, données structurées)
- Agent 5 : Tests d'accessibilité (labels ARIA, contraste, navigation au clavier)

Générez un rapport de problèmes classés par priorité.

Résultat : Un contrôle complet réalisé en quelques minutes, là où il aurait fallu une exécution séquentielle manuelle. Chaque Agent se concentre sur son domaine, et les résultats sont consolidés en une liste de problèmes classés par priorité.

Cas 5 : Mode de discussion multi-tours

Un pattern de prompt utile — faire discuter les Teammates comme en réunion :

Utilise Agent Teams pour créer 4 teammates qui discutent de [décision technique],
en 3 tours de discussion. Que les teammates échangent entre eux à chaque tour.
Un des teammates est spécifiquement chargé de la perspective Red Team,
pour formuler des critiques.

Ce mode est particulièrement adapté aux décisions d'architecture, aux choix technologiques et à d'autres scénarios nécessitant une évaluation multi-perspectives.

Cas 6 : Projet de compilateur C

Anthropic a utilisé 16 Agents pour construire de zéro un compilateur C capable de compiler le noyau Linux :

Résultat final : un compilateur Rust capable de construire un Linux 6.9 amorçable sur x86, ARM et RISC-V.

Gestion d'équipe

Spécifier les Teammates et le modèle

Claude décide automatiquement du nombre de Teammates à générer selon la tâche, mais vous pouvez également le spécifier explicitement :

Crée 4 teammates pour refactoriser ces modules en parallèle.
Chaque teammate utilise le modèle Sonnet.

Demander l'approbation du plan

Pour les tâches complexes ou à haut risque, vous pouvez demander aux Teammates de préparer un plan avant l'exécution :

Génère un teammate architecte pour refactoriser le module d'authentification.
Avant toute modification, exige l'approbation du plan.

Le Teammate, une fois son plan terminé, envoie une demande d'approbation au Lead. Le Lead peut alors approuver ou renvoyer avec des commentaires.

Communiquer directement avec les Teammates

Chaque Teammate est une session Claude Code complète. Vous pouvez envoyer un message directement à n'importe quel Teammate :

• Mode in-process : Basculez avec Shift+Down, puis saisissez votre message
• Mode split-pane : Cliquez directement sur le volet correspondant

Fermer des Teammates

Demande au teammate d'audit de sécurité de se fermer

Le Lead envoie une demande de fermeture ; le Teammate peut l'accepter ou la refuser (en expliquant pourquoi).

Nettoyer l'équipe

Une fois terminé, demandez au Lead de nettoyer les ressources :

Nettoie l'équipe

Important : Passez toujours par le Lead pour le nettoyage. Ne laissez pas les Teammates effectuer le nettoyage, car cela pourrait entraîner des incohérences d'état des ressources.

Bonnes pratiques

Contrôle de la taille de l'équipe

Recommandations de taille :

Règle générale : Attribuer 5-6 tâches par Teammate est un bon équilibre. Si vous avez 15 tâches indépendantes, 3 Teammates constituent un bon point de départ.

Granularité des tâches

• Trop petite : Les coûts de coordination dépassent les bénéfices
• Trop grande : Les Teammates travaillent trop longtemps sans point de contrôle, augmentant le risque de gaspillage
• Idéale : Des unités de travail indépendantes et complètes avec des résultats clairs (une fonction, un fichier de test, un rapport de revue)

Éviter les conflits de fichiers

Deux Teammates modifiant le même fichier provoquent des écrasements. Lors de la répartition du travail, assurez-vous que chaque Teammate est responsable d'un ensemble de fichiers différent :

Teammate 1 : responsable du répertoire src/auth/
Teammate 2 : responsable du répertoire src/api/
Teammate 3 : responsable du répertoire src/utils/

Surveillance et orientation

Vérifiez régulièrement la progression des Teammates et corrigez la direction si nécessaire. Laisser l'équipe fonctionner sans supervision trop longtemps augmente le risque de gaspillage.

Si le Lead commence à implémenter des tâches lui-même au lieu d'attendre les Teammates :

Attends que tes teammates aient terminé leurs tâches avant de continuer

Fournir suffisamment de contexte

Les Teammates chargent automatiquement le contexte du projet (CLAUDE.md, serveurs MCP, Skills), mais n'héritent pas de l'historique de conversation du Lead. Fournissez suffisamment de détails lors de la génération :

Génère un teammate d'audit de sécurité avec ce prompt :
"Audite les vulnérabilités de sécurité du module d'authentification dans src/auth/.
Concentre-toi sur la gestion des tokens, la gestion des sessions, la validation des entrées.
L'application utilise des tokens JWT stockés dans des cookies httpOnly.
Rapporte les découvertes avec un niveau de gravité."

Mode de vérification par auto-rapport

Incluez des critères de vérification clairs dans la description de la tâche pour que les Teammates s'auto-évaluent une fois terminé :

À la fin de la tâche, rapporte au Lead :
1. Quels fichiers tu as examinés
2. Quels problèmes tu as trouvés
3. Quelles modifications tu as apportées
4. Si les critères de validation (tests passés, lint sans avertissement, etc.) sont satisfaits

Ce mode réduit la charge de vérification du Lead tout en s'assurant que la tâche est réellement terminée et pas seulement « apparemment terminée ».

Techniques avancées

Utiliser les Hooks pour imposer des portes qualité

Imposez des règles via les Hooks lorsque les Teammates terminent leur travail :

{
  "hooks": {
    "TeammateIdle": [
      {
        "command": "your-validation-script.sh"
      }
    ],
    "TaskCompleted": [
      {
        "command": "your-quality-check.sh"
      }
    ]
  }
}

• TeammateIdle : S'exécute quand un Teammate est sur le point de devenir inactif. Renvoyer le code de sortie 2 envoie un retour et fait continuer le Teammate
• TaskCompleted : S'exécute quand une tâche est marquée comme terminée. Renvoyer le code de sortie 2 bloque la complétion et envoie un retour

Pré-approbation des permissions

Les demandes de permissions des Teammates remontent au Lead, ce qui peut causer des interruptions fréquentes. Pré-approuvez les opérations courantes avant la génération :

{
  "permissions": {
    "allow": [
      "Read(*)",
      "Write(src/**)",
      "Bash(npm test)"
    ]
  }
}

Combinaison avec Worktree

Agent Teams peut être utilisé conjointement avec Worktree, chaque Teammate travaillant dans son propre worktree :

Crée une agent team, chaque teammate travaille dans un worktree indépendant,
pour éviter les conflits de fichiers.

Outils d'orchestration tiers

En plus d'Agent Teams natif, la communauté a développé des outils d'orchestration :

Ces outils offrent des alternatives en dehors de la fonctionnalité expérimentale Agent Teams, mais nécessitent davantage de configuration manuelle. Si Agent Teams natif répond à vos besoins, il est recommandé de privilégier la fonctionnalité officielle.

Limitations actuelles

Agent Teams est encore une fonctionnalité expérimentale ; il est important d'en connaître les limitations :

Considérations de coût

La consommation de tokens d'Agent Teams est significativement plus élevée qu'une session unique :

Analyse des coûts :

• Chaque Teammate est une instance Claude totalement indépendante, avec son propre contexte
• La communication entre Teammates consomme également des tokens
• Le Lead doit coordonner tous les Teammates, ce qui ajoute des frais supplémentaires

Quand cela en vaut la peine :

• Tâches de recherche nécessitant une exploration parallèle
• Revues multi-perspectives (sécurité, performances, tests)
• Décisions nécessitant discussion et consensus
• Pas pour les tâches routinières pouvant être effectuées séquentiellement
• Pas pour les tâches parallèles ne nécessitant pas de communication mutuelle (les Subagents sont plus économiques)

Mon retour d'expérience

Quand utiliser Agent Teams

Mes critères de décision :

1. La tâche nécessite plusieurs perspectives : Expertise de domaines différents (sécurité + performances + tests)
2. Discussion et consensus nécessaires : Hypothèses concurrentes, décisions d'architecture
3. L'exploration parallèle apporte de la valeur : Comparaison de plusieurs approches d'implémentation

Si vous avez uniquement besoin d'exécution parallèle sans communication mutuelle, les Subagents ou Worktree sont plus adaptés.

Commencez par la recherche et la revue

Si vous débutez avec Agent Teams, commencez par des tâches qui ne nécessitent pas d'écriture de code : revue de PR, recherche de solutions techniques, investigation de bugs. Ces tâches ont des limites claires, démontrent la valeur de l'exploration parallèle et évitent les défis de coordination liés à l'implémentation parallèle.

Combinaison avec d'autres fonctionnalités

Conclusion

Agent Teams représente un nouveau paradigme du développement assisté par IA : du « un assistant IA » à « une équipe IA ».

Anthropic a utilisé 16 Agents pendant 2 semaines, pour 20 000 $, et a produit 100 000 lignes de code pour un compilateur C. L'enseignement clé de ce projet : la qualité des tests est plus importante que tout. Les Agents résolvent de manière autonome les problèmes que vous leur posez, donc les validateurs de tâches doivent être quasi parfaits, sinon les Agents résoudront le mauvais problème.

Retenez trois points essentiels :

Pour commencer, c'est très simple :

Crée une agent team pour [votre tâche]

Lectures complémentaires :

• Guide complet de Claude Worktree — Comprendre la combinaison entre Worktree et Agent Teams
• Guide complet de Claude Subagent — Comparer les cas d'utilisation de Subagent et Agent Teams
• Guide de démarrage rapide Tmux — Utiliser Tmux pour gérer plusieurs sessions Agent

Références :

• Documentation officielle Claude Code - Agent Teams
• Building a C compiler with a team of parallel Claudes
• Claude Code Agent Teams: The Complete Guide
• Multi-Agent Orchestration: Running 10+ Claude Instances in Parallel

Tutoriels vidéo :

• 7 Unexpected Use Cases for Claude Code Agent Teams — 7 cas d'utilisation non techniques
• Claude Code Multi-Agent Workflows — Flux de travail multi-agents expliqué en détail
• Agent Teams Orchestration Deep Dive — Analyse approfondie de l'orchestration d'équipe
• Claude Code Agent Teams Setup Guide — Tutoriel de configuration complet