Sub-agenti in Claude Code: parallelizzare il lavoro e proteggere il context

Quando un task in Claude Code inizia a gonfiare il context con risultati di grep, letture di file lunghi o ricerche esplorative, la soluzione non è comprimere: è delegare. I sub-agenti sono istanze separate di Claude che l’agent principale può lanciare per far svolgere un pezzo di lavoro in un context isolato, ricevendo indietro solo la sintesi finale. Nessun rumore nel thread principale, budget di token dedicato, possibilità di farli girare in parallelo.

Cos’è un sub-agente

Un sub-agente è una sessione Claude che parte da zero, riceve un prompt dall’agent principale, esegue il lavoro con i suoi tool e restituisce una risposta testuale. Non eredita la cronologia del padre, non vede i file già letti, non condivide memoria. Questo è il punto: l’isolamento è una feature, non un limite.

Il tool che li lancia si chiama Agent (in alcune versioni della CLI Task). Prende un subagent_type e un prompt. Il main agent aspetta che il figlio finisca, legge la risposta sintetizzata e continua il proprio ragionamento senza essersi mai sporcato le mani con i dettagli intermedi.

Tipi disponibili out-of-the-box

• general-purpose: agente tuttofare, utile quando non serve uno specializzato
• Explore: ricerca in codebase, leggere molti file, tornare con una mappa sintetica
• Plan: architetto, ragiona sul design prima di scrivere codice
• Custom: agenti definiti dall’utente in .claude/agents/

Perché usarli: parallelismo

La ragione numero uno è il parallelismo. Se in un singolo messaggio il main agent invoca N tool Agent diversi, quei N sub-agenti partono in parallelo. Dieci task indipendenti diventano dieci worker che girano contemporaneamente, non una coda sequenziale.

Esempio concreto: generare 20 articoli a partire da altrettanti brief. Un main agent che scrive gli articoli uno dopo l’altro ci mette ore ed esaurisce il context a metà. Un main agent che spawna 20 sub-writer in parallelo, ciascuno con il proprio brief, finisce in una decina di minuti e mantiene il thread principale pulito, pronto per l’integrazione finale.

Perché usarli: proteggere il context

La seconda ragione è difensiva. Una grep che restituisce 4.000 righe, una lettura di log da 2 MB, un file di dump JSON di 50.000 elementi: tutta roba che se finisce nel context principale lo satura. Delegare a un sub-agente significa che quei 4.000 match vengono letti e ragionati in un’altra sessione, e il main riceve indietro solo qualcosa come “i pattern rilevanti sono questi tre, vedi file X righe Y-Z”.

Questa tattica si sposa bene con i https://www.smartworkers.cloud/?p=3429: task lunghi mandati in background, ognuno nel suo sub-agente, notifica al completamento senza bloccare il main.

Run in background

Aggiungendo run_in_background: true all’invocazione di Agent, il sub-agent parte ma il main non aspetta. Torna un handle, arriva una notifica quando finisce. Utile per lavori che durano diversi minuti (una build, un test end-to-end, una scansione completa di una codebase) mentre il main continua a fare altro.

Creare un agente custom

Gli agenti custom si definiscono come file Markdown in .claude/agents/{nome}.md, con frontmatter YAML che ne descrive comportamento, tool ammessi e modello. Il nome del file è il subagent_type da passare al tool Agent.

---
name: security-reviewer
description: Revisiona patch Python/JS alla ricerca di vulnerabilità comuni (injection, path traversal, secret leak). Torna un report strutturato con severità e file:riga.
tools: Read, Grep, Glob
model: sonnet
---

Sei un revisore di sicurezza. Per ogni diff o file che ti viene passato:

1. Cerca pattern pericolosi: concatenazione SQL, exec/eval su input utente,
   path costruiti con input non validato, hardcoded secret, CORS wildcard.
2. Per ogni finding produci: severità (high/med/low), file, riga, descrizione,
   suggerimento di fix.
3. Non modificare file. Solo Read/Grep/Glob.
4. Rispondi con un elenco markdown compatto. Niente preamboli.

Una volta salvato, il main agent può invocarlo come subagent_type: "security-reviewer" passando i file da analizzare. Il risultato è un report pulito che non intasa il thread principale.

Quando NON usarli

• Task a 1-2 step dove il costo di spawn supera il beneficio
• Quando serve continuità di context (il sub non vede quello che hai già letto)
• Quando l’output deve essere voluminoso e strutturato: il sub-agent tende a sintetizzare, e se ti serve tutto il grezzo devi chiederlo esplicitamente
• Debug interattivo su un singolo file: stai lì, non delegare

Limiti da tenere a mente

Ogni sub-agente ha il suo budget di token indipendente. Dieci worker in parallelo consumano dieci budget. Non c’è memoria condivisa tra fratelli: se il risultato del worker 3 serve al worker 4, quella dipendenza va gestita dal main che orchestra, non dai figli. E il contratto di ritorno è solo testo: se il figlio crea file, il main deve saperlo per nome, non li “vede” magicamente.

Le istruzioni di progetto caricate via https://www.smartworkers.cloud/?p=3423 sono viste anche dai sub-agenti (ereditano lo stesso working directory), quindi conviene che il prompt dell’agent custom sia autosufficiente ma possa appoggiarsi alle skill comuni.

Pattern utile: orchestratore + worker

Il pattern che paga di più è quello dell’orchestratore. Il main agent non fa il lavoro sporco: riceve la richiesta, la spezza in N sotto-task indipendenti, spawna N sub-agenti in un unico messaggio, aspetta le sintesi, le integra. Il risultato finale è un thread principale corto e leggibile, con tutto il grosso del ragionamento isolato nei figli.

La domanda che mi faccio prima di delegare è sempre la stessa: il risultato di questo step mi serve nel thread principale per ragionare, o mi basta la conclusione? Se basta la conclusione, è un sub-agente.