Come creare Claude Code Subagenti

Come creare Claude Code Subagenti

Claude Code, il tool CLI di Anthropic per lo sviluppo assistito da AI, ha introdotto una delle funzionalità più potenti della sua evoluzione nel 2025-2026: i subagenti personalizzati. Si tratta di assistenti AI specializzati che operano in contesti isolati, con prompt dedicati, accesso controllato agli strumenti e permessi indipendenti. Se sei uno sviluppatore o un ingegnere informatico con esperienza media con strumenti AI e CLI, questo articolo ti guiderà passo dopo passo nella creazione e nell’uso efficace dei subagenti in Claude Code.

La documentazione ufficiale di Anthropic definisce i subagenti come assistenti AI specializzati che gestiscono tipi specifici di attività, ognuno con la propria finestra di contesto, prompt di sistema personalizzato, accesso specifico agli strumenti e permessi indipendenti.

Indice dei contenuti – Come creare Claude Code Subagenti

1. Cosa sono i subagenti di Claude Code e perché usarli

2. I subagenti integrati: Explore, Plan e General-purpose

3. Creare il primo subagente: quickstart con /agents

4. Struttura di un file subagente: frontmatter YAML e system prompt

5. Controllo degli strumenti, modelli e permission mode

6. Pattern pratici: isolamento, parallelismo e chaining

7. Esempi pratici con codice: code reviewer e debugger

8. Best practice, pro e contro

9. Conclusioni e formazione continua

1. Cosa sono i subagenti di Claude Code e perché usarli

Un subagente in Claude Code è un agente AI che lavora in modo autonomo all’interno di una sessione, con una propria finestra di contesto separata da quella principale. Quando Claude incontra un task che corrisponde alla descrizione di un subagente, lo delega automaticamente: il subagente lavora in modo indipendente e restituisce i risultati alla conversazione principale.

I vantaggi principali sono cinque:

• Preservazione del contesto: le attività esplorative o ad alto volume restano fuori dalla conversazione principale, evitando il consumo inutile del context window
• Vincoli applicati: è possibile limitare quali strumenti un subagente può usare, aumentando sicurezza e prevedibilità
• Riutilizzo: i subagenti user-level (~/.claude/agents/) sono disponibili in tutti i progetti del tuo ambiente
• Specializzazione: ogni subagente ha un prompt focalizzato su un dominio specifico (code review, debug, analisi dati, ecc.)
• Controllo dei costi: è possibile instradare task su modelli più veloci ed economici come claude-haiku-4-5, riducendo i consumi API

2. I subagenti integrati: Explore, Plan e General-purpose

Claude Code include tre subagenti built-in che vengono attivati automaticamente in base al contesto:

Explore

Agente veloce e read-only ottimizzato per la ricerca e l’analisi del codice. Usa il modello Haiku per bassa latenza. Ha accesso solo agli strumenti di lettura (Read, Grep, Glob) e viene delegato da Claude quando è necessario esplorare il codebase senza modificarlo. Supporta tre livelli di approfondimento: quick, medium, very thorough.

Plan

Agente di ricerca usato durante la modalità plan. Raccoglie contesto prima di presentare un piano d’azione. Ha accesso solo agli strumenti di lettura ed eredita il modello dalla conversazione principale. Impedisce la ricorsione infinita: i subagenti non possono spawnare altri subagenti.

General-purpose

Agente completo per task multi-step che richiedono sia esplorazione che azione. Ha accesso a tutti gli strumenti. Claude lo delega quando il task richiede sia lettura che modifica del codice, ragionamento complesso o operazioni con più passi dipendenti tra loro.

3. Creare il primo subagente: quickstart con /agents

Il modo più rapido per creare un subagente è usare il comando interattivo /agents direttamente nel terminale Claude Code:

/agents

Si apre un’interfaccia interattiva. Il flusso guidato è semplice:

• Seleziona Create new agent, poi scegli Personal (salvato in ~/.claude/agents/) o Project (salvato in .claude/agents/ del progetto)
• Scegli Generate with Claude e descrivi il subagente a parole tue
• Claude genera automaticamente identificatore, descrizione e system prompt
• Seleziona gli strumenti consentiti, il modello (Haiku, Sonnet, Opus) e un colore identificativo
• Configura la memoria persistente se vuoi che il subagente acumuli conoscenza tra sessioni diverse
• Premi s o Invio per salvare. Il subagente è subito disponibile

Una volta creato, puoi invocarlo così:

Usa il subagente code-improver per suggerire miglioramenti in questo progetto

I subagenti di progetto (.claude/agents/) possono essere committati in version control per condividerli con tutto il team — una funzionalità molto utile per standardizzare i workflow aziendali.

4. Struttura di un file subagente: frontmatter YAML e system prompt

I subagenti sono file Markdown con frontmatter YAML. La struttura base è:

---

name: code-reviewer

description: Revisore esperto di codice. Usalo dopo ogni modifica significativa.

tools: Read, Glob, Grep, Bash

model: sonnet

memory: project

---
Sei un senior code reviewer. Analizza il codice modificato e fornisci feedback strutturato su qualità, sicurezza e best practice.

I campi frontmatter più importanti sono:

• name (obbligatorio): identificatore univoco in lowercase con trattini
• description (obbligatorio): descrive quando Claude deve delegare a questo subagente — scrivi “usa proattivamente” per incentivare la delega automatica
• tools: elenco degli strumenti consentiti (allowlist). Se omesso, il subagente eredita tutti gli strumenti
• disallowedTools: strumenti da escludere (denylist) — si applica prima di tools
• model: sonnet, opus, haiku, un ID modello completo come claude-sonnet-4-6, oppure inherit (default)
• memory: user, project o local — abilita una directory persistente tra sessioni
• permissionMode: default, acceptEdits, auto, dontAsk, bypassPermissions, plan
• maxTurns: numero massimo di turni agentici prima che il subagente si fermi
• background: true per eseguire sempre il subagente in background (asincrono)
• isolation: worktree per eseguire in una git worktree temporanea isolata
• color: red, blue, green, yellow, purple, orange, pink, cyan — colore nella UI

5. Controllo degli strumenti, modelli e permission mode – Come creare Claude Code Subagenti

Strumenti: allowlist e denylist

Per creare un subagente strettamente read-only:

---

name: safe-researcher

description: Agente di ricerca con accesso limitato in sola lettura

tools: Read, Grep, Glob, Bash

---

Per ereditare tutti gli strumenti tranne la scrittura:

---

name: no-writes

description: Eredita tutti gli strumenti eccetto la modifica dei file

disallowedTools: Write, Edit

---

Selezione del modello

Claude Code risolve il modello in questo ordine di priorità: variabile d’ambiente CLAUDE_CODE_SUBAGENT_MODEL → parametro per-invocation → frontmatter del subagente → modello della conversazione principale. Usare Haiku per task semplici riduce notevolmente i costi.

Passare subagenti via CLI (senza file)

Per test rapidi o automazione puoi definire subagenti direttamente da riga di comando senza creare file:

claude --agents '{

  "code-reviewer": {

    "description": "Revisore esperto. Usa dopo ogni modifica.",

    "prompt": "Sei un senior code reviewer focalizzato su qualità e sicurezza.",

    "tools": ["Read", "Grep", "Glob", "Bash"],

    "model": "sonnet"

  }

}'

6. Pattern pratici: isolamento, parallelismo e chaining

6.1 Isolare operazioni ad alto volume

Uno degli usi più efficaci è isolare task che producono grandi quantità di output — esecuzione di test, recupero di log, elaborazione di documentazione. Tutto il verboso resta nel contesto del subagente; alla conversazione principale arriva solo il riassunto:

Usa un subagente per eseguire la suite di test e riportami

solo i test falliti con i relativi messaggi di errore

6.2 Ricerca parallela

Per investigazioni indipendenti, è possibile spawnare più subagenti contemporaneamente:

Analizza in parallelo i moduli di autenticazione, database e API

usando subagenti separati, poi sintetizza i risultati

Ogni subagente esplora la propria area in modo autonomo. Claude sintetizza i risultati al termine.

6.3 Chaining di subagenti

Per workflow multi-step, i subagenti possono essere chiamati in sequenza. Claude passa il contesto rilevante da uno all’altro:

Usa il subagente code-reviewer per trovare problemi di performance,

poi usa il subagente optimizer per correggerli

6.4 Invocare subagenti esplicitamente

Tre modalità di invocazione, per precisione crescente:

• Linguaggio naturale: “Usa il subagente test-runner per correggere i test falliti”
• @-mention: digita @ e seleziona il subagente dal typeahead — garantisce l’invocazione di quello specifico subagente
• Sessione intera: claude –agent code-reviewer — l’intera sessione usa il system prompt e i tool restrictions di quel subagente

7. Esempi pratici con codice: code reviewer e debugger

Code Reviewer (sola lettura)

Un subagente per la code review che non può modificare file — sicuro per ambienti CI/CD:

---

name: code-reviewer

description: Revisore esperto di codice. Usa proattivamente dopo aver scritto

  o modificato codice. Controlla qualità, sicurezza e manutenibilità.

tools: Read, Grep, Glob, Bash

model: inherit

---

Sei un senior code reviewer con focus su qualità e sicurezza.

Quando invocato:

1. Esegui git diff per vedere le modifiche recenti

2. Concentrati sui file modificati

3. Inizia la review immediatamente

Checklist di review:

- Codice chiaro e leggibile

- Nessun segreto o API key esposta

- Validazione degli input implementata

- Buona copertura di test

Organizza il feedback per priorità:

- Problemi critici (da correggere)

- Warning (da valutare)

- Suggerimenti (opzionali)

Debugger (con accesso in scrittura)

Un subagente per il debug che può anche correggere i problemi rilevati:

---

name: debugger

description: Specialista nel debug di errori e test falliti.

  Usa proattivamente quando incontri problemi.

tools: Read, Edit, Bash, Grep, Glob

---

Sei un esperto debugger specializzato nell'analisi della causa radice.

Quando invocato:

1. Cattura il messaggio di errore e lo stack trace

2. Identifica i passi per riprodurre il problema

3. Isola la posizione del fallimento

4. Implementa la correzione minima

5. Verifica che la soluzione funzioni

Per ogni problema fornisci:

- Spiegazione della causa radice

- Correzione specifica del codice

- Approccio per il testing

- Raccomandazioni per evitarlo in futuro

8. Best practice, pro e contro – Come creare Claude Code Subagenti

Pro

• Gestione ottimale del context window: le operazioni verbose non inquinano il contesto principale — fondamentale nei progetti complessi
• Sicurezza granulare: ogni subagente ha solo gli strumenti strettamente necessari — il principio del minimo privilegio applicato all’AI
• Riutilizzo e standardizzazione: i subagenti committati in .claude/agents/ sono condivisibili con tutto il team via version control
• Parallellizzazione reale: più subagenti possono lavorare simultaneamente su task indipendenti, riducendo i tempi
• Controllo dei costi API: instradare task semplici su Haiku invece di Sonnet/Opus può ridurre i costi in modo significativo
• Memoria persistente: il campo memory consente di costruire una knowledge base che migliora le prestazioni nel tempo

Contro

• Latenza iniziale: ogni subagente parte con un contesto fresco e può richiedere tempo per raccogliere il contesto necessario
• Nessuna delega annidata: un subagente non può spawnare altri subagenti — per workflow complessi annidati è necessario usare Skills o il chaining dalla conversazione principale
• Rischio bypassPermissions: usare questo permissionMode salta i prompt di conferma — va usato con estrema cautela in ambienti di produzione
• Complessità di configurazione: per subagenti con hooks PreToolUse/PostToolUse e script di validazione, la curva di apprendimento è più ripida
• Contesto di ritorno: se molti subagenti restituiscono risultati dettagliati alla conversazione principale, il context window può comunque riempirsi

Best practice operative

• Progetta subagenti focalizzati: ogni subagente dovrebbe eccellere in un unico task specifico
• Scrivi descrizioni dettagliate: Claude usa il campo description per decidere quando delegare — più è preciso, meglio funziona la delega automatica
• Limita gli strumenti: concedi solo il necessario, specialmente per subagenti che accedono a database o sistemi critici
• Committi i subagenti di progetto in .claude/agents/ così tutto il team ne beneficia
• Usa la memoria project per subagenti che accumulano conoscenza sul codebase: nel tempo diventano esponenzialmente più efficaci
• Per ambienti CI/CD, usa la modalità dontAsk o bypassPermissions (con cautela) per esecuzioni non interattive

9. Conclusioni: formazione continua nell’era degli agenti AI

I subagenti di Claude Code rappresentano un salto qualitativo nel modo in cui gli sviluppatori interagiscono con l’intelligenza artificiale. Non si tratta più di un semplice autocomplete o di un assistente passivo: con i subagenti personalizzati, è possibile costruire workflow agentici completi, con specializzazione dei ruoli, isolamento del contesto, controllo granulare dei permessi e memoria persistente. Dalla code review automatica al debug intelligente, dall’analisi dati al test parallelo — le possibilità sono concrete e immediatamente applicabili.

Il mercato dello sviluppo software è però in continua e rapida evoluzione: Claude Code stesso riceve aggiornamenti frequenti (la funzionalità subagenti è stata rilasciata e significativamente ampliata nel 2025-2026), i modelli Anthropic migliorano di versione in versione, e i paradigmi di sviluppo agentico cambiano le pratiche consolidate con una velocità mai vista prima. L’unico modo per mantenere il proprio team realmente competitivo è investire nella formazione continua degli sviluppatori. Non basta leggere la documentazione: serve pratica guidata, esempi reali e aggiornamento costante da parte di chi lavora quotidianamente con questi strumenti.

Per questo motivo ti consigliamo il nostro percorso formativo dedicato:

• Corso Claude Code per Sviluppatori, progettato specificamente per team aziendali che vogliono padroneggiare Claude Code nella sua interezza: dalla CLI ai subagenti, dai workflow agentici all’integrazione con MCP, fino all’uso avanzato in ambienti CI/CD. Un percorso pratico, aggiornato ai rilasci 2026, con esempi reali su codebase aziendali.

Tutti i percorsi Innovaformazione sono erogabili anche tramite Fondimpresa, il fondo paritetico interprofessionale per la formazione continua delle aziende aderenti a Confindustria. Questo significa che la tua azienda può finanziare la formazione dei propri sviluppatori senza costi diretti, attingendo al conto formazione aziendale o attraverso piani formativi condivisi. È un’opportunità concreta che molte aziende non sfruttano ancora a sufficienza: contattaci e ti guidiamo nell’accesso.

Vuoi saperne di più? Contattaci per informazioni e un preventivo personalizzato per la tua azienda:

Email: info@innovaformazione.net

Telefono: 347 101 2275 — Dario Carrassi

Sito: innovaformazione.net

(fonte) (fonte) (fonte)

Per altri articoli tecnici consigliamo di navigare sul nostro blog QUI.