Hai una feature che richiede tre cose contemporaneamente. Puoi lanciare subagent all'interno di una singola sessione Claude Code e farli lavorare in parallelo. Oppure puoi dividere il lavoro in tre task indipendenti, assegnare ciascuno a un agente separato nel suo pannello tmux, e farli girare senza che sappiano nulla l'uno dell'altro.

Entrambi gli approcci parallelizzano il lavoro. Risolvono problemi diversi. Scegli quello sbagliato e brucerai finestra di contesto in overhead di coordinamento oppure creerai conflitti di merge che richiedono piu tempo per essere risolti del task originale.

Questo e il framework decisionale che uso ogni giorno facendo girare 13 agenti Claude Code sulla stessa codebase. Non e teorico. E il risultato di aver sbagliato abbastanza volte da sapere dove si trova il confine.

Due tipi di parallelismo

Claude Code supporta due modi distinti di eseguire lavoro in modo concorrente.

I subagent sono processi figli lanciati all'interno di una singola sessione Claude Code. L'agente padre avvia piu subagent, ciascuno affronta una parte del problema, poi raccoglie i risultati. Condividono la stessa directory di lavoro e il contesto del padre. Pensali come thread in un singolo processo.

Parent agent
  ├── Subagent A: "Search lib/ for all usages of parseConfig"
  ├── Subagent B: "Search server/ for all usages of parseConfig"
  └── Subagent C: "Search components/ for all usages of parseConfig"

Gli agenti separati girano in sessioni Claude Code indipendenti, tipicamente in pannelli tmux separati. Ciascuno ha la propria finestra di contesto, il proprio file di identita CLAUDE.md e la propria visione della codebase. Non condividono memoria. Comunicano attraverso artefatti: commenti sui task, aggiornamenti di stato, codice committato. Pensali come processi separati senza stato condiviso.

tmux pane 1: eng1 agent → "Build the REST endpoint"
tmux pane 2: eng2 agent → "Build the React component"
tmux pane 3: qa1 agent  → "Write integration tests for both"

Il modello mentale conta perche determina come il lavoro fluisce tra le unita. I subagent possono restituire dati al padre a basso costo. Gli agenti separati passano dati attraverso il filesystem, git o un task tracker esterno.

Quando vincono i subagent

Usa i subagent quando il lavoro condivide stato e i risultati devono convergere.

Ricerca parallela. Devi cercare un pattern in cinque directory, leggere tre file di documentazione e sintetizzare i risultati in una raccomandazione. I subagent possono prendere ciascuno un percorso di ricerca, restituire risultati, e il padre puo combinarli senza overhead di serializzazione.

Trasformazioni indipendenti sugli stessi dati. Stai refactorizzando un modulo e devi aggiornare le definizioni dei tipi, i test e la documentazione in un unico cambiamento coerente. Ogni subagent gestisce un file, ma il padre garantisce che le modifiche siano coerenti perche vede tutti e tre i risultati prima di committare.

Esplorazione rapida. Stai debuggando e devi controllare il git log, l'output dei test e la configurazione runtime simultaneamente. I subagent possono raccogliere tutti e tre in parallelo e il padre sintetizza una diagnosi.

Il pattern: distribuire, raccogliere, agire sul risultato combinato. Se il tuo parallelismo finisce con il padre che deve ragionare su tutti gli output insieme, i subagent sono lo strumento giusto.

Dove i subagent falliscono: qualsiasi cosa che richieda piu di qualche minuto per ramo, qualsiasi cosa che modifichi file in percorsi sovrapposti, o qualsiasi cosa che necessiti di verifica indipendente. I subagent condividono una directory di lavoro, quindi due subagent che scrivono nello stesso file corromperanno il lavoro l'uno dell'altro. E poiche condividono il contesto, un subagent di lunga durata consuma la finestra disponibile del padre.

Quando vincono gli agenti separati

Usa agenti separati quando il lavoro puo essere verificato indipendentemente e non ha bisogno di un contesto condiviso per avere senso.

Componenti diversi della stessa feature. "Costruisci l'endpoint API" e "Costruisci il frontend che lo chiama" sono indipendenti fino all'integrazione. L'ingegnere API non ha bisogno del componente React nel suo contesto. L'ingegnere frontend non ha bisogno dello schema del database. Dare a ciascuno il proprio agente con un CLAUDE.md delimitato mantiene il contesto pulito e impedisce alla complessita di un agente di contaminare il lavoro dell'altro.

Criteri di accettazione diversi. Se il task A e completato quando l'endpoint restituisce 200 con la forma JSON corretta, e il task B e completato quando il componente renderizza i dati con gli stati di errore appropriati, questi sono obiettivi di verifica separati. Un agente QA puo validare ciascuno indipendentemente. I subagent non possono essere verificati indipendentemente perche producono un output combinato.

Lavoro che tocca parti diverse della codebase. Il file ownership e il modo piu semplice per prevenire conflitti di merge. L'agente A possiede server/, l'agente B possiede components/. Nessuno entra nel territorio dell'altro. Se provi questo con i subagent, il padre dovrebbe gestire il file locking, il che vanifica lo scopo del parallelismo.

Task con orizzonti temporali diversi. Un task richiede 10 minuti, l'altro 2 ore. Con i subagent, il padre aspetta il figlio piu lento. Con agenti separati, il task breve si completa, viene verificato e shippato mentre il task lungo sta ancora girando.

Il pattern: lanciare, dimenticare, verificare separatamente. Se ogni pezzo di lavoro regge da solo e puo essere controllato da solo, gli agenti separati con task strutturati sono piu puliti.

Il problema del passaggio

Il vero punto decisionale si riduce ai passaggi.

I passaggi dei subagent sono economici. Il figlio restituisce dati al padre nello stesso contesto. Nessuna serializzazione, nessuna scrittura di file, nessuna attesa di aggiornamenti di stato. Il padre lancia tre subagent, restituiscono tre risultati, il padre ha tutto cio di cui ha bisogno.

I passaggi tra agenti separati sono costosi ma durevoli. L'agente A completa il lavoro, committa codice, aggiorna lo stato di un task e commenta cosa ha fatto. L'agente B raccoglie quel segnale (tramite un coordinatore o interrogando il task tracker) e inizia il suo lavoro dipendente. L'overhead e reale: serve un sistema di task, un protocollo di stato e un modo per gli agenti di scoprire cosa hanno fatto gli altri agenti.

La regola pratica: se il lavoro richiede piu di un passaggio tra le unita parallele, usa i subagent. Per un singolo fan-out-and-gather, i subagent sono piu semplici. Se l'output dell'agente A e l'input dell'agente B, che diventa l'input dell'agente C, il costo di coordinamento degli agenti separati e giustificato perche ogni passaggio produce un artefatto verificato e committato che non andra perso se un agente crasha o raggiunge un limite di contesto.

Un esempio concreto. Devi:

Trovare tutti gli endpoint API che restituiscono dati utente
Aggiungere rate limiting a ciascuno
Scrivere test per i nuovi rate limit
Aggiornare la documentazione API

I passaggi 1 e 2 sono strettamente accoppiati. I risultati della ricerca (passaggio 1) alimentano direttamente la modifica (passaggio 2). Un subagent gestisce la ricerca; il padre applica le modifiche. Questo e un pattern da subagent.

I passaggi 3 e 4 sono indipendenti tra loro ma dipendono dal passaggio 2. I test hanno bisogno del codice reale dell'endpoint. La documentazione ha bisogno della forma finale dell'API. Questi sono task separati per agenti separati, ciascuno con i propri criteri di accettazione, ciascuno verificabile autonomamente.

Scomposizione strutturata nella pratica

Quando la risposta e "agenti separati," hai bisogno di un modo per scomporre la feature in task che possano girare in parallelo senza pestarsi i piedi.

Il processo di scomposizione:

1. Identificare il grafo delle dipendenze. Prima di dividere qualsiasi cosa, mappa cosa dipende da cosa:

Feature: User profile page with activity feed

- API endpoint: GET /users/:id/profile     (no deps)
- API endpoint: GET /users/:id/activity     (no deps)
- React component: ProfileHeader            (depends on profile API)
- React component: ActivityFeed             (depends on activity API)
- Integration test: profile page end-to-end (depends on all above)

I due endpoint API non hanno dipendenze. Possono girare in parallelo. I due componenti React dipendono ciascuno da un'API. Il test di integrazione dipende da tutto.

2. Tracciare i confini di proprieta. Ogni task riceve un ambito di file. L'agente del profile API possiede server/routes/profile.ts e server/services/profile.ts. L'agente dell'activity API possiede server/routes/activity.ts e server/services/activity.ts. Nessuno tocca i file dell'altro. Se un'utilita condivisa necessita di modifica, un agente crea il cambiamento e l'altro aspetta.

3. Definire i criteri di accettazione per task. Ogni task ha bisogno di una condizione "fatto" chiara che possa essere verificata senza guardare gli altri task. "Profile API restituisce 200 con la forma corretta" e verificabile. "La pagina profilo funziona" no, perche dipende dall'integrazione.

4. Specificare gli artefatti di passaggio. Di cosa ha bisogno un agente a valle da uno a monte? Di solito: codice committato su un branch noto, un aggiornamento di stato e un commento che descrive il contratto di interfaccia (forma API, props del componente, firme delle funzioni).

Questa scomposizione trasforma un vago "costruisci la pagina profilo" in cinque task discreti con dipendenze esplicite e criteri di verifica. Ogni task puo essere assegnato a un agente che ha esattamente il contesto di cui ha bisogno e niente di piu.

Beads per la scomposizione strutturata

Qui e dove avere un vero sistema di task conta. Non puoi tracciare cinque task paralleli con post-it e output del terminale.

beads e un issue tracker local-first che modella questa scomposizione nativamente. Un epic rappresenta la feature. I figli rappresentano i subtask. Le dipendenze impediscono agli agenti di iniziare il lavoro prima che i prerequisiti siano soddisfatti.

Ecco come appare la scomposizione nella pratica:

# Create the epic
bd create --title "User profile page with activity feed" \
  --type epic --priority p2

# Create subtasks as children
bd create --title "GET /users/:id/profile endpoint" \
  --parent bb-epic1 --type task --priority p2

bd create --title "GET /users/:id/activity endpoint" \
  --parent bb-epic1 --type task --priority p2

bd create --title "ProfileHeader React component" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-profile-api

bd create --title "ActivityFeed React component" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-activity-api

bd create --title "Profile page integration test" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-profile-header,bb-activity-feed

La struttura e ora esplicita. Un agente che esegue bd show bb-profile-header vede che dipende dal task del profile API. Se quel task non e ancora completato, l'agente sa di non iniziare. Quando l'agente API finisce e segna il suo task come completo, la dipendenza dell'agente frontend si risolve.

Il workflow dell'agente segue un ciclo prevedibile:

# Agent claims the task
bd update bb-profile-api --claim --actor eng1

# Agent comments its plan before writing code
bd comments add bb-profile-api --author eng1 "PLAN:
1. Create route handler at server/routes/profile.ts
2. Add service layer at server/services/profile.ts
3. Return shape: { id, name, avatar, bio, joinedAt }
4. Test: curl localhost:3000/users/1/profile returns 200"

# Agent implements, tests, commits
# ...

# Agent marks done with verification steps
bd comments add bb-profile-api --author eng1 "DONE: Profile endpoint implemented.
Returns { id, name, avatar, bio, joinedAt }.
Verified: curl returns 200 with correct shape.
Commit: abc1234"

bd update bb-profile-api --status ready_for_qa

Ogni passaggio e registrato. L'agente QA legge il commento DONE e sa esattamente come verificare. L'agente a valle legge il commento PLAN e conosce il contratto API prima che il codice sia terminato.

Questo non e overhead fine a se stesso. E la struttura minima che impedisce a cinque agenti paralleli di produrre cinque pezzi di codice incompatibili.

Scegliere di default

Dopo mesi di gestione di agenti paralleli su lavoro di produzione, ecco l'albero decisionale che seguo:

Inizia con i subagent quando:

Il task e ricerca o esplorazione (cercare, leggere, confrontare)
I risultati devono convergere in una singola azione
Tutto il lavoro sta in una finestra di contesto
Non c'e bisogno di verifica indipendente di ogni unita parallela

Passa a task separati quando:

Parti diverse del lavoro toccano file diversi
Ogni pezzo ha i propri criteri di accettazione
Vuoi che il QA verifichi i pezzi indipendentemente
Il lavoro durera abbastanza perche un pezzo finisca ore prima dell'altro
Gli agenti hanno bisogno di contesti diversi (un agente frontend non ha bisogno degli internals del database)

L'approccio ibrido per feature complesse: Usa i subagent per la fase di ricerca e pianificazione (distribuire, raccogliere informazioni, sintetizzare un piano), poi scomponi l'implementazione in task separati per agenti indipendenti. Il workflow spec-driven development si inserisce naturalmente qui: un singolo agente con subagent scrive la spec, poi la spec si scompone in task per la flotta multi-agente.

Visualizzare la scomposizione

Una volta che hai cinque o dieci task strutturati con dipendenze tra loro, tracciare il progresso nel terminale diventa difficile. bd list ti mostra una lista piatta. Non mostra quali task sono bloccati, quali sono pronti per partire o quanto e progredito l'epic.

Questo e il problema che Beadbox risolve. Legge lo stesso database beads e renderizza alberi di epic con indicatori di progresso, relazioni di dipendenza e assegnazioni degli agenti. Vedi quali subtask sono completati, quali sono bloccati da prerequisiti e quali sono pronti per essere presi da un agente. Il grafo delle dipendenze che hai specificato con --deps diventa una mappa visuale del tuo lavoro parallelo.

Quando un agente finisce un task e aggiorna lo stato, Beadbox riflette il cambiamento in tempo reale. Nessun refresh, nessun ri-esecuzione di bd list. L'albero si aggiorna, la barra di progresso avanza e i task bloccati si sbloccano man mano che le loro dipendenze si risolvono.

Gli stessi dati. Solo visibili.

Se stai costruendo workflow come questi, metti una stella a Beadbox su GitHub.

Subagent Claude Code vs. scomposizione strutturata dei task: quando usare quale