Vai al contenuto principale
I team di agenti sono sperimentali e disabilitati per impostazione predefinita. Abilitateli aggiungendo CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS al vostro settings.json o all’ambiente. I team di agenti hanno limitazioni note relative alla ripresa della sessione, al coordinamento delle attività e al comportamento di arresto.
I team di agenti vi permettono di coordinare più istanze di Claude Code che lavorano insieme. Una sessione agisce come il team lead, coordinando il lavoro, assegnando attività e sintetizzando i risultati. I compagni di team lavorano indipendentemente, ognuno nel proprio context window, e comunicano direttamente tra loro. A differenza dei subagents, che vengono eseguiti all’interno di una singola sessione e possono solo riferire al main agent, potete anche interagire direttamente con i singoli compagni di team senza passare attraverso il lead.
I team di agenti richiedono Claude Code v2.1.32 o successivo. Controllate la vostra versione con claude --version.
Questa pagina copre:

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
I team di agenti aggiungono overhead di coordinamento e utilizzano significativamente più token di una singola sessione. Funzionano meglio quando i compagni di team possono operare indipendentemente. Per attività sequenziali, modifiche dello stesso file o lavoro con molte dipendenze, una singola sessione o i subagents sono più efficaci.

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:
Diagramma che confronta le architetture di subagent e team di agenti. I subagents vengono generati dal main agent, svolgono il lavoro e riportano i risultati. I team di agenti si coordinano attraverso un elenco di attività condiviso, con i compagni di team che comunicano direttamente tra loro.
SubagentsTeam di agenti
ContextContext window proprio; i risultati tornano al chiamanteContext window proprio; completamente indipendente
ComunicazioneRiportano i risultati solo al main agentI compagni di team si messaggiano direttamente
CoordinamentoIl main agent gestisce tutto il lavoroElenco di attività condiviso con auto-coordinamento
Migliore perAttività focalizzate dove conta solo il risultatoLavoro complesso che richiede discussione e collaborazione
Costo in tokenInferiore: i risultati sono sintetizzati nel contesto principaleSuperiore: ogni compagno di team è un’istanza Claude separata
Utilizzate i subagents quando avete bisogno di worker veloci e focalizzati che riportino indietro. Utilizzate i team di agenti quando i compagni di team devono condividere i risultati, mettersi in discussione e coordinarsi autonomamente.

Abilitare i team di agenti

I team di agenti sono disabilitati per impostazione predefinita. Abilitateli impostando la variabile di ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS a 1, sia nell’ambiente della shell che tramite settings.json:
settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

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:
Sto progettando uno strumento CLI che aiuta gli sviluppatori a tracciare i commenti TODO
nel loro codebase. Crea un team di agenti per esplorare questo da diversi angoli: un
compagno di team su UX, uno su architettura tecnica, uno che gioca l'avvocato del diavolo.
Da lì, Claude crea un team con un elenco di attività condiviso, genera compagni di team per ogni prospettiva, li fa esplorare il problema, sintetizza i risultati e tenta di pulire il team al termine. Il terminale del lead elenca tutti i compagni di team e su cosa stanno lavorando. Utilizzate Shift+Down per scorrere i compagni di team e messaggiarli direttamente. Dopo l’ultimo compagno di team, Shift+Down torna al lead. Se desiderate che ogni compagno di team sia in un riquadro diviso proprio, consultate Scegliere una modalità di visualizzazione.

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.
L’impostazione predefinita è "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:
{
  "teammateMode": "in-process"
}
Per forzare la modalità in-process per una singola sessione, passatela come flag:
claude --teammate-mode in-process
La modalità split-pane richiede tmux o iTerm2 con la CLI 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:
Crea un team con 4 compagni di team per refactorizzare questi moduli in parallelo.
Usa Sonnet per ogni compagno di team.

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:
Genera un compagno di team architetto per refactorizzare il modulo di autenticazione.
Richiedi l'approvazione del piano prima che apportino modifiche.
Quando un compagno di team finisce di pianificare, invia una richiesta di approvazione del piano al lead. Il lead esamina il piano e lo approva o lo rifiuta con feedback. Se rifiutato, il compagno di team rimane in modalità piano, rivede in base al feedback e lo riinvia. Una volta approvato, il compagno di team esce dalla modalità piano e inizia l’implementazione. Il lead prende decisioni di approvazione autonomamente. Per influenzare il giudizio del lead, fornitegli criteri nel vostro prompt, come “approva solo i piani che includono la copertura dei test” o “rifiuta i piani che modificano lo schema del database”.

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
La rivendicazione delle attività utilizza il file locking per prevenire race condition quando più compagni di team tentano di rivendicare la stessa attività simultaneamente.

Spegnere i compagni di team

Per terminare gracefully la sessione di un compagno di team:
Chiedi al compagno di team ricercatore di spegnersi
Il lead invia una richiesta di arresto. Il compagno di team può approvare, uscendo gracefully, o rifiutare con una spiegazione.

Pulire il team

Quando avete finito, chiedete al lead di pulire:
Pulisci il team
Questo rimuove le risorse del team condivise. Quando il lead esegue la pulizia, controlla i compagni di team attivi e fallisce se ce ne sono ancora in esecuzione, quindi spegneteli prima.
Utilizzate sempre il lead per pulire. I compagni di team non dovrebbero eseguire la pulizia perché il loro contesto di team potrebbe non risolversi correttamente, lasciando potenzialmente le risorse in uno stato incoerente.

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.
In entrambi i casi, rimanete in controllo. Claude non creerà un team senza la vostra approvazione.

Architettura

Un team di agenti consiste di:
ComponenteRuolo
Team leadLa sessione Claude Code principale che crea il team, genera i compagni di team e coordina il lavoro
Compagni di teamIstanze 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
MailboxSistema di messaggistica per la comunicazione tra agenti
Consultate Scegliere una modalità di visualizzazione per le opzioni di configurazione della visualizzazione. I messaggi dei compagni di team arrivano al lead automaticamente. Il sistema gestisce le dipendenze delle attività automaticamente. Quando un compagno di team completa un’attività da cui altre attività dipendono, le attività bloccate si sbloccano senza intervento manuale. I team e le attività sono archiviati localmente:
  • Configurazione del team: ~/.claude/teams/{team-name}/config.json
  • Elenco di attività: ~/.claude/tasks/{team-name}/
La configurazione del team contiene un array 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.
Messaggistica dei compagni di team:
  • 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:
Crea un team di agenti per revisionare la PR #142. Genera tre revisori:
- Uno focalizzato sulle implicazioni di sicurezza
- Uno che controlla l'impatto sulle prestazioni
- Uno che convalida la copertura dei test
Che ognuno esamini e riporti i risultati.
Ogni revisore lavora dalla stessa PR ma applica un filtro diverso. Il lead sintetizza i risultati tra tutti e tre dopo che finiscono.

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.
Gli utenti segnalano che l'app esce dopo un messaggio invece di rimanere connessa.
Genera 5 compagni di team agenti per investigare diverse ipotesi. Fate loro parlare
tra loro per cercare di confutare le teorie reciproche, come un dibattito
scientifico. Aggiornate il documento dei risultati con qualsiasi consenso emerga.
La struttura del dibattito è il meccanismo chiave qui. L’investigazione sequenziale soffre di ancoraggio: una volta che una teoria è stata esplorata, l’investigazione successiva è distorta verso di essa. Con più investigatori indipendenti che attivamente cercano di confutarsi a vicenda, la teoria che sopravvive è molto più probabile che sia la causa principale effettiva.

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:
Genera un compagno di team revisore di sicurezza con il prompt: "Esamina il modulo di autenticazione
in src/auth/ per vulnerabilità di sicurezza. Concentrati sulla gestione dei token, sulla
gestione della sessione e sulla convalida dell'input. L'app utilizza token JWT archiviati in
cookie httpOnly. Segnala eventuali problemi con valutazioni di gravità."

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
Iniziate con 3-5 compagni di team per la maggior parte dei flussi di lavoro. Questo bilancia il lavoro parallelo con il coordinamento gestibile. Gli esempi in questa guida utilizzano 3-5 compagni di team perché quell’intervallo funziona bene in diversi tipi di attività. Avere 5-6 attività per compagno di team mantiene tutti produttivi senza eccessivo context switching. Se avete 15 attività indipendenti, 3 compagni di team è un buon punto di partenza. Scalate solo quando il lavoro beneficia genuinamente dall’avere compagni di team che lavorano simultaneamente. Tre compagni di team focalizzati spesso superano cinque dispersi.

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
Il lead suddivide il lavoro in attività e le assegna ai compagni di team automaticamente. Se non sta creando abbastanza attività, chiedetegli di dividere il lavoro in pezzi più piccoli. Avere 5-6 attività per compagno di team mantiene tutti produttivi e permette al lead di riassegnare il lavoro se qualcuno rimane bloccato.

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:
Aspetta che i tuoi compagni di team completino le loro attività prima di procedere

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:
    which tmux
    
  • Per iTerm2, verificate che la CLI it2 sia 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:
tmux ls
tmux kill-session -t <session-name>

Limitazioni

I team di agenti sono sperimentali. Le limitazioni attuali di cui essere consapevoli:
  • Nessuna ripresa della sessione con compagni di team in-process: /resume e /rewind non 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.
CLAUDE.md funziona normalmente: i compagni di team leggono i file CLAUDE.md dalla loro directory di lavoro. Utilizzate questo per fornire una guida specifica del progetto a tutti i compagni di team.

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