Fondations

20 — Exécution multi-agent

Statut : accepté · Phase : transverse · Mis à jour : 29/10/2026.

Décidé le 29/10/2026. Les plans de Récit s'exécutent par plusieurs agents en parallèle sur le même arbre de travail, une session coordinatrice en tête. Cette page fixe ce que l'outillage permet, les limites mesurées le 29/10 (dix-sept lots du plan 18, deux lots du plan 19, trois inventaires, trois plans écrits dans la journée), les rôles, le protocole, et le découpage le plus parallèle possible des vagues restantes du plan 19. Elle vaut pour tout plan à venir.

1. Ce que l'outillage permet

2. Les limites réelles, mesurées

3. Rôles et protocole

3.1 Les rôles

• Le coordinateur (la session principale) : découpe en lots, écrit les briefs, tient la porte entre deux vagues (vérifications, pnpm check, e2e, galerie), relit les plans, écrit le bilan du journal et la mémoire. Il ne code que les raccords entre lots (une ligne de navigation, une exclusion biome, un câblage oublié) : tout le reste est délégué.
• L'agent de lot : un lot, ses fichiers, sa vérification, sa note au journal, un rapport court. Il ne modifie jamais un fichier qu'il ne possède pas : il le demande dans son rapport.
• L'agent d'inventaire : lecture seule avant tout plan qui touche beaucoup de fichiers ; trois en parallèle, un par zone, pour le plan 19.
• L'agent relecteur : un plan est relu deux fois par son rédacteur et une fois par le coordinateur, contre le code et les inventaires, avant d'être exécuté.
• L'utilisateur : commits de contrôle (« Claude limit », « screenshot before migration »), la branche, les réponses aux questions ouvertes, la revue de la galerie servie quand il le veut.

3.2 La porte entre deux vagues

1. Chaque lot de la vague a rapporté, avec ses commandes de vérification passées.
2. Le coordinateur fait les raccords signalés par les rapports et relance pnpm check.
3. pnpm test:e2e:linux dans le conteneur, sur l'arbre stable, deux fois (règle du skill e2e-baselines) ; les specs de la surface touchée suffisent entre deux vagues, la suite entière à la fin.
4. La galerie (node scripts/screenshot-gallery.js, --serve <port> pour l'utilisateur) : chaque différence est voulue ou corrigée ; les références acceptées sont régénérées par pnpm test:e2e:update:linux <spec> et listées au journal avec la raison.
5. La vague suivante part. Le tableau d'état de la page du plan est mis à jour.

3.2 bis La boucle courte des agents (30/10)

Mesuré à la vague 4 : pnpm check dure environ 10 s, mais le conteneur e2e coûte 2 s de copie, 28 s d'installation, 2 min de build de tous les sites quelle que soit la spec, puis jusqu'à 5 min de tests, et un seul tourne à la fois : huit agents qui le lançaient chacun faisaient la queue et reconstruisaient tout. La règle depuis :

• un agent ne lance jamais le conteneur : il travaille avec pnpm check, pnpm test:related <fichiers>, pnpm test:stories <stories>, le build et le typecheck de son projet, et pnpm test:e2e:host <spec> (Playwright sur la machine, projet chromium, sans captures) pour le comportement ;
• les captures sont jugées à la porte, par le coordinateur seul : pnpm test:e2e:linux une fois pour toute la vague, la galerie, puis les références acceptées ;
• un agent qui pense avoir changé un rendu le dit dans son rapport, avec la page ; la porte vérifie.

Allègements du 30/10 (lot INFRA), mesurés sur pnpm test:e2e:linux e2e/site-docs.spec.ts avec d'autres agents au travail :

• avec des specs, le conteneur ne construit et Playwright ne sert que leurs projets (scripts/e2e-projects.js, variable E2E_PROJECTS) ; sans spec, tout, comme la CI ;
• node_modules Linux reste dans le volume recit-e2e-work, le reste est recopié de l'arbre et pnpm install --frozen-lockfile tourne toujours ; un second passage simultané s'arrête net ;
• le conteneur est plafonné à E2E_CPUS=6 et E2E_MEMORY=12g, quatre workers Playwright ;
• les hooks git restent courts : au commit Biome, oxfmt et les deux compteurs (quelques secondes), au push pnpm check, le typecheck des projets touchés et pnpm test:related (une à deux minutes), jamais Docker ; LEFTHOOK=0 ou --no-verify les sautent.

3.3 Le brief type

Dix éléments, toujours dans cet ordre, pour un agent frais comme pour un fork : l'objectif et le numéro du lot ; les sections du plan et le skill à lire d'abord ; les fichiers possédés, liste exhaustive ; les agents concurrents et leurs fichiers ; les faits de la machine (chaînes installées, caches, BROWSER=none, ce qui est déjà construit) ; les livrables numérotés comme dans le plan ; les commandes de vérification à coller dans le journal ; le titre de la note de journal ; la forme du rapport (langue, longueur, ce qu'il doit contenir pour les lots suivants) ; les interdits (git, branche, worktree, pnpm fix, oxfmt global, CLAUDE.md).

3.4 La coupure de limite d'usage

Quand la limite coupe une vague : le coordinateur note l'heure de remise à zéro, relit git status et pgrep, puis renvoie à chaque agent un message de reprise qui dit ce qui est sur le disque, ce qui tourne encore, et ce que les autres agents ont livré entre-temps. Un agent relancé repart de son contexte, pas de zéro. Rien n'est relancé en double.

4. Le découpage le plus parallèle du plan 19

Le plan 19 §10.1 prévoit sept vagues et dix-sept lots. Le 29/10, STY0 tournait seul en vague 1 alors que quatre de ses six items ne partagent aucun fichier : le découpage ci-dessous les sépare, et fait de même pour STY5 et STY6.3. Les dépendances de fichiers de §10 du plan 19 restent la seule contrainte ; chaque ligne nomme le type d'agent qui convient.

Vingt-trois agents au lieu de dix-sept, huit portes au lieu de sept, et jamais plus de cinq agents à la fois, dont trois lourds au plus. Les lots « frais » ont dans leur brief la page du plan, le skill et les notes du journal des lots dont ils dépendent : c'est ce qui les rend possibles. Le plan 21 (tests et Storybook) s'intercale sur les mêmes surfaces : ses lots qui touchent sites/storybook/.storybook/* et packages/components passent après STY6.1 et STY6.2, ou dans leur vague avec des fichiers distincts (ses propres *.stories.tsx et specs).

5. Budget et rythme

• Une vague de quatre à cinq lots coûte entre un et deux millions de jetons d'agents et une heure à une heure et demie de travail, porte comprise. Les sept vagues restantes du plan 19 tiennent en une à deux journées de calendrier selon les coupures.
• Un fork par vague au plus là où le contexte de la session compte (le thème, la bascule) ; tout le reste en agents frais. Les inventaires et les relectures en agents frais ou Explore.
• Le coordinateur garde son contexte pour les portes : il ne lit pas les transcriptions des agents, seulement leurs rapports ; les gros fichiers (un plan de mille lignes) sont lus par sections.

6. Ce que l'utilisateur voit

• sites/plans/pages/journal.md : une note par lot, un bilan par jour, toujours à la fin.
• Le tableau d'état en tête du §5 ou §10 de chaque plan (18 : fait ; 19 : à tenir à jour par vague).
• git status : rien n'est commité par un agent ; les commits de contrôle sont les siens.
• La galerie servie : node scripts/screenshot-gallery.js --serve 4390, à ouvrir depuis son poste.
• La mémoire de session (hors dépôt) garde l'état de la machine et les règles apprises.

7. Risques

8. Questions ouvertes

1. Faire tourner des vagues la nuit, sans porte humaine ? Proposé : oui pour les lots, non pour la fusion ; la galerie attend le matin.
2. Passer les vagues sous Workflow (pipeline écrit d'avance) ? Proposé : non tant que les coupures de limite demandent une reprise manuelle ; à revoir si elles disparaissent.
3. Autoriser un agent à committer à la fin de son lot sur feature/* ? Proposé : non, les commits de contrôle restent à l'utilisateur (règle globale).