Tutoriel Agent Teams de Claude Code : 15 étapes de la configuration à la dissolution
Agent Teams donne à chaque coéquipier sa propre session Claude Code, une liste de tâches partagée et une discussion directe entre eux. Ce tutoriel illustré couvre le drapeau settings.json, votre première équipe, le pilotage, la dissolution — et les limites dont personne ne parle.
L'essentiel
- Agent Teams est expérimental et désactivé par défaut : ajoutez "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" au bloc env de settings.json, puis exécutez Claude Code v2.1.32 ou plus récent.
- Il faut le dire — demandez à Claude de « create an agent team » en nommant les coéquipiers ou le modèle, sinon il spawn discrètement de simples subagents.
- Les coéquipiers n'héritent jamais de votre historique de conversation — remettez-leur un fichier de contexte et gardez chaque tâche assez petite pour produire un seul livrable clair.
- Chaque coéquipier est une instance Claude Code distincte avec sa propre fenêtre de contexte, donc les tokens se multiplient — rétrogradez-les vers Sonnet ou Haiku quand la tâche le permet et vérifiez /cost après chaque exécution.
Claude Code Agent Teams (Full Tutorial): The BEST FEATURE of Claude Code is HERE!
Vidéo:AICodeKing13:58
Agent teams — Orchestrate teams of Claude Code sessions
Documentation:code.claude.comDocs
Agent Teams est expérimental : attendez-vous à des aspérités autour de la reprise de session, de l'état des tâches et du délai de dissolution. Chaque commande, clé de réglage et raccourci de cette page a été revérifié contre la documentation officielle avant publication.
Les captures d'écran proviennent de l'enregistrement d'écran d'AICodeKing ; les tutoriels de Bart Slodyczka et Simon Scrapes ont fourni des faits pratiques supplémentaires. Toutes les sources sont créditées et liées, et chaque étape renvoie au moment exact de la vidéo.
D'un terminal froid à une équipe dissoute
1. Activer Agent Teams et vérifier l'installation
- 1
Trouver la doc agent teams et lire l'avertissement expérimental
Agent Teams se trouve dans la section Build with Claude Code de la documentation officielle. La page s'ouvre sur un bandeau orange : la fonctionnalité est expérimentale, désactivée par défaut, et présente des limites connues autour de la reprise de session, de la coordination des tâches et de la dissolution. Lisez ce bandeau avant de toucher au moindre drapeau.
La page officielle agent teams et son bandeau de fonctionnalité expérimentale.Voir à 0:20 - 2
Choisir entre subagents et agent teams
La doc inclut un tableau comparatif. Les subagents tournent dans une seule session, renvoient les résultats à l'appelant et coûtent moins de tokens. Les coéquipiers sont des instances Claude Code indépendantes qui se message directement et partagent une liste de tâches — la vraie collaboration coûte plus de tokens. Prenez des subagents quand seul le résultat compte ; une équipe quand les travailleurs doivent se challenger.
Subagents vs agent teams, tiré droit du tableau officiel.Voir à 1:00 - 3
Activer le drapeau dans settings.json
Ouvrez (ou créez) ~/.claude/settings.json et ajoutez un bloc env avec "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1". Les fichiers de réglages de projet et locaux peuvent aussi l'activer, et un export shell fonctionne — mais un "0" dans les réglages utilisateur l'emporte sur l'export. Le changement s'applique à la session en cours sans redémarrage.
Le bloc env qui allume agent teams.Voir à 2:00 - 4
Mettre Claude Code à jour, lancer, et demander une équipe en langage clair
Lancez d'abord claude update — les équipes exigent un build récent (2.1.32 ou plus), les versions anciennes ignorent silencieusement le drapeau. Démarrez Claude, vérifiez le sélecteur de modèle (la vidéo utilise Opus 4.6 sur Claude Max), puis tapez un prompt avec les mots magiques : "Use the agent teams feature." Sans cette phrase, Claude spawn de simples subagents à la place.
Claude Code v2.1.34 reçoit le prompt agent teams.Voir à 3:30
2. Lancer votre première équipe
- 5
Regarder le lead découper le travail en liste de tâches partagée
Le lead transforme votre prompt en tâches, puis spawn les coéquipiers. L'entrée de chacun montre sa tâche et « shift+↑ to manage ». Notez le marqueur de dépendance : « Build UI, styling, and user interaction > blocked by #1 » — le coéquipier UI ne peut prendre sa tâche qu'une fois le coéquipier engine terminé ; c'est ainsi que la liste partagée évite le travail en double.
Deux coéquipiers lancés, la tâche #2 bloquée par la #1.Voir à 4:30 - 6
Laisser tourner et lire la progression en direct
Les coéquipiers travaillent en parallèle dans leurs propres sessions. Le lead commente l'état — « Both agents are working » — tandis que chaque ligne de tâche porte le nom du coéquipier, le temps écoulé et la dépense en tokens. ctrl+o déplie une entrée, ctrl+t affiche ou masque le panneau des coéquipiers à tout moment.
Travail en parallèle avec comptabilité des tokens et du temps par tâche.Voir à 5:00 - 7
Option : figer le nombre de coéquipiers et leur modèle
Vous pouvez préciser exactement ce que vous voulez : « Create a team with 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate. » Assigner un modèle moins cher par coéquipier est le meilleur levier de coût — le travail de routine n'a pas besoin d'Opus. Pour les tâches risquées, exigez aussi la validation du plan pour que le plan d'un coéquipier attende votre feu vert.
L'exemple de la doc pour préciser coéquipiers et modèles.Voir à 6:30
3. Piloter, vérifier et itérer
- 8
Suivre le relais de dépendance et la revue du lead
Quand le coéquipier engine termine, la tâche #2 se débloque et le dev UI s'en empare. Le lead lit ensuite lui-même les fichiers modifiés — « Let me shut down the teammates and do a final review of the code to make sure everything integrates properly. » Vous n'intervenez que si quelque chose cloche.
Tâche #1 terminée, #2 débloquée, la revue finale commence.Voir à 7:30 - 9
Ouvrir le livrable et le vérifier vous-même
La sortie de l'équipe atterrit en fichiers ordinaires dans votre projet — ici un Démineur avec trois niveaux de difficulté, un dévoilement par propagation et un premier clic sûr. Ouvrez-le dans le navigateur et utilisez-le vraiment avant de renvoyer l'équipe : les agents vérifient leur propre code, mais la recette vous appartient.
Le livrable de l'équipe : un Démineur qui fonctionne.Voir à 9:00 - 10
Itérer en repromptant la même équipe
La liste des fonctionnalités est validée, alors la vidéo recommence : « Add more themes to it. Use team. » Pour les tâches de code, le lead garde souvent les coéquipiers en veille au lieu de les licencier — votre relance arrive avec tout le contexte de ce qui est déjà construit. Notez la barre d'état : accept edits on (shift+tab pour basculer).
La liste des fonctionnalités livrées et le prompt du second tour.Voir à 10:00 - 11
Piloter les individus depuis le panneau des coéquipiers
Dans une équipe plus grande (la seconde démo de la vidéo en fait tourner six), le panneau affiche le nom de chaque coéquipier, un mot d'état en direct et son compteur de tokens. shift+↑ / shift+↓ sélectionne, Enter ouvre sa conversation, et la zone de message accepte les mentions @ comme « Message @infra-dev… » pour joindre un coéquipier sans passer par le lead.
Six coéquipiers, compteurs de tokens en direct et zone de mention @.Voir à 13:30 - 12
Faire descendre les coéquipiers proprement
Demandez-le au lead en le nommant — « Ask the ui-dev teammate to shut down » — et le coéquipier approuve en finissant d'abord son appel d'outil en cours. Un coéquipier qui juge son travail critique peut refuser avec une explication. Quand tout est fini, « clean up the team » referme les sessions partagées et les volets reviennent à un seul.
Les deux coéquipiers descendent proprement pendant le nettoyage.Voir à 8:00
4. Connaître les limites avant de passer à l'échelle
- 13
Connaître la règle de contexte avant de monter en puissance
Les coéquipiers chargent automatiquement CLAUDE.md, les serveurs MCP et les skills, mais n'héritent jamais de l'historique de conversation du lead. Transmettez le contexte explicitement — l'exemple de la doc spawn un réviseur sécurité avec les fichiers exacts, les points d'attention et le format de rapport dans le prompt. Et dimensionnez les tâches honnêtement : trop petite gaspille la coordination, trop grande risque l'effort perdu, juste ce qu'il faut c'est un livrable autonome unique.
La règle d'héritage de contexte et la liste de dimensionnement des tâches.Voir à 10:15 - 14
Accepter que les équipes ne reprennent pas de session
La limite qui surprend le plus : /resume et /rewind ne restaurent pas les coéquipiers in-process. Après une reprise, le lead peut tenter de messager des coéquipiers disparus — dans ce cas, dites-lui de spawn de nouveaux coéquipiers. Attendez-vous aussi à un état des tâches en retard : si une tâche semble bloquée, vérifiez si le travail est réellement fait et mettez le statut à jour à la main.
Pas de reprise de session, plus l'avertissement sur l'état des tâches.Voir à 10:30 - 15
Vérifier les limites restantes, puis choisir du vrai travail
Trois règles de plus depuis la doc : le lead est fixe (pas de promotion d'un coéquipier), les permissions fixées au spawn se propagent — --dangerously-skip-permissions coule vers chaque coéquipier, changez donc le mode d'un réviseur ensuite s'il ne doit pas éditer — et les volets divisés exigent tmux ou iTerm2, car le terminal intégré de VS Code, Windows Terminal et Ghostty ne sont pas pris en charge. Ensuite, démarrez avec 3-5 coéquipiers sur du travail qui exige une vraie collaboration.
Lead fixe, permissions propagées, volets divisés avec tmux.Voir à 11:30