Orchestration Multi-Agents avec Claude Code Agent Teams

Le probleme

Pourquoi c'est lent avec un seul agent

Tu empiles les instructions dans un seul prompt et tu te retrouves avec un agent qui hallucine, oublie la moitie du brief et te coute une fortune en tokens.

🧠

Fenetre de contexte saturee

Un agent qui gere auth, front et tests dans le meme thread finit par oublier le debut. Compaction = perte d'info.

⏳

Execution sequentielle

Un agent fait une chose a la fois. Pendant qu'il code le backend, le front attend. Et les tests attendent le front.

💰

Cout qui explose

Plus le contexte grossit, plus chaque appel coute cher. Un agent sur-sollicite brule des tokens pour rien.

La solution

Agent Teams

Agent Teams te permet de spawner plusieurs agents Claude Code qui travaillent en parallele, chacun avec sa propre fenetre de contexte, son scope de fichiers, et la capacite de communiquer entre eux.

❌ Un seul agent

1 thread = 1 contexte Execution sequentielle Oublie le debut du brief Pas de specialisation

✅ Agent Teams

N threads = N contextes Execution parallele Chaque agent garde son focus Roles specialises

🎯

Plus rapide

3 agents en parallele sur auth, front et tests. Le boulot de 3h tombe a 45 minutes.

💬

Communication directe

Les agents se parlent via un systeme de mailbox. Pas besoin de tout faire transiter par toi.

⚡

Automatique avec Claude Code

Tu decris l'equipe en langage naturel. CC spawne les agents, distribue les taches, coordonne le tout.

Comment ca marche

L'architecture sous le capot

Team Lead (ta session CC principale)
↓ spawn ↓ assign ↓ coordinate
Teammate 1 ↔ Teammate 2 ↔ Teammate 3
↓ read/write ↓ read/write ↓ read/write
Shared Task List + Mailbox

Team Lead : ta session CC principale. Il coordonne, assigne et synthetise.

Teammates : des instances CC independantes, chacune avec sa propre fenetre de contexte. Elles lisent/ecrivent des fichiers et se parlent directement.

Shared Task List : file de taches partagee avec gestion des dependances. Quand une tache bloquante se termine, les dependantes se debloquent automatiquement.

Mailbox : messagerie inter-agents. C'est ce qui differencie fondamentalement les teams des sub-agents classiques.

La recette

Setup en 5 etapes

L'etape 1 est a faire une seule fois. Apres, tu spawn des teams a volonte.

Activer la feature (une seule fois)

Ajoute le flag dans ton settings.json Claude Code. C'est la seule config necessaire.

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

Alternative rapide dans le shell (ne persiste pas entre sessions) :

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Decrire ton equipe en langage naturel

Tu tapes directement dans Claude Code. Pas de fichier de config, pas de YAML. Tu decris les roles et CC s'occupe du reste.

# Exemple : refactoring d'authentification
Cree une agent team pour refactorer l'auth :
- Teammate 1 : implementer JWT dans /src/api/auth.ts
- Teammate 2 : creer le composant React login dans /src/components/Login.tsx
- Teammate 3 : ecrire les tests E2E Playwright dans /tests/auth.spec.ts

CC spawne les 3 agents, chacun commence a bosser dans son perimetre.

Choisir le mode d'affichage

Deux options pour voir tes agents travailler :

In-process (defaut)
  Tous les teammates dans ton terminal
  Navigation : Shift+Down pour switcher

Split panes (tmux / iTerm2)
  Chaque teammate a son propre panneau
  Tu vois tout le monde simultanement

Pour le mode split, lance tmux avant Claude Code :

# Installer tmux (une seule fois)
brew install tmux

# Lancer une session tmux AVANT Claude Code
tmux new-session -s claude
claude

Piloter en cours de route

Tu n'es pas spectateur. Tu peux intervenir a tout moment.

Shift+Tab    Forcer le lead en mode coordinateur pur
               (il ne touche plus au code, que de l'orchestration)

Mode plan     Demander a un teammate de soumettre un plan
               avant d'implementer quoi que ce soit

Message      Envoyer un message a n'importe quel teammate
               pour corriger sa trajectoire en temps reel

Bonus : optimiser la config

Deux reglages qui changent la vie en multi-agents :

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80"
  }
}

AUTOCOMPACT_PCT_OVERRIDE a 80 declenche la compaction plus tot. Chaque agent garde plus de contexte utile en fin de tache.

Et dans ton CLAUDE.md, definis les frontieres de modules et les commandes de verification. Ca reduit le cout d'exploration de chaque teammate au demarrage.

Cout

Ce que ca coute vraiment

Plan	Prix	Usage Agent Teams
Pro	20 $/mois	2-3 sessions/jour, teams legeres
Max 5x	100 $/mois	Usage intensif, teams de 3-4 agents
Max 20x	200 $/mois	Full power, 8-10 taches complexes sur 5h

Prerequis technique : Claude Code v2.1.32+ et le modele Opus 4.6. Les teams ne fonctionnent pas avec Sonnet ou Haiku.

A savoir

Les limites actuelles

Agent Teams est encore experimental. Quatre choses a garder en tete :

Pas de reprise de session : /resume et /rewind ne restaurent pas les teammates. Si tu reprends une session, il faut en spawner de nouveaux.
Lag des statuts : les teammates ratent parfois la mise a jour "tache completee", bloquant les dependances. A surveiller manuellement.
Shutdown lent : les teammates finissent leur appel outil en cours avant de s'arreter. Pas de kill instantane.
Une seule team par session : un lead ne gere qu'une team a la fois. Nettoie avant d'en demarrer une nouvelle. Pas de teams imbriquees (mais un teammate peut utiliser des sub-agents).

⚡ Le vrai game changer : Claude Code

Sans Agent Teams, tu geres un agent a la fois, tu copie-colles du contexte entre les sessions, tu perds du temps. Avec, tu decris ton equipe en une phrase et CC fait le reste : spawn, coordination, communication inter-agents, gestion des dependances. Le tout en langage naturel. Tape juste Cree une agent team pour [ta tache] et regarde tes agents collaborer pendant que tu bois ton cafe.