Claude Code Subagents: Quando e come eseguire team di agenti

Ultimo aggiornamento: June 28, 2026

Un subagent Claude Code è una sessione Claude separata che l'agente principale avvia per un compito focalizzato, e poi ripiega il risultato nel tuo lavoro. La scorsa settimana ne ho inviati tre in parallelo per dividere un refactoring in schema, API e test, e sono finiti prima che una singola lunga sessione avrebbe finito di pianificare. Questo post copre come definire e inviare i subagent, gli schemi di orchestrazione che uso per imitare un piccolo team, e la linea onesta su dove i subagent costano più di quanto risparmiano.

Risposta rapida: cos'è un subagent Claude Code?

Un subagent è un'istanza Claude con la propria finestra di contesto, il proprio prompt system e un set di strumenti ristretto. La sessione principale non perde il contesto quando ne esegue uno, perché il subagent lavora in isolamento e restituisce solo un riepilogo. Pensalo come delegare un compito a un collega che non interrompe mai il tuo schermo.

Il meccanismo ufficiale è semplice. Si fa cadere un file markdown in .claude/agents/ con frontmatter YAML, e Claude Code può richiamarlo tramite lo strumento Task quando un compito corrisponde alla sua descrizione. La documentazione sui sub-agent è la fonte di verità per i campi, e il repo Claude Code tiene traccia delle modifiche al formato.

Una definizione minimale di subagent assomiglia a questo:

---
name: migration-writer
description: Writes and runs database migrations for this repo. Use for schema changes.
tools: Read, Edit, Bash
model: inherit
---
You are a migration specialist. Always check existing migrations first, never drop columns without a confirmation step, and run the migration against the local DB before reporting done.

Una volta che quel file esiste, chiedo all'agente principale "usa il subagent migration-writer per aggiungere la tabella orders" e questo invia un worker circoscritto invece di inciampare in linea. La riga model: inherit mantiene costo e qualità sullo stesso livello della sessione principale; vincolare un modello più economico come haiku su un subagent ad alta lettura è una vera leva quando ne esegui molti.

Quando dovresti usare i subagents invece di una singola sessione?

Rivolgiti a un subagent quando il compito è a lunga esecuzione, pesante dal punto di vista del contesto o ha bisogno di un set di strumenti che non vuoi nella sessione principale. Tienilo in una singola sessione quando il lavoro è breve, strettamente accoppiato a ciò che stai già facendo, o ha bisogno di scambi continui con te.

Uso i subagents per lavori che altrimenti contaminerebbero il mio contesto principale con log, grandi letture o prove ed errori. Un audit su tutto il codebase che greps 200 file è un candidato perfetto, perché il subagent legge tutto e restituisce un riepilogo di due paragrafi mentre la mia sessione principale rimane pulita.

Se sei nuovo sull'agente stesso, la guida definitiva su Claude Code copre i fondamentali prima che tu aggiunga subagents sopra.

Come inviare i subagents in Claude Code?

L'invio avviene in due modi. L'agente principale può invocare lo strumento Task da solo quando un compito si adatta alla descrizione di un subagent, o puoi nominarlo esplicitamente nel tuo prompt. Preferisco nominarlo, perché l'invio implicito a volte salta un agente che volevo.

Alcuni schemi che eseguo regolarmente:

• "Usa il subagent code-reviewer sul diff in questo branch, poi applica i suoi suggerimenti."
• "Invia migration-writer per aggiungere una colonna users.email_verified, e invia test-writer per coprirla. Esegui entrambi."
• "Avvia il subagent api-docs contro src/routes/ e restituisci solo lo scheletro OpenAPI."

Il subagent gira nel proprio contesto, quindi non può vedere la tua conversazione in corso a meno che tu non passi il dettaglio nel prompt. Quell'isolamento è il punto. Quando finisce, ottieni un risultato, non un flusso di rumore intermedio.

Schemi che uso per flussi di lavoro simili a un team

Il trucco è copiare come un vero team divide il lavoro, quindi mappare ogni ruolo su un subagent. Ecco gli schemi a cui torno sempre.

Ricerca, poi espandere. Invio un subagent per raccogliere contesto, leggo il suo riepilogo, quindi invio diversi subagents di implementazione contro un'interfaccia condivisa. Questo rispecchia un tech lead che delimita il lavoro prima di distribuire i ticket.

Costruire dietro un contratto. Definisci prima l'API o le props del componente, quindi esegui un subagent backend e un subagent frontend in parallelo contro quel contratto. Nessuno blocca l'altro, e i conflitti sono rari perché toccano file diversi.

Revisione come ruolo separato. Mantengo un subagent code-reviewer con solo strumenti di lettura. Dopo qualsiasi modifica non banale lo eseguo sul diff. Restringergli gli strumenti significa che letteralmente non può modificare, il che mantiene la revisione onesta.

Per flussi di lavoro ripetibili come questo, abbina i subagents a Claude Code skills: uno skill codifica i passaggi e i subagents fanno il lavoro isolato. E se un subagent ha bisogno di dati esterni, collegalo a un server MCP nel modo descritto dalla guida all'integrazione Claude Code MCP.

Un esempio pratico: ordini e pagamenti

Il mese scorso ho diviso una funzionalità ordini più pagamenti in tre subagents contro un contratto tipizzato. Il contratto era un'unica interfaccia TypeScript per un Order con status, totalCents e paymentId. Ho inviato: un subagent backend per implementare la creazione dell'ordine e le transizioni di stato; un subagent payments per collegare la chiamata Stripe e memorizzare il paymentId; e un subagent test per coprire il percorso felice e il caso limite del rimborso. Tutti e tre hanno toccato file diversi, quindi la fusione è stata composta da tre operazioni pulite di copia-incolla invece di una sessione di risoluzione dei conflitti. L'intera esecuzione ha richiesto 14 minuti; lo stesso lavoro in una singola sessione seriale ne richiedeva 41 la settimana prima, perché il singolo contesto continuava a ricaricare i documenti Stripe.

Come si orchestra un lavoro parallelo senza perdere il contesto?

La sessione principale è il tuo coordinatore. Il suo compito è suddividere il lavoro, distribuire prompt circoscritti e ricomporre i risultati. Mantieni il coordinatore snello e lascia che i subagents gestiscano le letture pesanti.

Un tipico run parallelo per me assomiglia a questo:

1. Scrivere il contratto e i confini dei file nella sessione principale.
2. Inviare due o quattro subagents, ciascuno con una fetta e una chiara condizione di successo.
3. Leggere ogni riepilogo non appena viene restituito, non a metà esecuzione.
4. Unire nella sessione principale, risolvendo le cuciture da solo.
5. Eseguire l'ultimo subagent test sul risultato integrato.

Il parallelismo paga solo quando le fette sono genuinamente indipendenti. Se due subagents modificano entrambi schema.prisma, non hai diviso il lavoro, hai creato un problema di fusione. Traccia i confini a file e contratti, quindi applicali nel prompt.

Quando i subagents aggiungono più overhead di quanto ne risparmiano?

I subagents aggiungono latenza, token e costo di coordinamento. Il passaggio del riepilogo fa perdere dettagli, quindi qualsiasi cosa richieda una continuità profonda è un cattivo candidato. Sii onesto sul compromesso prima di ricorrervi.

Ho eseguito un benchmark su un branch feature una volta: un subagent per microservizio contro una singola sessione che li attraversava in ordine. Per cinque servizi poco accoppiati, il parallelo ha vinto con circa il 40% sul tempo reale. Per tre servizi che condividevano un modello di dati, la singola sessione era più veloce, perché fusione e riesplicazione hanno mangiato i guadagni del parallelo.

La lezione: il parallelismo premia l'indipendenza e punisce l'accoppiamento. Se le tue fette condividono stato, non parallelizzarle.

Quali sono gli errori comuni?

• Troppi subagents. Limito un run a tre o cinque. Oltre questo, il costo di coordinamento supera il guadagno parallelo.
• Prompt vaghi. "Correggi l'auth" fallisce. "Aggiungi un endpoint JWT refresh su /auth/refresh, restituendo { token }, con un test" ha successo.
• Nessun criterio di successo. Indica cosa significa fatto. "Migrazione applicata localmente e rollback testato" batte "gestire lo schema".
• Set di strumenti sbagliato. Dai a un revisore solo strumenti di lettura. Dai a un agente di deploy i comandi esatti di cui ha bisogno, nulla di più ampio.
• Ignorare i fallimenti. Se un subagent restituisce un errore, leggilo. Riprovare ciecamente brucia token e nasconde un problema reale.
• Saltare la fusione. I subagents restituiscono risultati; tu sei ancora responsabile dell'integrazione. Alloca tempo reale per farlo.

L'errore più costoso è trattare i subagents come parallelismo gratuito per qualsiasi cosa. Sono worker circoscritti dietro un confine riepilogativo, e quel confine ha un costo.

Riepilogo

I subagents trasformano Claude Code in qualcosa che sembra un piccolo team: un coordinatore snello che invia worker circoscritti che ognuno porta il proprio contesto e riporta un risultato. Definiscili in .claude/agents/, inviali con lo strumento Task, e mantieni la tua sessione principale pulita spingendo letture pesanti e ruoli ripetitivi nei subagents.

Usali quando il lavoro è lungo, pesante dal punto di vista del contesto o ha bisogno di un set di strumenti ristretto. Saltali per compiti brevi, accoppiati e interattivi dove il passaggio del riepilogo perde troppo. Traccia i confini a file e contratti, limita un run a una manciata di agenti e stima sempre tempo per unire i risultati da solo.

Un vero avvertimento: i subagents moltiplicano il throughput, non il giudizio. Costruireanno felicemente la cosa sbagliata in parallelo attraverso quattro contesti isolati. Il lavoro di coordinamento, la definizione del contratto e la revisione finale ricadono ancora su di te, quindi la leva si manifesta solo quando le fette sono veramente indipendenti e i criteri di successo sono precisi. Se vuoi il background più approfondito sul protocollo che alimenta gran parte di questo cablaggio di strumenti, MCP explainer è una buona lettura successiva, e la documentazione Claude Code copre impostazioni che non ho ripetuto qui.

Crediti immagini

• A team of developers working together at computers in a modern tech office — foto di Rebrand Cities su Pexels
• Colorful programming code on a computer monitor — foto di inna mykytas su Pexels
• A developer writing code on a laptop in front of multiple monitors — foto di Christina Morillo su Pexels
• Two programmers focused on coding side by side in a modern office — foto di Rebrand Cities su Pexels