quando mille mani valgono più di una
Orchestra. Ecco la parola che mi viene in mente guardando più istanze di Claude Code lavorare insieme. Non è la forza bruta di un singolo super-agente – è coordinazione. Tipo quando in azienda finalmente smetti di fare tutto da solo e deleghi, solo che qui i tuoi collaboratori sono AI che non si lamentano mai delle deadline.
I team di agenti rappresentano un salto rispetto ai subagent tradizionali. Differenza chiave? I subagent parlano solo col capo e basta. I team invece – e qui diventa interessante – comunicano tra loro. Si passano informazioni, si contestano le scoperte, lavorano su task condivisi. Praticamente un vero team di sviluppo, con la differenza che nessuno perde tempo davanti alla macchinetta del caffè.
Ma attenzione: più agenti = più token consumati. Non è gratis coordinare cinque AI che lavorano in parallelo. Bisogna capire quando vale la pena.
casi d’uso dove il gioco vale la candela
La ricerca parallela è il territorio dove questi team brillano. Immaginate di dover investigare un bug complesso con tre teorie possibili. Un singolo agente? Sceglie una strada e la segue fino in fondo. Un team di tre? Ogni membro testa una teoria diversa, poi si confrontano e convergono sulla soluzione reale.
Ho visto questo approccio funzionare bene su:
– **Code review strutturate**: un membro controlla la sicurezza, uno le performance, uno la copertura dei test. Tre lenti diverse sullo stesso PR
– **Nuove feature modulari**: ogni agente possiede un pezzo distinto del codice senza pestare i piedi agli altri
– **Debug con ipotesi concorrenti**: teoria A, teoria B, teoria C testate simultaneamente invece che in sequenza
– **Modifiche cross-layer**: frontend, backend, test – ognuno con il suo proprietario
Dove NON usarli? Task sequenziali, modifiche sullo stesso file, lavoro con troppe dipendenze incrociate. Lì il coordinamento ti mangia vivo e un singolo agente fa meglio.
subagent vs team: scegliere l’arma giusta
I subagent sono cecchini: task focalizzato, risultato pulito, riportano al main agent e basta. Zero comunicazione laterale.
I team sono plotoni: condividono task list, si auto-coordinano, discutono tra loro. Più autonomia, più overhead.
Costi token? I subagent costano meno perché riassumono i risultati nel contesto principale. I team moltiplicano il costo per ogni membro attivo.
Usa subagent per lavori veloci dove conta solo il risultato. Usa team quando serve discussione, sfida reciproca, coordinamento autonomo.
setup e configurazione iniziale
I team sono sperimentali e disabilitati di default. Per attivarli:
“`json
{
“env”: {
“CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS”: “1”
}
}
“`
Dopo l’abilitazione, basta chiedere a Claude in linguaggio naturale. Esempio che funziona bene:
“Sto progettando un tool CLI per analisi codebase. Crea un team con tre membri: uno su UX, uno su architettura tecnica, uno su implementazione.”
Claude genera il team, spawna i membri, coordina il lavoro. Il terminale del lead mostra tutti i teammate attivi. Shift+Down per navigare tra loro.
modalità di visualizzazione
Due opzioni:
– **In-process**: tutto nel terminale principale, navighi con Shift+Down. Funziona ovunque, zero setup aggiuntivo
– **Split panes**: ogni teammate in un pannello separato. Richiede tmux o iTerm2
La modalità auto usa split panes se sei già in tmux, altrimenti in-process. Per forzare una modalità:
“`json
{
“teammateMode”: “in-process”
}
“`
O via flag per singola sessione:
“`
claude –teammate-mode in-process
“`
Split panes è comoda per vedere tutto insieme, ma richiede configurazione. In-process funziona sempre.
gestione operativa del team
Il lead coordina tutto. Numero di teammate? Claude decide in base al task, oppure lo specifichi tu:
“Crea un team con 4 membri per refactoring backend. Usa Sonnet per ognuno.”
approvazione dei piani
Per task complessi o rischiosi puoi richiedere approvazione preventiva. Il teammate lavora in modalità read-only fino a quando il lead approva il suo piano:
“Spawna un teammate architect per refactoring. Richiedi approvazione del piano prima di qualsiasi modifica.”
Quando il teammate finisce la pianificazione, manda richiesta di approvazione al lead. Il lead valuta autonomamente – puoi influenzarlo dando criteri nel prompt tipo “approva solo piani con copertura test” o “rifiuta modifiche schema database”.
task assignment e claiming
La task list condivisa coordina il lavoro. Stati possibili: pending, in progress, completed. I task possono avere dipendenze – un task pending con dipendenze irrisolte non può essere claimed finché quelle non sono completate.
Due modalità:
– **Assegnazione dal lead**: dici esplicitamente chi fa cosa
– **Self-claim**: finito un task, il teammate prende il prossimo disponibile da solo
Il claiming usa file locking per evitare race condition quando più teammate provano a prendere lo stesso task.
comunicazione diretta coi teammate
Ogni teammate è una sessione Claude Code completa e indipendente. Puoi messaggiare qualsiasi membro direttamente.
In modalità in-process: Shift+Down per ciclare, poi scrivi per mandare messaggio. Enter per vedere la sessione, Escape per interrompere il turno corrente. Ctrl+T per toggle della task list.
In split panes: click sul pannello per interagire direttamente.
shutdown e cleanup
Per terminare un teammate:
“Chiedi al teammate researcher di spegnersi.”
Il lead manda richiesta shutdown. Il teammate può approvare (uscita graziosa) o rifiutare con spiegazione.
Pulizia finale del team:
“Pulisci il team.”
Rimuove risorse condivise. Il lead verifica che non ci siano teammate attivi prima di procedere – se trova processi in corso, fallisce. Quindi shutdowna prima i membri, poi cleanup.
Importante: usa SEMPRE il lead per cleanup. I teammate non dovrebbero farlo perché il loro contesto potrebbe non risolversi correttamente.
architettura e meccaniche interne
Componenti principali:
– **Team lead**: la sessione Claude Code principale che crea, coordina, assegna lavoro
– **Teammates**: istanze separate che lavorano su task assegnati
– **Task list**: lista condivisa di work item che i teammate claimano e completano
Team e task sono salvati localmente:
– Config team: `~/.claude/teams/{team-name}/config.json`
– Task list: `~/.claude/tasks/{team-name}/`
Il config contiene array members con nome, agent ID e tipo di ogni teammate.
permessi e contesto
I teammate partono con i permessi del lead. Se il lead gira con `–dangerously-skip-permissions`, anche tutti i teammate. Puoi cambiare modalità individuali dopo lo spawn, ma non settare permessi per-teammate allo spawn.
Ogni teammate ha il proprio context window. Allo spawn carica lo stesso project context di una sessione normale: CLAUDE.md, MCP server, skill. Riceve anche lo spawn prompt dal lead. La conversation history del lead NON viene trasferita.
Condivisione info:
– **Message delivery automatica**: quando i teammate mandano messaggi, vengono consegnati automaticamente ai destinatari
– **Idle notification**: quando un teammate finisce e si ferma, notifica automaticamente il lead
– **Task list condivisa**: tutti vedono status task e possono claim work disponibile
Messaging teammate:
– **message**: manda a un teammate specifico
– **broadcast**: manda a tutti simultaneamente. Usa con parsimonia – costi scalano col team size
costi token
Usano significativamente più token di una singola sessione. Ogni teammate ha context window proprio, usage scala col numero di membri attivi. Per ricerca, review, nuove feature di solito vale la pena. Per task routinari, singola sessione è più cost-effective.
best practice operative
**Dai contesto sufficiente ai teammate**
Caricano project context automaticamente ma non ereditano conversation history del lead. Includi dettagli task-specific nello spawn prompt:
“Spawna teammate security reviewer. Focus su src/auth/ per vulnerabilità. Controlla gestione token, validazione input. L’app usa JWT con httpOnly cookie. Reporta issue con severity.”
**Scegli team size appropriato**
Nessun hard limit ma vincoli pratici:
– Costi token scalano linearmente
– Coordination overhead aumenta
– Diminishing returns oltre un certo punto
Part da 3-5 teammate per la maggior parte dei workflow. Scala solo quando il lavoro beneficia genuinamente dal parallelismo. Tre teammate focalizzati spesso battono cinque sparsi.
5-6 task per teammate li tiene produttivi senza eccessivo context switching. Se hai 15 task indipendenti, 3 teammate è un buon starting point.
**Size task appropriato**
– Troppo piccoli: coordination overhead supera beneficio
– Troppo grandi: teammate lavorano troppo a lungo senza check-in, rischio effort sprecato
– Giusti: unità self-contained che producono deliverable chiaro (funzione, test file, review)
Il lead spezza lavoro in task automaticamente. Se non crea abbastanza task, chiedigli di dividere in pezzi più piccoli.
**Aspetta che i teammate finiscano**
A volte il lead inizia a implementare task da solo invece di aspettare. Se succede:
“Aspetta che i tuoi teammate completino.”
**Inizia con research e review**
Nuovo ai team? Parti con task che hanno confini chiari e non richiedono scrittura codice: review PR, ricerca libreria, investigazione bug. Mostrano valore dell’esplorazione parallela senza complessità coordinamento dell’implementazione parallela.
**Evita conflitti file**
Due teammate che editano stesso file = sovrascritture. Spezza lavoro così ogni teammate possiede set file diverso.
**Monitora e guida**
Check-in su progresso, reindirizza approcci che non funzionano, sintetizza findings man mano. Lasciare team unattended troppo a lungo aumenta rischio effort sprecato.
troubleshooting comune
**Teammate non appaiono**
In modalità in-process potrebbero già girare ma non visibili. Premi Shift+Down per ciclare.
Controlla che il task fosse abbastanza complesso da giustificare un team.
Se hai richiesto split panes, verifica tmux installato:
“`
which tmux
“`
Per iTerm2, verifica it2 CLI installato e Python API abilitata in preferenze.
**Troppi permission prompt**
Richieste permessi teammate bubbano al lead. Pre-approva operazioni comuni in permission settings prima di spawnare teammate.
**Teammate si fermano su errori**
Possono fermarsi dopo errori invece di recuperare. Controlla output con Shift+Down o click pannello, poi:
– Dai istruzioni aggiuntive dirette
– Spawna teammate sostitutivo per continuare lavoro
**Lead shutdowna prima che lavoro sia finito**
Può decidere che team sia finito prima che tutti task siano completi. Digli di continuare. Puoi anche dirgli di aspettare che teammate finiscano prima di procedere.
**Sessioni tmux orfane**
Se sessione tmux persiste dopo fine team, potrebbe non essere stata pulita completamente:
“`
tmux ls
tmux kill-session -t
“`
limitazioni note
Sperimentali. Awareness:
– **No session resumption con in-process teammate**: /resume e /rewind non ripristinano teammate in-process. Dopo resume, lead può tentare messaggi a teammate che non esistono più. Spawna nuovi teammate se succede
– **Task status può laggare**: teammate a volte falliscono nel marcare task completed, bloccando dipendenze. Se task sembra stuck, controlla se lavoro è fatto e aggiorna status manualmente
– **Shutdown può essere lento**: teammate finiscono request o tool call corrente prima di spegnersi
– **Un team per sessione**: lead può gestire solo un team alla volta. Cleanup quello corrente prima di iniziarne nuovo
– **No team nidificati**: teammate non possono spawnare propri team. Solo lead gestisce team
– **Lead fisso**: la sessione che crea team è lead per tutta la vita. Non puoi promuovere teammate a lead
– **Permessi settati allo spawn**: tutti teammate partono con permission mode del lead. Puoi cambiare modalità individuali dopo spawn ma non settare per-teammate allo spawn
– **Split panes richiede tmux o iTerm2**: modalità in-process funziona in qualsiasi terminale. Split panes non supportata in VS Code integrated terminal, Windows Terminal, Ghostty
CLAUDE.md funziona normalmente – teammate leggono file dalla working directory. Usa per guidance project-specific a tutti teammate.
esempio caso d’uso: code review parallelo
Un singolo reviewer tende a gravitare verso un tipo di issue alla volta. Dividere criteri review in domini indipendenti significa che security, performance, test coverage ricevono tutti attenzione approfondita simultaneamente:
“Crea team per review PR #142. Un membro focalizzato su implicazioni security, uno su impatto performance, uno su validazione test coverage. Ognuno fa review e reporta findings.”
Ogni reviewer lavora dallo stesso PR ma applica filtro diverso. Lead sintetizza findings da tutti e tre dopo che finiscono.
esempio caso d’uso: investigazione con ipotesi concorrenti
Quando root cause non è chiara, singolo agente tende a trovare una spiegazione plausibile e fermarsi. Questa struttura combatte il bias facendo teammate esplicitamente adversarial:
“User reportano app che esce dopo un minuto. Spawna 5 teammate per investigare ipotesi diverse. Ogni membro deve attivamente provare a confutare teorie degli altri in debate. Aggiorna findings doc con consensus emergente.”
La struttura debate è meccanismo chiave. Investigazione sequenziale soffre di anchoring – una volta esplorata una teoria, investigazione successiva è biased verso quella.
Con investigatori multipli indipendenti che provano attivamente a confutarsi, la teoria che sopravvive è molto più probabile essere la root cause reale.
