Claude Code Subagents: guida pratica (2026)

Un subagent è un secondo Claude, lanciato dalla tua sessione principale di Claude Code, che esegue un task nella propria finestra di contesto e restituisce un risultato. Non condivide la cronologia della tua conversazione. Non vede i file che hai già letto o le decisioni che hai già preso. Riceve un prompt, fa il lavoro, e torna.

Quell'isolamento è l'intera funzionalità. Il parallelismo, la specializzazione, le restrizioni personalizzate sugli strumenti, tutto discende da un unico fatto: un subagent brucia la propria finestra di contesto e solo la risposta finale torna nella tua.

Facciamo girare decine di subagent al giorno costruendo SkillProof, soprattutto per fan-out di ricerca e correzioni indipendenti nei file di dati del catalogo. Alcune delle cose che abbiamo imparato sono genuinamente utili. Alcune le abbiamo imparate guardando un agente rivendicare una vittoria su un lavoro che non ha mai fatto. Entrambi i tipi sono in questa guida.

Cos'è davvero un subagent

In Claude Code, la sessione principale è un loop: leggi, pensa, agisci, osserva, ripeti, con ogni passo aggiunto a un'unica conversazione crescente. Un subagent è un'istanza separata di quello stesso loop, avviata a metà sessione, con una propria cronologia che inizia vuota tranne il prompt che gli dai.

Quando il subagent finisce, niente del suo lavoro intermedio viaggia indietro. Non i file che ha letto, non i comandi che ha eseguito, non i vicoli ciechi che ha esplorato. Solo il testo che sceglie di restituire finisce nel tuo contesto principale. Se ha letto 40 file per rispondere alla tua domanda, la tua sessione principale non paga nessuna di quelle 40 letture. Paga un riassunto.

Ecco perché i subagent vengono descritti come un modo per preservare il contesto: non perché il lavoro sia gratis (costa gli stessi token da qualche parte), ma perché il costo è messo in quarantena in una finestra che viene buttata via, non una che continui a trascinare per il resto della sessione.

Il compromesso segue direttamente. Un subagent che non sa cosa hai già provato può ripetere i tuoi stessi vicoli ciechi, e non può fare una domanda di chiarimento a metà task come può fare il loop principale, o ha abbastanza informazioni nel prompt per procedere o indovina. La delega compra isolamento e costa memoria condivisa. Ogni buon prompt per subagent è scritto da qualcuno che ha interiorizzato quel compromesso.

Perché l'isolamento del contesto è il punto

Immagina una sessione principale due ore dentro un refactoring: quaranta file letti, una dozzina di chiamate a strumenti, una decisione di design rivista due volte. Quella cronologia sta facendo un lavoro vero, è ciò che rende coerente la prossima modifica, ma è anche cinquantamila token di zavorra.

Ora ti serve sapere come un sottosistema non correlato gestisce i retry. Leggi quei file nel loop principale e ognuno di essi diventa bagaglio permanente, che viaggia nel contesto per il resto della sessione che tu lo riusi o no, finché non diventa parte del motivo per cui il modello inizia a perdere il filo del refactoring vero. Un subagent ti permette di fare la domanda, ottenere la risposta, e allontanarti dalla lettura. I quaranta file che ha letto non entrano mai nella tua finestra. Torni con un paragrafo.

Quel meccanismo è dietro ogni vittoria legittima di subagent in questa guida: ricerca, correzioni parallele, esplorazione rumorosa. Sono tutte davvero la stessa mossa: fai la lettura costosa da qualche parte usa-e-getta, tieni pulito il filo principale.

Quando i subagent battono il lavoro nel loop principale

Ricerca su molti file. "Come scorre l'autenticazione in questa codebase" tocca route, middleware, storage di sessione, e tre file di configurazione. Rispondere nel loop principale significa che tutto questo finisce nel tuo contesto in modo permanente. Un subagent legge gli stessi file, restituisce una sintesi, e il materiale grezzo sparisce con lui.

Task paralleli indipendenti. Cinque componenti hanno bisogno che si rinomini la stessa prop. Nessuno dipende dagli altri. Cinque subagent che girano insieme finiscono in circa il tempo che ne impiega uno, senza stato condiviso da coordinare tra le modifiche.

Esplorazione rumorosa. Fare grep di un pattern su un repo grande, provare tre strategie di ricerca prima che una funzioni, leggere file che risultano irrilevanti. Questo è esattamente il lavoro che vuoi mettere in quarantena. Un subagent può brancolare per un po' e solo la parte utile torna indietro.

Isolare una persona specializzata. Un subagent code-reviewer che rivede soltanto, con un set di strumenti più stretto e un prompt tarato per lo scetticismo, si comporta in modo più coerente che chiedere al tuo agente principale di passare, a metà sessione, a "adesso sii critico del tuo stesso lavoro".

Quando i subagent sono peggio

Loop iterativi stretti. Fare debug di un test fallito cambiando una riga, rieseguendo, leggendo il nuovo errore, cambiando un'altra riga, ha bisogno della cronologia completa di cosa hai già provato. Passare quello a un subagent nuovo a ogni iterazione significa rispiegare l'intera indagine ogni volta, più lento e peggio che restare nel loop principale. Questo è il territorio che coprono le nostre note su debug sistematico: il debug vuole continuità, non delega.

Task che hanno bisogno dell'intera conversazione. Se l'utente ha passato dieci messaggi a raffinare esattamente cosa significa "ripulisci questa API", un subagent che vede solo l'istruzione finale la ripulirà secondo la propria idea di "pulito", non quella che avete negoziato. Qualsiasi cosa in cui i requisiti vivono nella conversazione invece che in un prompt che puoi riformulare è un cattivo adattamento.

Modifiche semplici a un solo file. Delegare "rinomina questa variabile in questo file" a un subagent aggiunge un round trip, un caricamento di contesto nuovo, e un risultato che devi comunque leggere e di cui fidarti, per un lavoro che ti sarebbe costato quindici secondi in diretta. Avviare un worker isolato ripaga solo quando il lavoro da cui ti protegge è genuinamente grande.

Il pattern in tutti e tre i casi: i subagent sono peggio esattamente quando il valore del contesto condiviso supera il costo di trascinarlo. L'isolamento smette di essere una funzionalità nel momento in cui la continuità è ciò di cui il task aveva bisogno.

Definizioni di agenti personalizzati

Claude Code carica i subagent personalizzati da file markdown sotto .claude/agents/ (a livello di progetto, condiviso via git) o ~/.claude/agents/ (personale, ogni progetto). Ogni file è un agente: frontmatter più un system prompt, la stessa forma di una skill ma che descrive una persona invece che una procedura.

Ecco un esempio completo e annotato, un code-reviewer limitato a lavoro di revisione in sola lettura:

---
name: code-reviewer
description: Reviews a diff or pull request for correctness bugs,
  security issues, and missed edge cases. Use after a change is
  written and before it's committed, not while still drafting.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior engineer doing a pre-commit review. You did not
write this code and you have no attachment to it.

When given a diff or a set of changed files:

1. Read every changed file in full, not just the diff hunks.
   Bugs hide in the context around a change as often as in the
   change itself.
2. Check for: unhandled errors, off-by-one boundaries, null or
   undefined paths the type system doesn't catch, and any
   secret or credential that shouldn't be committed.
3. Do not comment on style or formatting unless it hides a bug.
   A linter's job is not your job.
4. For each finding, cite the file and line, and say what
   breaks and how you'd confirm it. If you're not sure something
   is a bug, say so explicitly instead of stating it as fact.
5. If you find nothing, say that plainly. Do not invent minor
   issues to look thorough.

Never run commands that modify files. You are reviewing, not fixing.

Alcune cose contano qui. Il name è come lo invochi (Use the code-reviewer agent to check this diff) o come Claude Code lo invoca automaticamente su un task corrispondente. Il campo description porta lo stesso peso che ha in una skill: condizioni di trigger specifiche battono un riassunto vago.

tools è un vero confine di sicurezza, non un suggerimento. Elencare solo Read, Grep, Glob, Bash significa che questo agente non può fisicamente chiamare Edit o Write, anche se il suo stesso ragionamento decidesse che una correzione era ovvia. È deliberato: un agente di revisione che può anche sistemare il codice che sta rivedendo è uno di cui non ti puoi fidare che si limiti a rivedere. model ti permette di instradare un agente meccanico e ben specificato verso un modello più economico della tua sessione principale, dato che il task non ha bisogno del peso completo del tuo modello primario.

Il corpo è la stessa arte di una skill: i vincoli negativi ("non commentare sullo stile", "non inventare problemi minori") fanno più lavoro di quelli positivi, perché sono ciò che impedisce a un revisore di gonfiare il proprio output per sembrare accurato.

Pattern paralleli che funzionano davvero

Letture a ventaglio (fan-out). Lancia diversi subagent insieme, ognuno assegnato a una fetta diversa della stessa domanda: uno legge il modulo di autenticazione, uno il layer dati, uno la suite di test. Ognuno restituisce una breve sintesi. Ottieni tre risposte nel tempo che impiegherebbe un passaggio sequenziale, e il contenuto grezzo dei file non tocca mai il tuo contesto principale.

N correzioni indipendenti. Un lotto di componenti ha bisogno della stessa modifica meccanica identica, e nessuno importa dall'altro. Lancia un subagent per componente, ognuno con un prompt autonomo: la modifica esatta, il file esatto, il controllo di accettazione esatto. Questo è il caso parallelo più pulito, nessun subagent deve sapere cosa ha fatto un altro.

Entrambi i pattern condividono un requisito facile da saltare e costoso quando lo salti: ogni prompt deve essere autonomo. Non ha la tua conversazione. Se il task dipende da una decisione presa tre messaggi fa, quella decisione va riformulata nel prompt, o il subagent farà con sicurezza la cosa sbagliata.

I modi di fallire che abbiamo davvero incontrato

Questa è la parte che la maggior parte delle guide salta, scritta da qualcuno che ha fatto girare un subagent due volte e ha funzionato. Noi ne facciamo girare ogni giorno, ed ecco cosa si rompe in pratica.

Agenti che riportano "fatto" senza aver fatto il lavoro. Un subagent torna con un riassunto pulito e sicuro: "Aggiornati i tre file, i test passano, pronto per il commit." Controlli, e un file è intatto. Non è il modello disonesto in senso deliberato, è il riassunto restituito che si allontana da ciò che è davvero successo, specialmente su task lunghi dove il resoconto dell'agente sul proprio lavoro finisce compresso. La correzione è banale e non negoziabile: verifica dall'artefatto, non dal resoconto. Leggi tu il diff. Esegui tu il test. Il riassunto di un subagent è un'affermazione, non una ricevuta.

Agenti che aspettano notifiche fantasma. Abbiamo avuto subagent che si fermano a metà task aspettando un callback o un segnale da un altro processo che non sarebbe mai arrivato, perché il meccanismo di coordinamento esisteva solo nell'immaginazione del prompt, non in qualcosa realmente collegato. La correzione è non progettare mai un prompt per subagent attorno a un evento che non hai verificato scattare davvero. Se il prossimo passo di un subagent dipende dall'output di un altro agente, dagli quell'output direttamente quando lo lanci, non chiedergli di rilevare un segnale di completamento che non hai costruito.

Entrambi i fallimenti risalgono alla stessa disciplina: un prompt che non si appoggia a contesto condiviso o a una notifica presunta è uno che un agente può davvero completare correttamente, e un risultato che controlli leggendo il file, non leggendo il resoconto dell'agente sul file, è l'unico modo per saperlo. Niente di tutto ciò è un argomento contro i subagent. È un argomento contro il fidarsi di un riassunto testuale come ti fideresti di un diff. Ne facciamo girare in continuazione. Solo non facciamo merge di nulla sulla loro parola soltanto.

Anche le skill funzionano dentro i subagent

Un subagent è comunque un'istanza Claude, quindi carica le skill nello stesso modo della tua sessione principale: abbinando il proprio task alle descrizioni delle skill installate e tirando dentro il corpo al trigger. Un subagent di code-review con la nostra skill checklist di code review installata ottiene lo stesso passaggio strutturato che avrebbe nel loop principale, limitato a qualsiasi diff tu gli abbia dato.

Questo si compone in modo pulito. Il subagent gestisce dove succede il lavoro, la skill gestisce come viene fatto. Nessuno dei due deve sapere dell'altro; si sommano automaticamente finché entrambi sono installati dove il subagent può vederli, skill di progetto in .claude/skills/, skill personali in ~/.claude/skills/. La nostra pagina migliori skill di coding classifica quelle che vale la pena installare prima di configurare un agente di revisione o ricerca.

Subagent vs hook vs skill

Tre meccanismi diversi, tre lavori diversi, e vengono confusi costantemente:

	Cosa fa	Scatta su	Gira dove
Skill	Insegna a Claude una procedura o uno stile	Claude che abbina la tua richiesta a una descrizione	Dentro il contesto attuale
Hook	Esegue un comando shell fisso automaticamente	Un evento del ciclo di vita (prima di una chiamata a strumento, dopo una risposta, inizio sessione)	Fuori dal modello, deterministico
Subagent	Delega un task a un'istanza Claude isolata	Una chiamata esplicita, tua o dell'agente principale	Una finestra di contesto separata

Una skill cambia come Claude affronta qualcosa che sta già per fare. Un hook applica qualcosa ogni volta, senza condizioni, senza chiedere al modello di ricordare: esegui i test dopo ogni modifica, blocca un commit se vengono rilevati segreti. Un subagent cambia dove succede il lavoro, spostandolo in una finestra usa-e-getta invece che nella tua principale. Copriamo gli hook in profondità, incluso lo stesso tipo di cicatrici sopra, nella nostra guida agli hook di Claude Code.

Si sommano. Una configurazione di team potrebbe usare un hook per fare lint dopo ogni scrittura, una skill per insegnare lo stile di codice di casa, e un subagent per eseguire il passaggio di revisione completo prima del merge, tre livelli, nessuno ridondante. Se stai ancora assemblando il resto della tua configurazione, la nostra guida di setup 2026 attraversa dove va ogni pezzo, e la nostra guida sui costi in token copre quanto costano tutti e tre a riposo.

FAQ

I subagent condividono il contesto della mia sessione principale?

No, ed è tutto il punto. Un subagent inizia con una cronologia vuota tranne il prompt che gli dai. Niente della tua conversazione principale passa automaticamente, e niente di ciò che il subagent legge o fa torna indietro tranne il testo finale che restituisce. Se ha bisogno di contesto dalla tua conversazione, mettilo nel prompt.

I subagent possono girare in parallelo?

Sì. Lanciarne diversi insieme è il pattern standard per ricerca a ventaglio e per correzioni indipendenti che non si sovrappongono. Ognuno ottiene la propria finestra di contesto, quindi non interferiscono tra loro, ma non possono nemmeno coordinarsi a metà task a meno che tu non abbia esplicitamente dato l'output di uno come input del prompt di un altro.

Come faccio a sapere se un subagent ha davvero fatto quello che ha dichiarato?

Controlla l'artefatto, non il riassunto. Leggi il diff, esegui il test, apri il file. Abbiamo avuto subagent che riportavano un successo pulito su lavoro parzialmente non fatto, non per disonestà ma perché un riassunto è una ricostruzione, e le ricostruzioni si allontanano dalla realtà. Tratta ogni resoconto di subagent come un'affermazione da verificare.

Dove vivono le definizioni di agenti personalizzati?

.claude/agents/*.md per agenti a livello di progetto che viaggiano con il repo tramite git, e ~/.claude/agents/*.md per quelli personali disponibili in ogni progetto. Ogni file ha bisogno di name e description nel frontmatter come minimo; tools e model sono opzionali ma vale la pena impostarli deliberatamente invece di lasciarli ai default.

Dovrei limitare quali strumenti può usare un subagent?

Sì, ogni volta che l'agente ha un lavoro ristretto. Un agente di revisione che non può chiamare Edit non può accidentalmente sistemare la cosa che dovrebbe criticare. Un agente di ricerca in sola lettura che non può chiamare Bash non può eseguire per errore qualcosa di distruttivo mentre esplora. Il campo tools nel frontmatter di un agente è il meccanismo, e impostarlo costa meno che fare debug di cosa ha fatto un agente troppo potente con il tempo che gli restava.