Fan out de subagents dans Claude Code, puis vérifier ce qui revient

Les gens tapent « claude fan out subagents » dans Google, et pas mal ajoutent « command » à la fin, comme s'il y avait un interrupteur à basculer. Il y a une méthode, et il y a aussi une commande. On a vérifié les deux sur Claude Code 2.1.301, et dans la documentation d'Anthropic, le 16 octobre 2026.

Reste la partie dont la documentation parle peu, et la raison de cet article : quoi faire des résultats. On fait tourner un fan out chaque nuit. Six subagents traduisent chaque nouvel article de ce blog en dix-sept langues, et la session principale fusionne leur travail. Chacun d'eux déclare avoir suivi les règles. Le contrôle qu'on a écrit avant de les lancer trouve quand même des choses.

La réponse courte

Faire un fan out, c'est une session qui découpe un travail en tranches indépendantes, confie chaque tranche à un subagent, les laisse tourner en même temps, puis fusionne ce qui revient. Dans Claude Code, tu as trois façons de le faire.

La suite reprend chaque façon, puis les contrôles qu'on fait sur notre propre fan out.

Ce qu'un subagent voit, et ce qu'il ne voit pas

Trois faits de la documentation décident de la façon de découper le travail.

Chaque subagent part de zéro. Il tourne dans sa propre fenêtre de contexte, avec son propre system prompt, ses outils et ses permissions. Il ne voit ni ta conversation, ni les skills déjà utilisés, ni les fichiers que Claude a déjà lus. Tout ce qu'il doit savoir doit être dans son brief.

Les résultats reviennent dans la conversation principale. Le détail du travail d'un subagent reste dans son propre contexte, seul son résultat revient. Mais beaucoup de subagents qui renvoient de longs rapports peuvent quand même remplir ton contexte principal, et chacun dépense ses propres tokens pendant qu'il tourne.

Il y a des limites. Par défaut, 20 subagents peuvent tourner en même temps dans une session. Le 21e échoue avec Concurrent subagent limit reached, et l'erreur dit à Claude de ne pas réessayer. Tu peux monter ou baisser la limite avec CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Un subagent peut lancer ses propres subagents, jusqu'à trois niveaux sous la conversation principale, et le total sur une session n'est pas limité.

Façon 1 : le demander en toutes lettres

Le fan out le plus simple tient en une phrase. L'exemple de la documentation d'Anthropic :

Research the authentication, database, and API modules in parallel using separate subagents

Chaque subagent explore sa zone, puis Claude écrit une synthèse. La documentation ajoute la condition qui compte : ça marche le mieux quand les pistes de recherche ne dépendent pas les unes des autres. Si la question sur la base de données a besoin de la réponse sur l'auth, tu n'as pas trois tranches, tu as une seule suite d'étapes.

En toutes lettres, c'est Claude qui décide. Si tu as défini un subagent personnalisé dans .claude/agents/, le mentionner avec @ garantit qu'il tourne pour cette tâche. Notre page sur les subagents de Claude Code explique comment marchent ces fichiers.

Façon 2 : /batch, ce qui ressemble le plus à une commande de fan out

/batch est un skill livré avec Claude Code. Tu lui donnes une consigne :

/batch migrate src/ from JavaScript to TypeScript

Il explore le code, découpe le travail en 5 à 30 unités indépendantes et te montre un plan. Une fois le plan approuvé, il lance un subagent en arrière-plan par unité, chacun dans un worktree git isolé. Chaque subagent implémente son unité, lance les tests et publie son changement. Il faut un dépôt git, ou un hook WorktreeCreate qui crée les worktrees pour un autre gestionnaire de versions.

C'est au plan qu'il faut ralentir. C'est là que le découpage se décide, et le découpage est tout le jeu : deux unités qui touchent le même fichier, ou une unité qui a besoin du résultat d'une autre, ne fusionneront pas proprement, aussi bons que soient les subagents. Lis la liste des unités comme tu lirais un plan de migration écrit par un collègue.

Façon 3 : une boucle sur claude -p

Quand le travail est une liste de fichiers et que tu veux garder la main sur chaque appel, les bonnes pratiques d'Anthropic décrivent une boucle. D'abord, fais écrire la liste par Claude (list all 2,000 Python files that need migrating and save the list to files.txt). Puis :

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --permission-mode dontAsk
done

Trois détails de cet exemple méritent d'être recopiés.

• La réponse se lit par une machine. « Return OK or FAIL » veut dire que ton script peut compter les échecs sans lire de prose.
• Les permissions sont décidées avant. --allowedTools autorise exactement ce dont la migration a besoin, et --permission-mode dontAsk refuse tout le reste au lieu d'attendre quelqu'un qui n'est pas là.
• Tu commences par deux ou trois fichiers. La documentation le dit simplement : corrige le prompt sur ce qui rate avec les premiers fichiers, puis lance la liste entière.

Telle qu'elle est écrite, la boucle traite un fichier après l'autre. Lancer plusieurs appels en même temps, c'est du shell ordinaire, mais chaque appel est une session complète sur ta machine et sur ton quota. On a mesuré ce qui se passe quand plusieurs agents lancent la même commande lourde à la même minute dans cet article, et c'est la même histoire ici : commence avec peu d'appels en parallèle.

Pour la CI, la documentation recommande d'ajouter --bare, qui saute les hooks, les skills, les serveurs MCP et CLAUDE.md pour que chaque machine fasse le même run. Le mode bare n'utilise pas la connexion de ton abonnement : il lui faut ANTHROPIC_API_KEY.

Comment on fait un fan out chaque nuit

Voici le fan out qu'on fait vraiment tourner. Notre équipe SEO de nuit écrit chaque nouvel article en anglais et en français, à la main. Un second agent le traduit ensuite dans dix-sept autres langues avec des subagents de Claude Code, et produit le chinois traditionnel à partir du chinois simplifié par un script, sans le traduire. Onze articles sont passés par là depuis le 13 septembre 2026, et chacun arrive sous forme de vingt fichiers.

Les tranches

Six subagents, trois langues chacun (deux pour le dernier) : espagnol, portugais et italien ; allemand, néerlandais et polonais ; russe, ukrainien et turc ; japonais, coréen et chinois ; thaï, vietnamien et indonésien ; arabe et hindi. Aucune langue ne dépend d'une autre, et c'est ce qui en fait un fan out propre.

Chaque brief porte les cinq mêmes choses, parce que le subagent ne voit rien d'autre :

• la source anglaise, et la version française comme référence de ton et de termes produit ;
• pour chaque langue, des phrases déjà publiées sur le site dans cette langue, pour que le subagent reprenne les mots que le site emploie déjà au lieu d'en inventer ;
• les règles dures : les noms de marques et de produits restent tels quels, le code reste identique à l'octet près, aucun tiret cadratin ;
• le script de contrôle, avec la consigne de le relancer jusqu'à ce qu'il réponde OK ;
• la demande de signaler tout ce qui lui a semblé douteux, dans sa tranche ou en dehors.

Le contrôle s'écrit avant le lancement

Le contrôle est un script, pas l'avis d'un subagent. Pour chaque langue, il compare le fichier à la source anglaise :

• même slug et même date, titre égal au H1 ;
• même nombre de sections, de sous-sections, d'images, de liens et de lignes de tableau, et autant de réponses de FAQ dans le corps que de questions dans les métadonnées ;
• liens identiques à l'octet près, segments de code identiques à l'octet près ;
• noms de marques comptés, jamais moins qu'en anglais ;
• une longueur dans des bornes calibrées pour chaque langue, parce que le chinois dit la même chose en à peu près 36 % des caractères dont l'anglais a besoin, et le japonais en à peu près la moitié ;
• des accents là où la langue en a (polonais, turc, vietnamien).

Chaque subagent finit par une variante de « fini, tous les contrôles passent ». Le seul verdict sur lequel on agit, c'est le même script, relancé par la session principale, sur tous les fichiers d'un coup.

Ce que le contrôle central a trouvé et que les rapports des subagents ne disaient pas

Du code traduit dans un tableau. Le 13 septembre, environ la moitié des subagents ont traduit les mots qui suivaient une commande à l'intérieur des mêmes backticks d'un tableau. Chacun avait suivi son brief tel qu'il le comprenait. La correction est allée dans le brief, pas dans les subagents : un segment de code ne contient que la commande, et les mots qui suivent sortent des backticks.

Notre propre contrôle se trompait. Le 6 septembre, un contrôle de longueur calibré sur l'ancienne phrase qu'on remplaçait a signalé 11 subagents sur 17. Les 11 avaient raison : le nouveau texte devait être plus long. Calibré sur le français déjà corrigé, il n'en a plus signalé aucun. Un contrôle central peut se tromper aussi, et la façon de le voir, c'est de le lancer d'abord sur une livraison qu'on sait bonne.

La cohérence entre les tranches. Le 15 octobre, sur une nouvelle page de fonctionnalité traduite de la même façon, le contrôle de fusion a confirmé que seules les phrases attendues avaient changé dans 90 fichiers. Mais les subagents japonais, coréen et chinois avaient chacun choisi pour « You may also like » un autre titre que celui que leur langue employait déjà sur une page voisine. Chaque choix était une traduction correcte. Aucun n'était cohérent avec le site. Aucun subagent ne pouvait le voir depuis sa tranche : seule une passe sur le résultat fusionné le voit.

Un mot faux passe tous les contrôles de structure. Une langue du site a appelé un jour les agents IA des concessionnaires automobiles, et c'est resté en ligne des mois. Même longueur, même ponctuation, marque présente : tous les comptes étaient verts. La seule chose qui l'attrape, c'est une liste nommée de mots faux connus, qui bloque chaque déploiement et prend une ligne de plus à chaque fois qu'on en trouve un nouveau.

Les signalements hors de la tranche. Le 15 octobre, le subagent qui travaillait sur le turc a signalé que le site écrivait « ajans », agence, pour « agent » dans 97 phrases existantes. Il n'y a pas touché, parce que son brief le lui interdisait. On a ouvert un ticket et la correction est partie le lendemain. Demander aux subagents ce qu'ils ont vu, et pas seulement ce qu'ils ont fait, coûte peu et rapporte.

La fusion se fait à un seul endroit

Les subagents n'écrivent pas directement dans le dépôt. Chacun rend ses fichiers, un script les fusionne, puis compare le résultat à la version précédente phrase par phrase : seules les phrases demandées ont le droit d'avoir changé. Ensuite, les contrôles du dépôt et le build du site tournent une seule fois, sur le résultat fusionné. Lancer le build une fois par subagent serait plus lent, et testerait des états à moitié fusionnés qui ne partiront jamais en ligne.

Quand ne pas faire de fan out

• Les tranches dépendent les unes des autres. Si la tranche B a besoin du résultat de la tranche A, fais-les dans l'ordre.
• Le travail est petit. Chaque subagent part de zéro et relit ce dont il a besoin. Sur une tâche de dix minutes, les nouveaux départs coûtent plus qu'ils ne font gagner.
• Tu ne sais pas écrire le contrôle. S'il n'y a aucun moyen de distinguer une bonne tranche d'une mauvaise sans tout relire toi-même, c'est à la fusion que tu passeras ton temps.
• Le quota est serré. Chaque subagent dépense ses propres tokens. Le fan out fait gagner du temps et garde un contexte principal propre, il ne fait pas baisser la facture.

Où se place AgentsRoom

Les subagents vivent à l'intérieur d'une seule session de Claude Code. Tu vois leurs résultats, pas leur travail, et tu ne peux pas en reprendre un en cours de route. Quand tu veux que chaque tranche soit un agent que tu peux suivre, à qui tu peux répondre et dont tu relis le travail à part, lance plutôt des sessions séparées : chaque ticket dans son propre worktree git, et Agent Teams quand les tranches se passent le travail. Une étape d'équipe peut porter une commande de contrôle, et c'est son code de sortie, pas ce que dit l'agent, qui décide si le run avance. C'est la même règle que plus haut, appliquée par le runner. Ça marche avec Claude Code, Codex et les autres CLI d'agents qu'AgentsRoom prend en charge.

Si tu hésites encore entre subagents et Agent Teams, cette comparaison explique à quoi sert chacun.