Claude Code Agent Teams : Guide du développeur pour le coding IA parallèle

Nous utilisons Claude Code en production quotidiennement depuis son lancement. Workflows en session unique, sub-agents pour les tâches ciblées, contrats AGENTS.md comme fondation de tout. Quand Anthropic a livré Agent Teams avec Opus 4.6 le 5 février 2026, nous avons tout lâché pour le tester sur notre véritable codebase. Voici ce que nous avons appris — les aspects pratiques que personne ne couvre encore.

Ce que sont réellement les Agent Teams

Agent Teams permettent d'orchestrer plusieurs sessions Claude Code travaillant ensemble sur un projet partagé. Une session agit comme team lead. Elle crée des teammates, assigne des tâches via une liste de tâches partagée et synthétise les résultats. Chaque teammate dispose de sa propre fenêtre de contexte et peut communiquer directement avec les autres teammates.

C'est fondamentalement différent des sub-agents. Les sub-agents s'exécutent dans le contexte de votre session principale, effectuent un travail ciblé et rapportent les résultats. Ils ne peuvent pas communiquer entre eux. Agent Teams crée des sessions indépendantes qui collaborent via un système de messagerie et une liste de tâches partagée — pensez équipe projet versus file d'attente de freelances.

Configurer Agent Teams

Activez la fonctionnalité avec une seule variable d'environnement :

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Ou persistez-la dans vos paramètres Claude Code :

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

C'est tout. Pas de dépendances supplémentaires, pas d'outils externes. La fonctionnalité est intégrée nativement dans Claude Code 2.1.

Plan Mode vs Delegate Mode

C'est là que la plupart des guides échouent. Il existe deux façons distinctes d'utiliser Agent Teams, et un mauvais choix gaspille des tokens et produit de moins bons résultats.

Plan Mode (Par défaut)

L'agent lead planifie le travail ET participe à l'exécution. Il peut lire des fichiers, écrire du code et exécuter des commandes — tout en coordonnant les teammates. Cela semble efficace mais crée un problème : le lead se laisse distraire par les détails d'implémentation au lieu de se concentrer sur la coordination.

Quand utiliser le Plan Mode :

• Petites équipes (2-3 teammates) où les contributions directes du lead comptent
• Tâches où le lead doit valider le travail des teammates en temps réel
• Prototypage rapide où le surcoût de la délégation stricte ne vaut pas le coup

Delegate Mode (Shift+Tab)

Appuyez sur Shift+Tab après avoir démarré une équipe pour verrouiller le lead en mode coordination uniquement. Le lead peut créer des teammates, envoyer des messages, gérer la liste de tâches et arrêter des workers — mais il ne peut pas toucher directement au code. Les teammates gèrent toute l'implémentation.

Quand utiliser le Delegate Mode :

• Équipes plus grandes (4+ teammates) où le lead doit se concentrer uniquement sur l'orchestration
• Refactorisations complexes multi-couches où la qualité de coordination prime sur les contributions du lead
• Workflows de production avec séparation nette entre planification et exécution

Problème connu (février 2026) : Le Delegate Mode a un bug où les teammates héritent des accès restreints aux outils du lead. Si vos teammates ne peuvent soudainement plus lire des fichiers ou écrire du code, c'est la cause. Le contournement est d'accorder explicitement les permissions complètes dans le prompt de création de chaque teammate. Suivez ceci sur github.com/anthropics/claude-code/issues/25037.

L'approche Contract-First

Le facteur déterminant du succès d'Agent Teams n'est pas la fonctionnalité elle-même — c'est votre fichier AGENTS.md. Nous pratiquons le développement contract-first depuis des mois, et Agent Teams amplifie son importance d'un ordre de grandeur.

Pourquoi les contrats comptent davantage avec les Teams

Quand une seule session Claude Code lit votre AGENTS.md, elle obtient une interprétation de vos règles de projet. Quand quatre teammates la lisent indépendamment, vous obtenez quatre interprétations. Sans contrats explicites, les teammates font des hypothèses contradictoires sur le style de code, les patterns d'architecture, les exigences de tests et l'organisation des fichiers.

Notre structure AGENTS.md pour les Teams

# AGENTS.md

## Règles d'Architecture
- Toutes les routes API utilisent le pattern handler dans /src/handlers/
- Les requêtes base de données passent par /src/db/queries/ — jamais de SQL inline
- Chaque fonction publique a un JSDoc avec @param et @returns

## Propriété des Fichiers (Critique pour les Teams)
- /src/api/ → Le teammate API possède ce domaine
- /src/db/ → Le teammate Base de données possède ce domaine
- /src/components/ → Le teammate Frontend possède ce domaine
- /src/tests/ → Le teammate Test possède ce domaine

## Standards de Code
- TypeScript strict mode, pas de types `any`
- Gestion d'erreurs : toujours utiliser le pattern Result<T, E>
- Imports : chemins absolus via l'alias @/

## Règles de Coordination d'Équipe
- Avant de modifier un fichier partagé, contacter le propriétaire du fichier
- Points d'intégration documentés dans /docs/interfaces.md
- Tous les teammates exécutent `npm test` avant de signaler une tâche comme terminée

La section Propriété des Fichiers est l'ajout clé pour les teams. Sans elle, deux teammates modifiant le même fichier créent des conflits de merge qui gaspillent des tokens et produisent du code incohérent.

Quand utiliser Teams vs Sub-Agents

Après deux semaines d'utilisation quotidienne, voici notre cadre de décision :

La question clé : Vos workers ont-ils besoin de communiquer entre eux ? Si oui, Agent Teams. S'ils doivent juste travailler et rapporter, les sub-agents sont plus rapides et moins coûteux.

Patterns d'équipe éprouvés en pratique

Pattern 1 : Le Feature Squad

Lead → Crée 3 teammates :
  ├── Teammate API : Construit les endpoints REST
  ├── Teammate DB : Crée les migrations + queries
  └── Teammate Test : Écrit les tests d'intégration pendant que API + DB travaillent

Le teammate test surveille les messages des deux autres et écrit des tests contre les interfaces qu'ils définissent. Cela produit une meilleure couverture de tests que d'écrire les tests après l'implémentation car le teammate test challenge les hypothèses en temps réel.

Pattern 2 : Le Débat de Recherche

Lead → Crée 2-3 teammates :
  ├── Avocat A : Argumente pour l'approche X avec des preuves
  ├── Avocat B : Argumente pour l'approche Y avec des preuves
  └── (Optionnel) Critique : Essaie de casser les deux approches

Chaque teammate recherche indépendamment, puis ils s'envoient mutuellement leurs découvertes. Le lead synthétise les arguments les plus forts de tous les côtés. Nous utilisons cela pour les décisions architecturales sans réponse évidente.

Pattern 3 : Le Processeur Parallèle

Lead → Crée N teammates :
  ├── Worker 1 : Traite les fichiers 1-50
  ├── Worker 2 : Traite les fichiers 51-100
  └── Worker N : Traite les fichiers (N-1)*50+1 à N*50

Pour les opérations à grande échelle comme les refactorisations de codebase ou le traitement en masse de fichiers. Chaque worker possède une plage de fichiers distincte. Pas de communication nécessaire entre workers — le lead distribue et collecte.

Conseils pratiques de l'utilisation quotidienne

1. Commencer petit

Ne créez pas 6 teammates le premier jour. Commencez avec 2 teammates sur une tâche bien définie. Apprenez les patterns de coordination avant de monter en échelle.

2. Définir le scope explicitement

Les prompts vagues comme « refactorise la codebase » produisent le chaos avec les teams. Les prompts spécifiques comme « Teammate A : refactorise /src/api/auth.ts vers le nouveau pattern middleware. Teammate B : mets à jour tous les tests dans /src/tests/auth/ en conséquence » produisent des résultats propres.

3. Utiliser les raccourcis clavier

• Shift+Haut/Bas : Sélectionner un teammate pour voir ou envoyer un message
• Enter (sur un teammate sélectionné) : Ouvrir un message direct vers ce teammate
• Shift+Tab : Basculer le delegate mode

4. Surveiller la consommation de tokens

Agent Teams consomme significativement plus de tokens que les sessions individuelles. Chaque teammate est une instance Claude séparée avec sa propre fenêtre de contexte. Une session à 4 teammates utilise facilement 4-5x les tokens d'une session solo. Planifiez votre budget en conséquence.

5. Toujours nettoyer

Appelez TeamDelete quand le travail est terminé. Les sessions teammate orphelines continuent de tourner et brûlent des tokens. Le lead doit explicitement arrêter tous les teammates avant de terminer.

L'explosion YouTube

Trois vidéos YouTube majeures sont sorties en 24 heures sur Agent Teams — de WorldofAI, Cole Medin et AI Labs. Cela signale un intérêt massif des développeurs mais aussi que la demande de recherche va exploser. La plupart de ces contenus couvrent la configuration de base. Ce guide se concentre sur les patterns et pièges que vous rencontrerez après que le « wow » initial se dissipe.

Ce qui arrive ensuite

Agent Teams est encore expérimental. Basé sur les issues GitHub et le rythme de développement d'Anthropic, attendez-vous à :

• Correction du Delegate Mode : Le bug d'héritage des outils sera probablement résolu bientôt
• Teams persistants : Actuellement, les teams n'existent que dans une session. Des teams persistants entre sessions seraient transformateurs
• Meilleure efficacité tokens : Le surcoût actuel est élevé. Anthropic travaille probablement sur des optimisations de partage de contexte
• Intégration SDK : Le Claude Agent SDK supporte déjà les opérations d'équipe programmatiquement. Attendez une intégration plus profonde avec les pipelines CI/CD

Questions Fréquemment Posées (FAQ)

Comment activer Agent Teams dans Claude Code ?

Définissez la variable d'environnement CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 ou ajoutez-la dans votre settings.json de Claude Code sous la clé env. La fonctionnalité nécessite Claude Code 2.1 ou plus récent et fonctionne avec Opus 4.6.

Quelle est la différence entre sub-agents et Agent Teams ?

Les sub-agents s'exécutent dans votre session principale, effectuent un travail ciblé et rapportent les résultats — ils ne peuvent pas communiquer entre eux. Agent Teams crée des sessions indépendantes avec leurs propres fenêtres de contexte qui peuvent s'envoyer des messages directement via un système de messagerie et se coordonner via une liste de tâches partagée.

Combien de teammates devrais-je créer ?

Commencez avec 2-3 pour vos premiers projets. Chaque teammate est une instance Claude séparée consommant ses propres tokens. Une équipe de 4 teammates utilise environ 4-5x les tokens d'une session unique. Ne montez en échelle que quand vous avez confirmé que le surcoût de coordination en vaut la peine pour votre tâche spécifique.

Est-ce que AGENTS.md fonctionne avec Agent Teams ?

AGENTS.md est encore plus critique avec Agent Teams qu'en sessions solo. Chaque teammate le lit indépendamment, il doit donc être explicite sur la propriété des fichiers, les standards de code et les règles de coordination. Ajoutez une section « Propriété des Fichiers » qui mappe les répertoires aux rôles spécifiques des teammates pour éviter les conflits de merge.

Le Delegate Mode ou le Plan Mode est-il meilleur ?

Cela dépend de la taille de l'équipe et de la complexité de la tâche. Le Plan Mode fonctionne bien pour les petites équipes (2-3) où les contributions directes du lead ajoutent de la valeur. Le Delegate Mode (Shift+Tab) est meilleur pour les équipes plus grandes (4+) où le lead doit se concentrer sur la coordination. Notez que le Delegate Mode a actuellement un bug connu avec l'héritage des accès aux outils — consultez l'issue tracker pour les mises à jour.