Orchestrer des sub-agents & Quand ne pas déléguer

Orchestrer des sub-agents en parallèle

L’idée en une phrase

Le chapitre 8 a dessiné le flux en entonnoir ; ici, l’agent principal devient un orchestrateur à part entière : il décompose la tâche en sous-tâches indépendantes, dimensionne le fan-out, borne les rapports et synthétise — c’est le Delegate porté à maturité, avec une contrainte neuve : la fenêtre du parent paie N × rapport, donc orchestrer, c’est d’abord dimensionner.

Analogie : une tour de contrôle. Elle ne pilote aucun avion — chaque équipage gère son cockpit — mais elle séquence des dizaines de mouvements en parallèle sur un nombre de pistes limité. Ce qui lui parvient tient en messages radio courts et normalisés ; si chaque équipage racontait son vol en détail, la fréquence saturerait et plus personne ne serait guidé.

Points clés

• L’orchestrateur ne fait pas le travail. Son rôle : décomposer en sous-tâches indépendantes, rédiger des briefs autoportants (chapitre 8), lancer les workers de front, attendre les rapports, synthétiser. Chaque token qu’il dépense à lire du brut est un token volé à l’orchestration.
• Le motif est un fan-out / fan-in. L’agent principal émet plusieurs délégations sans attendre chacune, puis attend l’ensemble et recompose. Des sous-tâches indépendantes finissent dans ~le temps de la plus lente (chapitre 8).
• La concurrence est plafonnée. Claude Code limite le nombre de sous-agents simultanés (~20 par défaut, ajustable par la variable d’environnement CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) et la profondeur d’imbrication d’un sous-agent qui délègue à son tour (~3 niveaux par défaut). Un grand fan-out se pense en vagues.
• Le vrai plafond est le budget de retour. Ce que le parent paie, c’est N × taille de rapport : 20 workers × ~500 tokens = ~10 000 tokens qui remontent. Chaque brief doit donc imposer un format de rapport borné — sans cette borne, l’orchestrateur se fait saturer par ses propres workers.
• Paralléliser des lecteurs est sûr ; des écrivains, non. Plusieurs workers en lecture seule ne se gênent jamais. Dès qu’il y a écriture, exiger des périmètres disjoints (un fichier ou dossier par worker) — ou garder les écritures chez le parent.

Exemple concret

Tâche : auditer les 30 dépendances d’un package.json (versions, CVE connues, alternatives). L’orchestrateur lance 30 workers researcher ; chacun brasse ~12 000 tokens de doc et de changelog dans sa fenêtre isolée — ~360 000 tokens traités au total, dont rien n’entre chez le parent. Avec des rapports bornés à ~400 tokens, il remonte 30 × 400 = ~12 000 tokens (~6 % d’une fenêtre de 200k) : confortable. Sans borne, des workers verbeux rendent ~2 000 tokens chacun : ~60 000 tokens (~30 % de la fenêtre) — l’orchestrateur a délégué le bruit et l’a fait revenir par la porte des rapports. Même fan-out, même travail : seule la borne de rapport sépare les deux issues.

Fan-out de 30 workers — rapport borné vs rapport libre

Commande — dimensionner et lancer un fan-out

# Relever le plafond de concurrence pour une grande vague (defaut : ~20).
# Le POURQUOI : 30 sous-taches independantes, autant les traiter de front.
export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=30

claude -p "Audite les 30 dependances de package.json. Delegue CHAQUE dependance
  a un sous-agent researcher, EN PARALLELE. Impose a chaque worker un rapport de
  10 lignes max (version, risques, action). Puis synthetise en un seul tableau."

Piège courant : « plus de workers, c’est toujours mieux » est inexact — chaque worker ajoute son rapport à la fenêtre du parent, et au-delà d’un point l’orchestrateur se sature lui-même (~30 % de fenêtre en rapports, et l’attention plonge — chapitre 2). Le fan-out se dimensionne par le budget de retour (N × rapport, à garder sous ~10 % de la fenêtre), pas par l’envie de paralléliser.

Quand ne PAS déléguer : les anti-patterns de la délégation

L’idée en une phrase

Le Delegate n’est pas gratuit : chaque sous-agent repaie un préfixe fixe (system prompt, schémas d’outils — chapitre 7), consomme un brief, et relit ce dont il a besoin ; la délégation ne rapporte que s’il y a du bruit à isoler ou de l’indépendance à paralléliser — sinon, elle ajoute un surcoût sans rien retirer de la fenêtre principale.

Analogie : demander à quelqu’un d’aller chercher une tasse dans sa propre cuisine. Expliquer où est le placard, quelle étagère, quelle tasse — le briefing dure plus longtemps que le trajet. Déléguer a un coût fixe de transmission ; pour une course de trois pas, ce coût dépasse la course.

Points clés

• La tâche minuscule. Modifier 3 lignes d’un fichier déjà présent dans la fenêtre du parent : le sous-agent démarre dans une fenêtre fraîche, repaie plusieurs milliers de tokens de préfixe fixe et relit le fichier. Aucun bruit isolé — du surcoût pur.
• Les sous-tâches dépendantes. Déjà nommé au chapitre 8 : paralléliser une chaîne dont chaque étape a besoin du résultat de la précédente laisse chaque worker aveugle aux autres. Une chaîne s’enchaîne ; on ne la parallélise pas.
• La tâche qui exige l’historique. Si le brief autoportant doit recopier ~20 000 tokens de décisions accumulées dans la session, on n’a pas réduit le contexte : on l’a copié. Cette tâche appartient au parent.
• Les écritures concurrentes. Deux workers qui modifient les mêmes fichiers se marchent dessus — résultat non déterministe. Écritures = périmètres disjoints, ou pas de délégation.
• La boucle avec l’humain. Un sous-agent ne dialogue pas avec l’utilisateur en cours de tâche : tout ce qui demande des allers-retours, des validations, des choix intermédiaires reste chez l’agent principal.

Exemple concret

Renommer une variable dans un fichier de ~3 000 tokens déjà chargé dans la fenêtre principale. En direct : l’édition coûte ~200 tokens (l’appel d’outil et sa confirmation). Délégué : un brief de ~200 tokens descend, le sous-agent repaie ~8 000 à 12 000 tokens de préfixe fixe dans sa fenêtre (chapitre 7), relit les ~3 000 tokens du fichier, puis un rapport de ~300 tokens remonte. Le parent ne paie que ~500 tokens — mais ~12 000 tokens de calcul et une latence de démarrage ont été dépensés pour isoler… zéro bruit : le fichier était déjà dans la fenêtre du parent. La délégation n’a rien retiré ; elle a tout dupliqué.

Symptôme, anti-pattern, alternative

Commande — regarder la fenêtre avant de déléguer

# Avant de deleguer, verifier ce que le parent a DEJA en fenetre :
# si le fichier vise y est deja, la delegation n'isole aucun bruit.
claude
> /context   # etat de la fenetre (chapitre 2) : ce qui est charge ne se re-paie pas

Piège courant : « déléguer fait toujours gagner des tokens » est inexact — la délégation achète deux choses précises : de l’isolation (du bruit qui n’entre jamais chez le parent) et du parallélisme (du temps). Quand la tâche n’offre ni bruit à isoler ni sous-tâches indépendantes, elle n’achète rien et coûte un préfixe fixe, un brief et une relecture. Delegate est un outil, pas un réflexe.

Fil rouge — Reduce ou Delegate ?

Ce chapitre est le Delegate porté à maturité — et borné. Côté orchestration, le fan-out de 30 workers brasse ~360 000 tokens dans des fenêtres isolées et n’en fait remonter que ~12 000 (~6 % d’une fenêtre de 200k) à condition de borner les rapports : la même vague, non bornée, en ferait revenir ~60 000 et saturerait l’orchestrateur. Côté anti-patterns, la limite est chiffrable aussi : déléguer une micro-tâche déjà en fenêtre dépense ~12 000 tokens de calcul pour zéro bruit isolé. La règle du livre se précise : on délègue quand il y a du bruit à isoler ou de l’indépendance à paralléliser ; sinon, on reste chez le parent et on applique Reduce. Dans les deux cas, l’objectif est le même — une fenêtre principale dense, une attention intacte (chapitres 1 et 2).

Travaux pratiques

À chaque leçon, un petit artefact à déposer dans ton .claude/ — commande, sous-agent, hook, mémo… — pour te bâtir, au fil du livre, une boîte à outils de context engineering réutilisable.

Une commande maison — /fanout

La commande /veille du chapitre 8 orchestrait un cas précis — la documentation. Celle-ci généralise : un orchestrateur de fan-out avec garde-fous, qui commence par le go/no-go des anti-patterns de ce chapitre avant de déléguer quoi que ce soit, puis dimensionne la vague et borne les rapports. Delegate quand la tâche s’y prête, refus argumenté quand elle ne s’y prête pas. À déposer dans .claude/commands/fanout.md.

---
description: Orchestre un fan-out de sous-agents en parallele, apres un go/no-go anti-patterns
argument-hint: <tache a decomposer en sous-taches independantes>
---

Tu es l'ORCHESTRATEUR d'un fan-out. Tache : $ARGUMENTS

# Etape 1 — Go / no-go (les anti-patterns d'abord)
Avant TOUTE delegation, verifie chaque point. Au moindre « non », NE DELEGUE PAS :
traite en direct et explique en 2 lignes pourquoi.
- Les sous-taches sont-elles INDEPENDANTES (aucune n'attend le resultat d'une autre) ?
- Y a-t-il du BRUIT a isoler (grosses lectures par sous-tache) ou du temps a
  paralleliser ? Une modif de quelques lignes dans un fichier deja lu se fait en direct.
- Chaque brief tient-il en ~200 tokens SANS recopier l'historique de la session ?
- Les ecritures eventuelles portent-elles sur des perimetres DISJOINTS ?

# Etape 2 — Dimensionner
- Nombre de workers : le minimum qui couvre la tache (la concurrence est
  plafonnee — de l'ordre de 20 sous-agents simultanes par defaut).
- Budget de retour : N x taille de rapport doit rester sous ~10 % de la fenetre.
  Impose a chaque worker un rapport de 10 lignes max, au format fixe.

# Etape 3 — Fan-out / fan-in
- Un brief AUTOPORTANT par sous-tache : chemins ou URL exacts, question precise,
  format de rapport borne. Lance les workers DE FRONT, pas l'un apres l'autre.
- N'execute aucune sous-tache toi-meme. Ne recupere aucun contenu brut.

# Etape 4 — Synthese
- Dedoublonne, reconcilie, signale les contradictions entre rapports.
- Rends UN livrable : tableau ou liste courte, puis recommandation en 3 lignes.

Invoque /fanout audite les 30 dépendances de package.json : le go/no-go passe (30 sous-tâches indépendantes, bruyantes), la vague est dimensionnée, et ~12 000 tokens de rapports bornés remontent au lieu de ~360 000 brassés — l’empreinte du parent divisée par ~30. Invoque /fanout corrige le typo de la ligne 12 : la commande refuse de déléguer et traite en direct — c’est aussi ça, le context engineering : savoir quand Delegate n’achète rien.