Claude Code Agent Teams: Guida pratica al coding IA parallelo

Claude Code Agent Teams rappresenta una delle innovazioni più significative nel panorama dell'intelligenza artificiale. Claude Code Agent Teams si distingue per la sua capacità di trasformare i workflow di sviluppo. In questa guida completa, esploriamo come Claude Code Agent Teams funziona nella pratica e come implementarlo efficacemente.

Cosa sono realmente gli Agent Teams

Agent Teams permettono di orchestrare più sessioni Claude Code che lavorano insieme su un progetto condiviso. Una sessione agisce come team lead. Crea i teammate, assegna task tramite una lista di attività condivisa e sintetizza i risultati. Ogni teammate ha la propria finestra di contesto e può comunicare direttamente con gli altri teammate.

Questo è fondamentalmente diverso dai sub-agent. I sub-agent vengono eseguiti nel contesto della sessione principale, svolgono lavoro mirato e riportano i risultati. Non possono comunicare tra loro. Agent Teams crea sessioni indipendenti che collaborano tramite un sistema di messaggistica e una lista di task condivisa — pensate a un team di progetto rispetto a una coda di freelancer.

Configurare Agent Teams

Attiva la funzionalità con una singola variabile d'ambiente:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Oppure salvala nelle impostazioni di Claude Code:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Tutto qui. Nessuna dipendenza aggiuntiva, nessun tool esterno. La funzionalità è integrata nativamente in Claude Code 2.1.

Plan Mode vs Delegate Mode

È qui che la maggior parte delle guide fallisce. Esistono due modi distinti per utilizzare Agent Teams, e scegliere quello sbagliato spreca token e produce risultati peggiori.

Plan Mode (Predefinito)

L'agente lead pianifica il lavoro E partecipa all'esecuzione. Può leggere file, scrivere codice ed eseguire comandi — coordinando contemporaneamente i teammate. Sembra efficiente ma crea un problema: il lead si lascia distrarre dai dettagli implementativi invece di concentrarsi sulla coordinazione.

Quando usare il Plan Mode:

• Team piccoli (2-3 teammate) dove i contributi diretti del lead contano
• Compiti dove il lead deve validare l'output dei teammate in tempo reale
• Prototipazione rapida dove l'overhead della delega stretta non vale la pena

Delegate Mode (Shift+Tab)

Premi Shift+Tab dopo aver avviato un team per bloccare il lead in modalità solo coordinamento. Il lead può creare teammate, inviare messaggi, gestire la lista task e terminare i worker — ma non può toccare direttamente il codice. I teammate gestiscono tutta l'implementazione.

Quando usare il Delegate Mode:

• Team più grandi (4+ teammate) dove il lead deve concentrarsi esclusivamente sull'orchestrazione
• Refactoring complessi multi-livello dove la qualità della coordinazione conta più dei contributi del lead
• Workflow di produzione con separazione netta tra pianificazione ed esecuzione

Problema noto (febbraio 2026): Il Delegate Mode ha un bug per cui i teammate ereditano l'accesso limitato agli strumenti del lead. Se i tuoi teammate improvvisamente non possono leggere file o scrivere codice, è per questo motivo. Il workaround è concedere esplicitamente i permessi completi nel prompt di creazione di ogni teammate. Segui la questione su github.com/anthropics/claude-code/issues/25037.

L'approccio Contract-First

Il singolo fattore più importante per il successo di Agent Teams non è la funzionalità stessa — è il tuo file AGENTS.md. Pratichiamo lo sviluppo contract-first da mesi, e Agent Teams ne amplifica l'importanza di un ordine di grandezza.

Perché i contratti contano di più con i Teams

Quando una singola sessione Claude Code legge il tuo AGENTS.md, ottiene un'interpretazione delle regole del progetto. Quando quattro teammate lo leggono indipendentemente, ottieni quattro interpretazioni. Senza contratti espliciti, i teammate fanno ipotesi contrastanti su stile del codice, pattern architetturali, requisiti di testing e organizzazione dei file.

La nostra struttura AGENTS.md per i Teams

# AGENTS.md

## Regole di Architettura
- Tutte le route API usano il pattern handler in /src/handlers/
- Le query al database passano per /src/db/queries/ — mai SQL inline
- Ogni funzione pubblica ha JSDoc con @param e @returns

## Proprietà dei File (Critico per i Teams)
- /src/api/ → Il teammate API possiede quest'area
- /src/db/ → Il teammate Database possiede quest'area
- /src/components/ → Il teammate Frontend possiede quest'area
- /src/tests/ → Il teammate Test possiede quest'area

## Standard del Codice
- TypeScript strict mode, nessun tipo `any`
- Gestione errori: usare sempre il pattern Result<T, E>
- Import: percorsi assoluti tramite alias @/

## Regole di Coordinamento del Team
- Prima di modificare un file condiviso, contattare il proprietario del file
- Punti di integrazione documentati in /docs/interfaces.md
- Tutti i teammate eseguono `npm test` prima di segnalare un task come completato

La sezione Proprietà dei File è l'aggiunta chiave per i team. Senza di essa, due teammate che modificano lo stesso file creano conflitti di merge che sprecano token e producono codice inconsistente.

Quando usare Teams vs Sub-Agent

Dopo due settimane di uso quotidiano, ecco il nostro framework decisionale:

La domanda chiave: I tuoi worker hanno bisogno di parlare tra loro? Se sì, Agent Teams. Se devono solo lavorare e riportare, i sub-agent sono più veloci ed economici.

Pattern di team collaudati nella pratica

Pattern 1: Il Feature Squad

Lead → Crea 3 teammate:
  ├── Teammate API: Costruisce endpoint REST
  ├── Teammate DB: Crea migrazioni + query
  └── Teammate Test: Scrive test di integrazione mentre API + DB lavorano

Il teammate test monitora i messaggi degli altri due e scrive test contro le interfacce che definiscono. Questo produce una migliore copertura di test rispetto alla scrittura post-implementazione perché il teammate test sfida le ipotesi in tempo reale.

Pattern 2: Il Dibattito di Ricerca

Lead → Crea 2-3 teammate:
  ├── Sostenitore A: Argomenta per l'approccio X con prove
  ├── Sostenitore B: Argomenta per l'approccio Y con prove
  └── (Opzionale) Critico: Tenta di demolire entrambi gli approcci

Ogni teammate ricerca indipendentemente, poi si scambiano messaggi con le scoperte. Il lead sintetizza gli argomenti più forti da tutti i lati. Lo usiamo per decisioni architetturali dove non c'è una risposta ovviamente giusta.

Pattern 3: Il Processore Parallelo

Lead → Crea N teammate:
  ├── Worker 1: Elabora file 1-50
  ├── Worker 2: Elabora file 51-100
  └── Worker N: Elabora file (N-1)*50+1 fino a N*50

Per operazioni su larga scala come refactoring dell'intera codebase o elaborazione di file in massa. Ogni worker possiede un range di file distinto. Nessuna comunicazione necessaria tra worker — il lead distribuisce e raccoglie.

Consigli pratici dall'uso quotidiano

1. Iniziare in piccolo

Non creare 6 teammate il primo giorno. Inizia con 2 teammate su un compito ben definito. Impara i pattern di coordinamento prima di scalare.

2. Definire lo scope in modo esplicito

Prompt vaghi come "refactorizza la codebase" producono caos con i team. Prompt specifici come "Teammate A: refactorizza /src/api/auth.ts al nuovo pattern middleware. Teammate B: aggiorna tutti i test in /src/tests/auth/ di conseguenza" producono risultati puliti.

3. Usare le scorciatoie da tastiera

• Shift+Su/Giù: Selezionare un teammate per visualizzare o inviare un messaggio
• Enter (su teammate selezionato): Aprire messaggio diretto a quel teammate
• Shift+Tab: Attivare/disattivare il delegate mode

4. Monitorare il consumo di token

Agent Teams consuma significativamente più token delle sessioni singole. Ogni teammate è un'istanza Claude separata con la propria finestra di contesto. Una sessione con 4 teammate usa facilmente 4-5x i token di una sessione singola. Pianifica il budget di conseguenza.

5. Pulire sempre

Chiama TeamDelete quando il lavoro è completato. Le sessioni teammate orfane continuano a funzionare e consumare token. Il lead deve terminare esplicitamente tutti i teammate prima di concludere.

L'esplosione YouTube

Tre video YouTube importanti sono usciti in 24 ore sugli Agent Teams — da WorldofAI, Cole Medin e AI Labs. Questo segnala un interesse massivo degli sviluppatori ma anche che la domanda di ricerca sta per esplodere. La maggior parte di quei contenuti copre la configurazione di base. Questa guida si concentra sui pattern e le insidie che incontrerai dopo che il momento "wow" iniziale svanisce.

Cosa arriva dopo

Agent Teams è ancora sperimentale. Basandoci sulle issue GitHub e il ritmo di sviluppo di Anthropic, ci aspettiamo:

• Fix del Delegate Mode: Il bug di ereditarietà degli strumenti verrà probabilmente risolto presto
• Team persistenti: Attualmente i team esistono solo all'interno di una sessione. Team persistenti tra sessioni sarebbero trasformativi
• Migliore efficienza dei token: L'overhead attuale è elevato. Anthropic sta probabilmente lavorando su ottimizzazioni di condivisione del contesto
• Integrazione SDK: Il Claude Agent SDK supporta già operazioni di team in modo programmatico. Aspettati un'integrazione più profonda con le pipeline CI/CD

Domande Frequenti (FAQ)

Come attivo Agent Teams in Claude Code?

Imposta la variabile d'ambiente CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 oppure aggiungila nel tuo settings.json di Claude Code sotto la chiave env. La funzionalità richiede Claude Code 2.1 o successivo e funziona con Opus 4.6.

Qual è la differenza tra sub-agent e Agent Teams?

I sub-agent vengono eseguiti nella sessione principale, svolgono lavoro mirato e riportano i risultati — non possono comunicare tra loro. Agent Teams crea sessioni indipendenti con le proprie finestre di contesto che possono scambiarsi messaggi direttamente tramite un sistema di messaggistica e coordinarsi tramite una lista di task condivisa.

Quanti teammate dovrei creare?

Inizia con 2-3 per i primi progetti. Ogni teammate è un'istanza Claude separata che consuma i propri token. Un team di 4 teammate usa circa 4-5x i token di una singola sessione. Scala solo quando hai confermato che l'overhead di coordinamento ne vale la pena per il tuo compito specifico.

AGENTS.md funziona con Agent Teams?

AGENTS.md è ancora più critico con Agent Teams che nelle sessioni singole. Ogni teammate lo legge indipendentemente, quindi deve essere esplicito sulla proprietà dei file, gli standard del codice e le regole di coordinamento. Aggiungi una sezione "Proprietà dei File" che mappa le directory ai ruoli specifici dei teammate per prevenire conflitti di merge.

Il Delegate Mode o il Plan Mode è migliore?

Dipende dalla dimensione del team e dalla complessità del compito. Il Plan Mode funziona bene per team piccoli (2-3) dove i contributi diretti del lead aggiungono valore. Il Delegate Mode (Shift+Tab) è migliore per team più grandi (4+) dove il lead deve concentrarsi sulla coordinazione. Nota che il Delegate Mode ha attualmente un bug noto con l'ereditarietà degli accessi agli strumenti — controlla l'issue tracker per aggiornamenti.