I team di agenti richiedono Claude Code v2.1.32 o successivo. Controllate la vostra versione con
claude --version.- Quando utilizzare i team di agenti, inclusi i migliori casi d’uso e come si confrontano con i subagents
- Avviare un team
- Controllare i compagni di team, incluse le modalità di visualizzazione, l’assegnazione delle attività e la delega
- Best practice per il lavoro parallelo
Quando utilizzare i team di agenti
I team di agenti sono più efficaci per attività in cui l’esplorazione parallela aggiunge valore reale. Consultate gli esempi di casi d’uso per scenari completi. I casi d’uso più forti sono:- Ricerca e revisione: più compagni di team possono investigare diversi aspetti di un problema simultaneamente, quindi condividere e mettere in discussione i risultati reciproci
- Nuovi moduli o funzionalità: i compagni di team possono possedere ciascuno un pezzo separato senza interferire l’uno con l’altro
- Debug con ipotesi concorrenti: i compagni di team testano diverse teorie in parallelo e convergono sulla risposta più velocemente
- Coordinamento tra livelli: modifiche che si estendono su frontend, backend e test, ciascuno posseduto da un diverso compagno di team
Confronto con i subagents
Sia i team di agenti che i subagents vi permettono di parallelizzare il lavoro, ma operano diversamente. Scegliete in base al fatto che i vostri worker debbano comunicare tra loro:
| Subagents | Team di agenti | |
|---|---|---|
| Context | Context window proprio; i risultati tornano al chiamante | Context window proprio; completamente indipendente |
| Comunicazione | Riportano i risultati solo al main agent | I compagni di team si messaggiano direttamente |
| Coordinamento | Il main agent gestisce tutto il lavoro | Elenco di attività condiviso con auto-coordinamento |
| Migliore per | Attività focalizzate dove conta solo il risultato | Lavoro complesso che richiede discussione e collaborazione |
| Costo in token | Inferiore: i risultati sono sintetizzati nel contesto principale | Superiore: ogni compagno di team è un’istanza Claude separata |
Abilitare i team di agenti
I team di agenti sono disabilitati per impostazione predefinita. Abilitateli impostando la variabile di ambienteCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS a 1, sia nell’ambiente della shell che tramite settings.json:
settings.json
Avviare il vostro primo team di agenti
Dopo aver abilitato i team di agenti, dite a Claude di creare un team di agenti e descrivete il compito e la struttura del team che desiderate in linguaggio naturale. Claude crea il team, genera i compagni di team e coordina il lavoro in base al vostro prompt. Questo esempio funziona bene perché i tre ruoli sono indipendenti e possono esplorare il problema senza aspettarsi l’uno l’altro:Controllare il vostro team di agenti
Dite al lead cosa desiderate in linguaggio naturale. Gestisce il coordinamento del team, l’assegnazione delle attività e la delega in base alle vostre istruzioni.Scegliere una modalità di visualizzazione
I team di agenti supportano due modalità di visualizzazione:- In-process: tutti i compagni di team vengono eseguiti all’interno del vostro terminale principale. Utilizzate Shift+Down per scorrere i compagni di team e digitate per messaggiarli direttamente. Funziona in qualsiasi terminale, nessuna configurazione extra richiesta.
- Split panes: ogni compagno di team ottiene il proprio riquadro. Potete vedere l’output di tutti contemporaneamente e fare clic su un riquadro per interagire direttamente. Richiede tmux o iTerm2.
tmux ha limitazioni note su certi sistemi operativi e tradizionalmente funziona meglio su macOS. Utilizzare tmux -CC in iTerm2 è il punto di ingresso suggerito in tmux."auto", che utilizza split panes se state già eseguendo all’interno di una sessione tmux, e in-process altrimenti. L’impostazione "tmux" abilita la modalità split-pane e rileva automaticamente se utilizzare tmux o iTerm2 in base al vostro terminale. Per sovrascrivere, impostate teammateMode nel vostro settings.json:
it2. Per installare manualmente:
- tmux: installate tramite il gestore di pacchetti del vostro sistema. Consultate il wiki di tmux per istruzioni specifiche della piattaforma.
- iTerm2: installate la CLI
it2, quindi abilitate l’API Python in iTerm2 → Settings → General → Magic → Enable Python API.
Specificare compagni di team e modelli
Claude decide il numero di compagni di team da generare in base al vostro compito, oppure potete specificare esattamente quello che desiderate:Richiedere l’approvazione del piano per i compagni di team
Per compiti complessi o rischiosi, potete richiedere ai compagni di team di pianificare prima di implementare. Il compagno di team lavora in modalità piano di sola lettura fino a quando il lead approva il loro approccio:Parlare direttamente con i compagni di team
Ogni compagno di team è una sessione Claude Code completa e indipendente. Potete messaggiare qualsiasi compagno di team direttamente per fornire istruzioni aggiuntive, fare domande di follow-up o reindirizzare il loro approccio.- Modalità in-process: utilizzate Shift+Down per scorrere i compagni di team, quindi digitate per inviare loro un messaggio. Premete Invio per visualizzare la sessione di un compagno di team, quindi Escape per interrompere il loro turno attuale. Premete Ctrl+T per attivare/disattivare l’elenco delle attività.
- Modalità split-pane: fate clic nel riquadro di un compagno di team per interagire direttamente con la sua sessione. Ogni compagno di team ha una visualizzazione completa del proprio terminale.
Assegnare e rivendicare attività
L’elenco di attività condiviso coordina il lavoro nel team. Il lead crea attività e i compagni di team le elaborano. Le attività hanno tre stati: in sospeso, in corso e completate. Le attività possono anche dipendere da altre attività: un’attività in sospeso con dipendenze non risolte non può essere rivendicata fino a quando quelle dipendenze non sono completate. Il lead può assegnare attività esplicitamente, oppure i compagni di team possono auto-rivendicare:- Il lead assegna: dite al lead quale attività assegnare a quale compagno di team
- Auto-rivendicazione: dopo aver completato un’attività, un compagno di team raccoglie la prossima attività non assegnata e non bloccata da solo
Spegnere i compagni di team
Per terminare gracefully la sessione di un compagno di team:Pulire il team
Quando avete finito, chiedete al lead di pulire:Applicare quality gate con hooks
Utilizzate hooks per applicare regole quando i compagni di team finiscono il lavoro o le attività si completano:TeammateIdle: viene eseguito quando un compagno di team sta per andare inattivo. Uscite con codice 2 per inviare feedback e mantenere il compagno di team al lavoro.TaskCompleted: viene eseguito quando un’attività sta per essere contrassegnata come completata. Uscite con codice 2 per prevenire il completamento e inviare feedback.
Come funzionano i team di agenti
Questa sezione copre l’architettura e la meccanica dietro i team di agenti. Se desiderate iniziare a utilizzarli, consultate Controllare il vostro team di agenti sopra.Come Claude avvia i team di agenti
Ci sono due modi in cui i team di agenti vengono avviati:- Voi richiedete un team: date a Claude un compito che beneficia dal lavoro parallelo e chiedete esplicitamente un team di agenti. Claude ne crea uno in base alle vostre istruzioni.
- Claude propone un team: se Claude determina che il vostro compito beneficerebbe dal lavoro parallelo, potrebbe suggerire di creare un team. Voi confermate prima che proceda.
Architettura
Un team di agenti consiste di:| Componente | Ruolo |
|---|---|
| Team lead | La sessione Claude Code principale che crea il team, genera i compagni di team e coordina il lavoro |
| Compagni di team | Istanze Claude Code separate che lavorano ciascuna su attività assegnate |
| Elenco di attività | Elenco condiviso di elementi di lavoro che i compagni di team rivendicano e completano |
| Mailbox | Sistema di messaggistica per la comunicazione tra agenti |
- Configurazione del team:
~/.claude/teams/{team-name}/config.json - Elenco di attività:
~/.claude/tasks/{team-name}/
members con il nome di ogni compagno di team, l’ID dell’agente e il tipo di agente. I compagni di team possono leggere questo file per scoprire altri membri del team.
Permessi
I compagni di team iniziano con le impostazioni di permesso del lead. Se il lead viene eseguito con--dangerously-skip-permissions, lo fanno anche tutti i compagni di team. Dopo la generazione, potete cambiare le modalità dei singoli compagni di team, ma non potete impostare modalità per compagno di team al momento della generazione.
Context e comunicazione
Ogni compagno di team ha il proprio context window. Quando generato, un compagno di team carica lo stesso contesto di progetto di una sessione regolare: CLAUDE.md, MCP servers e skills. Riceve anche il prompt di generazione dal lead. La cronologia della conversazione del lead non viene trasferita. Come i compagni di team condividono le informazioni:- Consegna automatica dei messaggi: quando i compagni di team inviano messaggi, vengono consegnati automaticamente ai destinatari. Il lead non ha bisogno di eseguire il polling per gli aggiornamenti.
- Notifiche di inattività: quando un compagno di team finisce e si ferma, notifica automaticamente il lead.
- Elenco di attività condiviso: tutti gli agenti possono vedere lo stato delle attività e rivendicare il lavoro disponibile.
- message: invia un messaggio a un compagno di team specifico
- broadcast: invia a tutti i compagni di team simultaneamente. Utilizzate con parsimonia, poiché i costi si scalano con la dimensione del team.
Utilizzo dei token
I team di agenti utilizzano significativamente più token di una singola sessione. Ogni compagno di team ha il proprio context window e l’utilizzo dei token si scala con il numero di compagni di team attivi. Per ricerca, revisione e lavoro su nuove funzionalità, i token extra di solito valgono la pena. Per compiti di routine, una singola sessione è più conveniente. Consultate i costi dei token dei team di agenti per la guida all’utilizzo.Esempi di casi d’uso
Questi esempi mostrano come i team di agenti gestiscono compiti in cui l’esplorazione parallela aggiunge valore.Eseguire una revisione del codice parallela
Un singolo revisore tende a gravitare verso un tipo di problema alla volta. Dividere i criteri di revisione in domini indipendenti significa che la sicurezza, le prestazioni e la copertura dei test ricevono tutti un’attenzione approfondita simultaneamente. Il prompt assegna a ogni compagno di team una lente distinta in modo che non si sovrappongano:Investigare con ipotesi concorrenti
Quando la causa principale è poco chiara, un singolo agente tende a trovare una spiegazione plausibile e smettere di cercare. Il prompt combatte questo rendendo i compagni di team esplicitamente avversari: il lavoro di ognuno non è solo investigare la propria teoria ma sfidare le altre.Best practice
Fornire ai compagni di team contesto sufficiente
I compagni di team caricano il contesto del progetto automaticamente, inclusi CLAUDE.md, MCP servers e skills, ma non ereditano la cronologia della conversazione del lead. Consultate Context e comunicazione per i dettagli. Includete i dettagli specifici dell’attività nel prompt di generazione:Scegliere una dimensione del team appropriata
Non c’è un limite rigido al numero di compagni di team, ma si applicano vincoli pratici:- I costi dei token si scalano linearmente: ogni compagno di team ha il proprio context window e consuma token indipendentemente. Consultate i costi dei token dei team di agenti per i dettagli.
- L’overhead di coordinamento aumenta: più compagni di team significa più comunicazione, coordinamento delle attività e potenziale per conflitti
- Rendimenti decrescenti: oltre un certo punto, i compagni di team aggiuntivi non accelerano il lavoro proporzionalmente
Dimensionare le attività appropriatamente
- Troppo piccole: l’overhead di coordinamento supera il beneficio
- Troppo grandi: i compagni di team lavorano troppo a lungo senza check-in, aumentando il rischio di sforzo sprecato
- Giuste: unità auto-contenute che producono un deliverable chiaro, come una funzione, un file di test o una revisione
Aspettare che i compagni di team finiscano
A volte il lead inizia a implementare le attività stesso invece di aspettare i compagni di team. Se notate questo:Iniziare con ricerca e revisione
Se siete nuovi ai team di agenti, iniziate con compiti che hanno confini chiari e non richiedono di scrivere codice: revisionare una PR, ricercare una libreria o investigare un bug. Questi compiti mostrano il valore dell’esplorazione parallela senza le sfide di coordinamento che vengono con l’implementazione parallela.Evitare conflitti di file
Due compagni di team che modificano lo stesso file porta a sovrascritture. Suddividete il lavoro in modo che ogni compagno di team possieda un set diverso di file.Monitorare e sterzare
Controllate il progresso dei compagni di team, reindirizzate gli approcci che non funzionano e sintetizzate i risultati man mano che arrivano. Lasciare un team senza supervisione per troppo tempo aumenta il rischio di sforzo sprecato.Troubleshooting
I compagni di team non appaiono
Se i compagni di team non appaiono dopo aver chiesto a Claude di creare un team:- In modalità in-process, i compagni di team potrebbero già essere in esecuzione ma non visibili. Premete Shift+Down per scorrere i compagni di team attivi.
- Controllate che il compito che avete dato a Claude fosse abbastanza complesso da giustificare un team. Claude decide se generare compagni di team in base al compito.
- Se avete esplicitamente richiesto split panes, assicuratevi che tmux sia installato e disponibile nel vostro PATH:
- Per iTerm2, verificate che la CLI
it2sia installata e che l’API Python sia abilitata nelle preferenze di iTerm2.
Troppi prompt di permesso
Le richieste di permesso dei compagni di team si propagano al lead, il che può creare attrito. Pre-approvate le operazioni comuni nelle vostre impostazioni di permesso prima di generare i compagni di team per ridurre le interruzioni.I compagni di team si fermano su errori
I compagni di team possono fermarsi dopo aver incontrato errori invece di recuperare. Controllate il loro output utilizzando Shift+Down in modalità in-process o facendo clic sul riquadro in modalità split, quindi:- Date loro istruzioni aggiuntive direttamente
- Generate un compagno di team sostitutivo per continuare il lavoro
Il lead si spegne prima che il lavoro sia finito
Il lead potrebbe decidere che il team è finito prima che tutte le attività siano effettivamente completate. Se questo accade, ditegli di continuare. Potete anche dire al lead di aspettare che i compagni di team finiscano prima di procedere se inizia a fare lavoro invece di delegare.Sessioni tmux orfane
Se una sessione tmux persiste dopo che il team finisce, potrebbe non essere stata completamente pulita. Elencate le sessioni e uccidete quella creata dal team:Limitazioni
I team di agenti sono sperimentali. Le limitazioni attuali di cui essere consapevoli:- Nessuna ripresa della sessione con compagni di team in-process:
/resumee/rewindnon ripristinano i compagni di team in-process. Dopo aver ripreso una sessione, il lead potrebbe tentare di messaggiare compagni di team che non esistono più. Se questo accade, dite al lead di generare nuovi compagni di team. - Lo stato dell’attività può ritardare: i compagni di team a volte non riescono a contrassegnare le attività come completate, il che blocca le attività dipendenti. Se un’attività sembra bloccata, controllate se il lavoro è effettivamente fatto e aggiornate lo stato dell’attività manualmente o dite al lead di spingere il compagno di team.
- L’arresto può essere lento: i compagni di team finiscono la loro richiesta attuale o la chiamata dello strumento prima di spegnersi, il che può richiedere tempo.
- Un team per sessione: un lead può gestire solo un team alla volta. Pulite il team attuale prima di iniziarne uno nuovo.
- Nessun team annidato: i compagni di team non possono generare i loro propri team o compagni di team. Solo il lead può gestire il team.
- Il lead è fisso: la sessione che crea il team è il lead per tutta la sua durata. Non potete promuovere un compagno di team a lead o trasferire la leadership.
- Permessi impostati al momento della generazione: tutti i compagni di team iniziano con la modalità di permesso del lead. Potete cambiare le modalità dei singoli compagni di team dopo la generazione, ma non potete impostare modalità per compagno di team al momento della generazione.
- Split panes richiedono tmux o iTerm2: la modalità in-process predefinita funziona in qualsiasi terminale. La modalità split-pane non è supportata nel terminale integrato di VS Code, Windows Terminal o Ghostty.
Prossimi passi
Esplorate approcci correlati per il lavoro parallelo e la delega:- Delega leggera: i subagents generano agenti helper per ricerca o verifica all’interno della vostra sessione, migliore per compiti che non hanno bisogno di coordinamento tra agenti
- Sessioni parallele manuali: i Git worktrees vi permettono di eseguire più sessioni Claude Code voi stessi senza coordinamento automatico del team
- Confrontare gli approcci: consultate il confronto subagent vs agent team per una suddivisione fianco a fianco
