I subagent di Claude Code spiegati (con esempi)

Cos'e davvero un subagent

Ogni subagent gira nella propria context window con il proprio system prompt, un accesso ai tool specifico e permessi indipendenti. Quando Claude incontra un compito che corrisponde alla descrizione di un subagent, delega a quel subagent, che lavora in modo indipendente e restituisce il suo risultato. La parola chiave e isolamento: tutto il lavoro intermedio disordinato, la dozzina di file che ha letto, gli approcci falliti, l'output grezzo dei comandi, resta nella finestra del subagent e non tocca mai la conversazione principale. L'agente principale riceve solo la conclusione.

• Context window separata: il subagent non eredita tutta la tua conversazione principale.
• System prompt pulito: un briefing corto e mirato, calibrato sul suo unico compito.
• Tool e permessi ristretti: solo cio di cui il compito ha bisogno, spesso in read-only.
• Restituisce un riassunto: il lavoro rumoroso e assorbito, la sessione principale riceve il risultato pulito.

Quando usare un subagent

Ricorri a un subagent quando un compito accessorio inonderebbe la tua conversazione principale di risultati di ricerca, log o contenuti di file a cui non tornerai mai. Il subagent fa quel lavoro nel proprio contesto e restituisce solo la risposta, cosi la tua finestra principale resta pulita ed eviti la falesia di prestazioni che colpisce quando una context window si riempie di rumore. Definisci un subagent dedicato quando lanci continuamente lo stesso tipo di lavoratore con le stesse istruzioni: un code reviewer, uno scrittore di test, un generatore di documentazione.

• Risparmiare contesto: tieni esplorazione e lettura di massa fuori dalla tua conversazione principale.
• Imporre vincoli: limita un subagent ai tool read-only, cosi un reviewer non puo modificare.
• Specializzare il comportamento: un system prompt mirato lo rende piu affidabile sul suo unico compito.
• Pilotare i costi: dirigi il lavoro ristretto verso un modello piu veloce ed economico come Haiku.

I subagent integrati che hai gia

Claude Code fornisce subagent integrati che usa automaticamente, quindi ne trai beneficio ancora prima di crearne uno. Explore e un agente veloce, read-only, per esplorare e comprendere una codebase, spesso su Haiku per restare economico. Plan e l'agente di ricerca che raccoglie il contesto in modalita plan prima di proporre un piano. General-purpose gestisce i compiti complessi e multi-step che richiedono sia esplorazione sia modifiche. Puoi bloccare un tipo integrato via i permessi se serve, ma il piu delle volte li lasci fare il loro lavoro.

• Explore: ricerca e analisi rapide e read-only della codebase (spesso Haiku).
• Plan: agente di ricerca read-only che raccoglie il contesto in modalita plan.
• General-purpose: agente con tutti i tool per lavoro complesso e multi-step.

Creare il tuo subagent

I subagent sono file Markdown con un frontmatter YAML. Il modo piu semplice di crearne uno e il comando /agents, che apre un'interfaccia guidata dove nomini il subagent, scrivi la sua descrizione, scegli i suoi tool e il suo modello, e puoi lasciare che Claude scriva il system prompt per te. I subagent di progetto vivono in .claude/agents/ (fai commit di questi nella version control cosi la tua squadra li condivide); quelli personali vivono in ~/.claude/agents/ e ti seguono da un progetto all'altro. Nel frontmatter, solo name e description sono obbligatori; la description e cio che Claude legge per decidere quando delegare, quindi scrivila con chiarezza.

<!-- .claude/agents/code-reviewer.md -->
---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. When invoked, analyse the changed code and
return a concise, prioritised list of issues covering correctness, security
and readability. Do not edit files; only report. Cite the file and line for
each issue and suggest the smallest fix.

I file creati direttamente sul disco vengono caricati all'avvio della sessione, quindi riavvia Claude Code (o crealo via /agents, che ha effetto immediato) per far riconoscere un nuovo file. Il campo model accetta sonnet, opus, haiku o inherit; il campo tools eredita per default tutti i tool se lo ometti.

Invocare i subagent e lavorare con loro

Il piu delle volte, non invochi un subagent a mano: Claude legge la descrizione di ogni subagent e delega automaticamente quando un compito corrisponde. Puoi anche attivarlo esplicitamente, per esempio "usa l'agente code-reviewer per rivedere questo diff". Un buon motivo e scrivere la funzionalita con il tuo agente principale poi delegare la review a un subagent reviewer read-only, che ispeziona il diff nel proprio contesto e restituisce una lista concisa di problemi, dopodiche l'agente principale li corregge. Poiche il ragionamento di review non e mai stato caricato nella tua finestra principale, la sessione resta pulita.

Passo dopo passo

1. 01

   Aprire l'interfaccia dei subagent

   In una sessione Claude Code, esegui /agents per aprire l'interfaccia guidata di creazione e gestione dei subagent.

2. 02

   Scegliere uno scope e creare

   Scegli Project (.claude/agents/, condiviso via version control) o Personal (~/.claude/agents/, tutti i tuoi progetti), poi crea un nuovo agente. Puoi lasciare che Claude generi l'identificativo, la descrizione e il system prompt.

3. 03

   Scrivere una descrizione chiara

   La descrizione e cio con cui Claude decide quando delegare, quindi dici esattamente quando questo subagent va usato. name e description sono gli unici campi obbligatori.

4. 04

   Restringere tool e modello

   Limita i tool a cio di cui il compito ha bisogno (per un reviewer: read-only), e scegli un modello. Dirigi il lavoro ristretto verso un modello piu economico come Haiku per pilotare i costi.

5. 05

   Salvare e provare

   Salva il subagent e testalo chiedendo a Claude di usarlo. Se hai creato il file direttamente sul disco, riavvia la sessione perche venga caricato.

Domande frequenti

Continua a imparare