Subagenti di Claude Code: struttura, cinque ruoli e orchestrazione

Che cos’è un subagente in Claude Code e perché non è «solo un’altra Skill»?#

La documentazione di Claude Code lo definisce così:

Per dirlo in termini comprensibili a un imprenditore: immagina un’agenzia immobiliare. Ci sono un direttore, un addetto al marketing, un avvocato e i responsabili delle vendite. Un dipendente che passa da un ruolo all’altro non è un team: è una persona sovraccarica. Un team si forma quando ogni persona ha il proprio contesto e ambito di responsabilità, mentre il direttore assegna le attività e mette insieme i risultati.

I subagenti in Claude Code funzionano allo stesso modo. La chat principale è il direttore. Un subagente è uno specialista con un’attività circoscritta, il proprio contesto e un insieme di strumenti. Quando un’attività corrisponde alla descrizione di uno specialista, il direttore gliela delega e non si perde nei dettagli.

5 obiettivi per cui Anthropic ha creato i subagenti

La documentazione di Anthropic elenca esattamente cinque ragioni per creare un proprio subagente:

Per chi non è programmatore, l’elemento più pratico di questo elenco è il controllo dei costi. Puoi affidare un’attività di ricerca impegnativa al modello Haiku, più economico, e continuare la conversazione principale con Sonnet o Opus. Il risparmio di token è direttamente proporzionale.

Verifica il supporto all’annidamento nella versione installata

I modelli qui usano una sessione principale che delega direttamente ai lavoratori. Non trattare come legge permanente la vecchia documentazione secondo cui i subagenti non ne avviano altri: l’annidamento dipende da versione e strumenti consentiti. La guida separata sui subagenti annidati tratta una ricetta specifica per versione. Verifica il supporto prima di progettare livelli ulteriori.

In cosa differisce un subagente da una Skill, da un comando slash e da un hook?#

La guida precedente sulle Skills spiega che skills e comandi slash in Claude Code sono di fatto confluiti in un unico formato. Ma un subagente è un’entità diversa, non semplicemente «una Skill più grande».

Tabella riassuntiva dei quattro meccanismi:

Un buon modo per dirlo in una guida in inglese: le Skills sono ricette; i subagenti sono colleghi specializzati.

Put simply: le competenze sono ricette; i subagenti sono come colleghi specializzati.

In pratica funziona così: le Skills si attivano automaticamente quando la loro descrizione corrisponde all’attività, mentre i subagenti vengono richiamati esplicitamente: la chat principale decide di delegare oppure tu ne richiami uno per nome.

Albero decisionale: «Quale dovrei scegliere?»

Quando pensi «mi serve che Claude faccia X», passa in rassegna queste quattro domande:

1. È una conoscenza che dovrebbe essere sempre disponibile? Per esempio: «localizziamo nella lingua preferita dall’utente» oppure «non usiamo i trattini lunghi». Inseriscila in CLAUDE.md.
2. È una metodologia che si attiva e che ora esegui manualmente? Per esempio: «scrivo un rapporto vendite ogni lunedì». Crea una Skill.
3. È un’attività che consumerà il contesto della chat principale o che può essere eseguita in parallelo? Per esempio: «ricerca approfondita su 30 fonti» oppure «audit di sicurezza mentre scrivo una nuova funzionalità». Crea un subagente.
4. Ti serve una risposta automatica a un evento in Claude Code? Per esempio: «esegui il linter dopo ogni Edit». Scrivi un hook.

Il 90% delle attività di un imprenditore rientra nelle prime due categorie. I subagenti sono uno strumento di livello superiore, per quando si passa da «un’attività alla volta» all’orchestrazione.

Dove si trovano i subagenti e quale ha la precedenza?#

La gerarchia dei subagenti ha cinque livelli, ordinati dal più alto al più basso:

La logica delle priorità è la stessa di Skills e CLAUDE.md: l’organizzazione prevale sulla CLI, la CLI sul progetto, il progetto sulle impostazioni personali e queste ultime sul plugin.

Cosa sapere sul caricamento

I subagenti vengono caricati all’avvio di una sessione di Claude Code. Se modifichi manualmente un file agente sul disco, le modifiche non verranno recepite fino al riavvio della sessione. Le modifiche effettuate dall’interfaccia interattiva /agents si applicano subito.

Un subagente per ambito significa un file. Se .claude/agents/ contiene code-reviewer.md e un altro code-reviewer.md accanto (per esempio da un vecchio backup), Claude Code ne ignorerà uno in silenzio. Non verrà mostrata alcuna notifica.

I subagenti dei plugin sono un caso a parte. Hanno restrizioni di sicurezza: non supportano i campi hooks, mcpServers e permissionMode. In questo modo si impedisce che l’installazione di un plugin di terze parti gli conceda il permesso di eseguire codice arbitrario sulla tua macchina.

Struttura di un file subagente: frontmatter e corpo#

Un esempio minimo dalla documentazione ufficiale, di sole 9 righe:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

È sufficiente. Se un utente dice «esamina la mia PR» nella chat principale, Claude abbina «revisore / codice / qualità» alla descrizione e delega al subagente. Il subagente legge il diff, produce commenti e restituisce un riepilogo alla chat principale. Quest’ultima non viene appesantita da log e analisi intermedie.

Schema completo del frontmatter

Il campo model: haiku è proprio quell’«controllo dei costi» tra i cinque obiettivi. Se hai un agente di ricerca che legge 50 pagine di documentazione, eseguilo con Haiku per risparmiare da 5 a 7 volte rispetto a Opus.

Il campo isolation: worktree affronta un problema importante: un subagente apporta modifiche potenzialmente pericolose (refactoring, migrazioni), ma non vuoi che tocchi la tua copia di lavoro. Imposta isolation: worktree e Claude Code crea una copia temporanea git del progetto; il subagente ci lavora e restituisce un diff da esaminare.

Il corpo del file è il prompt di sistema

Dopo il frontmatter viene il normale Markdown, cioè il prompt di sistema del subagente. Non è richiesta una struttura speciale, ma questo è un modello collaudato:

1. Chi sei: una frase: «sei un revisore del codice», «sei un auditor di sicurezza», «sei un curatore della documentazione».
2. Quando vieni invocato e cosa fai per prima cosa: le prime 2–3 azioni dopo aver ricevuto l’attività.
3. Una lista di controllo di verifiche o passaggi: 5–10 punti da seguire.
4. Cosa restituisci: il formato del rapporto finale. È fondamentale: se non specifichi un formato, il subagente produrrà un «tema» invece di un riepilogo strutturato.
5. Cosa NON fai: limiti espliciti. Senza questa sezione, il subagente finisce per improvvisare.

Mantieni il corpo del file tra 200 e 500 righe. Se diventa più lungo, sposta i riferimenti estesi in file vicini separati e inserisci nel prompt un collegamento a essi.

Come scrivere una descrizione perché Claude richiami sicuramente il tuo subagente#

Un problema comune è configurare un subagente per la revisione del codice e poi vedere Claude fare tutto da solo senza usare l’agente. Di solito c’è un’unica ragione: la descrizione è scritta come «Assistente per la revisione del codice». Claude non capisce quando attivarlo.

Formula per una descrizione efficace (3 parti)

Parte 1 — cosa fa. Una frase sul risultato, non sul processo. Non «analizza il codice», ma «individua le vulnerabilità nel codice e restituisce un elenco con gravità e correzione».

Parte 2 — quando attivarlo. 3–5 frasi tra virgolette, formulate come le richieste effettive degli utenti. Non indovinare: guarda la cronologia delle tue chat e le formulazioni reali.

Parte 3 — quando NON attivarlo. 1–2 frasi su attività simili a cui questo subagente non dovrebbe rispondere. Senza questa sezione, due agenti simili entrano costantemente in conflitto.

La frase magica «Use Proactively»

La documentazione ufficiale di Anthropic dà una raccomandazione diretta:

In altre parole, se la descrizione non contiene segnali chiari, per impostazione predefinita Claude tende a non richiamare un subagente. Aggiungi «use proactively» o «use immediately after writing code» e l’attivazione aumenta nettamente.

Ecco come appare una descrizione efficace

description: |
  Specialista esperto nella revisione del codice. Esamina proattivamente il codice in termini di qualità,
  sicurezza e manutenibilità. Da usare immediatamente dopo aver scritto o
  modificato codice. Restituisce un elenco prioritario di problemi con gravità
  e consigli per la correzione.
  Non invocare per modifiche alla documentazione, modifiche al README o riscritture dei messaggi di commit: se ne occupa doc-maintainer.

Cosa funziona qui:

• I verbi «esamina» + «restituisce» indicano un risultato concreto, non un processo.
• «Proattivamente» e «immediatamente dopo» sono criteri di attivazione espliciti.
• «Non invocare per...» evita il conflitto con un subagente simile.
• L’inglese nella descrizione è standard. Claude abbina meglio in inglese.

5 ruoli di subagente pronti all’uso in 10 minuti#

Ogni ruolo riportato sotto è un singolo file, .claude/agents/<name>.md. Dopo aver creato il file, riavvia Claude Code, apri /agents e verifica che il nuovo agente compaia nell’elenco. Poi puoi richiamarlo con @agent-name.

1. code-reviewer — esamina il codice dopo ogni modifica

Questo è l’esempio ufficiale della documentazione di Anthropic, adattato a un flusso di lavoro:

---
name: code-reviewer
description: |
  Specialista esperto nella revisione del codice. Esamina proattivamente il codice in termini di qualità,
  sicurezza e manutenibilità. Da usare immediatamente dopo aver scritto o
  modificato codice.
tools: Read, Grep, Glob
model: inherit
color: blue
---

Sei un revisore senior del codice e garantisci elevati standard di qualità.

Quando vieni invocato:
1. Leggi diff ed elenco dei file forniti dalla sessione principale. Se mancano, chiedili.
2. Usa Read, Grep e Glob per esaminare i file pertinenti.
3. Restituisci risultati senza cambiare file o eseguire comandi shell.

Elenco di controllo della revisione:
- Il codice è chiaro e leggibile
- Funzioni e variabili hanno nomi appropriati
- Non c’è codice duplicato
- Gestione degli errori adeguata
- Nessun segreto o chiave API esposti
- Convalida dell’input implementata
- Copertura dei test adeguata
- Aspetti prestazionali considerati

Fornisci un riscontro organizzato per priorità:
- Problemi critici (da correggere prima del merge)
- Avvertenze (da correggere)
- Suggerimenti (miglioramenti da considerare)

Formato: per ogni problema, file:linea + 1 frase sul perché costituisce un problema + correzione concreta.

L’elemento chiave è tools: Read, Grep, Glob: lettura e ricerca, senza Bash, Write o Edit. La sessione principale prepara e consegna il diff. Limitarsi a scrivere «esegui solo git diff» non restringe uno strumento Bash pienamente concesso.

2. security-auditor — individua vulnerabilità e fughe di dati

Il ruolo usa opus per ragionamento approfondito e la stessa restrizione Read, Grep e Glob. La memoria persistente è omessa dal modello in sola lettura perché abilitarla aggiunge capacità di scrittura nella memoria:

---
name: security-auditor
description: |
  Specialista di audit della sicurezza. Usalo proattivamente per trovare vulnerabilità OWASP Top 10,
  segreti esposti, rischi di injection e problemi di autenticazione.
  Esegui prima di qualsiasi deploy o merge in main.
tools: Read, Grep, Glob
model: opus
color: red
---

Sei un auditor di sicurezza. Individua vulnerabilità sfruttabili, non problemi di stile.

Elenco di controllo dell’audit:
- Injection SQL / NoSQL
- XSS (stored, reflected, basata su DOM)
- Rischi CSRF / SSRF
- Segreti hardcoded (chiavi API, token, password)
- Autenticazione o gestione delle sessioni non sicure
- Deserializzazione non sicura
- Mancata convalida dell’input
- Path traversal
- Reindirizzamenti aperti
- Riferimenti diretti a oggetti non sicuri (IDOR)

Per ogni rilievo:
- Gravità: Critical / High / Medium / Low
- File:linea
- Scenario di attacco in 1–2 frasi
- Consiglio per la correzione con esempio di codice

Ignora il rumore del linter e le questioni di stile. Segnala solo problemi sfruttabili.

Sola lettura quanto agli strumenti, con model: opus per verifiche complesse come le catene di vulnerabilità.

3. research-agent — ricerca approfondita su 8 o più fonti

Questo modello è descritto da Anthropic stessa nell’articolo sul sistema di ricerca multiagente. L’elemento chiave è un formato di output esplicito e il divieto di riversare risultati grezzi:

---
name: research-agent
description: |
  Specialista di ricerca approfondita sul web. Usalo proattivamente per accertare i fatti,
  svolgere analisi della concorrenza e raccogliere documentazione esterna, confrontare
  approcci su più fonti.
tools: WebFetch, WebSearch, Read, Write
model: sonnet
maxTurns: 30
color: purple
---

Sei un analista di ricerca. Obiettivo: una sintesi, non risultati di ricerca grezzi.

Procedura:
1. Scomponi la domanda in 3–5 sottoquery
2. Esegui WebSearch per ciascuna sottoquery e recupera le prime 3–5 fonti per sottoquery
3. Verifica le affermazioni confrontando almeno 2 fonti indipendenti
4. Escludi contenuti di siti SEO e aggregatori; privilegia le fonti primarie
5. Cita testualmente con attribuzione e URL ogni affermazione specifica
6. Restituisci: TL;DR (3 punti) + Risultati + Fonti (almeno 8 domini)

Antimodelli da evitare:
- Non citare un fatto basandoti su una sola fonte
- Non parafrasare citazioni spacciandole per testuali
- Non restituire al genitore risultati di ricerca grezzi
- Non includere introduzioni o conclusioni riempitive («Spero che sia utile»)

maxTurns: 30 è una protezione per evitare che la ricerca prosegua all’infinito. Anthropic riporta questa cifra nel suo sistema multiagente:

Il novanta percento si riferisce ad attività di benchmark sulla ricerca. Nelle attività aziendali il guadagno è minore, ma l’ordine di grandezza è simile.

4. doc-maintainer — mantiene la documentazione sincronizzata con il codice

Questo ruolo usa model: haiku, un esempio tipico di «controllo dei costi». Per la documentazione non serve Opus; Haiku svolge il lavoro a un terzo del prezzo:

---
name: doc-maintainer
description: |
  Specialista nella sincronizzazione della documentazione. Dopo il merge delle funzionalità, aggiorna
  README, documentazione API, CHANGELOG. Legge i commit recenti, individua
  le modifiche non documentate e aggiorna proattivamente la documentazione.
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
memory: project
color: green
---

Mantieni la documentazione sincronizzata con il codice.

Quando vieni invocato:
1. Esegui `git log --since="last release"` per vedere le modifiche recenti
2. Leggi README.md, docs/, CHANGELOG.md
3. Individua le lacune: nuove funzionalità senza documentazione, API rimosse ancora documentate, discrepanze di versione

Output:
- File aggiornati (usa Edit, non Write: preserva la struttura esistente)
- Voce in CHANGELOG.md nel formato Keep-A-Changelog
- Elenco delle modifiche apportate (riepilogo del diff effettivo, non una parafrasi)

Regole di stile:
- Forma attiva, tempo presente
- Gli esempi di codice devono poter essere copiati e incollati
- Niente linguaggio di marketing («potente», «robusto», «senza interruzioni»)
- Niente frasi riempitive («Questa guida ti sarà utile per...»)

5. refactor-agent — refactoring sicuro tramite un worktree

Questo ruolo usa isolation: worktree: il subagente lavora in una copia separata del repository e fai il merge solo se va tutto bene:

---
name: refactor-agent
description: |
  Specialista di refactoring sicuro. Usalo per rinominare, estrarre o incorporare elementi
  senza toccare la copia di lavoro prima della revisione. Opera in un
  worktree git temporaneo.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
isolation: worktree
permissionMode: acceptEdits
color: yellow
---

Fai refactoring del codice senza cambiarne il comportamento.

Regole rigorose:
1. I test devono passare PRIMA e DOPO il refactoring.
   Se i test non passano prima del refactoring, FERMATI e segnala il problema.
2. Un solo refactoring atomico per commit (estrazione, rinomina, incorporamento).
3. Non modificare mai le API pubbliche senza istruzioni esplicite.
4. Non modificare i test, a meno che non verifichino direttamente l’implementazione sottoposta a refactoring.

Procedura:
- Esegui la suite di test -> baseline
- Esegui un refactoring atomico
- Esegui la suite di test -> verifica
- Crea un commit con un messaggio convenzionale: refactor(scope): cosa

Restituisci: riepilogo delle modifiche + percorso del worktree affinché l’utente possa confrontare e fare il merge.

Con questo ruolo scompare il problema più frustrante del refactoring, cioè «l’ho rotto e non so come tornare indietro»: la copia originale rimane intatta e il subagente lavora in un worktree isolato.

Vuoi non solo copiare subagenti già pronti, ma assemblare una combinazione che renda Claude uno strumento stabile? I subagenti fanno parte del tuo clone AI: un modo per dare a Claude un team specializzato che lavora secondo la tua logica. I tre pilastri della metodologia sono: clone AI (Skills + subagenti) + Second Brain + Ingegneria del contesto. Questa combinazione trasforma Claude da assistente che tira a indovinare in uno strumento che ragiona secondo la tua logica.

Avviare 5 subagenti in parallelo: orchestratore e operatori#

L’orchestrazione parallela è un’organizzazione «direttore d’orchestra + orchestra». Il direttore mantiene il piano, non scrive le note e verifica ciò che suonano i musicisti. Se qualcuno stona, il direttore gli chiede di riprovare invece di finire al suo posto.

Per un imprenditore, un’analogia più vicina è un’agenzia di marketing che prepara una strategia per un nuovo cliente. Un analista fa un’analisi SWOT, un altro analizza la concorrenza, un terzo crea il profilo del pubblico, un analista senior scarta le ipotesi incompatibili con il budget e il project manager assembla la presentazione finale. In Claude Code, questa pipeline parte da una frase e include il revisore nel processo, invece di farlo intervenire a posteriori.

Prompt minimo di orchestrazione

Basta una frase nella chat principale:

Avvia cinque subagenti in parallelo: tre research-agents su fonti diverse
(documentazione Anthropic, repository GitHub, blogger di AI), un critic-agent per filtrare
le conclusioni deboli e un summary-agent per il documento finale.

Contesto: sto scrivendo una guida su X. Lunghezza prevista: 2,000 parole con fonti.
Prima di iniziare, ciascuno legge CLAUDE.md.

Claude delega quindi ai cinque agenti. Ognuno lavora nel proprio contesto: gli agenti di ricerca consultano le rispettive fonti, il revisore filtra e l’agente di riepilogo assembla. Alla chat principale tornano solo i riepiloghi finali.

Quando conviene il parallelismo

Non sempre. L’esecuzione parallela ha senso solo se:

1. Le attività sono indipendenti. Se il research-agent #2 aspetta il risultato del research-agent #1, non c’è parallelismo: di fatto lavoreranno in sequenza.
2. Le attività durano a lungo. Parallelizzare «rimuovi gli spazi finali» è inutile: il costo di avvio dei subagenti annullerà il vantaggio.
3. Hai limiti sufficienti. Se ne parla più avanti in una sezione apposita: i subagenti paralleli consumano token rapidamente.

Multi-Agent v2 di Anthropic: un passo in più

Nel maggio 2026, Anthropic ha rilasciato Multi-Agent Orchestration v2 con tre differenze importanti rispetto all’approccio classico di avvio di subagenti paralleli. Se ne parla nella sezione successiva.

Novità di Multi-Agent v2: Orchestration, Outcomes, Dreaming#

Multi-Agent Orchestration: filesystem condiviso + verifiche durante il flusso di lavoro

Anthropic descrive la funzionalità così:

La differenza principale rispetto ai subagenti classici è il filesystem condiviso. Prima ogni subagente lavorava in completo isolamento e lo scambio avveniva solo attraverso il riepilogo restituito. Ora gli specialisti possono scrivere in una cartella condivisa e l’agente principale legge i risultati man mano che il lavoro procede, non solo alla fine. Questo risolve il problema di «tutti hanno lavorato tutto il giorno e alla fine si è scoperto che due persone seguivano approcci incompatibili».

La seconda novità sono le verifiche durante il flusso di lavoro. L’agente principale può fermarsi e chiedere a uno specialista «come procede?», quindi modificare il piano generale. È simile al modo in cui lavora un vero responsabile di team.

Outcomes: una rubrica invece di istruzioni passo passo

Con Outcomes, scrivi i criteri di successo e l’agente trova il modo di soddisfarli. Un valutatore separato verifica il risultato nel proprio contesto, così non viene «contaminato» dal ragionamento dell’agente principale.

Il dieci percento sulle attività impegnative è un miglioramento notevole. Soprattutto se un’attività è formulata come «assembla un articolo lungo che soddisfi questi criteri di qualità», invece di «segui i passaggi da 1 a 7».

Dreaming: gli agenti accumulano esperienza tra una sessione e l’altra

Questa è la funzionalità concettualmente più nuova. Un agente esamina le sessioni passate, individua schemi nei successi e negli errori e aggiorna l’archivio della memoria. Puoi configurare una revisione manuale prima di applicare le modifiche oppure lasciargli modificare la memoria direttamente.

Anthropic riferisce che Harvey, un’azienda di tecnologia legale, ha registrato un aumento di circa sei volte del successo nelle attività di redazione legale dopo aver implementato Dreaming. Funziona già in produzione, non solo in una demo.

Cosa significa per gli imprenditori che non programmano

Multi-Agent Orchestration è attualmente disponibile tramite Claude Agent SDK, non direttamente nella CLI di Claude Code. Ma la direzione è chiara: l’orchestrazione passa da «avvii manualmente N subagenti» a «descrivi l’attività e l’agente principale decide a chi delegare e come». Se hai appena iniziato con i subagenti, per ora non preoccuparti di v2. Impara il modello classico «1 chat principale + 3–5 subagenti con ruoli diversi» e, tra 3–6 mesi, potrai passare naturalmente a Managed Agents.

7 errori che fanno arenare i subagenti#

Errore 1. Le descrizioni «Assistente per X» non attivano nulla

Sintomo: hai scritto un subagente, controllato la struttura e tutto è valido, ma Claude non lo richiama per le richieste degli utenti. La ragione è quasi sempre la stessa: la descrizione è astratta, per esempio «Assistente per la revisione del codice». La soluzione: scrivi 3–5 frasi reali degli utenti tra virgolette direttamente nella descrizione e aggiungi «use proactively» / «use immediately after».

Errore 2. Creare un subagente quando serve una Skill

Un subagente costa più di una Skill: crea un proprio contesto, carica il proprio prompt di sistema e usa più token. Se l’attività è breve, non consumerà il contesto principale e si può svolgere in un solo passaggio, dovrebbe essere una Skill, non un subagente. Un esempio di antimodello: un subagente format-validator che verifica uno schema JSON rispetto a 20 regole. Dovrebbe essere una Skill: un solo modello, nessun isolamento necessario, nessun contesto aggiuntivo da caricare.

Errore 3. Avviare subito «60 agenti paralleli»

È l’illusione più diffusa. Vedi un tweet che dice «ho 1,500 agenti al lavoro» e pensi «dovrei farlo anch’io». In pratica, 60 agenti consumano i limiti di un piano Pro in un’ora, generano un mucchio di risultati contraddittori e alla fine della giornata non hai concluso nulla.

Un professionista su Medium la mette così:

La soluzione: inizia con un subagente per un’attività. Dopo aver imparato a usarlo, aggiungine un secondo con un ruolo diverso. Dopo aver imparato a orchestrarne due, passa a un team di 3–5. Passare da «ho installato Claude Code ieri» a «20 in parallelo oggi» finirà sicuramente per rompere il codice e consumare i limiti.

Errore 4. Dare a ogni agente accesso a tutti gli strumenti

Se il revisore del codice può usare Bash, Write e WebFetch, si crea una grave falla di sicurezza e di costo. Un revisore non dovrebbe avere il permesso di scrivere file, né tanto meno di accedere a Internet.

La soluzione: limita rigorosamente tools. Un revisore del codice riceve solo Read, Grep, Glob. Un auditor riceve gli stessi strumenti di lettura/ricerca e un diff dalla sessione principale. Aggiungere Bash concede la shell senza limitarla automaticamente a git diff. Un agente di ricerca riceve WebFetch, WebSearch, Read, Write. Non concedere a un subagente più autorizzazioni di quante gliene servano per una specifica attività.

Errore 5. Un subagente riversa risultati grezzi nel contesto principale

Se un agente di ricerca risponde «ecco tutte le 30 pagine che ho trovato; vedi tu» nella chat principale, hai perso il vantaggio principale dei subagenti: isolare il rumore. La soluzione: richiedi esplicitamente un formato di output nel prompt di sistema del subagente. «Restituisci SOLO: TL;DR in 3 punti + elenco di 5 fonti. NESSUN dump di codice, NESSUN risultato di ricerca grezzo». Il formato deve essere rigoroso: il subagente non deve poter «trasformarlo in un tema».

Errore 6. Richieste vaghe: istruzioni di delega poco chiare

Un subagente non può vedere la cronologia della conversazione principale. Parte con un contesto pulito + CLAUDE.md + ciò che gli hai scritto esplicitamente. Se scrivi «correggi l’autenticazione», il subagente si inventerà delle cose. Invece: «Correggi il ciclo di reindirizzamento OAuth per cui, dopo un accesso riuscito, l’utente viene reindirizzato a /login invece che a /dashboard. File: src/lib/auth.ts».

Una regola chiara: quando deleghi, dai al subagente lo stesso contesto che daresti a un nuovo collaboratore appena entrato nel progetto.

Errore 7. Agenti basati sui ruoli anziché sulle attività

Un modello allettante è: «creiamo un frontend-developer, un backend-developer e un qa-engineer e facciamoli lavorare in team». Non funziona. Ogni «ruolo» perde il contesto del progetto nel suo insieme e non riescono a concordare i dettagli perché non possono vedersi tra loro.

La soluzione: un subagente dovrebbe gestire un’attività ricorrente con un risultato chiaro, non un ruolo. Non «frontend-developer», ma «explore-ui-tree», «refactor-component», «audit-accessibility». Ogni subagente basato su un’attività svolge un compito specifico e restituisce un risultato specifico.

Quanto costano i subagenti paralleli e quando convengono?#

Un piano Pro si esaurirà entro un’ora se avvii 5 subagenti paralleli per attività complesse. Max 5x ($100) è il minimo realistico per un uso regolare del lavoro parallelo. Per i team e le aziende, la questione economica è già gestita a livello del budget per gli strumenti.

Per saperne di più su come risparmiare token in Claude Code, consulta la guida separata sui limiti. Per i subagenti, la regola fondamentale è che convengono per un’attività che richiede almeno 10 minuti di lavoro concentrato. Se è più breve, non creare un subagente: svolgila nella chat principale o con una Skill.

Come integrare i subagenti nel tuo clone AI e Second Brain?#

Prima di creare il tuo primo specialista, nel progetto dovrebbero essere presenti tre elementi su cui si baserà il subagente:

1. Il giusto CLAUDE.md. Un subagente legge CLAUDE.md prima di iniziare: è il suo «contratto di lavoro». Senza, non conosce il contesto del progetto, i suoi vincoli o il suo tono. Si inventerà le cose.

2. Le Skills di base. Una Skill è una metodologia raccolta in un pacchetto. Un subagente carica solo le Skills necessarie, non tutte insieme. Senza Skills, ripete ogni volta lo stesso lavoro da zero.

3. Second Brain: una struttura della conoscenza. La cartella business/ (o l’equivalente nel tuo settore) è una biblioteca consultata da tutti i subagenti. Senza, un subagente dà una risposta media da ChatGPT, indistinguibile da quella di chiunque altro.

Invertire quest’ordine significa ottenere entusiasmo senza risultati. «Ho 60 subagenti paralleli» con una cartella business/ vuota significa avere 60 sessioni di ChatGPT mediocri con lo stesso approccio.

La combinazione completa, clone AI + Second Brain + Ingegneria del contesto, è costituita dai tre pilastri che rendono Claude coerente. I subagenti fanno parte del clone AI: un modo per dare a Claude un team specializzato che lavora secondo la tua logica.

Il modo più rapido per iniziare è copiare code-reviewer dal primo esempio qui sopra in .claude/agents/code-reviewer.md, riavviare Claude Code e richiamarlo con @agent-code-reviewer al tuo prossimo commit. In 5 minuti capirai se hai bisogno di subagenti o se basta la chat principale.