Vous avez une fonctionnalite qui necessite trois choses en meme temps. Vous pouvez lancer des sous-agents dans une seule session Claude Code et les laisser travailler en parallele. Ou vous pouvez decouper le travail en trois taches independantes, confier chacune a un agent separe dans son propre panneau tmux, et les laisser tourner sans qu'ils se connaissent.

Les deux approches parallelisent le travail. Elles resolvent des problemes differents. Choisissez la mauvaise et vous brulerez soit de la fenetre de contexte en overhead de coordination, soit vous creerez des conflits de merge plus longs a resoudre que la tache initiale.

Voici le cadre de decision que j'utilise chaque jour en faisant tourner 13 agents Claude Code sur la meme codebase. Ce n'est pas theorique. C'est le resultat d'avoir fait suffisamment d'erreurs pour savoir ou se trouve la frontiere.

Deux types de parallelisme

Claude Code propose deux facons distinctes d'executer du travail de maniere concurrente.

Les sous-agents sont des processus enfants lances au sein d'une seule session Claude Code. L'agent parent demarre plusieurs sous-agents, chacun s'attaque a une partie du probleme, puis rassemble les resultats. Ils partagent le meme repertoire de travail et le contexte du parent. Pensez a eux comme des threads dans un seul processus.

Parent agent
  ├── Subagent A: "Search lib/ for all usages of parseConfig"
  ├── Subagent B: "Search server/ for all usages of parseConfig"
  └── Subagent C: "Search components/ for all usages of parseConfig"

Les agents separes tournent dans des sessions Claude Code independantes, generalement dans des panneaux tmux distincts. Chacun a sa propre fenetre de contexte, son propre fichier d'identite CLAUDE.md et sa propre vue de la codebase. Ils ne partagent pas de memoire. Ils communiquent a travers des artefacts : commentaires de taches, mises a jour de statut, code commite. Pensez a eux comme des processus separes sans etat partage.

tmux pane 1: eng1 agent → "Build the REST endpoint"
tmux pane 2: eng2 agent → "Build the React component"
tmux pane 3: qa1 agent  → "Write integration tests for both"

Le modele mental compte parce qu'il determine comment le travail circule entre les unites. Les sous-agents peuvent renvoyer des donnees au parent a moindre cout. Les agents separes transmettent des donnees via le systeme de fichiers, git ou un gestionnaire de taches externe.

Quand les sous-agents gagnent

Utilisez les sous-agents quand le travail partage un etat et que les resultats doivent converger.

Recherche en parallele. Vous devez parcourir cinq repertoires a la recherche d'un pattern, lire trois fichiers de documentation et synthetiser les resultats en une recommandation. Les sous-agents peuvent chacun prendre un chemin de recherche, retourner des resultats, et le parent peut les combiner sans overhead de serialisation.

Transformations independantes sur les memes donnees. Vous refactorisez un module et devez mettre a jour les definitions de types, les tests et la documentation en un seul changement coherent. Chaque sous-agent gere un fichier, mais le parent s'assure de la coherence puisqu'il voit les trois resultats avant de commiter.

Exploration rapide. Vous debuguez et devez verifier le git log, la sortie des tests et la config runtime simultanement. Les sous-agents peuvent collecter les trois en parallele et le parent synthetise un diagnostic.

Le pattern : distribuer, rassembler, agir sur le resultat combine. Si votre parallelisme se termine par le parent devant raisonner sur tous les outputs ensemble, les sous-agents sont le bon outil.

Ou les sous-agents echouent : tout ce qui prend plus de quelques minutes par branche, tout ce qui modifie des fichiers dans des chemins superposes, ou tout ce qui necessite une verification independante. Les sous-agents partagent un repertoire de travail, donc deux sous-agents ecrivant dans le meme fichier corrompront mutuellement leur travail. Et puisqu'ils partagent le contexte, un sous-agent de longue duree consomme la fenetre disponible du parent.

Quand les agents separes gagnent

Utilisez des agents separes quand le travail peut etre verifie independamment et n'a pas besoin d'un contexte partage pour avoir du sens.

Differents composants de la meme fonctionnalite. "Construire l'endpoint API" et "Construire le frontend qui l'appelle" sont independants jusqu'a l'integration. L'ingenieur API n'a pas besoin du composant React dans son contexte. L'ingenieur frontend n'a pas besoin du schema de base de donnees. Donner a chacun son propre agent avec un CLAUDE.md delimite garde le contexte propre et empeche la complexite d'un agent de contaminer le travail de l'autre.

Des criteres d'acceptation differents. Si la tache A est terminee quand l'endpoint retourne 200 avec la bonne forme JSON, et la tache B est terminee quand le composant affiche les donnees avec les bons etats d'erreur, ce sont des cibles de verification separees. Un agent QA peut valider chacune independamment. Les sous-agents ne peuvent pas etre verifies independamment car ils produisent un output combine.

Du travail qui touche differentes parties de la codebase. Le file ownership est le moyen le plus simple de prevenir les conflits de merge. L'agent A possede server/, l'agent B possede components/. Aucun n'entre dans le territoire de l'autre. Si vous essayez avec des sous-agents, le parent devrait gerer le file locking, ce qui annule l'interet du parallelisme.

Des taches avec des horizons de temps differents. Une tache prend 10 minutes, l'autre 2 heures. Avec les sous-agents, le parent attend l'enfant le plus lent. Avec des agents separes, la tache courte se termine, est verifiee et shippee pendant que la tache longue tourne encore.

Le pattern : lancer, oublier, verifier separement. Si chaque morceau de travail tient seul et peut etre verifie seul, les agents separes avec des taches structurees sont plus propres.

Le probleme du transfert

Le veritable point de decision se resume aux transferts.

Les transferts de sous-agents sont peu couteux. L'enfant renvoie des donnees au parent dans le meme contexte. Pas de serialisation, pas d'ecriture de fichiers, pas d'attente de mise a jour de statut. Le parent lance trois sous-agents, ils retournent trois resultats, le parent a tout ce qu'il faut.

Les transferts entre agents separes sont couteux mais durables. L'agent A termine son travail, commite du code, met a jour un statut de tache et commente ce qu'il a fait. L'agent B capte ce signal (soit via un coordinateur, soit en interrogeant le gestionnaire de taches) et commence son travail dependant. L'overhead est reel : vous avez besoin d'un systeme de taches, d'un protocole de statut et d'un moyen pour que les agents decouvrent ce que d'autres agents ont fait.

La regle generale : si le travail necessite plus d'un transfert entre les unites paralleles, utilisez les sous-agents. Pour un simple fan-out-and-gather, les sous-agents sont plus simples. Si l'output de l'agent A est l'input de l'agent B, qui devient l'input de l'agent C, le cout de coordination des agents separes est justifie parce que chaque transfert produit un artefact verifie et commite qui ne sera pas perdu si un agent plante ou atteint une limite de contexte.

Un exemple concret. Vous devez :

Trouver tous les endpoints API qui retournent des donnees utilisateur
Ajouter du rate limiting a chacun
Ecrire des tests pour les nouveaux rate limits
Mettre a jour la documentation API

Les etapes 1 et 2 sont fortement couplees. Les resultats de recherche (etape 1) alimentent directement la modification (etape 2). Un sous-agent gere la recherche ; le parent applique les changements. C'est un pattern de sous-agent.

Les etapes 3 et 4 sont independantes l'une de l'autre mais dependent de l'etape 2. Les tests ont besoin du code reel de l'endpoint. La documentation a besoin de la forme finale de l'API. Ce sont des taches separees pour des agents separes, chacune avec ses propres criteres d'acceptation, chacune verifiable independamment.

Decomposition structuree en pratique

Quand la reponse est "agents separes," vous avez besoin d'un moyen de decomposer la fonctionnalite en taches qui peuvent tourner en parallele sans se marcher dessus.

Le processus de decomposition :

1. Identifier le graphe de dependances. Avant de decouper quoi que ce soit, cartographiez ce qui depend de quoi :

Feature: User profile page with activity feed

- API endpoint: GET /users/:id/profile     (no deps)
- API endpoint: GET /users/:id/activity     (no deps)
- React component: ProfileHeader            (depends on profile API)
- React component: ActivityFeed             (depends on activity API)
- Integration test: profile page end-to-end (depends on all above)

Les deux endpoints API n'ont pas de dependances. Ils peuvent tourner en parallele. Les deux composants React dependent chacun d'une API. Le test d'integration depend de tout.

2. Tracer les limites de propriete. Chaque tache recoit un perimetre de fichiers. L'agent du profile API possede server/routes/profile.ts et server/services/profile.ts. L'agent du activity API possede server/routes/activity.ts et server/services/activity.ts. Aucun ne touche aux fichiers de l'autre. Si un utilitaire partage necessite une modification, un agent cree le changement et l'autre attend.

3. Definir les criteres d'acceptation par tache. Chaque tache a besoin d'une condition "termine" claire qui peut etre verifiee sans regarder les autres taches. "Profile API retourne 200 avec la bonne forme" est verifiable. "La page profil fonctionne" ne l'est pas, car cela depend de l'integration.

4. Specifier les artefacts de transfert. De quoi un agent en aval a-t-il besoin d'un agent en amont ? Generalement : du code commite sur une branche connue, une mise a jour de statut et un commentaire decrivant le contrat d'interface (forme API, props de composant, signatures de fonctions).

Cette decomposition transforme un vague "construire la page profil" en cinq taches discretes avec des dependances explicites et des criteres de verification. Chaque tache peut etre assignee a un agent qui a exactement le contexte dont il a besoin et rien de plus.

Beads pour la decomposition structuree

C'est la que disposer d'un vrai systeme de taches compte. Vous ne pouvez pas suivre cinq taches paralleles avec des post-it et de l'output terminal.

beads est un issue tracker local-first qui modelise cette decomposition nativement. Un epic represente la fonctionnalite. Les enfants representent les sous-taches. Les dependances empechent les agents de commencer un travail avant que les prerequis soient remplis.

Voici a quoi ressemble la decomposition en pratique :

# Create the epic
bd create --title "User profile page with activity feed" \
  --type epic --priority p2

# Create subtasks as children
bd create --title "GET /users/:id/profile endpoint" \
  --parent bb-epic1 --type task --priority p2

bd create --title "GET /users/:id/activity endpoint" \
  --parent bb-epic1 --type task --priority p2

bd create --title "ProfileHeader React component" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-profile-api

bd create --title "ActivityFeed React component" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-activity-api

bd create --title "Profile page integration test" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-profile-header,bb-activity-feed

La structure est maintenant explicite. Un agent executant bd show bb-profile-header voit qu'il depend de la tache profile API. Si cette tache n'est pas terminee, l'agent sait qu'il ne doit pas commencer. Quand l'agent API termine et marque sa tache comme terminee, la dependance de l'agent frontend se resout.

Le workflow de l'agent suit une boucle previsible :

# Agent claims the task
bd update bb-profile-api --claim --actor eng1

# Agent comments its plan before writing code
bd comments add bb-profile-api --author eng1 "PLAN:
1. Create route handler at server/routes/profile.ts
2. Add service layer at server/services/profile.ts
3. Return shape: { id, name, avatar, bio, joinedAt }
4. Test: curl localhost:3000/users/1/profile returns 200"

# Agent implements, tests, commits
# ...

# Agent marks done with verification steps
bd comments add bb-profile-api --author eng1 "DONE: Profile endpoint implemented.
Returns { id, name, avatar, bio, joinedAt }.
Verified: curl returns 200 with correct shape.
Commit: abc1234"

bd update bb-profile-api --status ready_for_qa

Chaque etape est enregistree. L'agent QA lit le commentaire DONE et sait exactement comment verifier. L'agent en aval lit le commentaire PLAN et connait le contrat API avant meme que le code soit termine.

Ce n'est pas de l'overhead pour le plaisir du processus. C'est la structure minimale qui empeche cinq agents paralleles de produire cinq morceaux de code incompatibles.

Choisir par defaut

Apres des mois a faire tourner des agents en parallele sur du travail de production, voici l'arbre de decision que je suis :

Commencez avec les sous-agents quand :

La tache est de la recherche ou de l'exploration (chercher, lire, comparer)
Les resultats doivent converger en une seule action
Tout le travail tient dans une fenetre de contexte
Il n'y a pas besoin de verification independante de chaque unite parallele

Passez aux taches separees quand :

Differentes parties du travail touchent differents fichiers
Chaque morceau a ses propres criteres d'acceptation
Vous voulez que le QA verifie les morceaux independamment
Le travail durera assez longtemps pour qu'un morceau finisse des heures avant l'autre
Les agents ont besoin de contextes differents (un agent frontend n'a pas besoin des details internes de la base de donnees)

L'approche hybride pour les fonctionnalites complexes : Utilisez les sous-agents pour la phase de recherche et planification (distribuer, collecter l'information, synthetiser un plan), puis decomposez l'implementation en taches separees pour des agents independants. Le workflow spec-driven development s'integre naturellement ici : un seul agent avec des sous-agents ecrit la spec, puis la spec se decompose en taches pour la flotte multi-agents.

Visualiser la decomposition

Une fois que vous avez cinq ou dix taches structurees avec des dependances entre elles, suivre la progression dans le terminal devient difficile. bd list vous montre une liste plate. Il ne montre pas quelles taches sont bloquees, lesquelles sont pretes a demarrer, ou a quel point l'epic a progresse.

C'est le probleme que Beadbox resout. Il lit la meme base de donnees beads et affiche des arbres d'epics avec des indicateurs de progression, des relations de dependance et des assignations d'agents. Vous voyez quels sous-taches sont terminees, lesquelles sont bloquees par des prerequis et lesquelles sont pretes a etre prises par un agent. Le graphe de dependances que vous avez specifie avec --deps devient une carte visuelle de votre travail parallele.

Quand un agent termine une tache et met a jour le statut, Beadbox reflete le changement en temps reel. Pas de rafraichissement, pas de re-execution de bd list. L'arbre se met a jour, la barre de progression avance et les taches bloquees se debloquent a mesure que leurs dependances se resolvent.

Les memes donnees. Juste visibles.

Si vous construisez des workflows comme ceux-ci, mettez une etoile a Beadbox sur GitHub.

Sous-agents Claude Code vs. decomposition structuree des taches : quand utiliser quoi