Lavoro parallelo con Claude Code: worktree, agenti e workflow

Materiali pratici sul lavoro con agenti in parallelo: documentazione Ailoot.

Questa guida riunisce l’esperienza pratica e una mappa degli ambiti in cui si applicano gli strumenti. I quattro elementi ufficiali di Claude Code, una mappa dei loro ambiti di applicazione e un quadro anti-hype per capire quanti agenti paralleli servano davvero a chi fa vibe coding. Tutte le cifre e le citazioni rimandano a fonti primarie di Anthropic.

Che cos’è il multi-agent in Claude Code e perché non significa «1000 agenti»#

Una configurazione multi-agent è una configurazione in cui un’attività viene suddivisa in più flussi di lavoro indipendenti, ognuno dei quali gestisce la propria parte e restituisce un risultato. L’esempio più semplice: scrivi il frontend in una finestra di Claude Code e il backend in un’altra finestra sulla stessa macchina, con un repository git condiviso tra loro. Questo è già multi-agent, anche se «orchestrazione» sarebbe una parola superflua per descriverlo.

Una configurazione più articolata: all’interno di una sessione di Claude Code avvii cinque subagent con ruoli diversi (sviluppatore frontend, sviluppatore backend, revisore della sicurezza, tester, redattore della documentazione) e ognuno restituisce il proprio risultato alla conversazione condivisa. È lo stesso approccio multi-agent, ma con un solo punto di controllo.

Ancora più articolato: dici a Claude «esegui ogni settimana un audit di sicurezza su tutti i 500 file del mio progetto» e Claude scrive uno script orchestratore JavaScript. Il runtime avvia in background alcune decine di agenti, ognuno controlla la propria sezione, poi agenti indipendenti verificano i risultati degli altri e tu ricevi un unico rapporto. Questo è Dynamic Workflows, rilasciato da Anthropic il 28 maggio 2026. Un’analisi dettagliata delle funzionalità è disponibile nella guida separata a Dynamic Workflows.

La differenza tra questi tre scenari non è il numero di agenti. La differenza è chi decide che cosa farà l’agente successivo. Nel primo scenario sei tu. Nel secondo decide Claude man mano che la conversazione procede. Nel terzo è uno script JavaScript scritto da Claude.

«1000 agenti» è, per inciso, una cifra reale. È il limite superiore per un singolo Dynamic Workflow in Claude Code. La documentazione ufficiale di Anthropic dice:

In altre parole, è una protezione tecnica contro comportamenti incontrollati, non un carico di lavoro consigliato. In pratica, il 95% delle attività viene gestito da 2–8 flussi di lavoro paralleli. Se stai pensando di usarne di più, chiediti prima che cosa dovranno fare.

4 elementi di Claude Code: subagent, skill, team di agenti e workflow#

Claude Code offre quattro elementi ufficiali per suddividere una singola attività tra più agenti. Anthropic li ha riuniti in una tabella comparativa nella documentazione di Dynamic Workflows. Ecco il confronto in parole semplici:

Ognuno di questi elementi risolve un problema diverso. I subagent servono a delegare 2–3 controlli nell’ambito di una singola attività. Le skill servono quando hai istruzioni già pronte che Claude deve seguire (per esempio «esegui una revisione PR usando questa checklist»). I team di agenti servono quando parti diverse di un prodotto si trovano in finestre diverse e ti serve un coordinatore. I workflow servono quando un’attività è troppo ampia per una sola finestra di contesto.

I subagent sono trattati in dettaglio nella guida 2026 ai subagent di Claude Code. L’albero decisionale per scegliere «che cosa usare per una determinata attività» è nella guida a Skill, Subagent, MCP e Plugin. Questa guida spiega come assemblarli in una configurazione multi-agent basata su git worktree.

Livello 1: subagent in una sessione — il punto di partenza più semplice#

Un subagent è il modo più semplice per suddividere un’attività. La conversazione principale funge da coordinatore. I subagent sono collaboratori temporanei che l’agente principale avvia man mano che procede il lavoro.

Un esempio concreto del progetto descritto. Dopo la prima bozza di una guida, la revisione viene impostata così: Claude riceve la richiesta «avvia sei subagent in parallelo: uno controlla gli indicatori di testo generato dall’IA, il secondo il vocabolario giuridico, il terzo la voce e il tono, il quarto verifica i fatti con WebFetch, il quinto esamina la struttura SEO e il sesto controlla l’accuratezza dei collegamenti interni». Ognuno restituisce un rapporto, dopodiché vengono applicate le modifiche.

Tecnicamente, si usano file in .claude/agents/[subagent-name].md che descrivono il ruolo e gli strumenti. La chiamata avviene tramite lo strumento Agent nella conversazione principale. Claude decide quando inviare una richiesta a un subagent.

Dove funziona. Attività che prevedono 3–7 controlli paralleli di un singolo artefatto (codice, testo, design). Ogni controllo è indipendente. I risultati entrano nella finestra di contesto principale.

Dove incontra dei limiti. Se hai più di 50 file o ogni controllo richiede un proprio contesto da 50K token, la finestra principale si riempie. Ti servono workflow o team di agenti.

Rischio principale. Ogni subagent consuma token separatamente. Se ne avvii sei su un progetto di 200 file e ognuno rilegge tutti i 200 file, paghi 6×. Devi quindi specificare ESATTAMENTE quali file il subagent deve controllare. Per i dettagli, consulta la guida a dove finiscono i token in Claude Code.

Livello 2: git worktree — isolare i file tra sessioni parallele#

Quando i subagent non bastano e ti servono due istanze complete di Claude Code in terminali diversi che lavorano sullo stesso repository, si presenta un problema classico. Entrambe iniziano a modificare lo stesso file; una salva per prima e la seconda sovrascrive le sue modifiche. La settimana scorsa un cliente ha detto al team di supporto: «5 si sovrascrivono a vicenda nello stesso momento».

La soluzione è git worktree. È una funzionalità integrata di git che permette di avere più copie di lavoro dello stesso repository, ciascuna sul proprio branch e con un repository .git condiviso. Un’unica origine, directory diverse sul disco e nessuna sovrapposizione tra i file. Il meccanismo è descritto in dettaglio nella guida a Git worktree in Claude Code.

Comandi per una configurazione di cinque minuti:

# Dalla directory principale del progetto
cd ~/projects/my-app

# Crea un worktree per feature/auth
git worktree add ../my-app-auth feature/auth

# Crea un worktree per feature/billing
git worktree add ../my-app-billing feature/billing

# Apri due finestre del terminale
cd ~/projects/my-app-auth && claude   # primo Claude Code
cd ~/projects/my-app-billing && claude # secondo Claude Code

Ogni copia si trova sul proprio branch. Ogni istanza di Claude Code scrive nella propria directory. Al termine dell’attività, esegui git push dal relativo branch, poi git worktree remove ../my-app-auth.

Che cosa devi sapere. Un worktree non duplica node_modules, .venv o altri file in .gitignore. Se ti servono dipendenze indipendenti (una versione diversa di una libreria su ciascun branch), esegui npm install separatamente nella nuova directory dopo worktree add.

Quanti worktree per persona. Secondo i sondaggi tra i team del 2026, il limite pratico è di 4–8 worktree paralleli per sviluppatore. Il fattore limitante non è Claude, ma la capacità di una persona di esaminare e accettare i risultati. Se hai 10 worktree, resteranno in attesa di revisione.

Nella pratica descritta, di solito le persone usano 2–3 worktree paralleli. Un worktree principale per il lavoro attivo, uno di riserva per le correzioni urgenti e uno per un esperimento (una nuova funzionalità su cui non sei sicuro). Non ne servono altri.

Livello 3: team di agenti — più finestre, un agente guida#

I team di agenti sono un elemento relativamente nuovo. L’idea è questa: un agente guida mantiene il piano condiviso sotto forma di elenco di attività e diverse sessioni peer in finestre separate si occupano delle attività assegnate dal leader. Lavorano tutte sullo stesso filesystem e possono vedere i rispettivi artefatti intermedi.

È utile quando un’attività si suddivide in 3–5 flussi di lavoro ampi, ciascuno della durata di ore (migrare un modulo grande, riscrivere un sottosistema, eseguire un audit di sicurezza completo). In quel caso, l’agente guida conserva il piano in un solo file condiviso, a un percorso assoluto esterno ai worktree. Gli altri agenti leggono quel percorso e riferiscono i risultati; solo la guida aggiorna gli stati, evitando scritture concorrenti nel file di coordinamento.

Tecnicamente, i team di agenti sono più finestre che lavorano su git worktree con un unico punto di pianificazione condiviso. In pratica, l’80% delle persone gestisce i team di agenti manualmente (come descritto sopra con worktree) e non usa un «framework per team» specifico. Va benissimo.

Se non sai se ti serve davvero un framework, quasi certamente non ti serve. Usa worktree manuali e un agente guida nella directory principale.

Livello 4: Dynamic Workflows — Claude scrive uno script di orchestrazione JS#

Nei tre livelli precedenti, il piano resta in una conversazione: nella mente dell’agente principale o nell’elenco di attività del leader. Dynamic Workflows sposta il piano nel codice. Claude esprime l’attività sotto forma di script JavaScript, il runtime lo esegue in un ambiente isolato, i risultati intermedi vengono conservati nelle variabili dello script anziché nel tuo contesto e la sessione rimane reattiva mentre gli agenti lavorano in background.

Un esempio concreto tratto dalla documentazione ufficiale. Dici:

ultracode: audit every API endpoint under src/routes/ for missing auth checks

Claude scrive uno script JavaScript con una logica più o meno di questo tipo: «prendi tutti i file da src/routes/, suddividili in gruppi di 30 endpoint, avvia un agente su ciascun gruppo con lo stesso controllo, poi avvia due agenti valutatori indipendenti sui risultati e riunisci tutto in un rapporto finale». Lo script viene eseguito. Ricevi una tabella dei risultati e un elenco di endpoint che devono sicuramente essere esaminati.

Dove funziona.

• Esaminare un intero progetto per individuare un singolo problema (sicurezza, tipizzazione, API deprecate).
• Migrazioni ampie (500+ file governati da una regola condivisa).
• Domande di ricerca che richiedono verifiche da più punti di vista indipendenti (Anthropic lo fa con il comando integrato /deep-research).

Un’analisi dettagliata di Dynamic Workflows, dei loro limiti e del funzionamento di ultracode è disponibile nella guida separata a Dynamic Workflows in Claude Code.

Quando NON usarlo. Quando l’attività è lineare e chiara. Non serve un workflow per un’attività come «completa questo componente». Un workflow ha senso quando un’attività si suddivide in 10+ sottoattività indipendenti e serve un controllo incrociato.

Limite principale. Un workflow consuma molti più token di una sessione normale. Nella documentazione, Anthropic consiglia:

In altre parole, esegui il tuo primo workflow su una directory, non sull’intero progetto. Controlla quanto è costato, poi decidi se vale la pena ampliarne la portata.

Outcomes: una rubrica di criteri e un revisore indipendente#

La cosa più pericolosa nel lavoro multi-agent è fidarsi dei risultati degli agenti. Ogni agente restituisce un testo che sembra un lavoro completato. Una citazione sembra vera, un rapporto sembra completo, una migrazione sembra conclusa. Con un agente puoi controllare il risultato personalmente. Con 10 non puoi: non avrai tempo.

Anthropic affronta il problema con Outcomes, una funzionalità di Managed Agents rilasciata il 6 maggio 2026. L’idea è semplice: alla sessione si aggiunge un SECONDO agente (un valutatore) il cui unico compito è verificare il lavoro del primo agente rispetto a una rubrica rigorosa.

Come funziona tecnicamente. Scrivi una rubrica, un documento markdown con un elenco dettagliato di ciò che significa «completato», delle fonti da controllare e delle etichette da usare. La piattaforma crea automaticamente un agente valutatore in una finestra di contesto nuova. Riceve solo la rubrica e il risultato, nient’altro. Dopo ogni tentativo dell’agente principale (l’autore), il valutatore rilegge il risultato e lo approva oppure restituisce un elenco dettagliato di ciò che è ancora incompleto.

Una citazione dall’Anthropic Cookbook:

Risultati concreti: dopo aver integrato Outcomes in Claude Managed Agents, il tasso di completamento delle attività dell’azienda di IA Harvey è aumentato di circa 6×. Presso Wisedocs (documentazione medica), il tempo dedicato alla revisione di un documento è diminuito del 50%. Questi dati provengono dall’annuncio ufficiale della funzionalità.

Che cosa conta per chi fa vibe coding, anziché per una grande azienda. Outcomes è un approccio, non solo una funzionalità specifica. Puoi creare un tuo agente valutatore descrivendo gli stessi criteri in .claude/agents/grader.md e chiedendo all’agente principale di eseguirlo dopo ogni tentativo. Funziona con qualsiasi configurazione multi-agent, non solo con Managed Agents.

La regola principale per scrivere la rubrica, secondo il cookbook, è specificare qualcosa di verificabile, non qualcosa di generico. Non «controlla che il brief tratti la fatturazione», ma «apri il brief, trova la sezione sulla fatturazione e verifica che riporti un importo in $ o una percentuale dei ricavi». La prima istruzione permette al valutatore di dare un’occhiata e spuntare una casella. La seconda lo obbliga ad aprire il documento e trovare un numero specifico.

Antimodello: «50 agenti che fanno sciocchezze»#

Questo è l’antimodello centrale del multi-agent. Qualcuno scopre che Claude Code può eseguire 16 agenti alla volta e che Dynamic Workflows può eseguirne 1000 per esecuzione, quindi si mette a lanciarli. Il risultato: zero. Consumo di token: 10× una sessione normale.

Una verifica semplice. Prendi un foglio di carta e disegna una casella per ciascuno dei tuoi agenti. In ogni casella scrivi:

1. Che cosa fa esattamente (una frase).
2. Quali file tocca.
3. Che cosa restituisce.
4. Chi lo controlla.

Se non riesci a rispondere anche solo a una di queste domande in 30 secondi, quell’agente non ti serve. Questa regola vale a ogni livello: subagent, team di agenti, Dynamic Workflows.

Il secondo antimodello è eseguire in parallelo attività che dovrebbero essere sequenziali. Se il frontend ha bisogno prima del backend perché legge lo schema dell’API, non eseguirli in parallelo. Prima il backend, poi il frontend. Le attività dovrebbero essere parallele solo se sono indipendenti.

Il terzo antimodello è usare il multi-agent per fare prima. Funziona solo fino a un certo punto. Se suddividi un’attività in quattro flussi di lavoro indipendenti, finiranno più o meno nel tempo necessario a un unico flusso (più un minimo di sovraccarico di coordinamento). Ma se ci sono 50 flussi su una macchina, ognuno procede più lentamente perché condividono la CPU. Su un laptop, il limite pratico è di 4–6 istanze di Claude Code contemporanee; oltre, inizia il throttling.

Quanto costa e come evitare di esaurire i propri limiti?#

Tra maggio e giugno 2026, il settore ha dovuto fare i conti con costi di programmazione con IA più alti del previsto.

Una normale sessione di chat di Claude Code ha un costo relativamente ragionevole. Attiva Dynamic Workflows su un intero repository e ti ritrovi una fattura 20× più alta. Dalla documentazione ufficiale di Anthropic:

Che cosa fare in pratica. Ecco le regole per risparmiare ricavate dall’esperienza descritta.

1. Specifica con precisione i file per ciascun agente. Non «esamina il progetto e trova i problemi», ma «esamina src/auth/*.ts e controlla che ogni funzione convalidi userId». Il secondo prompt ti darà esattamente il lavoro per cui stai pagando.

2. Prova sempre un workflow prima su una directory. Non su tutta src/. Inizia da src/auth/. Se il risultato ti soddisfa e ne capisci il costo, estendilo.

3. Usa /effort high per impostazione predefinita e ultracode solo consapevolmente. /effort ultracode significa xhigh più orchestrazione automatica. È molto costoso. Usalo quando un’attività richiede davvero più flussi di lavoro paralleli.

4. Quando puoi, passa i subagent a un modello più piccolo. Se hai sei subagent che revisionano una guida, né l’agente QA che cerca contenuti generati dall’IA né il controllore dei collegamenti interni hanno bisogno di Opus. Sonnet basta. Questo riduce l’utilizzo di 3–5×.

Un’analisi dettagliata del risparmio di token è disponibile nella guida a dove finiscono i token in Claude Code e nella guida a come non esaurire i limiti di Claude Code.

Da dove iniziare oggi: checklist di 30 minuti#

1. Aggiorna Claude Code a v2.1.154+

   È la versione minima che supporta Dynamic Workflows. Esegui claude update nel terminale.

2. Abilita Dynamic Workflows in /config

   Sono disattivati per impostazione predefinita nel piano Pro. Apri /config, trova la riga «Dynamic workflows» e attivala. Sono già abilitati nei piani Max, Team ed Enterprise.

3. Crea il tuo primo worktree

   Nella directory principale del progetto, esegui git worktree add ../<project>-experiment <branch>. Apri una seconda finestra del terminale in quella directory. Esegui claude.

4. Aggiungi un elenco di attività condiviso

   Usa un unico percorso assoluto esterno a tutti i worktree. Un tasks.md in ciascun worktree è un file separato e non si sincronizza automaticamente. La sessione guida deve essere l’unica a scrivere; gli altri leggono l’elenco e riferiscono i risultati.

   Crea una sola volta directory di coordinamento ed elenco:

   mkdir -p "$HOME/projects/my-app-coordination"
   printf '%s\n' '# Tasks' '- Auth: assegnato al worktree auth' '- Billing: assegnato al worktree billing' > "$HOME/projects/my-app-coordination/tasks.md"
   

   Nel primo terminale:

   cd "$HOME/projects/my-app-auth"
   printf 'Elenco condiviso: %s\n' "$HOME/projects/my-app-coordination/tasks.md"
   claude
   

   Nel secondo terminale:

   cd "$HOME/projects/my-app-billing"
   printf 'Elenco condiviso: %s\n' "$HOME/projects/my-app-coordination/tasks.md"
   claude
   

   Fornisci a entrambe le sessioni lo stesso percorso assoluto espanso stampato sopra: «Leggi questo elenco condiviso. Lavora solo sull’attività e sui file assegnati. Non modificare l’elenco; riferisci completamento e blocchi alla guida, responsabile degli aggiornamenti». Verifica prima del lavoro che entrambi possano leggere quel file esatto; risolvi l’eventuale richiesta di autorizzazione per quel percorso. L’elenco coordina gli stati, mentre le modifiche al codice restano nei worktree separati.

5. Lavora così per una settimana

   Non installare subito un wrapper GUI. Passa una settimana lavorando manualmente con due worktree. Vedrai che cosa manca; poi scegli uno strumento per risolvere un problema specifico.

6. Solo allora abilita `/effort ultracode`

   Scegli un’attività, per esempio «trova tutti gli endpoint API senza controlli di autenticazione in src/routes/». Abilita /effort ultracode. Osserva quale workflow scrive Claude, quanto costa e quale risultato produce. Quello sarà il tuo primo Dynamic Workflow.

Prossimi passi: memoria tra sessioni, Code Review, Multi-Agent v2#

Ecco che cosa è apparso tra maggio e giugno 2026 e verso quale direzione si sta muovendo il multi-agent in Claude Code.

Managed Agents con Dreaming. Presentato il 6 maggio 2026 a Code with Claude. Un processo pianificato che legge le trascrizioni passate di un agente tra una sessione e l’altra, identifica schemi ricorrenti e aggiorna la sua memoria. Il completamento delle attività dell’azienda legale di IA Harvey è aumentato di sei volte proprio dopo Dreaming. È ancora in anteprima di ricerca.

Outcomes come funzionalità di Managed Agents. Descritto sopra. È disponibile tramite Claude Agent SDK, non direttamente nella CLI di Claude Code. Puoi applicare subito lo stesso approccio manualmente usando un subagent valutatore.

Multi-Agent Orchestration v2 nel Claude Agent SDK. Un agente guida delega autonomamente i subagent usando un filesystem condiviso. È un passaggio da «avvia manualmente N subagent» a «descrivi un’attività e il leader decide da solo a chi delegarla e come». Se stai imparando ora a usare i subagent, non preoccuparti ancora della v2. Impara il metodo classico — «un agente principale + 3–5 subagent con ruoli» — e passa alla v2 in modo naturale nell’arco di 3–6 mesi.

Code Review da parte di un team di agenti. A Code with Claude, Anthropic ha annunciato una funzionalità per la revisione automatica del codice all’apertura di una PR. Un team di agenti IA controlla le modifiche in parallelo, cerca bug, verifica i risultati a vicenda e li ordina per gravità. È disponibile nei piani Team ed Enterprise, ma non ancora nel piano Pro.

Plugin Marketplace. Lanciato il 23 maggio 2026, nelle versioni v2.1.128-136. Alcuni plugin del marketplace sono configurazioni multi-agent già pronte (parallel-review, security-audit, migration-helper). Puoi installarli con /plugin install <name>@claude-plugins-official e vedere come sono composti: è un buon modo per imparare a scriverne di tuoi.

Il multi-agent in Claude Code si presenta ancora come un insieme di elementi a diversi stadi di maturità. I subagent e git worktree sono stabili, collaudati e funzionano ovunque. I team di agenti sono metà automatizzati e metà manuali. Dynamic Workflows è in anteprima di ricerca e cambia rapidamente. Managed Agents v2 è riservato alle aziende. Ciò significa che nel corso del prossimo anno la configurazione ideale per chi fa vibe coding non sarà l’ultima versione, ma la configurazione minima necessaria per l’attività specifica. Due worktree e un subagent valutatore bastano per un mese di lavoro attivo. Aggiungi complessità solo quando inizi a sentirne la mancanza.

Una configurazione funzionante per il vibe coding#

Materiali pratici: documentazione Ailoot.

Altri materiali e strumenti: Ailoot.