Subagenti di Claude Code: configurazione, impostazioni e quando utilizzarli

La maggior parte delle sessioni di Claude Code diventa lenta e caotica per lo stesso motivo: ogni ricerca esplorativa con grep, ogni dump dei log e ogni “controlliamo un altro file” rimane nella conversazione principale per sempre.

I subagenti esistono per risolvere esattamente questo problema. Sono uno dei primitivi degli agenti integrati in Claude Code per gestire lavori rumorosi e parallelizzabili — un modo per spostare il disordine in una finestra isolata e riportare solo il riepilogo che conta.

Un subagente non è un Claude più intelligente, né è la stessa cosa di una Skill. È un agente di ragionamento separato con la propria finestra di contesto, la propria lista di strumenti consentiti e nessuna memoria della tua conversazione corrente, a meno che tu non lo forchi esplicitamente. Comprendere questa distinzione è la differenza tra una configurazione di subagenti che ti fa risparmiare budget di contesto in silenzio e una che aggiunge solo latenza senza alcun beneficio.

Subagenti vs Skill vs MCP

Claude Code ti offre tre punti di estensione che risolvono problemi diversi e vengono spesso confusi perché tutti e tre possono tecnicamente “aiutare con un compito”.

Una regola pratica utile: un hook impone un vincolo rigido in modo deterministico, una Skill fornisce all’agente principale una capacità inline e un subagente è destinato a lavori che vuoi delegare e mantenere completamente fuori dal contesto principale. Se il compito di una Skill è orchestrare uno strumento che non esiste ancora, è solitamente un segnale che hai bisogno di un server MCP, non di un subagente. Claude Code non è l’unico a seguire questa struttura — l’ecosistema di OpenCode ha un’idea comparabile nei suoi agenti specializzati, che separano pianificazione, ricerca e revisione in ruoli dedicati in modo simile.

Cos’è effettivamente un subagente

Tre proprietà definiscono un subagente di Claude Code e tutte e tre sono importanti per il modo in cui lo utilizzi:

• Contesto isolato. Un subagente parte con una finestra pulita. Non vede la cronologia della tua conversazione a meno che tu non lo forchi esplicitamente, il che mantiene il suo output libero da qualsiasi cosa tu abbia discusso tre turni fa.
• Una lista di strumenti consentiti ristretta. I subagenti possono utilizzare solo un sottoinsieme di ciò che la sessione genitrice già possiede — non possono concedersi nuove capacità e un subagente ben progettato dovrebbe ricevere solo gli strumenti richiesti dal suo compito (strumenti di sola lettura per un agente di ricerca, ad esempio).
• Nessuna visibilità tra subagenti. I subagenti non possono vedere il lavoro in corso degli altri. Se il compito B ha genuinamente bisogno dell’output del compito A, si tratta di una dipendenza sequenziale, non di qualcosa che puoi parallelizzare tra due subagenti.

Il trigger per utilizzarne uno non è “questo compito è difficile”. È “questo compito è rumoroso” — il tipo di lavoro che genera molto output intermedio (decine di letture di file, un log lungo, un grep esplorativo su tutto il repository) dove nessuno di quel materiale intermedio deve sopravvivere fino al tuo prossimo turno di conversazione.

Quando usare un subagente (e quando non farlo)

Buoni candidati: esplorazione del codebase prima di un grande cambiamento, esecuzioni automatizzate di test in cui ti interessa solo il pass/fail e i riepiloghi degli errori, revisioni di sicurezza o stile e qualsiasi compito di ricerca multi-step il cui output grezzo altrimenti inonderebbe la tua sessione principale.

Cattivi candidati: ricerche di due secondi (“cosa restituisce questa funzione”), qualsiasi cosa richieda un affinamento stretto e iterativo, e compiti dipendenti che sei tentato di “parallelizzare” anche se il secondo ha bisogno della risposta del primo. Utilizzare un subagente per una ricerca banale aggiunge solo l’overhead di avviare una nuova finestra di contesto senza alcun reale beneficio di isolamento.

Misurare il rendimento: matematica di contesto e costi

La proposta dei subagenti è astratta finché non si applicano numeri a un compito reale. Prendiamo uno comune: eseguire grep su un servizio di ~500 file per ogni luogo in cui una chiave di configurazione deprecata è ancora letta, e poi riportare le corrispondenze esatte file:riga.

Si tratta di una riduzione di circa 15-20 volte di ciò che la tua sessione principale deve gestire per quel passaggio, che è il meccanismo effettivo dietro “i subagenti mantengono le sessioni più veloci” — non è magia, è contesto che non viene mai caricato in primo luogo.

Il lato dei costi si accumula allo stesso modo. Utilizzando i prezzi dal dettaglio prezzi di Claude Code, eseguire quella stessa pass di esplorazione su Opus (5$/MTok input, 25$/MTok output) costa circa $0.20-0.25 solo per i ~40K token di input. Inviandolo a Haiku (1$/MTok input, 5$/MTok output) riduce il costo a $0.04-0.05 — e il budget Opus della sessione principale non viene mai toccato dai token di esplorazione, poiché vede solo il riepilogo di ~2K token.

Definire un subagente personalizzato

I subagenti personalizzati vivono come file Markdown con frontmatter YAML, sia a livello di progetto in .claude/agents/ (commit nel repository, condivisi da tutto il team) che a livello di utente in ~/.claude/agents/ (strumenti personali che porti in ogni progetto).

---
name: code-reviewer
description: >
  Reviews staged changes for bugs, security issues, and style violations
  before commit. Use when the user asks to review, audit, or check
  changes prior to committing or opening a PR.  
tools: Read, Grep, Glob
model: sonnet
skills:
  - security-checklist
---
You are a careful code reviewer. Read the staged diff, flag concrete
issues with file:line references, and end with a short pass/fail summary.
Do not modify any files.

Il campo description è la riga più importante del file. È ciò che la logica di routing della sessione genitrice legge per decidere se questo subagente si adatta al compito corrente. Scrivilo come un annuncio di lavoro — nomina la condizione di trigger esplicitamente, non un vago “aiuta con il codice”. Le descrizioni vaghe vengono saltate o applicate in modo errato dal dispatch automatico.

Il campo tools è il tuo confine di isolamento. Dai a un subagente di ricerca Read, Grep e Glob e nient’altro; dargli ogni strumento disponibile sconfigge l’intero punto di eseguirlo in un sandbox ristretto. Il campo skills opzionale precarica il contenuto completo delle Skills nominate nel contesto di avvio del subagente — utile quando un subagente ha bisogno di conoscenza del dominio senza spendere un turno per scoprirla e caricarla a metà lavoro.

Routing del modello: modelli economici per lavori pesanti

I subagenti sono anche dove il controllo dei costi diventa reale. Instrada la scoperta di file, la scansione dei log e altri lavori economici da verificare verso Haiku, e riserva Sonnet o Opus per i passaggi pesanti di ragionamento — decisioni architetturali, debug ambigui, qualsiasi cosa in cui sbagliare sia costoso. Haiku è circa 15 volte più economico per token rispetto a Opus e, sul tipo di esplorazione rumorosa per cui i subagenti sono costruiti, questo divario si accumula rapidamente in una vera sessione di lavoro.

Il pattern Explore, Plan, Execute

Per lavori complessi e multi-step, il pattern che tiene in piedi nella pratica è Explore, Plan, Execute — utilizzando subagenti economici per le parti che generano rumore e mantenendo il gate di revisione umana nell’unico posto in cui conta davvero.

Il dettaglio chiave che le persone capiscono al contrario è dove appartiene il gate di revisione. L’esplorazione è economica, quindi lascia che un subagente legga liberamente senza chiedere permesso prima. La pianificazione è analitica, quindi lascia che l’agente progetti l’approccio da solo. Ma prima che qualsiasi agente modifichi i file, vuoi vedere il piano e approvarlo — è per questo che esiste la modalità plan di Claude Code (permissionMode: plan) ed è lo stesso principio discusso nelle best practices di vibe coding sulla revisione di ogni diff prima che venga applicato.

Errori comuni

Un pugno di errori si presentano ripetutamente una volta che i team iniziano a scrivere subagenti personalizzati:

• Descrizioni vaghe. “Aiuta con il codice” non instraderà mai correttamente. Nomina la condizione di trigger esatta.
• Accesso agli strumenti troppo ampio. Dare a un subagente di ricerca di sola lettura accesso in scrittura e a bash rimuove la garanzia di isolamento che lo rendeva utile da creare in primo luogo.
• Parallelizzare compiti dipendenti. Se il compito B ha bisogno dell’output finito del compito A, eseguili in sequenza — i subagenti non possono coordinarsi a metà lavoro come può fare un orchestratore condiviso. Per flussi di lavoro che hanno genuinamente bisogno di agenti che si parlano a metà lavoro, è una forma diversa di problema; vedi pattern di orchestrazione multi-agente se stai costruendo un sistema di produzione piuttosto che un flusso di lavoro single-repo.
• Usare un subagente per lavori banali. “Formatta questo JSON” o “esegui questo singolo comando” non ha bisogno di una nuova finestra di contesto; fallo direttamente.

Esempio pratico: un subagente di code-review da capo a fondo

Immagina di voler fare revisionare ogni commit non banale prima che venga applicato. Metti la definizione code-reviewer mostrata in precedenza in .claude/agents/code-reviewer.md, falla commitare in modo che tutto il team condivida lo stesso revisore e invoccala con una richiesta naturale come “revisiona i miei cambiamenti staged prima di fare commit”. Claude Code fa corrispondere la tua richiesta con la description del subagente, la avvia con solo accesso Read, Grep e Glob e torna con risultati riferiti a file:riga e un riepilogo pass/fail — nessun rumore file per file del percorso ci arriva mai a toccare la tua sessione principale.

Come appare nel transcript principale, annotato:

You:  review my staged changes before I commit

Main: [dispatches code-reviewer subagent — 6 files read, 1 grep pass,
       zero of it shown here]

Main: code-reviewer findings:
      - auth/session.go:142 — token refresh path doesn't handle expired
        refresh token; falls through to nil dereference
      - auth/session.go:203 — style: error wrapped without %w
      PASS/FAIL: FAIL (1 blocking issue)

Sono avvenute sei letture di file e una pass di grep, e la tua sessione principale ha pagato esattamente per quattro righe di tutto ciò. Quel divario — tutto ciò che il subagente ha fatto versus il riepilogo di tre righe che vedi effettivamente — è l’intera proposta di valore in un unico transcript.

Se il tuo team utilizza anche scaffold Spec-Driven Development, un subagente di revisione si inserisce naturalmente nel passo di validazione; vedi GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows per vedere come quel gate di revisione si confronta tra setup SDD portatili e integrati nell’IDE.

Vale la pena configurare subagenti personalizzati?

Non il primo giorno. Il subagente generalizzato integrato copre già la maggior parte della delega di esplorazione e ricerca senza che tu scriva un singolo file YAML e una singola pass Explore-Plan-Execute è sufficiente per la maggior parte del lavoro quotidiano. Scrivi un file personalizzato .claude/agents/*.md solo dopo aver delegato lo stesso compito a mano tre volte — un revisore di codice, un triager di test, un agente di ricerca documenti per una specifica libreria interna. I team che scrivono cinque subagenti nella loro prima settimana finiscono solitamente con cinque campi description obsoleti che nessuno aggiorna quando la condizione di trigger effettiva cambia, il che rompe silenziosamente il routing automatico mesi dopo. Inizia con zero subagenti personalizzati, aggiungine uno alla volta e solo quando la ripetizione — non l’utilità teorica — lo richiede.

Limitazioni note

Alcuni lati ruvidi vale la pena conoscerli prima di costruire attorno ai subagenti:

• Nessuna delega ricorsiva. Un subagente non può generare i propri subagenti. Se un compito ha genuinamente bisogno di un secondo livello di delega, è un segnale che vuoi una forma di orchestrazione diversa — vedi pattern di orchestrazione multi-agente per come appare al di fuori di una singola sessione Claude Code.
• Nessuna memoria tra le invocazioni. Ogni dispatch parte da zero, anche se hai chiamato lo stesso subagente cinque minuti fa su un compito correlato. Non esiste un meccanismo integrato per un subagente per ricordare la sua ultima esecuzione.
• L’isolamento è una lista di strumenti consentiti, non un sandbox. Un subagente con accesso Bash può ancora toccare il filesystem e la rete come qualsiasi altra chiamata di strumento. Ristrettire tools riduce il raggio d’esplosione; non crea un confine di sicurezza rigido.

Risoluzione dei problemi

Il subagente non si attiva mai. Il problema è quasi sempre la descrizione. Riscrivila attorno alla condizione di trigger specifica invece che a un’affermazione di capacità generale e ricontrolla che il file viva in .claude/agents/ (progetto) o ~/.claude/agents/ (personale) con l’estensione corretta.

Il subagente consuma troppo contesto comunque. Controlla la lista tools consentiti — un set di strumenti troppo ampio invita un’esplorazione troppo ampia. Controlla anche se il compito avrebbe dovuto essere diviso in due subagenti invece di uno che fa tutto.

Una skill elencata non si carica all’interno del subagente. Claude Code salta una skill mancante o disabilitata nominata nel campo skills invece di fallire l’esecuzione e registra una riga a tal fine nell’output di debug (/debug dalla sessione principale, poi riproduci il dispatch) — qualcosa come skill "security-checklist" not found, skipping. Esegui /doctor dopo per confermare che il resto della tua configurazione sia sano.

I risultati sembrano incoerenti tra le esecuzioni. Questo è spesso un problema di routing del modello, non di progettazione del subagente — il lavoro pesante di ragionamento assegnato a un modello economico varierà di più. Spostalo su Sonnet o Opus e tieni Haiku per i passaggi deterministici e a bassa ambiguità.

I subagenti sono un pezzo di un toolbox molto più grande; se stai confrontando Claude Code con il resto dell’ecosistema degli strumenti per sviluppatori AI prima di impegnarti in questo flusso di lavoro, quella panoramica è una buona prossima tappa.

Link utili

• Installazione e configurazione di Claude Code per Ollama, llama.cpp, prezzi
• Claude Skills e SKILL.md per sviluppatori
• GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows
• Cos’è il Vibe Coding?
• Pattern di Orchestrazione Multi-Agente: Una Guida Pratica
• Approfondimento sugli Agenti Specializzati Oh My Opencode
• Strumenti per Sviluppatori AI: La Guida Completa