Travail parallèle avec Claude Code : worktree, Agents et Workflows

Ressources pratiques pour travailler avec des agents en parallèle : documentation Ailoot.

Ce guide rassemble des conseils pratiques et présente les outils selon leurs usages. Il couvre les quatre primitives officielles de Claude Code, leurs cas d’utilisation, ainsi qu’un cadre anti-hype pour déterminer le nombre d’agents parallèles réellement utiles à un vibe coder. Tous les chiffres et les citations renvoient à des sources primaires d’Anthropic.

Qu’est-ce que le multi-agent dans Claude Code, et pourquoi ce n’est pas « 1000 agents » ?#

On parle de configuration multi-agent lorsqu’une tâche est répartie entre plusieurs flux de travail indépendants, chacun prenant en charge sa propre partie et renvoyant un résultat. L’exemple le plus simple : vous écrivez le frontend dans une fenêtre Claude Code et le backend dans une autre, sur la même machine, avec un dépôt git partagé entre les deux. C’est déjà du multi-agent, même si le mot « orchestration » serait excessif.

Une configuration plus complexe : dans une même session Claude Code, vous lancez cinq subagents aux rôles différents (développeur frontend, développeur backend, réviseur sécurité, testeur, rédacteur de documentation), et chacun renvoie sa partie du résultat dans la conversation commune. C’est la même approche multi-agent, mais avec un seul point de contrôle.

Plus complexe encore : vous dites à Claude « lance un audit de sécurité hebdomadaire de tous les 500 fichiers de mon projet », et il écrit un script d’orchestration JavaScript. Le runtime lance plusieurs dizaines d’agents en arrière-plan, chacun audite sa propre section, puis des agents indépendants vérifient mutuellement leurs conclusions, et vous recevez un rapport unique. Ce sont les Dynamic Workflows, lancés par Anthropic le 28 mai 2026. Une présentation détaillée de la fonctionnalité figure dans le guide séparé sur les Dynamic Workflows.

La différence entre ces trois scénarios ne tient pas au nombre d’agents. Elle tient à qui décide de ce que fera le prochain agent. Dans le premier scénario, c’est vous. Dans le deuxième, c’est Claude, au fil de la conversation. Dans le troisième, c’est un script JavaScript écrit par Claude.

« 1000 agents » est bel et bien un chiffre réel, au fait. C’est la limite maximale d’un Dynamic Workflow dans Claude Code. La documentation officielle d’Anthropic indique :

Autrement dit, c’est une protection technique contre les comportements incontrôlés, et non une charge de travail recommandée. En pratique, 95 % des tâches sont prises en charge par 2 à 8 flux de travail parallèles. Si vous en prévoyez davantage, demandez-vous d’abord ce qu’ils feront.

Les 4 primitives de Claude Code : subagents, skills, agent teams et workflows#

Claude Code propose quatre primitives officielles pour répartir une tâche entre plusieurs agents. Anthropic les a réunies dans un tableau comparatif de la documentation des Dynamic Workflows. Voici la comparaison en termes simples :

Chacune de ces primitives répond à un problème différent. Les subagents servent à déléguer 2–3 vérifications dans le cadre d’une tâche. Les skills sont utiles lorsque vous disposez d’instructions prêtes à suivre par Claude (par exemple, « effectue une revue de PR à l’aide de cette liste de contrôle »). Les agent teams sont adaptés lorsque plusieurs parties d’un produit se trouvent dans des fenêtres différentes et que vous avez besoin d’un coordinateur. Les workflows conviennent aux tâches trop volumineuses pour une seule fenêtre de contexte.

Les subagents sont présentés en détail dans le guide Claude Code Subagents 2026. L’arbre de décision « que faut-il utiliser pour une tâche donnée ? » figure dans le guide sur les Skills, Subagents, MCP et Plugins. Ce guide explique comment les combiner dans une configuration multi-agent reposant sur git worktree.

Niveau 1 : les subagents dans une session, le point de départ le plus simple#

Un subagent est le moyen le plus simple de répartir une tâche. La conversation principale assure la coordination. Les subagents sont des travailleurs temporaires que l’agent principal lance au fil du travail.

Un exemple concret tiré du projet décrit. Après le premier brouillon d’un guide, la révision s’organise ainsi : Claude reçoit la demande suivante : « Lance six subagents en parallèle : l’un recherche les marqueurs d’IA, le deuxième le vocabulaire juridique, le troisième vérifie la voix et le ton, le quatrième contrôle les faits avec WebFetch, le cinquième examine la structure SEO et le sixième vérifie l’exactitude des liens croisés. » Chacun renvoie un rapport, puis les modifications sont appliquées.

Techniquement, cela se fait à l’aide de fichiers dans .claude/agents/[subagent-name].md qui décrivent le rôle et les outils. L’appel s’effectue à l’aide de l’outil Agent dans la conversation principale. Claude décide quand envoyer une requête à un subagent.

Quand cela fonctionne. Pour les tâches comprenant 3 à 7 vérifications parallèles d’un même livrable (code, texte, design). Chaque vérification est indépendante. Les résultats tiennent dans la fenêtre de contexte principale.

Quand cela atteint ses limites. Avec plus de 50 fichiers ou lorsque chaque vérification nécessite son propre contexte de 50K tokens, la fenêtre principale se remplit. Il faut alors passer aux workflows ou aux agent teams.

Risque principal. Chaque subagent consomme des tokens séparément. Si vous en lancez six sur un projet de 200 fichiers et que chacun relit les 200 fichiers, vous payez 6× plus. Vous DEVEZ donc préciser exactement quels fichiers le subagent doit examiner. Consultez le guide sur l’utilisation des tokens dans Claude Code pour plus de détails.

Niveau 2 : git worktree, isoler les fichiers entre les sessions parallèles#

Lorsque les subagents ne suffisent plus et que vous avez besoin de deux instances Claude Code à part entière, dans des terminaux différents, qui travaillent sur le même dépôt, un problème classique se pose. Elles commencent à modifier le même fichier ; l’une enregistre en premier et la seconde écrase ses changements. La semaine dernière, un client a demandé à l’équipe d’assistance : « 5 s’écrasent mutuellement en même temps. »

La solution est git worktree. Cette fonctionnalité intégrée à git permet d’avoir plusieurs copies de travail du même dépôt, chacune sur sa propre branche et partageant un dépôt .git. Une seule origine, différents répertoires sur le disque et aucun chevauchement entre leurs fichiers. Le mécanisme est expliqué en détail dans le guide Git worktree dans Claude Code.

Commandes pour une configuration en cinq minutes :

# From the main project directory
cd ~/projects/my-app

# Create a worktree for feature/auth
git worktree add ../my-app-auth feature/auth

# Create a worktree for feature/billing
git worktree add ../my-app-billing feature/billing

# Open two terminal windows
cd ~/projects/my-app-auth && claude   # first Claude Code
cd ~/projects/my-app-billing && claude # second Claude Code

Chaque copie se trouve sur sa propre branche. Chaque instance Claude Code écrit dans son propre répertoire. Une fois la tâche terminée, exécutez git push depuis sa branche, puis git worktree remove ../my-app-auth.

Ce qu’il faut savoir. Un worktree ne duplique pas node_modules, .venv ni les autres fichiers présents dans .gitignore. Si vous avez besoin de dépendances indépendantes (une version différente d’une bibliothèque sur chaque branche), exécutez npm install séparément dans le nouveau répertoire après worktree add.

Combien de worktrees par personne ? D’après les enquêtes menées auprès des équipes en 2026, la limite pratique est de 4 à 8 worktrees parallèles par développeur. Le facteur limitant n’est pas Claude, mais la capacité d’une personne à examiner et à accepter les résultats. Si vous avez 10 worktrees, ils attendent une révision.

Dans la pratique décrite, les gens utilisent généralement 2 à 3 worktrees parallèles. Un worktree principal pour le travail en cours, un autre en réserve pour les correctifs urgents, et un troisième pour une expérience (une nouvelle fonctionnalité sur laquelle vous avez des doutes). Il n’en faut pas plus.

Niveau 3 : les agent teams, plusieurs fenêtres et un agent principal#

Les agent teams sont une primitive relativement récente. Le principe : un agent principal conserve le plan commun sous forme de liste de tâches, et plusieurs sessions pair à pair dans des fenêtres distinctes prennent en charge les tâches qui leur sont confiées. Elles travaillent toutes dans le même système de fichiers et peuvent voir les artefacts intermédiaires des autres.

C’est utile lorsqu’une tâche peut être divisée en 3 à 5 grands flux de travail, qui prennent chacun plusieurs heures (migrer un module volumineux, réécrire un sous-système, réaliser un audit de sécurité complet). Dans ce cas, l’agent principal conserve le plan dans un seul fichier partagé, à un chemin absolu hors des worktrees. Les assistants lisent ce chemin et lui transmettent les résultats ; seul le responsable modifie les statuts, pour éviter des écritures concurrentes.

Techniquement, les agent teams sont plusieurs fenêtres fonctionnant avec git worktree et un point de planification commun. En pratique, 80 % des gens gèrent les agent teams manuellement (comme décrit plus haut avec worktree) et n’utilisent pas de « framework d’équipe » spécial. C’est très bien ainsi.

Si vous ne savez pas si vous avez besoin d’un framework, vous n’en avez presque certainement pas besoin. Utilisez des worktrees manuels et un agent principal dans le répertoire principal.

Niveau 4 : les Dynamic Workflows, Claude écrit un script d’orchestration JS#

Dans les trois niveaux décrits ci-dessus, le plan reste dans une conversation : dans la tête de l’agent principal ou dans la liste de tâches de l’agent principal de l’équipe. Les Dynamic Workflows déplacent le plan dans le code. Claude exprime la tâche sous la forme d’un script JavaScript, le runtime l’exécute dans un environnement isolé, les résultats intermédiaires sont conservés dans des variables du script plutôt que dans votre contexte, et la session reste réactive pendant que les agents travaillent en arrière-plan.

Un exemple concret tiré de la documentation officielle. Vous dites :

ultracode: audit every API endpoint under src/routes/ for missing auth checks

Claude écrit un script JavaScript qui suit à peu près cette logique : « prends tous les fichiers de src/routes/, répartis-les en groupes de 30 endpoints, lance un agent pour chaque groupe avec la même vérification, puis lance deux agents évaluateurs indépendants pour contrôler leurs résultats et rassemble le tout dans un rapport final ». Le script s’exécute. Vous obtenez un tableau de résultats et une liste des endpoints qui nécessitent sans aucun doute un examen.

Quand cela fonctionne.

• Auditer l’ensemble d’un projet pour y repérer un seul type de problème (sécurité, typage, API obsolètes).
• Grandes migrations (500+ fichiers régis par la même règle).
• Questions de recherche qui doivent être vérifiées sous plusieurs angles indépendants (Anthropic utilise cette méthode dans sa commande intégrée /deep-research).

Une présentation détaillée des Dynamic Workflows, de leurs limites et du fonctionnement de ultracode figure dans le guide séparé sur les Dynamic Workflows dans Claude Code.

Quand NE PAS l’utiliser. Lorsque la tâche est linéaire et claire. Un workflow n’est pas nécessaire pour une tâche comme « termine ce composant ». Il est pertinent lorsqu’une tâche se divise en 10+ sous-tâches indépendantes et qu’il faut les vérifier mutuellement.

Limite principale. Un workflow consomme sensiblement plus de tokens qu’une session classique. Anthropic recommande dans sa documentation :

Autrement dit, exécutez votre premier workflow sur un seul répertoire, et non sur tout le projet. Voyez combien il coûte, puis décidez s’il vaut la peine de l’étendre.

Outcomes : une grille de critères et un réviseur indépendant#

La chose la plus dangereuse dans le travail multi-agent est de faire confiance aux résultats des agents. Chaque agent renvoie un texte qui a l’air d’un travail terminé. Une citation semble vraie, un rapport paraît complet, une migration semble achevée. Avec un seul agent, vous pouvez vérifier vous-même. Avec 10, vous ne le pouvez pas : vous n’aurez pas le temps.

Anthropic répond à ce problème avec Outcomes, une fonctionnalité de Managed Agents lancée le 6 mai 2026. L’idée est simple : la session reçoit un DEUXIÈME agent (un évaluateur) dont le seul rôle est de vérifier le travail du premier agent selon une grille de critères stricte.

Voici comment cela fonctionne techniquement. Vous rédigez une grille de critères, un document Markdown qui précise en détail ce que signifie « terminé », quelles sources vérifier et quels labels utiliser. La plateforme crée automatiquement un agent évaluateur dans une nouvelle fenêtre de contexte. Il ne reçoit que la grille et le résultat, rien d’autre. Après chaque tentative de l’agent principal (le rédacteur), l’évaluateur relit le résultat et le valide ou renvoie une liste détaillée des éléments incomplets.

Une citation tirée de l’Anthropic Cookbook :

Chiffres sur l’impact réel : après l’intégration d’Outcomes dans Claude Managed Agents, le taux de réalisation des tâches de l’entreprise d’IA Harvey a été multiplié par environ 6. Chez Wisedocs (documentation médicale), le temps consacré à la révision d’un document a diminué de 50 %. Ces chiffres proviennent de l’annonce officielle de la fonctionnalité.

Ce qui compte pour un vibe coder plutôt que pour une entreprise, c’est qu’Outcomes est un modèle, et pas seulement une fonctionnalité particulière. Vous pouvez créer votre propre agent évaluateur en décrivant les mêmes critères dans .claude/agents/grader.md et en demandant à l’agent principal de le lancer après chaque tentative. Cela fonctionne avec toute configuration multi-agent, et pas seulement avec Managed Agents.

La principale règle de rédaction d’une grille de critères issue du Cookbook est de spécifier quelque chose de vérifiable plutôt que quelque chose de général. Pas « vérifie que le brief couvre la facturation », mais « ouvre le brief, trouve la section sur la facturation et confirme qu’elle indique un montant en $ ou un pourcentage du chiffre d’affaires ». Avec la première instruction, l’évaluateur peut parcourir le document et cocher une case. La seconde l’oblige à ouvrir le document et à trouver un chiffre précis.

Anti-pattern : « 50 agents qui font n’importe quoi »#

C’est l’anti-pattern central du multi-agent. Quelqu’un apprend que Claude Code peut exécuter 16 agents simultanément et que les Dynamic Workflows peuvent en lancer 1000 par exécution, alors il s’assoit et les lance. Résultat : zéro. Consommation de tokens : 10× celle d’une session ordinaire.

Un test simple. Prenez une feuille de papier et dessinez une case pour chacun de vos agents. Dans chaque case, écrivez :

1. Ce qu’il fait précisément (une phrase).
2. Les fichiers auxquels il touche.
3. Ce qu’il renvoie.
4. Qui le vérifie.

Si vous ne pouvez pas répondre à une seule de ces questions en 30 secondes, vous ne devriez pas utiliser cet agent. Cette règle s’applique à tous les niveaux : subagents, agent teams et Dynamic Workflows.

Le deuxième anti-pattern consiste à exécuter en parallèle des tâches qui devraient être séquentielles. Si le frontend a besoin du backend en premier parce qu’il lit le schéma de l’API, ne les exécutez pas en parallèle. Faites d’abord le backend, puis le frontend. Les tâches ne doivent être exécutées en parallèle que si elles sont indépendantes.

Le troisième anti-pattern consiste à utiliser le multi-agent pour gagner en vitesse. Cela ne fonctionne que jusqu’à un certain point. Si vous répartissez une tâche entre quatre flux de travail indépendants, ils termineront à peu près dans le temps qu’aurait pris un seul flux (avec un minimum de coordination en plus). Mais si 50 flux tournent sur une seule machine, chacun fonctionne plus lentement parce qu’ils se partagent le CPU. Sur un ordinateur portable, la limite pratique est de 4 à 6 instances Claude Code simultanées ; au-delà, la limitation des performances commence.

Combien cela coûte-t-il, et comment éviter d’épuiser vos limites ?#

En mai et juin 2026, le secteur a dû se rendre à l’évidence : le codage assisté par IA coûtait plus cher que prévu.

Une session de chat Claude Code ordinaire coûte relativement peu. Activez les Dynamic Workflows pour tout un dépôt, et vous recevrez une facture 20× plus élevée. La documentation officielle d’Anthropic indique :

Que faire en pratique ? Voici les règles d’économie tirées de la pratique décrite.

1. Précisez exactement les fichiers de chaque agent. Pas « examine le projet et trouve les problèmes », mais « examine src/auth/*.ts et vérifie que chaque fonction valide userId ». Le second prompt vous donnera précisément le travail que vous payez.

2. Essayez toujours un workflow sur un seul répertoire d’abord. Pas sur tout src/. Commencez par src/auth/. Si les résultats vous conviennent et que vous comprenez le coût, vous pouvez ensuite l’étendre.

3. Utilisez /effort high par défaut, et ultracode uniquement de manière réfléchie. /effort ultracode signifie xhigh plus une orchestration automatique. C’est très coûteux. Utilisez-le lorsqu’une tâche nécessite réellement plusieurs flux de travail parallèles.

4. Passez les subagents à un modèle plus petit lorsque c’est possible. Si six subagents relisent un guide, ni l’agent QA chargé de repérer les marqueurs d’IA ni celui qui vérifie les liens croisés n’ont besoin d’Opus. Sonnet suffit. Cela réduit la consommation de 3 à 5 fois.

Pour approfondir les économies de tokens, consultez le guide sur l’utilisation des tokens dans Claude Code et Comment ne pas épuiser les limites de Claude Code.

Par où commencer aujourd’hui : une liste de contrôle de 30 minutes#

1. Mettez Claude Code à jour vers v2.1.154+

   C’est la version minimale compatible avec les Dynamic Workflows. Exécutez claude update dans le terminal.

2. Activez les Dynamic Workflows dans /config

   Ils sont désactivés par défaut avec l’offre Pro. Ouvrez /config, trouvez la ligne « Dynamic workflows » et activez-la. Ils sont déjà activés avec les offres Max, Team et Enterprise.

3. Créez votre premier worktree

   Dans le répertoire principal du projet, exécutez git worktree add ../<project>-experiment <branch>. Ouvrez une deuxième fenêtre de terminal dans ce répertoire. Exécutez claude.

4. Ajoutez une liste de tâches partagée

   Utilisez un chemin absolu hors de tous les worktrees : chaque tasks.md de worktree est un fichier distinct, sans synchronisation automatique. Seule la session responsable écrit ; les assistants lisent et lui transmettent les résultats.

   Créez une seule fois le dossier et la liste de coordination :

   mkdir -p "$HOME/projects/my-app-coordination"
   printf '%s\n' '# Tâches' '- Auth : attribuée au worktree auth' '- Billing : attribuée au worktree billing' > "$HOME/projects/my-app-coordination/tasks.md"
   

   Premier terminal :

   cd "$HOME/projects/my-app-auth"
   printf 'Liste partagée : %s\n' "$HOME/projects/my-app-coordination/tasks.md"
   claude
   

   Second terminal :

   cd "$HOME/projects/my-app-billing"
   printf 'Liste partagée : %s\n' "$HOME/projects/my-app-coordination/tasks.md"
   claude
   

   Donnez aux deux agents le même chemin absolu développé affiché : « Lis cette liste partagée. Travaille seulement sur ta tâche et tes fichiers. Ne modifie pas la liste ; signale résultats et blocages au responsable qui la tient à jour. » Vérifiez qu’ils lisent ce fichier exact avant de commencer et résolvez les permissions pour ce chemin. La liste coordonne les statuts ; les changements de code restent dans les worktrees distincts.

5. Travaillez ainsi pendant une semaine

   N’installez pas tout de suite un wrapper GUI. Passez une semaine à travailler manuellement avec deux worktrees. Vous verrez ce qui manque, puis choisirez un outil pour répondre à un problème précis.

6. Activez `/effort ultracode` seulement ensuite

   Choisissez une tâche, par exemple « trouve tous les endpoints d’API sans vérification d’auth dans src/routes/ ». Activez /effort ultracode. Observez le workflow écrit par Claude, son coût et le résultat qu’il produit. Ce sera votre premier Dynamic Workflow.

La suite : mémoire entre les sessions, Code Review et Multi-Agent v2#

Voici ce qui est apparu en mai et juin 2026, et la direction que prend le multi-agent dans Claude Code.

Managed Agents avec Dreaming. Lancé le 6 mai 2026 à Code with Claude. Un processus planifié lit les transcriptions passées d’un agent entre les sessions, repère les schémas récurrents et met à jour sa mémoire. Le taux de réalisation des tâches de l’entreprise juridique spécialisée en IA Harvey a été multiplié par six précisément après l’adoption de Dreaming. Toujours en préversion de recherche.

Outcomes en tant que fonctionnalité de Managed Agents. Présenté plus haut. Disponible via le Claude Agent SDK, mais pas directement dans la CLI Claude Code. Vous pouvez dès maintenant appliquer manuellement la même approche à l’aide d’un subagent évaluateur.

Multi-Agent Orchestration v2 dans le Claude Agent SDK. Un agent principal délègue lui-même le travail à des subagents, en s’appuyant sur un système de fichiers partagé. On passe ainsi de « lancer N subagents manuellement » à « décrire une tâche, et laisser l’agent principal décider lui-même à qui la déléguer et comment ». Si vous découvrez les subagents, inutile de vous préoccuper de la v2 pour l’instant. Apprenez d’abord le modèle classique — « un agent principal + 3 à 5 subagents avec des rôles » — puis passez naturellement à la v2 dans 3 à 6 mois.

Code Review par une équipe d’agents. Lors de Code with Claude, Anthropic a annoncé une fonctionnalité de revue de code automatique à l’ouverture d’une PR. Une équipe d’agents IA examine le diff en parallèle, recherche les bugs, vérifie mutuellement ses conclusions et les classe par gravité. Disponible avec Team et Enterprise, mais pas encore avec Pro.

Plugin Marketplace. Lancé le 23 mai 2026 avec v2.1.128-136. Certains plugins de la marketplace sont des configurations multi-agent prêtes à l’emploi (parallel-review, security-audit, migration-helper). Vous pouvez les installer avec /plugin install <name>@claude-plugins-official et examiner leur fonctionnement : c’est une bonne façon d’apprendre à écrire les vôtres.

Le multi-agent dans Claude Code reste un ensemble de primitives à différents stades de maturité. Les subagents et git worktree sont stables, éprouvés et fonctionnent partout. Les agent teams sont à moitié automatisés, à moitié manuels. Les Dynamic Workflows sont en préversion de recherche et évoluent rapidement. Managed Agents v2 est réservé aux entreprises. Cela signifie que, l’année prochaine, la configuration optimale pour un vibe coder ne sera pas la dernière version, mais la configuration minimale nécessaire à la tâche concernée. Deux worktrees et un subagent évaluateur suffisent pour un mois de travail actif. N’ajoutez de la complexité que lorsque vous commencez à vous sentir limité.

Une configuration qui fonctionne pour le vibe coding#

Ressources pratiques : documentation Ailoot.

Autres ressources et outils : Ailoot.