Subagent di Claude Code: Cosa Abbiamo Imparato Gestendone 18 in Produzione

Subagent di Claude Code: Cosa Abbiamo Imparato Gestendone 18 in Produzione

Diciotto subagent Claude Code pubblicano ogni post di questo sito, incluso questo. Sei girano su Opus, undici su Sonnet, uno su Haiku. Il subagent researcher da solo ha accumulato 74 file di memoria da quando abbiamo iniziato. Nessuno di loro parla con gli altri. Questo è ciò che ci ha sorpreso di più: un subagent non vede mai la tua conversazione, e non vede nemmeno la conversazione di un altro subagent. Così l'intera pipeline è costruita attorno a file su disco. Ecco la fleet, lo split dei modelli, il setup della memoria, e le cose che si sono rotte lungo la strada.

La versione breve:

• Un subagent gira nella propria context window, con un system prompt, tool e permessi propri.
• Ne gestiamo 18: 6 su Opus, 11 su Sonnet, 1 su Haiku.
• Gli agent si passano il lavoro tramite file su disco, mai tramite un contesto condiviso.
• Da v2.1.198 il wizard di creazione /agents non c'è più. Scrivi il file da solo.

Cos'è un Subagent di Claude Code?

Un subagent di Claude Code è un assistente specializzato che gira nella propria context window, con un system prompt personalizzato, un accesso specifico ai tool e permessi indipendenti. Svolge un task secondario senza intasare la tua conversazione principale, e restituisce solo il proprio riepilogo. Le definizioni vivono come file Markdown con frontmatter YAML in .claude/agents/, documentate nel riferimento sui subagent di Anthropic.

Claude delega automaticamente a uno di loro. Legge il campo description di ogni subagent che riesce a vedere, e quando un task corrisponde, passa il lavoro senza chiedertelo prima. Da v2.1.198 questi subagent girano in background di default, quindi la delega spesso avviene mentre continui a scrivere. Puoi anche chiamarne uno per nome quando vuoi un worker specifico su un task specifico.

Claude Code include tre subagent predefiniti: Explore per la ricerca in sola lettura nel codebase, Plan per il lavoro di pianificazione, e general-purpose per tutto il resto.

Un dettaglio di naming che mette in difficoltà guide e file di config più vecchi: il tool che genera un subagent si chiama Agent, non Task. È stato rinominato in v2.1.63, e la documentazione conferma che i riferimenti a Task(...) esistenti continuano a funzionare come alias. In questo post usiamo Agent.

Il resto di questo articolo non è un riferimento tecnico. La documentazione di Anthropic fa già questo lavoro meglio di quanto potremmo fare noi, con circa 8.000 parole e annotazioni di versione che arrivano fino a v2.1.212. Quello che segue è come si comportano diciotto di questi subagent quando girano ogni giorno.

La Nostra Fleet di 18 Agent: Come Appare un Setup Reale su Disco

La nostra directory .claude/agents/ contiene 18 file di definizione dei subagent, ciascuno un file Markdown con frontmatter YAML. Insieme gestiscono l'intera pipeline di contenuti di questo sito: ricerca, brief, scrittura, validazione, traduzione in nove lingue, generazione immagini e pubblicazione. Sei girano su Opus, undici su Sonnet, uno su Haiku.

Ogni guida sui subagent nella prima pagina di Google usa lo stesso esempio code-reviewer copiato dalla documentazione. Ecco come si comportano diciotto di questi subagent quando spediscono davvero del lavoro.

.claude/agents/
├── abc-link-checker.md
├── brief-creator.md
├── content-gap-finder.md
├── content-refresher.md
├── content-writer.md
├── image-handler.md
├── language-translator.md
├── payload-publisher.md
├── pipeline-manager.md
├── rank-checker.md
├── rescue-diagnoser.md
├── rescue-prioritizer.md
├── researcher.md
├── sanity-publisher.md
├── seo-auditor.md
├── sitemap-checker.md
├── translation-coordinator.md
└── validator.md

Si raggruppano in quattro aree. La produzione di contenuti passa da researcher a brief-creator a content-writer a validator. La distribuzione copre translation-coordinator, language-translator, image-handler, payload-publisher e sanity-publisher. La manutenzione è affidata a content-refresher, rank-checker, rescue-diagnoser, rescue-prioritizer, seo-auditor, sitemap-checker e abc-link-checker. Il coordinamento è pipeline-manager e content-gap-finder.

Due di questi file, copiati alla lettera dal disco, portano da soli tutto l'argomento sui costi:

# .claude/agents/researcher.md
name: researcher
tools: Read, Write, Glob, Grep, WebSearch, WebFetch, Bash
model: opus
memory: project
skills:
  - seo
  - competitor-analysis

# .claude/agents/sitemap-checker.md
name: sitemap-checker
tools: Read, Write, Edit, Glob, Grep, WebFetch
model: haiku

Stesso meccanismo, circa dieci volte il costo per token. Uno è un agent Opus con accesso al web e memoria persistente che decide cosa deve sostenere un post. L'altro è un agent Haiku che scarica una sitemap e scrive un file JSON. Niente nel formato dei subagent ti obbliga a pagare le tariffe di Opus per il secondo lavoro, eppure la maggior parte delle fleet che abbiamo visto fa esattamente questo di default.

Il campo skills: di researcher precarica due definizioni di skill nel system prompt di quel subagent al momento dello spawn, ed è così che conosce le nostre convenzioni SEO senza che gli venga detto ogni volta. Se non ne hai ancora scritto uno, abbiamo trattato come scrivere uno skill Claude separatamente, e questo post non lo ripete.

Se vuoi un catalogo consultabile di definizioni da cui copiare, la raccolta community awesome-claude-code-subagents è quella che le persone cercano davvero. Leggila per la forma, non per l'aggiornamento: alcune voci sono precedenti al rename di Agent.

Come Si Crea un Subagent? (Il Wizard /agents Non C'è Più)

Crei un subagent Claude Code scrivendo tu stesso un file Markdown in .claude/agents/, oppure chiedendo a Claude di scriverlo per te. Da v2.1.198 il comando /agents non apre più il wizard di creazione interattivo. Eseguirlo ora stampa solo un promemoria che ti rimanda alla directory.

1. Crea il file. .claude/agents/{name}.md per un subagent di progetto che finisce nel version control, oppure ~/.claude/agents/{name}.md per uno che ti segue tra i progetti.
2. Scrivi name e description. La description conta più di ogni altra cosa nel file, perché è ciò a cui Claude fa corrispondere il task quando decide se delegare. Scrivila come una regola di instradamento, non come un titolo di lavoro.
3. Imposta tools e model. tools è una allowlist; ometterlo fa sì che il subagent erediti i tool della conversazione principale. model sovrascrive il modello della tua sessione.
4. Scrivi il system prompt come corpo Markdown sotto il frontmatter. I subagent ricevono solo questo prompt più alcuni dettagli di base sull'ambiente, non l'intero system prompt di Claude Code.
5. Invocalo. Automaticamente, lasciando che la description corrisponda, oppure esplicitamente chiedendolo per nome.

---
name: changelog-writer
description: Writes release notes from merged pull requests. Use when the user asks for a changelog, release notes, or a summary of what shipped.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You write release notes. Read the merged PRs since the last tag with `git log`,
group them into Added / Changed / Fixed, and write one line per change in past
tense. Never invent a change that is not in the log. Return only the markdown.

Diverse guide attualmente ben posizionate dicono ancora ai lettori di eseguire /agents per aprire l'interfaccia di gestione. Quell'istruzione è morta. Un'altra insidia su cui la documentazione è esplicita: il file watcher copre solo le directory che esistevano già all'avvio della sessione, quindi il primo file agent in una directory agents/ appena creata richiede un riavvio di Claude Code prima di essere caricato.

Subagent vs Skill vs Agent Team vs Fork: Di Quale Hai Davvero Bisogno?

Scegli un subagent quando un task secondario intaserebbe la tua conversazione principale e ti serve solo il riepilogo. Scegli uno skill quando vuoi insegnare a Claude una procedura che gira dentro il tuo contesto esistente. Scegli un agent team quando i worker devono coordinarsi tra loro. Scegli un fork quando il task secondario ha bisogno della cronologia della tua conversazione.

I subagent riportano a te e mai gli uni agli altri. Gli agent team si scambiano messaggi direttamente tra loro. Questa singola differenza decide di quale primitiva hai bisogno.

Il nostro default è il subagent, e non abbiamo mai avuto bisogno di un team. Il coordinamento nella nostra pipeline è sequenziale, non conversazionale, quindi una task list condivisa non porterebbe nulla e costerebbe solo token. I team sono anche ancora sperimentali e disattivati di default, il che è uno stop assoluto per tutto ciò che facciamo girare senza supervisione. Gli skill stanno su un livello del tutto diverso: sono istruzioni caricate in qualsiasi contesto già in esecuzione, incluso quello di un subagent, ed è per questo che researcher ne dichiara due invece di delegarli.

Scelta del Modello: Quali Agent Vanno su Haiku, Sonnet e Opus

Imposta model nel frontmatter di un subagent su haiku, sonnet, opus, o un ID di modello specifico, e quel subagent sovrascrive il modello della tua sessione. La nostra distribuzione reale su 18 agent è sei su Opus, undici su Sonnet, uno su Haiku, assegnata in base a quanto giudizio richiede davvero l'output dell'agent.

Tre regole che daremmo a chiunque debba organizzare i livelli di una fleet. Metti un agent su Haiku quando il suo output è deterministico e il suo input è piccolo: scaricare, fare parsing, contare, riformattare. Metti un agent su Sonnet quando il task è lungo e ben specificato ma qualcuno ha già deciso come appare una risposta "corretta", il che copre la maggior parte del lavoro di esecuzione, inclusi tutti e nove i worker di traduzione. Riserva Opus agli agent il cui output nessuno, più a valle, rimetterà in discussione.

Quell'ultima regola è il motivo per cui validator sta su Opus anche se produce un report breve. Nessuno controlla chi controlla.

Una nota di versione che cambia i conti: da v2.1.198 il subagent predefinito Explore non gira più sempre su Haiku, ma eredita il modello della sessione. Un subagent a livello utente o progetto chiamato Explore sovrascrive quello predefinito e mantiene il proprio campo model, quindi definiscine uno con model: haiku se vuoi tenere l'esplorazione su un modello economico.

Contratti su File: Come i Nostri Agent Si Passano il Lavoro Senza Condividere il Contesto

Un subagent non vede la cronologia della tua conversazione, e non vede nemmeno quella di nessun altro subagent. I passaggi di consegna in memoria tra agent sono quindi strutturalmente impossibili. La soluzione è rendere ogni passaggio un artefatto su disco, così il prossimo agent legge un file invece di ereditare un contesto che non potrà mai avere.

techsy.community/posts/claude-code-subagents/
├── research.md      # researcher       → SERP analysis, keyword data, gaps
├── brief.md         # brief-creator    → section-by-section spec
├── en.md            # content-writer   → the post you are reading
├── de.md            # language-translator (one subagent per language)
├── hero.webp        # image-handler
├── validation.md    # validator
└── meta.json        # pipeline stage, updated by a PostToolUse hook

Cinque artefatti, ciascuno scritto da un agent diverso, ciascuno letto dal successivo, tutti leggibili da un umano e tracciati in git. La pipeline sopravvive ai limiti di contesto perché nessun agent ha mai bisogno del contesto di un altro agent. Ha bisogno solo del file dell'agent precedente.

Il payoff più chiaro è la traduzione. translation-coordinator legge en.md, poi genera un subagent language-translator per lingua, nove o dieci alla volta. Nel nostro repo la concorrenza dipende dall'inviare tutte le chiamate di spawn in un unico messaggio: è un comportamento osservato sul nostro setup, non qualcosa che la documentazione dichiara esplicitamente, ma è stato abbastanza costante da far sì che il coordinator sia scritto per farlo deliberatamente. Ogni traduttore scrive il proprio {lang}.md e nessuno di loro può vedere il lavoro degli altri, il che va bene, perché il contratto è il file e il file è già completo.

È anche qui che i subagent si fermano e inizia qualcos'altro. I subagent lavorano dentro una singola sessione. Se vuoi workspace davvero indipendenti con una propria cronologia, stai invece eseguendo più sessioni Claude Code in parallelo, oppure usando isolation: worktree per dare a un subagent una propria copia del repository.

Come Fanno i Subagent a Ricordare le Cose tra una Sessione e l'Altra?

Solo se imposti il campo memory, che accetta tre scope: user scrive in ~/.claude/agent-memory/<name>/, project scrive in .claude/agent-memory/<name>/, e local scrive in .claude/agent-memory-local/<name>/. Senza, ogni invocazione parte da zero. Dodici dei nostri diciotto agent dichiarano memory: project.

Dopo circa quaranta post, quelle directory sono sostanziose. researcher ne ha 74, validator 66, brief-creator 65 file di memoria. Non sono log. Sono decisioni accumulate: quali pattern di H1 hanno reso poco, quali affermazioni sui client non possiamo fare, quali forme di SERP premiano una tabella rispetto alla prosa.

Ecco il vincolo che modella tutto questo. Un subagent con memoria abilitata riceve solo le prime 200 righe o i primi 25KB di MEMORY.md iniettati nel suo system prompt, a seconda di cosa arriva prima. Questo singolo limite è il motivo per cui ognuno dei nostri agent tiene un indice invece di un diario.

# Researcher Memory

## Reusable post patterns
- [Challenger H1 pattern](feedback_challenger_h1_pattern.md): when a question-shaped H1 earns the click
- [Sponsored post research](feedback_sponsored_post_research.md): H1 must be category-shaped, never a review
- [Claude Skills tutorial](project_claude_skills_tutorial.md): docs own the top two slots, target the long tail

Una riga per voce, il dettaglio spostato nel file di topic collegato, che l'agent legge su richiesta con il proprio tool Read. MEMORY.md resta un indice che sta dentro il budget di iniezione, mentre il corpus dietro di esso cresce senza limiti.

Usiamo project invece di user per quasi tutto, perché la memoria di progetto vive nel repo e viaggia tramite il version control. Quando un collega fa pull, tira giù anche il giudizio accumulato dell'agent insieme al codice. local esiste per i casi in cui vuoi le note ma non il commit.

Cosa Si È Rotto: Modalità di Guasto, Nomi Duplicati e un Alias Legacy nel Nostro Stesso Repo

Quattro modalità di guasto spiegano quasi tutto ciò in cui siamo incappati. Un subagent che si rifiuta di partire, un subagent che silenziosamente non è quello che hai modificato, un subagent che Claude non riesce proprio a trovare, e un tetto rigido di sessione su quanti puoi generarne. Tutte e quattro hanno soluzioni brevi e inequivocabili.

Quello dei nomi duplicati è più insidioso di quanto sembri. Modifichi un file, il comportamento non cambia, e non c'è nessun errore da nessuna parte, perché un altro file con lo stesso name ha vinto l'ordine di lettura.

Gli hooks ci hanno aiutato più di quanto ci aspettassimo per i guasti che non sono affatto errori, solo passaggi che un umano dimentica. Il nostro è deliberatamente semplice:

"SubagentStop": [
  {
    "matcher": "content-writer",
    "hooks": [
      {
        "type": "command",
        "command": "echo 'Content writer finished. Run /validate to check quality and SEO compliance.'"
      }
    ]
  }
]

Ora quella onesta. Scrivendo questo post abbiamo fatto un grep sulla nostra fleet e abbiamo trovato questo ancora fermo in translation-coordinator.md:

# .claude/agents/translation-coordinator.md
name: translation-coordinator
tools: Read, Write, Glob, Grep, Task
model: sonnet

Task, non Agent. Quel campo è rimasto stantio da v2.1.63 e non ha mai fallito nemmeno una volta, perché Anthropic ha mantenuto l'alias. Non l'abbiamo ancora ripulito. Se anche i tuoi file agent dicono ancora Task, non sono rotti, sono solo vecchi, e l'alias sta facendo un lavoro silenzioso per un sacco di repo in questo momento.

Una correzione nella direzione opposta: le guide scritte prima di v2.1.172 dicono ai lettori che un subagent non può generare altri subagent. Invece può, e lo fa da quella release. La profondità è fissa a cinque livelli sotto la conversazione principale e non è configurabile, quindi un subagent a profondità cinque semplicemente non riceve il tool Agent.

Quanto Costano i Subagent, e Quando Non Usarne Uno

Ogni spawn di un subagent crea una context window nuova, quindi la delega non è mai gratuita. Il team di engineering di Anthropic riporta che gli agent usano circa 4 volte più token rispetto alle interazioni in chat, e i sistemi multi-agent circa 15 volte in più, e che il solo utilizzo di token spiega l'80% della varianza di performance che hanno misurato.

Non abbiamo misurazioni di token nostre da aggiungere, quindi tratta qualsiasi moltiplicatore specifico che leggi su questo argomento, incluse le cifre da 4x a 7x che girano su altri blog, come il numero di quell'autore, non come un benchmark. L'approfondimento sul multi-agent research system di Anthropic è l'unica fonte qui con dati reali dietro, e lo stesso studio ha scoperto che un lead agent Opus con subagent Sonnet ha battuto un singolo agent Opus del 90,2% nella loro valutazione interna. È quel risultato, non il conteggio dei token, l'argomento a favore dei livelli di modello.

Salta il subagent quando l'output appartiene comunque alla tua conversazione principale, perché finiresti solo per incollarlo di nuovo dentro e pagare due volte. Saltalo per le modifiche piccole, dove il giro di andata e ritorno della delega costa più del lavoro stesso. E saltalo quando il task ha davvero bisogno della cronologia della tua conversazione: usa invece un fork, che eredita l'intera conversazione e riusa la prompt cache del parent, rendendolo più economico di un subagent nuovo per lavori secondari pesanti di contesto. Sia la guida sui costi di Anthropic sia il loro inquadramento su quando usarli arrivano alla stessa conclusione.

Vale la pena conoscere il tetto di 200 per sessione prima di progettare un fan-out. È un limite reale contro la delega fuori controllo, e alzarlo è un atto deliberato, non un default.

Informazioni sull'autore

Mert Batur costruisce prodotti presso Techsy, dove il team spedisce agent AI, sistemi di automazione e pipeline voice/SDR per client B2B. Scrive dello stack di strumenti LLM e delle Claude Skills che il team Techsy usa realmente in produzione.

Techsy — University of Birmingham · LinkedIn

Domande Frequenti

Cosa sono i subagent di Claude Code?

I subagent di Claude Code sono assistenti specializzati che girano ciascuno nella propria context window, con un system prompt personalizzato, accesso ristretto ai tool e permessi indipendenti. Ne definisci uno come file Markdown con frontmatter YAML in .claude/agents/. Il subagent svolge un task secondario e restituisce solo il proprio riepilogo alla tua conversazione principale.

Claude Code usa i subagent automaticamente?

Sì. Claude legge il campo description di ogni subagent a sua disposizione e delega quando un task corrisponde, senza chiedertelo prima. Da v2.1.198 i subagent girano in background di default, quindi il lavoro delegato spesso avviene mentre continui a scrivere nella conversazione principale.

Dove vivono i file dei subagent?

I subagent di progetto vivono in .claude/agents/ e quelli utente in ~/.claude/agents/. Entrambe le posizioni vengono scansionate ricorsivamente, quindi le sottocartelle vanno bene. L'identità viene solo dal campo frontmatter name, mai dal percorso. I subagent gestiti, distribuiti da un amministratore, hanno la precedenza sulle definizioni di progetto e utente che condividono lo stesso nome.

Come invoco esplicitamente un subagent?

Chiedilo per nome nel tuo prompt, per esempio "usa il subagent validator su questa bozza". L'invocazione esplicita salta il matching sulla description che guida la delega automatica, il che aiuta quando due dei tuoi subagent hanno description che si sovrappongono e Claude continua a prendere quello sbagliato.

Un subagent può generare i propri subagent?

Sì, da Claude Code v2.1.172. Le guide scritte prima di quella release affermano che il nesting è impossibile, e sono superate. La profondità conta i livelli sotto la conversazione principale ed è fissa a cinque: un subagent a profondità cinque non riceve il tool Agent. Il limite non è configurabile.

I subagent ricordano qualcosa tra una sessione e l'altra?

Solo se imposti il campo memory. Accetta user per ~/.claude/agent-memory/<name>/, project per .claude/agent-memory/<name>/, oppure local per .claude/agent-memory-local/<name>/. Senza, ogni invocazione parte da zero. Dodici dei nostri diciotto agent usano memory: project così le loro note viaggiano nel version control.

Un subagent può usare un modello diverso dalla mia sessione?

Sì. Imposta model nel frontmatter su haiku, sonnet, opus, o un ID di modello specifico, e sovrascrive il modello della tua sessione per quel subagent. La nostra fleet si divide in sei su Opus, undici su Sonnet e uno su Haiku, assegnati in base a quanto giudizio richiede l'output di ogni agent.

Perché il mio nuovo subagent non compare?

Tre cause abituali. La directory agents non esisteva all'avvio della sessione, quindi il watcher non l'ha mai rilevata: riavvia Claude Code. Oppure due file condividono lo stesso name e ne viene caricato solo uno. Oppure niente nella tua lista tools si risolve, il che da v2.1.208 impedisce l'avvio con un errore di naming.

Task è ancora un nome di tool valido?

Sì, come alias. Il tool Task è stato rinominato Agent in v2.1.63, e i riferimenti esistenti a Task(...) continuano a funzionare nei settings e nelle definizioni degli agent. Scrivi Agent nei nuovi file. Il nostro stesso translation-coordinator.md dichiara ancora Task, cosa che abbiamo scoperto scrivendo questo post e non abbiamo ancora ripulito.

Tre Cose da Portarti a Casa

Se stai mettendo in piedi la tua prima fleet, parti da qui. Il campo description decide tutto, perché è ciò che Claude legge quando sceglie un worker, quindi scrivilo come una regola di instradamento e non come un titolo di lavoro. Progetta il passaggio di consegna come un file prima di progettare l'agent, dato che nessun subagent vedrà mai il contesto di un altro. E metti ogni agent sul modello più economico in grado di produrre una risposta corretta, spostandolo più in alto solo quando lo becchi sbagliare.

Esplora la libreria completa per le specifiche dietro questa pipeline.