Workflow des équipes d'agents

Problème : Les équipes d'agents sont activées. Tu as lancé ta première équipe. La création fonctionne. Mais le résultat c'est un tas de morceaux à moitié intégrés que tu finis par assembler toi-même. L'écart entre "les équipes d'agents tournent" et "les équipes d'agents livrent du code de production" c'est un processus, pas un flag de fonctionnalité.

Gain rapide : Un workflow qui rend les équipes d'agents fiables tourne en deux phases. La planification supprime les suppositions et verrouille les contrats entre les domaines. L'exécution crée ensuite des agents par vagues et donne à chaque vague les contrats dont elle a besoin pour que le travail parallèle s'assemble proprement. Le workflow complet est ci-dessous.

C'est le guide compagnon de la vue d'ensemble des équipes d'agents. Si tu n'as pas encore activé la fonctionnalité ou lancé une première équipe, commence là. Pour les contrôles et la configuration, voir Contrôles avancés. Pour des modèles copiables, voir Cas d'utilisation.

Pouvoir créer des sessions Claude parallèles qui communiquent, c'est une capacité. Les workflows agentiques ont besoin de plus qu'une capacité. Créer des agents bruts sans processus, c'est comme donner les clés d'un chantier à cinq prestataires sans plans : tout le monde construit, rien ne s'emboîte.

Deux modes d'échec apparaissent quand il n'y a pas de workflow :

1. Dérive des suppositions. Chaque agent choisit ses propres formes de données, nommage, formats d'erreurs, et cas limites. Le backend renvoie { notif_type: "comment" } et le frontend lit { type: "COMMENT" }. Les tests unitaires passent des deux côtés. L'intégration explose.

2. Validation manquante. Chaque agent signale un succès, donc le chef marque les tâches comme terminées. Personne n'a testé le flux complet. L'application casse la première fois que tu cliques dessus et des erreurs cachées remontent à la surface.

Un pipeline corrige les deux :

1. Brain dump de tes exigences (non structuré, désordonné, c'est bien)
2. Recherche et Q&R où Claude examine ta base de code et te pose des questions de clarification
3. Plan structuré avec les membres de l'équipe, les chaînes de dépendances, et les critères d'acceptation
4. Contexte frais où tu démarres une nouvelle session avec seulement le plan
5. Analyse de la chaîne de contrats où le chef dérive les interfaces du graphe de dépendances du plan
6. Exécution par vagues où les agents construisent en parallèle contre des contrats injectés
7. Boucle de validation où le chef effectue des vérifications de bout en bout contre les critères d'acceptation

Chaque étape existe parce que la sauter produit un échec spécifique. Le reste de cet article les parcourt une par une.

Étape 1 : Brain dump

Ne soigne pas l'entrée. Écris ce que tu veux en langage courant. Inclus tout ce qui est dans ta tête, même quand c'est désordonné, mal défini, ou contradictoire. Objectif : vider ta tête sur la page.

Ce n'est pas une spec. C'est de la matière première. Tout l'intérêt du brain dump c'est de capturer l'intention et le contexte qui meurent dès que tu essaies de forcer une spec formelle hors de ta tête.

Un brain dump double comme vérification de portée. Si tu ne peux pas esquisser ce que tu veux en quelques paragraphes, la fonctionnalité est trop grande pour une seule session d'équipe d'agents. Découpe-la d'abord.

Étape 2 : Recherche et Q&R

C'est l'étape que la plupart des gens sautent, et c'est celle qui compte le plus. Objectif : réduire les suppositions avant qu'une seule ligne de code soit écrite.

La plupart des échecs d'équipes d'agents ne viennent pas de mauvais code. Ils viennent d'un désalignement. L'agent livre quelque chose qui ne correspond pas à ce que tu voulais parce qu'il a mal deviné. Remède : demande à Claude de lire ta base de code et de te poser des questions avant de planifier quoi que ce soit. La planification structurée d'équipe remplace l'habitude ad-hoc de "passer en mode plan".

Pas 2 ou 3 questions. Au moins 10. Chaque question supplémentaire que Claude pose est une supposition de moins baked dans le plan.

Claude reviendra avec des questions comme :

• La page de facturation doit-elle se trouver sous le layout du tableau de bord ou être autonome ?
• Quels niveaux de packs de tokens et prix veux-tu ?
• Devrions-nous utiliser le checkout hébergé de ChargeB ou intégré in-app ?
• Que doit-il se passer dans l'UI de chat quand un utilisateur n'a plus de tokens ?
• Tu as déjà un compte ChargeB et un endpoint webhook configurés ?

Chaque question est un embranchement potentiel dans l'implémentation. Un agent qui suppose "checkout intégré" et commence à construire va tout gâcher dès que tu lui dis que tu voulais le checkout hébergé. Dix minutes de Q&R tuent des heures de refonte.

L'outil AskUserQuestion dans Claude Code rend ça rapide. La plupart des réponses sont à choix multiples. Clique là où le choix de Claude est correct. Tape une réponse personnalisée là où tu as besoin de précision.

Pour des approches plus structurées de la phase de planification, voir les stratégies d'auto-planification.

Étape 3 : Transformer ça en plan structuré

Avec le Q&R terminé, intègre tout dans un plan structuré. Ce plan devient l'artefact unique qui pilote toute la session d'équipe. Il doit contenir :

• Description et objectif de la tâche pour que l'équipe sache à quoi ressemble le succès
• Fichiers pertinents pour que les agents sachent ce qui existe et ce qu'il faut créer
• Membres de l'équipe avec des rôles nommés, des types d'agents, et des responsabilités uniques
• Tâches étape par étape avec des chaînes de dépendances (champs Depends On) et des limites de propriété de fichiers
• Critères d'acceptation qui sont spécifiques et mesurables
• Commandes de validation qui peuvent être exécutées pour vérifier le travail

Voici la structure qui rend l'orchestration d'équipe fonctionnelle :

Le plan fait trois choses à la fois : il trace les lignes de propriété de fichiers (pas de conflits), encode une chaîne de dépendances (pour que l'exécution sache quoi construire en premier), et écrit les critères d'acceptation (pour que la validation ait quelque chose de concret à cibler).

Regarde les champs Depends On. Ce ne sont pas des docs. Ils forment la chaîne de contrats que la phase d'exécution utilise pour choisir quels agents créer en premier et quelles interfaces récupérer entre les vagues.

Étape 4 : Repartir à zéro avec le plan

Ça semble contre-intuitif et ça compte quand même. Ouvre une nouvelle session Claude Code avec seulement le plan chargé. Ne continue pas dans la même fenêtre de contexte où tu as fait le brain dump et le Q&R.

Pourquoi ? Les conversations de planification brûlent du contexte. Elles sont bourrées de questions exploratoires, d'idées mortes, et d'allers-retours qui sont maintenant sans intérêt. Le plan est la version distillée. Il contient déjà ce dont l'équipe a besoin. Le bavardage de planification est du poids mort qui encombre la construction.

Ça signifie aussi que les plans sont réutilisables. Une session qui échoue à mi-chemin repart du même fichier plan. Aucun travail de planification n'est refait.

Étape 5 : Analyse de la chaîne de contrats

Avant qu'un agent ne soit créé, le chef parcourt le graphe de dépendances du plan et extrait la chaîne de contrats. C'est l'étape qui rend les équipes d'agents fiables pour les builds de production.

Une chaîne de contrats regroupe les tâches en vagues selon leurs dépendances, puis nomme les sorties que chaque vague complétée produit et dont la vague suivante a besoin.

Voici l'insight clé : aucun agent ne commence son travail avant que ses contrats n'existent. L'agent base de données tourne en premier. Quand il finit, il envoie au chef les vraies définitions de schéma, les types de tables et les relations. Ces sorties SONT le contrat. Le chef colle ensuite ces schémas concrets directement dans les prompts de création des agents API et frontend, pour que les deux construisent contre des interfaces réelles au lieu d'inventer les leurs.

C'est pourquoi les agents parallèles finissent avec du code qui s'intègre vraiment : ils ne devinent pas les formes de données indépendamment. Ils écrivent tous contre le même contrat, et ce contrat vient d'un travail qui a déjà été livré.

Ce qui est injecté comme contrat

Les contrats ne sont pas des specs abstraites. Ce sont les sorties réelles du travail en amont :

• Base de données complétée -> contrat de schéma : définitions exactes des tables, types de colonnes, clés étrangères, types TypeScript
• API complétée -> contrat d'API : routes des endpoints, formes des requêtes/réponses, codes de statut, exigences d'auth
• Types partagés créés -> contrat de types : interfaces, enums, constantes que plusieurs agents référencent

Chaque agent en aval reçoit les contrats correspondants collés dans son prompt de création. Pas "va lire ce que l'agent base de données a fait." Le contenu brut. Ça tue le mode d'échec où un agent lit des fichiers obsolètes ou comprend mal la sortie d'un autre agent. Les patterns de sous-agents laissent chaque agent deviner dans son coin. Un vrai workflow agentique connecte chaque agent à une interface vérifiée.

Étape 6 : Exécution par vagues

Avec la chaîne de contrats établie, le chef crée les agents par vagues.

Vague 1 (Fondation) : L'agent base de données passe en premier. Il gère le travail fondationnel : schémas, types partagés, config. Le chef attend la complétion et reçoit le contrat.

Vague 2+ (Parallèle) : Une fois le contrat de schéma livré, les agents API et frontend sont créés ensemble. Chacun reçoit le contrat de schéma dans son prompt, avec son assignation de tâche et ses lignes de propriété de fichiers.

Les prompts de création des équipiers suivent cette structure :

Les éléments clés : les limites de propriété de fichiers (aucun agent ne touche les mêmes fichiers), les contrats en amont (contenu réel, pas de références), et les obligations de contrats en aval (ce que cet agent doit produire pour les autres).

Active le mode délégué pour que le chef coordonne au lieu d'écrire du code lui-même. Pendant l'exécution, le rôle du chef c'est de surveiller la liste des tâches, régler les incompatibilités de contrats, et recentrer les agents qui commencent à dériver.

Bases de code brownfield

La plupart du travail réel se fait dans une base de code existante. Les équipes d'agents brownfield ont besoin de cohérence des conventions. Trois agents qui éditent le même projet en même temps doivent quand même suivre les patterns déjà en place.

Solution : documente les conventions de ton projet dans CLAUDE.md (nommage, gestion des erreurs, organisation des fichiers, approche de test). Les équipes d'agents lisent CLAUDE.md comme contexte runtime partagé, donc chaque équipier démarre aligné depuis la première ligne. Saute ça et un agent livre des réponses API en camelCase pendant qu'un autre livre en snake_case parce qu'ils ont chacun choisi une convention à la volée.

Étape 7 : Validation post-build

Les équipiers qui terminent leurs tâches, ce n'est pas "terminé". Les builds parallèles produisent des composants qui passent seuls mais craquent aux jonctions. La validation capture ces échecs.

Les critères d'acceptation et les commandes de validation du plan pilotent cette étape. Le chef (ou un agent qualité dédié) parcourt chaque critère un par un.

Le problème des faux positifs

Le scénario post-build le plus effrayant : chaque agent marque ses tâches comme complètes et signale un succès, mais des erreurs cachées sont là à traîner. Ça arrive parce que les agents sont incités à fermer les tâches et valident parfois leur propre travail de façon trop facile.

Contrecarre ça en demandant des preuves, pas des confirmations. Ne demande jamais "est-ce que tout a fonctionné ?" Demande des sorties spécifiques.

Exiger des preuves force le chef à vraiment vérifier au lieu de faire du pattern-matching sur une intuition. Même idée que la revue de code : tu lis le diff, tu ne demandes pas juste à l'auteur si ça marche.

La boucle corriger-retester

Quand la validation détecte un problème, la boucle est simple :

1. Le chef identifie l'incompatibilité (ex : le handler webhook renvoie un mauvais code de statut)
2. Le chef envoie un message à l'équipier responsable ou crée un agent de correction ciblé
3. La correction est appliquée
4. Le chef relance les vérifications de validation affectées

La plupart des runs convergent en 1 ou 2 itérations si les contrats étaient bien configurés. Sans contrats, la boucle corriger-retester s'emballe parce que chaque correction en fait remonter une autre incompatibilité de suppositions. Cette spirale est exactement pourquoi la chaîne de contrats existe.

Pour des boucles de correction structurées basées sur des chaînes de dépendances, le pattern constructeur-validateur formalise ça comme des dépendances de tâches où les validateurs s'exécutent automatiquement après que les constructeurs terminent.

Les étapes 1 à 3 (planification) prennent 15 à 30 minutes de travail interactif. Les étapes 4 à 7 (exécution) tournent principalement sans surveillance une fois que la première vague est lancée.

Le ratio c'est le point clé : 30% de ton temps sur la planification et les contrats annule les 70% de refonte que tu devrais sinon avaler à nettoyer les échecs d'intégration d'un build parallèle mal planifié.

Les sept étapes peuvent être faites à la main avec des prompts bruts. Mais les parties répétitives (formatage du plan, dérivation de la chaîne de contrats, exécution par vagues, séquençage de la validation) sont assez mécaniques pour être encapsulées dans des commandes réutilisables.

Les concepts ici (réduction des suppositions par le Q&R, chaînes de contrats entre les vagues, validation basée sur des preuves) s'appliquent peu importe si tu les exécutes avec des commandes, des prompts bruts, ou une couche d'orchestration personnalisée.

Choisis une fonctionnalité qui traverse au moins deux couches (frontend + backend, ou API + base de données) :

1. Brain dump ce que tu veux
2. Demande à Claude de te poser 10 questions de clarification
3. Construis un plan structuré avec les membres de l'équipe et les chaînes de dépendances
4. Repars à zéro et laisse le chef dériver la chaîne de contrats
5. Regarde les agents construire par vagues contre des contrats partagés
6. Valide les points d'intégration avec des preuves, pas des confirmations

Le premier run prend plus longtemps parce que tu construis la mémoire musculaire. Dès la troisième fonctionnalité, le workflow devient une seconde nature et le compounding se déclenche : les plans deviennent des modèles réutilisables, les contrats deviennent des interfaces standardisées, et les critères de validation s'accumulent en une base qualité à l'échelle du projet.