Claude Code /agents: creare subagent specializzati per delegare i task senza intasare il contesto

🔍 Cosa sono i subagent e perché passo dal comando /agents

Un subagent è un'istanza di Claude Code specializzata: gira nel suo context window, con un system prompt dedicato, un set di tool ristretto e permessi indipendenti. Quando un task secondario inonderebbe la conversazione principale — risultati di ricerca, output di test, contenuti di decine di file che non mi servono più — lo delego: il subagent fa quel lavoro nel suo contesto e mi restituisce solo la sintesi.

La differenza con la conversazione principale è tutta qui. Ogni subagent parte da zero: non vede la cronologia, le skill già caricate o i file già letti. Claude compone un messaggio di delega che riassume il compito, e il subagent lavora da lì. È esattamente questo isolamento a tenere pulito il contesto principale: la stack trace da 4.000 righe e i quindici risultati di grep restano nel transcript del subagent e non sporcano la sessione che paga le bollette.

Per gestire tutto questo uso il comando /agents, l'interfaccia a schede che Claude indica come modo predefinito: una scheda Running per i subagent attivi e una Library per crearne, modificarne ed eliminarne. È da qui che parto, invece di scrivere file a mano.

L'interfaccia da cui creo, modifico ed elimino i subagent: i tre integrati e quelli di progetto, ciascuno con il suo modello.

🧩 I tre subagent integrati: Explore, Plan e general-purpose

Prima ancora di crearne uno mio, Claude Code ne ha già tre pronti, che delega da solo quando servono. Conoscerli evita di reinventare la ruota:

• Explore: agente di sola lettura ottimizzato per cercare e analizzare il codice. Gira su Haiku — veloce ed economico — e non può scrivere né modificare file. È ciò che uso per la ricerca pura.
• Plan: l'agente di ricerca della plan mode. Eredita il modello della conversazione, resta in sola lettura e raccoglie contesto prima di presentare un piano.
• general-purpose: il tuttofare, con accesso a tutti i tool, per task multi-step che richiedono sia esplorazione sia azione.

🧱 Creare un subagent con /agents: il flusso che seguo

Quando lo stesso tipo di lavoro torna di continuo — un revisore di sicurezza, chi scrive i test, chi tiene allineata la documentazione — smetto di ri-spiegarlo ogni volta e lo definisco una volta sola. Il flusso, dentro /agents, è sempre lo stesso e mi prende un paio di minuti.

La scelta che conta di più è lo scope. Un subagent di progetto vive in .claude/agents/ e lo committo nel repo: così ogni persona del team lavora con lo stesso revisore e lo stesso scrittore di test. Un subagent utente vive in ~/.claude/agents/ e mi segue su tutti i progetti. Quando due hanno lo stesso nome, vince quello a priorità più alta (progetto prima di utente).

⚙️ description, tools e model: i campi che decidono il comportamento

Un subagent è un file markdown con frontmatter YAML in testa e il system prompt nel corpo. Gli unici campi obbligatori sono name e description: tutto il resto eredita valori di default sensati. Ma sono proprio i campi opzionali a fare la differenza tra una delega che funziona e una che frustra.

Il campo description è il più sottovalutato: è ciò che Claude legge per decidere quando delegare in automatico. Va scritto sulle condizioni d'uso, non sulla capacità: "revisiona il codice prima di un commit" instrada meglio di "esperto di sicurezza". Aggiungere use proactively spinge la delega spontanea.

Gli altri due campi che tocco quasi sempre:

• tools: una allowlist. Se la specifico, il subagent può usare solo quei tool — un revisore di sola lettura riceve Read, Grep, Glob e non può toccare i file. In alternativa disallowedTools sottrae singoli tool da quelli ereditati.
• model: haiku, sonnet, opus o inherit (default). Qui si gioca buona parte del risparmio: instradare i task ad alto volume su Haiku abbatte il costo senza perdere qualità dove non serve.
• memory: opzionale, dà al subagent una cartella persistente in cui accumula pattern e decisioni tra una conversazione e l'altra.

---
name: code-reviewer
description: revisione qualità e sicurezza,
  usalo dopo ogni modifica al codice
tools: Read, Grep, Glob
model: sonnet
---
Sei un senior code reviewer: segnala bug, rischi
di sicurezza e codice duplicato. Sola lettura.

⚠️ Quando NON uso un subagent

I subagent non sono gratis: ognuno avvia un contesto nuovo, consuma token e aggiunge un livello di indirezione. Valgono il prezzo quando isolamento, parallelismo o uno sguardo fresco aiutano davvero. Negli altri casi resto nella conversazione principale, ed è la scelta più semplice e più veloce.

I casi in cui evito la delega, imparati sul campo:

• Lavoro sequenziale e dipendente: se il passo due ha bisogno di tutto l'output del passo uno, una sola sessione è più pulita di una staffetta di subagent.
• Modifiche allo stesso file in parallelo: due subagent che editano lo stesso file sono una ricetta per il conflitto.
• Task piccoli: per una correzione rapida l'overhead della delega supera il beneficio.
• Troppi specialisti: riempire Claude di subagent rende la delega automatica meno affidabile, perché le descrizioni si sovrappongono.
• Lavoro che richiede coordinamento tra agenti: i subagent rispondono solo al genitore, non si parlano tra loro. Lì servono gli agent teams.

🏢 Cosa cambia per un team (e per una PMI)

Il valore vero dei subagent, per chi sviluppa in azienda, non è la singola sessione più pulita: è che gli specialisti diventano parte del repo. Un code-reviewer, un debugger e uno scrittore di test versionati in .claude/agents/ fanno sì che ogni persona del team lavori con gli stessi controlli, senza che nessuno debba ricordarsi di chiederli.

C'è anche un lato governance che per una PMI conta. Restringere i tool di un subagent a sola lettura significa avere revisori che non possono modificare il codice o toccare dati sensibili: il permesso minimo non è un'intenzione, è scritto nella definizione. È lo stesso principio con cui affronto la shadow AI, applicato alla riga di comando.

Il consiglio che do a chi parte: comincia con un solo specialista, di solito un code-reviewer di sola lettura, misura quanto viene invocato e aggiungi gli altri man mano che i pattern emergono. Un piccolo team — o un singolo sviluppatore — si ritrova così una squadra di specialisti virtuali, a costo di qualche file markdown.

Altri articoli del blog