Vous avez vu les captures d'ecran. Cinq, dix, quinze agents Claude Code tournant dans tmux, chacun travaillant sur une partie differente de la meme codebase. Ca a l'air productif. Ca a l'air excitant. Et si vous avez essaye de le reproduire, vous savez que ca parait beaucoup plus facile que ca ne l'est.
Faire tourner un agent Claude Code est simple. Vous lui donnez une tache, il ecrit du code, vous relisez. Deux sont gerables mais introduisent un nouveau probleme : ils pourraient se marcher dessus. Cinq necessitent un systeme. Dix sans systeme, c'est le chaos avec une facture mensuelle.
Ce guide traite de ce systeme. Pas la theorie des architectures multi-agents. Le workflow reel et pratique pour faire tourner plusieurs agents Claude Code sur une vraie codebase sans que tout s'effondre.
Pourquoi un seul agent ne suffit pas
Un seul agent Claude Code peut accomplir une quantite surprenante de travail. Mais c'est sequentiel. Pendant qu'il implemente un endpoint backend, votre frontend est au point mort. Pendant qu'il ecrit des tests, la documentation prend du retard. Pendant qu'il debogue un echec de build, trois nouvelles fonctionnalites attendent dans la file.
Le calcul change quand on realise que la majorite du travail logiciel est parallelisable. Un composant frontend et un endpoint API ne partagent pas de fichiers. Une suite de tests et une mise a jour de documentation touchent des repertoires differents. Une revue d'architecture et un correctif de bug operent sur des echelles de temps completement differentes.
Le goulot d'etranglement en developpement mono-agent n'est pas la vitesse de l'agent. C'est la profondeur du pipeline. Un agent signifie une seule chose en cours a la fois. Plusieurs agents signifient plusieurs choses en cours simultanement, et ca change ce qu'un seul developpeur peut livrer en une journee.
Strategies de repartition du travail
Avant d'ouvrir un deuxieme panneau tmux, vous devez decider comment diviser le travail. Trois patterns fonctionnent en pratique.
Repartition par composant
L'approche la plus simple. L'Agent A possede components/, l'Agent B possede server/, l'Agent C possede lib/. Chaque agent travaille dans son territoire et ne touche jamais aux fichiers en dehors.
Cela fonctionne bien quand votre codebase a des frontieres architecturales claires. Une app Next.js avec des composants frontend distincts, des actions backend et des librairies partagees se divise naturellement selon ces lignes.
La limitation : le travail transversal. Une fonctionnalite qui necessite des changements dans l'UI, l'API et la couche de donnees ne s'integre pas proprement dans le territoire d'un seul agent. On resout cela en decoupant la fonctionnalite en sous-taches par composant et en les sequencant.
Repartition par role
Au lieu de diviser par emplacement de code, divisez par fonction. Un agent ecrit du code. Un autre ecrit les tests. Un troisieme gere la documentation. Un quatrieme fait la revue de code.
Cela reflete le fonctionnement des equipes humaines et produit une qualite superieure parce que l'agent de tests ne sait pas (et s'en fiche) a quel point le code etait facile a ecrire. Il teste contre la spec, pas contre les hypotheses de l'auteur.
Le compromis est plus de surcharge de coordination. L'agent de tests a besoin que l'agent d'implementation finisse d'abord. L'agent de documentation a besoin des deux. Vous gerez un pipeline, pas seulement des workers paralleles.
Repartition par phase du cycle de vie
Une version plus sophistiquee de la repartition par roles. Un agent brainstorme et planifie. Un autre implemente. Un troisieme verifie. Le travail coule a travers les phases, et chaque agent est specialise pour sa phase.
C'est le pattern que nous utilisons chez Beadbox. Notre agent architecte concoit, nos agents d'ingenierie implementent, nos agents QA verifient independamment. La meme tache traverse plusieurs specialistes, et chacun ajoute une couche de qualite que les agents generalistes ratent. J'ai decrit le setup complet dans Je Livre du Logiciel avec 13 Agents IA.
La bonne strategie depend de votre projet. Les petits projets avec des frontieres de fichiers claires fonctionnent bien avec la repartition par composant. Les projets plus grands ou la qualite compte beneficient de la repartition par role ou cycle de vie. La plupart des equipes finissent avec un hybride.
Le pattern d'identite CLAUDE.md
C'est la ou la theorie rencontre l'implementation. Chaque agent Claude Code recoit son propre fichier CLAUDE.md, et ce fichier est la piece la plus importante du systeme multi-agent.
Un CLAUDE.md definit quatre choses :
- Ce que l'agent est. Son role, sa specialite et son domaine.
- Ce qu'il possede. Les fichiers, repertoires ou responsabilites qu'il controle.
- Ce qu'il ne doit pas toucher. Les frontieres explicites qui empechent les conflits.
- Comment il communique. Les protocoles pour rapporter le travail et se coordonner avec les autres agents.
Voici un exemple reel. Deux agents Claude Code avec des scopes complementaires :
# CLAUDE.md for Agent: frontend-eng
## Identity
Frontend engineer. You implement UI components, pages, and client-side
logic. You own everything under components/, app/, and hooks/.
## File Ownership
- components/** (you own these)
- app/** (you own these)
- hooks/** (you own these)
- lib/utils.ts (shared, read-only for you)
- server/** (DO NOT MODIFY — owned by backend-eng)
## Communication
When you need a backend change, create a task describing what API
you need. Do not implement it yourself.
When done with a task, comment: "DONE: <summary>. Commit: <hash>"
# CLAUDE.md for Agent: backend-eng
## Identity
Backend engineer. You implement server actions, API routes, and
data layer logic. You own everything under server/, actions/, and lib/.
## File Ownership
- server/** (you own these)
- actions/** (you own these)
- lib/** (you own these, except utils.ts is shared)
- components/** (DO NOT MODIFY — owned by frontend-eng)
- app/** (DO NOT MODIFY — owned by frontend-eng)
## Communication
When you change a data type in lib/types.ts, notify frontend-eng
by commenting on the relevant task.
When done with a task, comment: "DONE: <summary>. Commit: <hash>"
Remarquez les lignes explicites "DO NOT MODIFY". Sans elles, les agents derivent. Ils voient une opportunite d'"aider" en corrigeant une typo dans un fichier qui ne leur appartient pas, et soudain vous avez des conflits de merge. Ou pire, ils refactorisent silencieusement du code dont un autre agent dependait.
La section identite n'est pas de la decoration. Claude Code lit CLAUDE.md au debut de chaque session et l'utilise pour cadrer son comportement. Un agent a qui on dit qu'il est un "ingenieur frontend" resistera naturellement aux changements backend. Un agent a qui on dit qu'il possede des repertoires specifiques demandera avant de modifier des fichiers en dehors.
Eviter les conflits de merge
La propriete au niveau des fichiers, comme montre dans les exemples CLAUDE.md ci-dessus, est la premiere ligne de defense. Mais pas la seule.
Committez et pushez frequemment. Un agent qui travaille 45 minutes sans committer construit une bombe a retardement de conflits de merge. Instruisez les agents (dans leur CLAUDE.md) de committer apres avoir complete chaque unite logique de travail.
Pullez avant de commencer un nouveau travail. Chaque agent devrait executer git pull --rebase avant de commencer une nouvelle tache. C'est trivialement facile a appliquer en l'ajoutant au protocole de demarrage de l'agent dans CLAUDE.md.
Utilisez des feature flags pour le travail transversal. Quand deux agents doivent modifier le meme fichier, l'approche la plus sure est souvent de faire creer l'interface ou le flag par un agent, committer et pusher, puis faire puller et construire par-dessus par le deuxieme agent. Le sequentiel bat le parallele quand l'alternative est un cauchemar de merge.
Des branches separees pour le travail risque. Si un agent fait quelque chose d'experimental, donnez-lui sa propre branche. Particulierement utile pour les spikes d'architecture ou le travail de refactoring qui pourrait ne pas aboutir.
En pratique, la combinaison de regles de propriete de fichiers et de commits frequents elimine 90% des conflits de merge. Les 10% restants se produisent dans les fichiers partages comme types.ts ou package.json, et ils sont generalement triviaux a resoudre.
Communication entre agents
Les agents Claude Code ne peuvent pas se parler directement. Pas de memoire partagee, pas de bus de messages, pas de canal temps reel entre eux. C'est en fait une bonne chose. La communication directe entre agents cree du couplage, des race conditions et des cauchemars de debogage.
A la place, la communication passe par les artefacts. Trois patterns fonctionnent :
Le pattern le plus fiable. L'Agent A termine son travail et commente sur une tache partagee : "DONE: endpoint /api/users implemente. Retourne du JSON. Le schema est dans lib/types.ts." L'Agent B lit le commentaire et sait exactement ce qui est disponible.
Mises a jour de statut
Chaque tache a un statut : open, in_progress, done, blocked. Quand l'Agent A marque un prerequis comme done, l'Agent B (ou vous, ou un coordinateur) sait que le travail dependant peut commencer.
Changements de fichiers
La forme la plus simple. L'Agent A ecrit une interface TypeScript dans lib/types.ts et committe. L'Agent B pulle et voit les nouveaux types. Aucune communication explicite necessaire car le code lui-meme est le message.
Ce qui NE fonctionne PAS : essayer de construire un systeme de passage de messages en temps reel entre agents. Si vous avez besoin que l'Agent A attende la sortie de l'Agent B, modelisez cela comme une dependance entre taches, pas comme un appel synchrone.
La boucle de dispatch
Quelqu'un doit diriger l'orchestre. Dans un setup multi-agent Claude Code, il y a deux options : vous le faites manuellement, ou vous designez un agent coordinateur.
Dispatch manuel
Vous maintenez une liste de taches. Vous assignez des taches aux agents. Vous verifiez la progression. Vous gerez les blocages. Cela fonctionne jusqu'a environ cinq agents avant que la surcharge de coordination commence a grignoter les gains de productivite.
Un cycle typique de dispatch manuel ressemble a ceci :
- Matin : Revoir ce qui est en cours, ce qui est bloque, ce qui est pret
- Assigner : Envoyer a chaque agent sa prochaine tache avec le contexte
- Surveiller : Toutes les 10-15 minutes, verifier le output des agents pour des signes de blocage
- Debloquer : Quand un agent rencontre un probleme, intervenir ou reassigner
- Cloture : En fin de journee, revoir ce qui a ete livre et planifier demain
En tmux, cela ressemble a passer d'un panneau a l'autre, lire les sorties recentes et decider de quoi chaque agent a besoin. Des outils comme gp (consulter la sortie recente d'un agent sans l'interrompre) aident, mais vous restez le goulot d'etranglement.
Agent coordinateur
Dediez un agent Claude Code au dispatching du travail aux autres. Cet agent n'ecrit pas de code. Il lit le backlog de taches, assigne le travail aux agents disponibles, verifie la progression et gere la boucle de dispatch programmatiquement.
C'est le pattern que nous utilisons. Notre agent "super" execute une boucle de patrouille : toutes les quelques minutes, il consulte chaque agent actif, verifie les statuts des taches, identifie les blocages et dispatche du nouveau travail quand un agent est inactif. L'humain (moi) prend les decisions de priorite et resout les situations ambigues. Super gere la logistique.
Un agent coordinateur a besoin de son propre CLAUDE.md :
# CLAUDE.md for Agent: super
## Identity
Dispatch coordinator. You assign work to agents, monitor progress,
and ensure the pipeline keeps moving. You do NOT write code.
## Responsibilities
- Maintain awareness of all active tasks and their statuses
- Assign ready tasks to idle agents
- Monitor agent progress every 5-10 minutes
- Escalate blockers to the human when agents can't self-resolve
- Verify agents follow the protocol: plan before code, test before done
## Communication
- To assign work: message the agent with task ID and priority
- To check progress: peek at agent's recent output
- To escalate: message the human with context and options
Le pattern coordinateur passe beaucoup mieux a l'echelle que le dispatch manuel. A 10+ agents, la coordination manuelle est un emploi a temps plein. Un agent coordinateur gere la logistique de routine et n'escalade que les decisions qui necessitent un jugement humain.
Layout tmux pour le travail multi-agent
Le layout physique compte plus qu'on ne le pense. Voici une configuration tmux qui fonctionne pour faire tourner plusieurs agents Claude Code :
# Create a new tmux session
tmux new-session -s agents -n super
# Split into panes for each agent
tmux split-window -h -t agents:super
tmux split-window -v -t agents:super.1
# Or create named windows (easier to manage at scale)
tmux new-window -t agents -n eng1
tmux new-window -t agents -n eng2
tmux new-window -t agents -n qa1
tmux new-window -t agents -n frontend
tmux new-window -t agents -n backend
Les fenetres nommees battent les panneaux divises une fois que vous depassez quatre agents. Vous ne pouvez pas lire cinq panneaux sur un seul ecran, mais vous pouvez rapidement basculer entre des fenetres nommees. La convention de nommage compte aussi. eng1, eng2, qa1 sont immediatement lisibles. agent-1, agent-2, agent-3 ne vous disent rien.
Demarrez chaque agent dans son propre repertoire de travail avec son propre CLAUDE.md :
# In the eng1 window
cd ~/project
claude --claude-md ./agents/eng1/CLAUDE.md
# In the qa1 window
cd ~/project
claude --claude-md ./agents/qa1/CLAUDE.md
Un conseil pratique : gardez une fenetre "dashboard" qui est juste un shell. Utilisez-la pour executer git log --oneline -10, verifier le statut des taches, ou observer les agents sans interrompre leur travail. Cela devient votre centre de commande.
Quand les choses tournent mal
Les workflows multi-agents echouent de manieres previsibles. Connaitre les modes de defaillance vous evite de les apprendre a la dure.
Deux agents editent le meme fichier. Generalement parce que la propriete des fichiers dans CLAUDE.md n'etait pas assez specifique. lib/utils.ts est un classique aimant a conflits. Solution : soit assigner les fichiers utilitaires partages a un agent specifique, soit les rendre en lecture seule pour tous et router les changements via un seul proprietaire.
Un agent devient silencieux. Il a atteint une limite de taux, une boucle d'erreur, ou s'est enlise dans une chaine de raisonnement profonde. Verifiez la sortie. S'il reessaie la meme commande echouee, tuez la session et redemarrez avec des instructions plus claires. Des verifications de sante periodiques (toutes les 10-15 minutes) detectent cela avant que vous ne perdiez une heure.
Les fenetres de contexte se remplissent. Les agents de longue duree accumulent du contexte et commencent a moins bien performer. Le CLAUDE.md de chaque agent devrait inclure un protocole pour cela : "Si vous travaillez depuis plus de 90 minutes, sauvegardez votre etat et demandez une nouvelle session." En pratique, cela signifie que l'agent committe son travail, note ou il en est reste, et une nouvelle session Claude Code reprend depuis ce commit.
Le travail derive de la spec. L'agent construit quelque chose qui fonctionne techniquement mais ne correspond pas a ce qui etait demande. La solution est le pattern planifier-avant-de-coder : avant d'ecrire du code, l'agent commente son plan d'implementation. Vous relisez le plan en 60 secondes et attrapez les malentendus avant qu'ils ne deviennent des diffs de 500 lignes.
Le pipeline stagne. L'Agent B attend l'Agent A, mais l'Agent A attend une decision de votre part. Pendant ce temps, l'Agent C a termine son travail il y a 30 minutes et est inactif. C'est un echec de coordination, pas technique. L'agent coordinateur (ou vous) doit maintenir le pipeline en mouvement en surveillant les blocages et en reassignant les agents inactifs.
Tout ce qui precede fonctionne avec des post-it et de bonnes intentions. Mais autour de cinq agents, l'approche informelle commence a craquer. Vous oubliez sur quoi l'Agent C travaillait. Vous perdez le fil de quelles taches sont bloquees. Vous ne vous souvenez plus si l'endpoint API dont l'Agent B a besoin etait termine ou juste commence.
C'est le probleme que beads resout. Beads est un issue tracker open-source et local-first. Chaque tache est un "bead" avec un ID unique, un statut, une description, des criteres d'acceptation, des dependances et un fil de commentaires. Le tout accessible via un CLI appele bd, ce qui signifie que vos agents Claude Code peuvent lire et ecrire sans quitter le terminal.
Voici a quoi ressemble la boucle de dispatch avec beads :
# See what's ready for work
bd list --status open
# Assign a task to an agent
bd update bb-a1b2 --claim --actor eng1
# Agent reads its assignment
bd show bb-a1b2
# Agent comments its plan before coding
bd comments add bb-a1b2 --author eng1 "PLAN:
1. Add endpoint at /api/users
2. Define UserResponse type in lib/types.ts
3. Write integration test
Files: server/api/users.ts (new), lib/types.ts (modify)
Test: curl localhost:3000/api/users returns 200 with JSON array"
# Agent finishes and comments what it did
bd comments add bb-a1b2 --author eng1 "DONE: /api/users endpoint live.
Returns paginated JSON. Added UserResponse type.
Verification:
1. curl http://localhost:3000/api/users → 200, JSON array
2. curl http://localhost:3000/api/users?page=2 → 200, second page
3. pnpm test → all passing
Commit: 8f3c2a1"
# Agent marks the task done
bd update bb-a1b2 --status closed
Chaque agent suit ce protocole : revendiquer, planifier, implementer, commenter DONE, mettre a jour le statut. Le fil de commentaires de chaque bead devient un journal d'audit complet de ce qui s'est passe, pourquoi, et comment le verifier.
Les dependances empechent le travail conflictuel :
# Create a task that depends on another
bd create --title "Build user list component" \
--deps bb-a1b2 \
--description "Frontend component that calls /api/users. Blocked until API is live."
La tache dependante reste bloquee jusqu'a ce que bb-a1b2 soit terminee. Aucun agent ne la prendra prematurement. Personne ne perd de temps a construire un frontend pour une API qui n'existe pas encore.
La commande bd list vous donne un instantane de tout le pipeline :
bd list --status in_progress
# Shows what every agent is actively working on
bd blocked
# Montre les taches en attente de dependances non terminees
bd list --status open --priority p1
# Shows the highest-priority work that's ready to start
Cela remplace le modele mental que vous gardiez dans votre tete. L'etat de chaque tache, le travail en cours de chaque agent, chaque chaine de dependances, le tout interrogeable depuis la ligne de commande.
Monter en echelle sur la visibilite
Le CLI fonctionne. Mais a l'echelle, il y a une limite a ce que vous pouvez absorber en executant bd list dans un terminal. Quand vous avez huit agents travaillant sur trois epics avec dix-sept taches ouvertes et une douzaine de dependances, vous avez besoin de voir la forme du travail, pas juste une liste.
C'est le vide que nous avons construit Beadbox pour combler. Beadbox est un tableau de bord en temps reel qui se positionne au-dessus de beads et vous montre :
- Des arbres d'epics avec des barres de progression, pour voir comment chaque fonctionnalite progresse a travers toutes ses sous-taches
- Des graphes de dependances qui revelent le travail bloque avant qu'il ne paralyse le pipeline
- L'activite des agents montrant quel agent travaille sur quoi, avec leurs commentaires de plan et done visibles en contexte
- Des mises a jour en temps reel parce que le dashboard surveille votre base de donnees beads et se rafraichit quand les agents mettent a jour les statuts
Beadbox ne remplace pas le CLI. Vos agents continuent de lire et ecrire dans beads via bd. Beadbox vous donne la vue d'ensemble pour prendre les decisions de jugement : quel epic prend du retard, quel agent a besoin d'aide, ou le goulot d'etranglement se forme.
C'est gratuit pendant la beta. Si vous construisez des workflows comme celui-ci, mettez une etoile a Beadbox sur GitHub.
Pour commencer
Vous n'avez pas besoin de treize agents pour en beneficier. Voici le setup minimum viable :
- Deux agents Claude Code dans des fenetres tmux separees, chacun avec son propre CLAUDE.md definissant les frontieres de propriete de fichiers.
- Une liste de taches (meme un fichier texte suffit a cette echelle) pour que les deux agents sachent sur quoi ils travaillent et ce qui vient ensuite.
- Un protocole de commits : les deux agents committent frequemment et pullent avant de commencer un nouveau travail.
Une fois que c'est naturel, ajoutez un troisieme agent pour les tests ou la documentation. Puis envisagez un agent coordinateur. Puis adoptez beads pour le suivi structure des taches. Faites monter le systeme en echelle quand la douleur de coordination augmente, pas avant.
Le plus dur n'est pas l'outillage. C'est le changement de perspective : de "j'utilise un assistant IA" a "je dirige une equipe." Les fichiers CLAUDE.md, les protocoles de dispatch, les frontieres de propriete : ce sont des pratiques de management, pas des fichiers de configuration. Vous construisez une organisation, meme si les membres de l'equipe fonctionnent sur des appels API.
Commencez avec deux agents et des frontieres claires. Tout le reste en decoule.
