La documentazione ufficiale di Claude Code presenta i "subagents", assistenti IA specializzati progettati per migliorare i flussi di lavoro specifici per task e ottimizzare la gestione del contesto all'interno dell'ambiente di sviluppo. Questi subagents sono personas IA preconfigurate a cui Claude Code può delegare dei task, ciascuna operando con uno scopo distinto e una competenza di dominio mirata.
Caratteristiche Fondamentali
Ogni subagent possiede quattro attributi essenziali: una finestra di contesto indipendente che evita di inquinare il contesto conversazionale principale, un insieme configurabile di strumenti specifico per il suo dominio, e un system prompt personalizzato che guida il suo comportamento. Questo isolamento contestuale consente una risoluzione dei problemi più mirata ed efficace, con istruzioni finemente calibrate che migliorano i tassi di successo sui task designati.
Vantaggi Strutturali
I subagents offrono quattro benefici principali: preservazione del contesto mantenendo la conversazione principale focalizzata sugli obiettivi di alto livello, competenza specializzata tramite istruzioni dettagliate per domini specifici che migliorano le prestazioni, riutilizzabilità cross-progetto con la possibilità di condivisione tra team che promuove flussi di lavoro coerenti, e permessi flessibili con controllo granulare dell'accesso agli strumenti per tipo di subagent per una sicurezza rafforzata.
Creazione e Configurazione
La creazione viene avviata tramite il comando /agents in Claude Code, che consente di scegliere tra subagents a livello di progetto o a livello utente. Gli utenti definiscono lo scopo e concedono l'accesso a strumenti specifici. I subagents sono memorizzati come file Markdown con frontmatter YAML: .claude/agents/ per il livello progetto, ~/.claude/agents/ per il livello utente. I campi di configurazione includono name (identificatore univoco), description (descrizione dello scopo), tools (elenco opzionale separato da virgole) e model (specifica opzionale come sonnet, opus, haiku o inherit).
Esempi Pratici e Pattern
La documentazione fornisce tre esempi archetipici: Code reviewer, esperto in qualità del codice e sicurezza che utilizza Read, Grep, Glob, Bash; Debugger, specializzato nell'analisi delle cause profonde con Read, Edit, Bash, Grep, Glob; Data scientist, esperto in analisi SQL e BigQuery che utilizza Bash, Read, Write. Questi pattern illustrano come limitare l'accesso agli strumenti al minimo stretto migliori sicurezza e focalizzazione.
Gestione e Invocazione
Il comando /agents offre un'interfaccia interattiva per visualizzare, creare, modificare, eliminare i subagents e gestire i permessi sugli strumenti. Alternativa: gestione diretta dei file. Claude Code può delegare automaticamente i task ai subagents in base alla descrizione del task, alla configurazione del subagent e al contesto corrente. È possibile l'invocazione esplicita menzionando il nome.
Best Practice e Casi d'Uso Avanzati
Le raccomandazioni chiave includono: iniziare con agenti generati da Claude per una calibrazione iniziale, progettare subagents focalizzati con responsabilità chiare, scrivere system prompt dettagliati, limitare l'accesso agli strumenti al minimo stretto e utilizzare il controllo di versione per i subagents di progetto. Gli usi avanzati includono il concatenamento di più subagents per flussi di lavoro complessi e lo sfruttamento della selezione dinamica, in cui Claude sceglie automaticamente il subagent appropriato in base al contesto. Questa architettura modulare consente una composizione flessibile di capacità specializzate mantenendo al contempo la separazione delle responsabilità e la chiarezza contestuale.