Avete visto gli screenshot. Cinque, dieci, quindici agenti Claude Code in esecuzione su tmux, ognuno che lavora su una parte diversa della stessa codebase. Sembra produttivo. Sembra entusiasmante. E se avete provato a replicarlo, sapete che sembra molto piu facile di quanto sia.
Far girare un agente Claude Code e semplice. Gli date un task, scrive codice, voi revisionate. Due sono gestibili ma introducono un nuovo problema: potrebbero pestarsi i commit a vicenda. Cinque richiedono un sistema. Dieci senza sistema e caos con fattura mensile.
Questa guida parla di quel sistema. Non la teoria delle architetture multi-agente. Il workflow reale e pratico per far girare piu agenti Claude Code su una codebase reale senza che tutto crolli.
Perche un agente non basta
Un singolo agente Claude Code puo gestire una quantita sorprendente di lavoro. Ma e sequenziale. Mentre implementa un endpoint backend, il frontend resta fermo. Mentre scrive test, la documentazione rimane indietro. Mentre fa debug di un errore di build, tre feature nuove aspettano in coda.
Il calcolo cambia quando ci si rende conto che la maggior parte del lavoro software e parallelizzabile. Un componente frontend e un endpoint API non condividono file. Una suite di test e un aggiornamento di documentazione toccano directory diverse. Una revisione architetturale e un bugfix operano su scale temporali completamente diverse.
Il collo di bottiglia nello sviluppo con un singolo agente non e la velocita dell'agente. E la profondita della pipeline. Un agente significa una sola cosa in corso alla volta. Piu agenti significano piu cose in corso simultaneamente, e questo cambia cio che un singolo sviluppatore puo consegnare in una giornata.
Strategie di suddivisione del lavoro
Prima di aprire un secondo pannello tmux, dovete decidere come dividere il lavoro. Tre pattern funzionano nella pratica.
Suddivisione per componente
L'approccio piu semplice. L'Agente A possiede components/, l'Agente B possiede server/, l'Agente C possiede lib/. Ogni agente lavora nel proprio territorio e non tocca mai file al di fuori.
Funziona bene quando la codebase ha confini architetturali chiari. Un'app Next.js con componenti frontend distinti, action backend e librerie condivise si divide naturalmente lungo queste linee.
Il limite: lavoro trasversale. Una feature che richiede modifiche all'UI, all'API e al layer dati non rientra ordinatamente nel territorio di un singolo agente. Si risolve scomponendo la feature in sotto-task con scope per componente e sequenziandoli.
Suddivisione per ruolo
Invece di dividere per posizione nel codice, dividete per funzione. Un agente scrive codice. Un altro scrive test. Un terzo gestisce la documentazione. Un quarto fa code review.
Questo rispecchia il funzionamento dei team umani e produce qualita superiore perche l'agente dei test non sa (e non gli importa) quanto fosse facile scrivere il codice. Testa contro la spec, non contro le assunzioni dell'autore.
Il compromesso e piu overhead di coordinamento. L'agente dei test ha bisogno che l'agente di implementazione finisca prima. L'agente della documentazione ha bisogno di entrambi. State gestendo una pipeline, non solo worker paralleli.
Suddivisione per fase del ciclo di vita
Una versione piu sofisticata della suddivisione per ruoli. Un agente fa brainstorm e pianifica. Un altro implementa. Un terzo verifica. Il lavoro scorre attraverso le fasi, e ogni agente e specializzato per la propria fase.
Questo e il pattern che usiamo in Beadbox. Il nostro agente architetto progetta, i nostri agenti di ingegneria implementano, i nostri agenti QA verificano indipendentemente. Lo stesso task attraversa piu specialisti, e ognuno aggiunge un livello di qualita che gli agenti generalisti non raggiungono. Ho scritto del setup completo in Consegno Software con 13 Agenti IA.
La strategia giusta dipende dal progetto. Progetti piccoli con confini di file chiari vanno bene con la suddivisione per componente. Progetti piu grandi dove la qualita conta beneficiano della suddivisione per ruolo o ciclo di vita. La maggior parte dei team finisce con un ibrido.
Il pattern di identita CLAUDE.md
Qui la teoria incontra l'implementazione. Ogni agente Claude Code riceve il proprio file CLAUDE.md, e questo file e il pezzo piu importante dell'intero sistema multi-agente.
Un CLAUDE.md definisce quattro cose:
- Cosa e l'agente. Il suo ruolo, specialita e dominio.
- Cosa possiede. I file, le directory o le responsabilita che controlla.
- Cosa non deve toccare. I confini espliciti che prevengono i conflitti.
- Come comunica. I protocolli per reportare il lavoro e coordinarsi con altri agenti.
Ecco un esempio reale. Due agenti Claude Code con scope complementari:
# 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>"
Notate le righe esplicite "DO NOT MODIFY". Senza queste, gli agenti derivano. Vedono un'opportunita di "aiutare" correggendo un typo in un file che non gli appartiene, e improvvisamente avete conflitti di merge. O peggio, refactorizzano silenziosamente codice da cui un altro agente dipendeva.
La sezione identita non e decorazione. Claude Code legge CLAUDE.md all'inizio di ogni sessione e la usa per delimitare il proprio comportamento. Un agente a cui si dice che e un "ingegnere frontend" resistera naturalmente dal fare modifiche backend. Un agente a cui si dice che possiede directory specifiche chiedera prima di modificare file al di fuori.
Evitare conflitti di merge
La proprieta a livello di file, come mostrato negli esempi CLAUDE.md sopra, e la prima linea di difesa. Ma non l'unica.
Committate e pushate frequentemente. Un agente che lavora 45 minuti senza committare sta costruendo una bomba a orologeria di conflitti di merge. Istruite gli agenti (nel loro CLAUDE.md) a committare dopo aver completato ogni unita logica di lavoro.
Pullate prima di iniziare nuovo lavoro. Ogni agente dovrebbe eseguire git pull --rebase prima di iniziare un nuovo task. E banalmente facile da applicare aggiungendolo al protocollo di avvio dell'agente nel CLAUDE.md.
Usate feature flag per il lavoro trasversale. Quando due agenti devono modificare lo stesso file, l'approccio piu sicuro e spesso far creare l'interfaccia o il flag a un agente, committare e pushare, poi far pullare e costruire sopra al secondo agente. Sequenziale batte parallelo quando l'alternativa e un incubo di merge.
Branch separati per lavoro rischioso. Se un agente sta facendo qualcosa di sperimentale, dategli il proprio branch. Particolarmente utile per spike architetturali o lavoro di refactoring che potrebbe non andare in porto.
In pratica, la combinazione di regole di proprieta dei file e commit frequenti elimina il 90% dei conflitti di merge. Il restante 10% accade in file condivisi come types.ts o package.json, e sono generalmente banali da risolvere.
Comunicazione tra agenti
Gli agenti Claude Code non possono parlarsi direttamente. Nessuna memoria condivisa, nessun bus di messaggi, nessun canale in tempo reale tra loro. Questa e in realta una cosa buona. La comunicazione diretta tra agenti crea accoppiamento, race condition e incubi di debug.
Invece, la comunicazione avviene attraverso artefatti. Tre pattern funzionano:
Il pattern piu affidabile. L'Agente A finisce il lavoro e commenta su un task condiviso: "DONE: endpoint /api/users implementato. Ritorna JSON. Lo schema e in lib/types.ts." L'Agente B legge il commento e sa esattamente cosa e disponibile.
Aggiornamenti di stato
Ogni task ha uno stato: open, in_progress, done, blocked. Quando l'Agente A segna un prerequisito come done, l'Agente B (o voi, o un coordinatore) sa che il lavoro dipendente puo iniziare.
Modifiche ai file
La forma piu semplice. L'Agente A scrive un'interfaccia TypeScript in lib/types.ts e committa. L'Agente B pulla e vede i nuovi tipi. Nessuna comunicazione esplicita necessaria perche il codice stesso e il messaggio.
Cosa NON funziona: provare a costruire un sistema di scambio messaggi in tempo reale tra agenti. Se avete bisogno che l'Agente A attenda l'output dell'Agente B, modellate questo come una dipendenza tra task, non come una chiamata sincrona.
Il loop di dispatch
Qualcuno deve dirigere lo spettacolo. In un setup multi-agente Claude Code, ci sono due opzioni: lo fate manualmente, o designate un agente coordinatore.
Dispatch manuale
Mantenete una lista di task. Assegnate task agli agenti. Verificate il progresso. Gestite i blocchi. Funziona fino a circa cinque agenti prima che l'overhead di coordinamento cominci a mangiarsi i guadagni di produttivita.
Un ciclo tipico di dispatch manuale appare cosi:
- Mattina: Rivedere cosa e in corso, bloccato, pronto per il lavoro
- Assegnare: Inviare a ogni agente il prossimo task con contesto
- Monitorare: Ogni 10-15 minuti, controllare l'output degli agenti per segni di blocco
- Sbloccare: Quando un agente incontra un problema, intervenire o riassegnare
- Chiusura: A fine giornata, rivedere cosa e stato consegnato e pianificare domani
In tmux, questo assomiglia a scorrere i pannelli, leggere l'output recente e decidere cosa serve a ogni agente. Tool come gp (sbirciare l'output recente di un agente senza interromperlo) aiutano, ma restate il collo di bottiglia.
Agente coordinatore
Dedicate un agente Claude Code al dispatching del lavoro agli altri. Questo agente non scrive codice. Legge il backlog dei task, assegna lavoro agli agenti disponibili, verifica il progresso e gestisce il loop di dispatch programmaticamente.
Questo e il pattern che usiamo. Il nostro agente "super" esegue un loop di pattuglia: ogni pochi minuti, controlla ogni agente attivo, verifica gli stati dei task, identifica i blocchi e dispatcha nuovo lavoro quando un agente diventa inattivo. L'umano (io) prende le decisioni di priorita e risolve le situazioni ambigue. Super gestisce la logistica.
Un agente coordinatore ha bisogno del proprio 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
Il pattern coordinatore scala molto meglio del dispatch manuale. Con 10+ agenti, il coordinamento manuale e un lavoro a tempo pieno. Un agente coordinatore gestisce la logistica di routine e scala solo le decisioni che richiedono giudizio umano.
Layout tmux per lavoro multi-agente
Il layout fisico conta piu di quanto si pensi. Ecco una configurazione tmux che funziona per far girare piu agenti 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
Le finestre con nome battono i pannelli divisi una volta superati quattro agenti. Non potete leggere cinque pannelli su un unico schermo, ma potete rapidamente passare tra finestre con nome. Anche la convenzione dei nomi conta. eng1, eng2, qa1 sono immediatamente leggibili. agent-1, agent-2, agent-3 non vi dicono nulla.
Avviate ogni agente nella propria directory di lavoro con il proprio 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 consiglio pratico: tenete una finestra "dashboard" che e solo una shell. Usatela per eseguire git log --oneline -10, controllare lo stato dei task, o osservare gli agenti senza interrompere il loro lavoro. Diventa il vostro centro di comando.
Quando le cose vanno male
I workflow multi-agente falliscono in modi prevedibili. Conoscere le modalita di fallimento vi risparmia di impararle nel modo piu duro.
Due agenti editano lo stesso file. Di solito perche la proprieta dei file nel CLAUDE.md non era abbastanza specifica. lib/utils.ts e un classico magnete di conflitti. Soluzione: o assegnate i file utility condivisi a un agente specifico, o rendeteli in sola lettura per tutti e incanalate le modifiche attraverso un unico proprietario.
Un agente diventa silenzioso. Ha raggiunto un rate limit, un loop di errori, o si e bloccato in una catena profonda di ragionamento. Controllate l'output. Se sta ritentando lo stesso comando fallito, terminate la sessione e riavviate con istruzioni piu chiare. Controlli di salute periodici (ogni 10-15 minuti) intercettano questo prima che perdiate un'ora.
Le finestre di contesto si riempiono. Agenti di lunga durata accumulano contesto e iniziano a performare peggio. Il CLAUDE.md di ogni agente dovrebbe includere un protocollo per questo: "Se stai lavorando da piu di 90 minuti, salva il tuo stato e richiedi una nuova sessione." In pratica, questo significa che l'agente committa il lavoro, annota dove e rimasto, e una nuova sessione Claude Code riprende da quel commit.
Il lavoro devia dalla spec. L'agente costruisce qualcosa che tecnicamente funziona ma non corrisponde a cio che era richiesto. La soluzione e il pattern pianificare-prima-di-codare: prima di scrivere codice, l'agente commenta il proprio piano di implementazione. Voi revisionate il piano in 60 secondi e intercettate i malintesi prima che diventino diff di 500 righe.
La pipeline si blocca. L'Agente B aspetta l'Agente A, ma l'Agente A aspetta una decisione vostra. Nel frattempo, l'Agente C ha finito il lavoro 30 minuti fa ed e inattivo. Questo e un fallimento di coordinamento, non tecnico. L'agente coordinatore (o voi) deve mantenere la pipeline in movimento monitorando i blocchi e riassegnando gli agenti inattivi.
Come abbiamo risolto questo con Beads
Tutto quanto sopra funziona con post-it e buone intenzioni. Ma intorno ai cinque agenti, l'approccio informale inizia a scricchiolare. Dimenticate su cosa stava lavorando l'Agente C. Perdete traccia di quali task sono bloccati. Non ricordate se l'endpoint API di cui l'Agente B ha bisogno era finito o appena iniziato.
Questo e il problema che beads risolve. Beads e un issue tracker open-source e local-first. Ogni task e un "bead" con un ID univoco, uno stato, una descrizione, criteri di accettazione, dipendenze e un thread di commenti. Tutto accessibile tramite un CLI chiamato bd, il che significa che i vostri agenti Claude Code possono leggere e scrivere senza lasciare il terminale.
Ecco come appare il loop di dispatch con 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
Ogni agente segue questo protocollo: rivendicare, pianificare, implementare, commentare DONE, aggiornare stato. Il thread di commenti di ogni bead diventa un registro di audit completo di cosa e successo, perche e come verificarlo.
Le dipendenze prevengono il lavoro conflittuale:
# 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."
Il task dipendente rimane bloccato finche bb-a1b2 non e completato. Nessun agente lo prendera prematuramente. Nessuno spreca tempo costruendo un frontend per un'API che non esiste ancora.
Il comando bd list vi da uno snapshot dell'intera pipeline:
bd list --status in_progress
# Shows what every agent is actively working on
bd blocked
# Mostra i task in attesa di dipendenze non completate
bd list --status open --priority p1
# Shows the highest-priority work that's ready to start
Questo sostituisce il modello mentale che tenevate in testa. Lo stato di ogni task, il lavoro attuale di ogni agente, ogni catena di dipendenze, tutto interrogabile dalla linea di comando.
Scalare la visibilita
Il CLI funziona. Ma su scala, c'e un limite a quanto potete assorbire eseguendo bd list in un terminale. Quando avete otto agenti che lavorano su tre epic con diciassette task aperti e una dozzina di dipendenze, dovete vedere la forma del lavoro, non solo una lista.
Questo e il vuoto che abbiamo costruito Beadbox per colmare. Beadbox e una dashboard in tempo reale che si posiziona sopra beads e vi mostra:
- Alberi di epic con barre di progresso, per vedere come ogni feature avanza attraverso tutti i sotto-task
- Grafi di dipendenze che rivelano il lavoro bloccato prima che fermi la pipeline
- Attivita degli agenti che mostra quale agente sta lavorando su cosa, con i commenti di piano e done visibili nel contesto
- Aggiornamenti in tempo reale perche la dashboard monitora il vostro database beads e si aggiorna quando gli agenti modificano gli stati dei task
Beadbox non sostituisce il CLI. I vostri agenti continuano a leggere e scrivere su beads tramite bd. Beadbox vi da il quadro d'insieme per prendere le decisioni di giudizio: quale epic e in ritardo, quale agente ha bisogno di aiuto, dove si sta formando il collo di bottiglia.
E gratuito durante la beta. Se state costruendo workflow come questo, mettete una stella a Beadbox su GitHub.
Per iniziare
Non servono tredici agenti per beneficiarne. Ecco il setup minimo funzionante:
- Due agenti Claude Code in finestre tmux separate, ognuno con il proprio CLAUDE.md che definisce i confini di proprieta dei file.
- Una lista di task (anche un file di testo funziona a questa scala) cosi entrambi gli agenti sanno su cosa stanno lavorando e cosa viene dopo.
- Un protocollo di commit: entrambi gli agenti committano frequentemente e pullano prima di iniziare nuovo lavoro.
Una volta che diventa naturale, aggiungete un terzo agente per test o documentazione. Poi considerate un agente coordinatore. Poi adottate beads per il tracciamento strutturato dei task. Scalate il sistema quando il dolore di coordinamento aumenta, non prima.
La parte difficile non e il tooling. E il cambio di prospettiva: da "sto usando un assistente IA" a "sto gestendo un team." I file CLAUDE.md, i protocolli di dispatch, i confini di proprieta: sono pratiche di management, non file di configurazione. State costruendo un'organizzazione, anche se i membri del team girano su chiamate API.
Iniziate con due agenti e confini chiari. Tutto il resto segue da li.
