Meilleures pratiques des équipes d'agents

Problème : Ton équipe d'agents Claude Code démarre et brûle immédiatement des tokens sans produire de résultat utilisable. Les équipiers écrasent les fichiers les uns des autres. Le chef retrousse ses manches au lieu de coordonner. Les tâches restent bloquées sur "en cours" indéfiniment. Tout ça se corrige, et les patterns ci-dessous ont été forgés à partir des retours de la communauté et de mois d'itération réelle depuis la sortie de la fonctionnalité.

Gain rapide : Active le mode délégué (Shift+Tab) et donne à chaque équipier des limites de fichiers explicites dans le prompt de création. Ces deux ajustements à eux seuls éliminent les échecs d'équipe les plus courants.

Note : C'est un guide complémentaire à la vue d'ensemble des équipes d'agents. Va d'abord là-bas si tu n'as pas encore configuré une équipe. Pour les réglages et paramètres, voir Contrôles avancés.

Donne assez de contexte aux équipiers

Charge les détails spécifiques à la tâche dans le prompt de création. Le contexte du projet (CLAUDE.md, serveurs MCP, skills) arrive automatiquement, mais l'historique de conversation du chef ne voyage pas avec l'équipier. Pointe vers des fichiers spécifiques, des critères d'acceptation, et des contraintes. Un prompt de création précis réduit considérablement les allers-retours.

Un prompt flou comme "révise le module d'auth" fait que l'équipier fouille dans la base de code, comprend ce qui compte, et devine les priorités. Cette exploration brûle des tokens et du temps. Un prompt spécifique supprime l'ambiguïté.

La forme est simple : quoi faire, où le faire, sur quoi se concentrer, et à quoi le livrable doit ressembler. Les équipiers qui connaissent leur portée dès le départ finissent plus vite et produisent un meilleur travail. Si tu viens des patterns de sous-agents, la règle est identique, mais les enjeux sont plus élevés. Chaque équipier est maintenant une fenêtre de contexte complète.

Calibre les tâches pour les équipiers

Trop petites et la taxe de coordination mange le gain. Trop grandes et les équipiers bossent sans check-ins, risquant des efforts perdus. L'idéal c'est une unité autonome avec un livrable net : une fonction, un fichier de test, un document de revue.

Vise 5 à 6 tâches par équipier. Ça garde tout le monde en mouvement et permet au chef de réassigner le travail quand quelqu'un cale. Si le chef ne découpe pas assez finement, dis-lui de diviser les morceaux plus petits. Un équipier avec une seule tâche énorme n'a pas de point de contrôle naturel. Un équipier avec 5 à 6 tâches ciblées rend compte après chacune, te donnant de l'espace pour piloter.

Évite les conflits de fichiers

Deux équipiers qui éditent le même fichier signifient des écrasements silencieux. C'est la règle la plus importante pour le travail d'implémentation. Divise les tâches pour que chaque équipier possède un ensemble de fichiers distinct. Précise les limites de répertoires dans le prompt de création.

Si le dépôt ne se divise pas naturellement en répertoires indépendants, crée la division dans ta décomposition. Plutôt que "refactorise la couche API" sur trois équipiers, assigne "refactorise les endpoints utilisateurs dans src/api/users/" à l'un et "refactorise les endpoints de facturation dans src/api/billing/" à un autre. La propriété explicite évite les écrasements silencieux qui torpillent des sessions d'équipiers entières.

Pour les projets où les fichiers partagés sont inévitables, marque-les comme "coordonne avant d'éditer" dans ton CLAUDE.md et laisse le chef séquencer l'accès via la liste de tâches.

Utilise le mode délégué

Active le mode délégué (Shift+Tab) dès qu'une équipe démarre. Sans lui, le chef s'empare parfois de tâches destinées aux équipiers, brouillant qui possède quoi. Le mode délégué restreint le chef aux seuls outils de coordination, pour qu'il reste sur l'orchestration au lieu de l'implémentation. Pour le guide complet et les options de configuration, voir le guide du mode délégué.

Commence par des tâches de recherche

Nouveau dans les équipes d'agents ? Commence par des tâches avec des limites nettes et sans écriture de code : revues de PR, recherche de bibliothèques, investigation de bugs, ou audits de modules contre une checklist spécifique. Ça montre les avantages de l'exploration parallèle sans les maux de tête de coordination de l'implémentation parallèle.

Les tâches de recherche sont aussi indulgentes. Quand un équipier s'aventure dans une voie improductive, tu perds des tokens, pas du code. Les erreurs d'implémentation sont plus difficiles à défaire, surtout quand plusieurs équipiers ont superposé des changements les uns par-dessus les autres.

Une fois que la dynamique d'équipe semble naturelle, passe aux tâches d'implémentation. Les mêmes patterns s'appliquent, mais les enjeux montent et les limites de propriété des fichiers comptent beaucoup plus.

Surveille activement

Utilise Ctrl+T pour jeter un oeil aux progrès et rediriger les approches qui ne fonctionnent pas. Laisser une équipe tourner sans surveillance trop longtemps accumule le risque d'efforts gaspillés, surtout si un équipier s'accroche à une impasse.

Traite les équipes d'agents comme un workflow supervisé. Tu es le chef de projet. Le chef coordonne, mais tu prends les décisions stratégiques : quand rediriger, quand créer un remplaçant, et quand arrêter un équipier bloqué. Pense à gérer une équipe distribuée de prestataires. Les check-ins réguliers détectent les problèmes avant qu'ils s'aggravent.

La taille de l'équipe compte

En pratique, 3 à 5 équipiers c'est le vrai sweet spot. Plus d'équipiers signifie plus de taxe de coordination, plus de dépenses en tokens, et plus de risques de fils croisés. Le contexte du chef se remplit plus vite en suivant 8 équipiers que 3. Le coût de communication évolue avec la taille de l'équipe, parce que chaque diffusion atterrit dans la fenêtre de chaque équipier.

Si la tâche exige vraiment plus de 5 travailleurs parallèles, divise-la en phases à la place. Lance une équipe de 3 équipiers pour la phase un, nettoie, puis lance une autre équipe de 3 équipiers pour la phase deux. Des phases séquentielles avec des équipes plus petites produisent des résultats plus propres qu'une grande équipe qui se bat avec tout d'un coup.

Comportement du mode plan

Le mode plan dans les équipes d'agents a deux comportements importants qui ne sont pas évidents dans la doc.

Le mode plan est réévalué à chaque tour, pas seulement une fois. Quand un équipier tourne en mode plan, il y reste toute sa durée de vie. Chaque action qu'il prend est filtrée par la contrainte lecture seule. Ça rend le mode plan idéal pour les rôles de conception uniquement et le façonnage initial des tâches, mais mauvais pour l'exécution.

Le mode d'un équipier est fixé au moment de sa création. Une fois lancé, tu ne peux pas passer un équipier du plan au défaut. Si tu as besoin d'une transition de la planification vers l'exécution, crée un nouvel équipier en mode défaut et transmets-lui le plan. N'essaie pas de "changer" un équipier existant hors du mode plan.

Ça façonne la conception de l'équipe. Utilise les équipiers en mode plan pour les rôles d'architecture et de revue où une perspective lecture seule est tout l'intérêt. Utilise les équipiers en mode défaut pour tout rôle qui a besoin d'écrire du code ou modifier des fichiers. Pour un flux plan-puis-implémente, utilise la fonctionnalité d'approbation de plan à la place. Ça permet à un équipier en mode défaut de planifier d'abord et de construire après approbation.

Des règles claires produisent des rapports clairs

Avec des règles solides dans CLAUDE.md, les équipiers rapportent exactement ce qu'ils ont fait sans que le chef intervienne. Un équipier qui termine une tâche de nettoyage contre un CLAUDE.md bien écrit retourne quelque chose comme : "Supprimé 27 console.log dans 3 fichiers. Conservé tous les 12 console.error et 2 console.warn dans component-page.js. Vérifié zéro console.log restant dans mes fichiers assignés."

Pas besoin d'intervention du chef. Des règles claires en entrée, des rapports clairs en sortie.

Ce pattern émerge naturellement quand ton CLAUDE.md liste des critères de vérification spécifiques. Au lieu de "nettoie les logs", l'équipier sait déjà que "vérifié" signifie lancer grep pour les instances restantes et confirmer que les logs de niveau erreur ont survécu. Pour plus sur la structuration de CLAUDE.md pour les équipes, voir la maîtrise de CLAUDE.md et la section d'optimisation CLAUDE.md dans Contrôles avancés.

Dépannage

Problèmes courants et leurs solutions, tirés des rapports de la communauté et des notes de version :

Si ton problème n'est pas sur cette liste, vérifie quelle version de Claude Code tu utilises. Beaucoup de problèmes précoces ont été résolus dans les versions v2.1.33 à v2.1.45.

Limitations actuelles

Les équipes d'agents sont expérimentales. Ces contraintes valent la peine d'être connues avant de t'engager dans un workflow basé sur les équipes :

• Pas de reprise de session : Les équipiers in-process ne sont pas restaurés lors de l'utilisation de /resume ou /rewind. Après une reprise, le chef peut essayer d'envoyer des messages à des équipiers qui n'existent plus. Dis-lui de créer des remplaçants.
• Le statut des tâches peut être en retard : Les équipiers oublient parfois de marquer les tâches comme terminées, bloquant le travail dépendant. Vérifie manuellement si quelque chose semble bloqué.
• Arrêt lent : Les équipiers terminent leur requête ou appel d'outil en cours avant de s'arrêter. Ça peut prendre du temps si un équipier est en pleine implémentation.
• Une équipe par session : Un chef gère une équipe à la fois. Nettoie l'équipe actuelle avant d'en démarrer une autre.
• Pas d'équipes imbriquées : Les équipiers ne peuvent pas créer leurs propres équipes. Seul le chef gère la hiérarchie d'équipe.
• Chef fixe : La session qui crée l'équipe reste le chef pour sa durée de vie. Tu ne peux pas promouvoir un équipier ou transférer le leadership.
• Permissions définies à la création : Tous les équipiers démarrent avec les paramètres de permission du chef. Tu peux changer les modes individuels après la création, mais pas au moment de la création.
• Les volets divisés nécessitent tmux ou iTerm2 : Le mode split-pane n'est pas supporté dans le terminal intégré de VS Code, Windows Terminal, ou Ghostty.

Être direct sur ces aspérités, c'est important. Les équipes d'agents sont une fonctionnalité puissante avec des coutures visibles. Les développeurs qui apprennent les contournements maintenant sont ceux qui seront prêts quand Anthropic les résoudra.

Corrections récentes

Depuis le lancement initial des équipes d'agents dans v2.1.32, Anthropic a publié plusieurs corrections importantes. Si tu as essayé les équipes d'agents tôt et que tu as eu des problèmes, vérifie si ton problème a été résolu :

v2.1.33 :

• Ajout des hooks TeammateIdle et TaskCompleted pour l'application des portes qualité
• Ajout des restrictions de création Task(agent_type) pour contrôler quels types de sous-agents peuvent être créés
• Ajout d'un champ memory persistant pour les agents avec des portées utilisateur, projet et local
• Corrigé les sessions d'équipiers tmux pour envoyer et recevoir correctement des messages
• Corrigé les avertissements du mode plan dans les contextes d'équipe

v2.1.34 :

• Corrigé un plantage quand le paramètre équipes d'agents changeait entre les rendus

v2.1.41 :

• Corrigé l'identifiant de modèle incorrect pour les équipiers sur Bedrock/Vertex/Foundry
• Ajout de l'attribut speed aux événements OTel pour l'observabilité du mode rapide

v2.1.45 :

• Corrigé les équipiers qui échouent sur Bedrock/Vertex/Foundry en propagant les variables d'environnement du fournisseur d'API aux sessions tmux
• Corrigé les skills invoquées par des sous-agents qui apparaissaient incorrectement dans la session principale après compaction

Tu as des problèmes ? Mets à jour Claude Code vers la dernière version. L'équipe publie des corrections à un rythme rapide et les équipes d'agents sont en développement actif.

Guides associés

Ce guide est le manuel opérationnel. Pour le reste du tableau d'ensemble :

• Vue d'ensemble des équipes d'agents pour les bases de la fonctionnalité et l'architecture
• Contrôles avancés pour les modes d'affichage, le mode délégué, les hooks et la gestion du coût en tokens
• Cas d'utilisation et modèles de prompts pour des prompts copiables sur 10+ scénarios réels
• Workflow de bout en bout pour le pipeline complet en 7 étapes du brain dump au code de production validé
• Meilleures pratiques des sous-agents pour quand une équipe complète est exagérée et que des sous-agents ciblés sont la bonne approche