Claude Code Dynamic Workflows : comment orchestrer 1 000 sous-agents sur une vraie codebase

Les dynamic workflows de Claude Code sont un système d'orchestration multi-agent : Claude écrit un script JavaScript qui répartit le travail sur jusqu'à 1 000 sous-agents en parallèle, garde tous les résultats intermédiaires dans des variables de script plutôt que dans la fenêtre de contexte du modèle, et ne renvoie dans ta session que la réponse finale vérifiée. Sortis le 28 mai 2026 en même temps que Claude Opus 4.8, ils demandent la CLI v2.1.154 ou plus récente.

Ce post couvre l'architecture, les six primitives de script, des cas d'usage concrets, le vrai calcul des coûts, et les pièges que les devs rencontrent dans les premières semaines de la research preview.

Sommaire

1. C'est quoi le système de dynamic workflow de Claude Code ?
2. Comment fonctionnent les workflows de Claude Code : l'architecture
3. Cas d'usage concrets pour les workflows de Claude Code
4. Coûts, limites et efficacité des workflows de Claude Code
5. Réserves et pièges rencontrés par les devs
6. Workflows de Claude Code vs LangGraph, Temporal, et les autres
7. Bonnes pratiques pour les workflows de Claude Code
8. Questions fréquentes

C'est quoi le système de dynamic workflow de Claude Code ?

Avant les dynamic workflows, chaque sous-agent que Claude lançait renvoyait son résultat dans la fenêtre de contexte de la conversation principale. Du coup, un run de 50 agents accumulait 50 blocs de texte intermédiaire, le contexte se remplissait, et la qualité chutait bien avant la fin de la tâche. Le plafond d'agents n'était pas vraiment une limite dure, plutôt un mur mou où le modèle se retrouvait à court de mémoire de travail utile.

Les dynamic workflows règlent ça en sortant l'orchestration de la conversation, entièrement. Claude écrit un script JavaScript pour la tâche précise que tu lui donnes. Ce script tourne dans un runtime en arrière-plan. La logique d'orchestration (quels agents lancer, combien, dans quel ordre, quand vérifier) vit dans des variables de script. La fenêtre de contexte du modèle ne reçoit que le résultat final synthétisé.

Les six primitives disponibles dans un script de workflow :

• agent(prompt, opts?) — lance un seul sous-agent, renvoie son texte final ou du JSON validé
• parallel(thunks) — exécute un tableau de tâches en concurrence avec une barrière de synchronisation
• pipeline(items, ...stages) — fait circuler les items à travers les étapes sans barrière entre elles
• workflow(nameOrRef, args?) — invoque un workflow sauvegardé comme sous-étape (un seul niveau d'imbrication max)
• phase(title) — nomme un groupe de progression dans le dashboard de suivi /workflows
• log(msg) — émet une ligne de narration dans la sortie du workflow

Le mot « dynamic » a un sens précis ici. Claude décide en temps réel de la décomposition de la tâche, du nombre d'agents, de la stratégie de phasage et de l'approche de vérification, pour la tâche précise que tu as décrite. Pas deux scripts de workflow identiques. C'est différent des Routines (des prompts planifiés statiquement que tu définis une fois) et différent de l'ancienne primitive ScheduleWakeup utilisée dans les sessions /loop.

Voici la structure minimale d'un script de workflow valide :

export const meta = {
  name: 'security-audit',
  description: 'Parallel security scan across auth, DB, and input layers',
  whenToUse: 'When you need a full security sweep before shipping',
  phases: [
    { title: 'Scan', detail: 'Three specialized agents run in parallel' },
    { title: 'Synthesize', detail: 'One agent compiles a prioritized report' },
  ]
}

phase('Scan')
const [auth, db, input] = await parallel([
  () => agent('Audit authentication flows for bypass vulnerabilities', { label: 'auth-scanner' }),
  () => agent('Check all database queries for injection risks', { label: 'db-scanner' }),
  () => agent('Review input validation and sanitization', { label: 'input-scanner' }),
])

phase('Synthesize')
const report = await agent(
  `Compile a prioritized security report from these three findings:\n\nAuth: ${auth}\n\nDB: ${db}\n\nInput: ${input}`,
  { label: 'synthesizer' }
)

return report

Comment fonctionnent les workflows de Claude Code : l'architecture

Quand tu déclenches un workflow, voici la suite des événements :

Étape 1 : planification. Claude analyse ta demande et écrit un script d'orchestration JavaScript. Le script encode quelles phases existent, combien d'agents tournent dans chaque phase, si les items circulent en parallèle ou via un pipeline, et quelle logique de vérification tourne avant de renvoyer les résultats.

Étape 2 : validation. Tu vois les phases prévues à partir du tableau meta.phases. Tu peux le lancer, le marquer comme de confiance pour ce projet pour qu'il ne redemande plus jamais, ouvrir le script JS brut avec Ctrl+G pour l'inspecter, ou annuler.

Étape 3 : exécution. Le runtime du workflow exécute le script dans un processus en arrière-plan. Les sous-agents font le vrai boulot : lecture de fichiers, commandes shell, requêtes web, appels d'outils MCP. Chaque appel agent() renvoie son résultat sous forme de valeur JavaScript (une chaîne, ou du JSON validé si tu as passé un schema). Ces valeurs s'accumulent dans des variables de script, pas dans le contexte de Claude.

Étape 4 : vérification. La plupart des workflows générés par Claude incluent une phase de vérification où des agents séparés tentent de réfuter ou de contester les conclusions de la phase principale. Le workflow itère jusqu'à ce que les résultats convergent.

Étape 5 : livraison. La valeur de retour du script, la réponse finale synthétisée, arrive dans ta session. C'est la seule chose qui touche la fenêtre de contexte de Claude.

Reprise et mise en cache. Le runtime journalise le résultat de chaque appel agent() terminé. Si tu mets un workflow en pause avec la touche p dans le dashboard /workflows, les agents terminés renvoient leurs résultats en cache instantanément à la reprise. Ça ne marche que dans la même session Claude Code : si tu quittes l'application, le journal est jeté et la session suivante repart de zéro.

Le cache de prompt et ses implications de coût. Par défaut, le cache de prompt d'Anthropic a un TTL de 5 minutes. Tout appel agent() qui se déclenche plus de 300 secondes après le précédent rate complètement le cache, ce qui déclenche une réécriture complète à 12,5x le coût d'une lecture de cache. Pour les workflows avec des écarts entre phases de plus de cinq minutes, demande explicitement l'extension du TTL à 1 heure via cache_control: { type: 'ephemeral', ttl: '1h' } au moment du setup initial. Ça coûte 2x le prix d'écriture du cache mais rend les longs workflows beaucoup moins chers.

Le dashboard de suivi /workflows (tape /workflows pour l'ouvrir) affiche les phases, le nombre d'agents actifs, les totaux de tokens, et le temps écoulé. Navigation : Haut/Bas pour sélectionner des phases ou des agents, p pour mettre en pause ou reprendre, x pour stopper un agent ou tout le workflow, r pour redémarrer un agent sélectionné, s pour sauvegarder le run comme commande réutilisable.

Cas d'usage concrets pour les workflows de Claude Code

1. Revue de code en parallèle sur une grosse PR. Découpe les fichiers modifiés en lots, lance un agent par lot pour vérifier la logique, les types, la sécurité et les tests, puis synthétise les conclusions en une revue priorisée. Un dev a lancé 90 agents pour une seule revue de code sur ce pattern et a atteint ses limites mensuelles de tokens, ce qui prouve que le pattern marche mais qu'il faut des garde-fous de budget.

2. Migration ou réécriture à grande échelle. L'exemple canonique, c'est le projet Bun de Jarred Sumner : environ 750 000 lignes de Zig portées en Rust en 11 jours, avec 99,8 % de la suite de tests existante qui passe du premier commit au merge. Le pattern, c'est un document de mapping de 600 lignes (chaque type et idiome Zig traduit vers son équivalent Rust) plus des agents en parallèle traitant des ensembles de fichiers non chevauchants, avec isolation par worktree pour qu'ils puissent écrire sans collisions.

3. Audit de sécurité avec contre-vérification adversariale. Un orchestrateur lance trois scanners spécialisés (flux d'authentification, requêtes base de données, validation des entrées) en parallèle, puis un agent de vérification séparé tente de trouver les faux positifs dans chaque conclusion avant de compiler un rapport priorisé. La phase de vérification adversariale intégrée, c'est ce qui rend ce pattern assez fiable pour des audits avant mise en prod.

4. Moteur de recherche multi-sources. La commande intégrée /deep-research est elle-même un workflow qui illustre le pattern de fan-out : neuf agents explorent différentes sources en même temps, les conclusions intermédiaires se réduisent en candidats classés, un agent de synthèse compile le rapport final. Le même pattern marche pour l'analyse concurrentielle, les audits de dépendances, ou le résumé de changelogs sur un monorepo.

5. Génération de tests à grande échelle. Répartis sur chaque module d'une codebase, un agent par module qui écrit des tests contre la surface d'API publique, puis une phase de convergence vérifie le chevauchement de couverture et supprime les doublons avant d'écrire les fichiers de tests finaux. L'option isolation: 'worktree' dans agent() empêche les agents en parallèle de créer des conflits de fichiers.

Coûts, limites et efficacité des workflows de Claude Code

Limites dures (imposées par le runtime, non négociables) :

Tarification des tokens (à l'usage) :

• Claude Opus 4.8 : $5 en entrée / $25 en sortie par million de tokens
• Claude Sonnet 4.6 : $3 en entrée / $15 en sortie par million de tokens
• Lectures de cache : ~10 % du prix d'entrée. Écritures de cache : ~25 % du prix d'entrée (quand ça marche correctement).

Le calcul de coût sur un vrai workflow. Un audit de sécurité en parallèle qui fait tourner trois agents Sonnet 4.6 à 8 000 tokens d'entrée chacun et 2 000 tokens de sortie chacun coûte à peu près : (3 × 8 000 × $3/M) + (3 × 2 000 × $15/M) = $0,072 + $0,090 = $0,162. Bascule-les sur Opus 4.8 et le même run coûte $0,42. Faire tourner 90 agents comme ça sur une revue d'une grosse codebase aux tarifs Opus atteint $12,60 rien qu'en tokens de sortie avant les frais annexes, ce qui explique comment un dev peut cramer ses limites mensuelles en une seule session.

Quand les workflows sont rentables vs gaspilleurs :

Rentable :

• Les tâches où le parallélisme réduit le temps d'horloge (tu as besoin du résultat vite, le coût est secondaire)
• Les grosses migrations où l'exécution séquentielle prendrait des jours
• Les tâches avec des frontières de sous-tâches claires et aucune dépendance entre agents en cours de run

Gaspilleur :

• Les éditions de routine sur un seul fichier (une conversation normale est plus rapide et moins chère)
• Les tâches qui demandent un pilotage en temps réel ou des consignes en cours de run (les workflows tournent sans surveillance)
• Les demandes exploratoires ou ambiguës où la stratégie de décomposition est inconnue

La falaise de cache des 5 minutes. Si ton workflow a des phases séparées par plus de 300 secondes, chaque agent de la phase suivante paie le plein tarif d'écriture de cache au lieu des lectures de cache bon marché. Sur un run de 50 agents avec un orchestrateur Opus, ça peut gonfler les coûts de 3x à 6x par rapport à un run bien mis en cache. Passe le flag TTL d'1 heure sur le contexte initial pour éviter ça.

Boucles conscientes du budget. La variable globale budget dans les scripts de workflow expose la cible de tokens fixée au lancement. Protège toujours les boucles sensibles au budget : if (budget.total && tokensUsed > budget.total * 0.8) break. Sans garde-fou, les boucles tournent jusqu'au plafond dur de 1 000 agents.

Réserves et pièges rencontrés par les devs

Les scripts de workflow sont en JavaScript, pas en TypeScript. Le runtime n'a pas de couche de transpilation TypeScript. Ajouter des annotations de type à un script de workflow provoque une erreur de parsing. Si tu veux une orchestration typée, écris un wrapper TypeScript qui appelle le workflow à l'exécution ; ne mets pas de types dans le script lui-même.

Trois built-ins non déterministes lèvent une erreur dans les scripts de workflow. Date.now(), Math.random(), et new Date() sans arguments sont interdits. La raison, c'est que le cache de reprise journalise chaque appel agent() par sa clé déterministe. Des valeurs non déterministes généreraient des clés différentes à la réexécution, ce qui casse la reprise. Les contournements : passe les timestamps via args au moment du lancement, fais varier les prompts par index de boucle plutôt que par valeur aléatoire.

Pas d'accès direct au système de fichiers ou au shell dans le script. La couche d'orchestration ne peut pas lire de fichiers ni exécuter de commandes. Toutes les entrées/sorties passent par les sous-agents. Le script est une couche de coordination pure.

Confusion entre parallel() et pipeline(). parallel() est une barrière de synchronisation : il attend chaque thunk avant de renvoyer. pipeline() n'a pas de barrière : l'item A peut être à l'étape 3 pendant que l'item B est encore à l'étape 1. Par défaut, utilise pipeline() pour le traitement d'items indépendants. N'utilise parallel() que quand une étape en aval a besoin de l'ensemble complet de tous les résultats précédents d'un coup (déduplication, classement croisé, revue adversariale de l'ensemble complet). Un thunk en échec dans parallel() se résout en null plutôt qu'en rejet, donc fais toujours .filter(Boolean) sur le tableau de résultats.

Le mode acceptEdits applique automatiquement les changements de fichiers. Les sous-agents qui tournent dans un workflow opèrent en mode acceptEdits par défaut. Les éditions de fichiers s'appliquent sans prompt de revue individuel. Sur un run de 50 agents qui touche des centaines de fichiers, ça veut dire que des changements non revus arrivent à grande échelle. Relis le script de workflow généré (Ctrl+G dans le prompt de validation) avant de le lancer sur des branches de production.

Quand ne pas utiliser les dynamic workflows :

• Toute tâche où tu as besoin de piloter ou d'ajuster en cours de run
• Le débogage exploratoire où l'étape suivante dépend de ce que tu viens de voir
• Les tâches qui demandent une seule réponse ciblée en moins de 10 minutes
• Les environnements sensibles aux coûts sans garde-fous de budget par run en place

Le bug de scope sur les pushes .github/workflows/. Si un sous-agent édite des fichiers sous .github/workflows/, l'édition réussit en local mais échoue au push parce que le credential OAuth de Claude Code n'a pas le scope workflow. L'erreur apparaît une fois tout le budget de la session dépensé. Vérifie que le script de workflow n'écrit pas dans .github/workflows/ avant de valider.

Workflows de Claude Code vs LangGraph, Temporal, et les autres

Ces outils occupent des couches différentes de la stack et ne sont pas interchangeables. La vraie question, c'est quelle couche tu cherches à résoudre.

Claude Code vs LangGraph. Ce ne sont pas des concurrents. Claude Code est un outil de temps de développement. LangGraph est un framework applicatif d'exécution pour des workflows avec état qui tournent en production. Utilise Claude Code pour construire des applications LangGraph. La contrainte importante : Claude Code est verrouillé sur les modèles Claude d'Anthropic. LangGraph est agnostique au modèle via les intégrations LangChain.

Claude Code vs Temporal. Temporal enveloppe n'importe quelle exécution (y compris des agents propulsés par Claude) dans une durabilité à l'épreuve des crashs. Claude Code n'a pas de persistance d'état entre sessions, pas de sémantique exactement-une-fois, et pas d'historique d'exécution auditable. Si ton agent touche à de l'argent, à des dossiers légaux, ou à une opération irréversible, Temporal a sa place dans la stack.

L'architecture complémentaire pour les agents IA de production : le Claude Agent SDK gère le raisonnement IA et la boucle d'usage d'outils. Temporal l'enveloppe pour la tolérance aux pannes. OpenAI Codex et Replit Agent 3 ont tous les deux choisi cette répartition.

Bonnes pratiques pour les workflows de Claude Code

Par défaut, utilise pipeline(), pas parallel(). pipeline() commence à traiter l'item N+1 dès que l'item N termine sa première étape, ce qui élimine les temps morts. Ne va vers parallel() que quand une étape a vraiment besoin de tous les résultats précédents d'un coup.

Utilise schema pour les sorties structurées dès que tu as besoin de parser les résultats d'agents. Passer un JSON Schema à agent() force le sous-agent dans un appel d'outil à sortie structurée avec retry automatique en cas d'écart. Ça enlève le parsing de texte fragile de ta logique d'orchestration.

Mets le TTL de cache à 1 heure sur les longs workflows. Pour les runs avec des phases séparées de plus de quelques minutes, le TTL de cache par défaut de 5 minutes te coûtera 3x à 6x plus cher que nécessaire. Le flag TTL d'1 heure coûte 2x le prix d'écriture mais économise bien plus sur les lectures pour les runs multi-phases.

Protège les boucles sensibles au budget. Chaque boucle infinie-jusqu'à-convergence devrait vérifier budget.total avant d'itérer : if (budget.total && estimatedTokensUsed > budget.total * 0.8) { log('approaching budget, stopping early'); break }. Sans ça, la boucle tourne jusqu'au plafond de 1 000 agents.

Utilise phase() et log() généreusement. Des phases bien étiquetées et des lignes de narration dans le dashboard /workflows te permettent de mettre en pause un run qui part de travers avant qu'il ne finisse. Un workflow sans étiquettes de phase est une boîte noire jusqu'à ce qu'il se termine.

N'utilise isolation: 'worktree' que quand les agents écrivent vraiment dans les mêmes fichiers. L'isolation par worktree crée un worktree git séparé par agent, ce qui est correct pour les tâches d'écriture de fichiers en parallèle mais ajoute une surcharge dont tu n'as pas besoin pour des agents en lecture seule.

Sauvegarde les workflows qui marchent. Appuie sur s dans le dashboard /workflows sur un run terminé et sauvegarde dans .claude/workflows/ (partagé sur le projet) ou ~/.claude/workflows/ (personnel). Un workflow que tu sauvegardes une fois devient une /command utilisable à chaque run futur avec le même pattern.

Questions fréquentes

Combien d'agents Claude Code peut-il faire tourner en parallèle ?

Les dynamic workflows de Claude Code plafonnent l'exécution concurrente à 16 agents qui tournent en même temps. Le total d'agents sur tout un run est plafonné à 1 000. Ces limites sont imposées par le runtime du workflow, quel que soit ton plan d'abonnement. Le plafond de concurrence peut être plus bas sur les machines avec peu de cœurs CPU.

Comment déclencher un dynamic workflow de Claude Code ?

Trois façons : inclure le mot « workflow » n'importe où dans un prompt (Claude Code met le mot-clé en surbrillance et écrit un script d'orchestration), lancer la commande /deep-research, ou régler /effort ultracode qui planifie automatiquement un workflow pour chaque tâche substantielle de la session. Appuie sur alt+w pour supprimer le déclencheur par mot-clé sur un seul prompt sans désactiver la fonctionnalité globalement.

Les dynamic workflows de Claude Code sont-ils dispos sur le plan gratuit ou Pro ?

Les dynamic workflows sont désactivés par défaut sur Pro ($20/mois) et doivent être activés manuellement via /config. Ils sont activés par défaut sur Max (paliers $100/mois et $200/mois) et les plans Team. Sur les plans Enterprise, ils sont désactivés par défaut et demandent une activation par l'admin. Tous les plans demandent la CLI v2.1.154 ou plus récente.

En quoi Claude Code est-il différent de Cursor pour les workflows d'agents ?

Claude Code est un outil agentique natif terminal, conçu pour l'orchestration multi-agent de longue durée sur toute une codebase. Il a les Hooks, les intégrations MCP, les Skills, les dynamic workflows, et il opère entièrement depuis la ligne de commande avec un accès complet au système de fichiers et au shell. Cursor est intégré à l'IDE et optimisé pour l'édition rapide d'un seul fichier dans VS Code. Pour l'édition de code au quotidien dans un IDE, Cursor gagne sur l'ergonomie. Pour les migrations à l'échelle du dépôt, les audits de sécurité, ou les builds multi-agent, le système de workflow de Claude Code n'a pas d'équivalent direct dans Cursor.

Pour quelles tâches concrètes les dynamic workflows de Claude Code ont-ils été utilisés ?

L'exemple le plus cité, c'est la réécriture Zig-vers-Rust de Bun : environ 750 000 lignes portées en 11 jours pour un taux de réussite de 99,8 % de la suite de tests sur Linux x64 (PR #30412, mergée le 14 mai 2026). Rakuten a réduit le délai de livraison d'une fonctionnalité de 24 jours ouvrés à 5 jours grâce à des sessions Claude Code en parallèle. Uber a atteint 84 % d'adoption de Claude Code sur environ 5 000 ingénieurs, avec à peu près 70 % du code commité d'origine IA en mars 2026.

Pour conclure

Les dynamic workflows de Claude Code déplacent l'orchestration depuis la fenêtre de contexte du modèle vers un runtime JavaScript, et c'est ce changement structurel qui rend les runs de 500 et 1 000 agents viables sans dégradation de qualité. Les primitives sont petites et composables. Les coûts sont réels et demandent des garde-fous. Les pièges (scripts JS uniquement, built-ins non déterministes interdits, application auto en acceptEdits, la falaise de cache des 5 minutes) sont assez précis pour être contournés une fois que tu les connais.

Commence par un cas d'usage cadré : une revue de code en parallèle, un balayage de documentation sur une frontière de module, ou un audit de sécurité sur une surface bien bornée. Sauvegarde le run comme commande. Itère sur le script. Les workflows qui marchent de façon fiable sont ceux que tu affines sur plusieurs runs, pas ceux que tu balances sur une tâche à l'échelle de toute la codebase dès le premier jour.

Posté par @speedy_devv