- Preservare il contesto mantenendo l’esplorazione e l’implementazione fuori dalla tua conversazione principale
- Applicare vincoli limitando quali strumenti un subagent può utilizzare
- Riutilizzare configurazioni tra progetti con subagent a livello utente
- Specializzare il comportamento con prompt di sistema focalizzati per domini specifici
- Controllare i costi instradando le attività a modelli più veloci e economici come Haiku
Subagent integrati
Claude Code include subagent integrati che Claude utilizza automaticamente quando appropriato. Ognuno eredita le autorizzazioni della conversazione principale con restrizioni di strumenti aggiuntive.- Explore
- Plan
- General-purpose
- Other
Un agente veloce e di sola lettura ottimizzato per la ricerca e l’analisi delle basi di codice.
- Modello: Haiku (veloce, bassa latenza)
- Strumenti: Strumenti di sola lettura (accesso negato agli strumenti Write e Edit)
- Scopo: Scoperta di file, ricerca di codice, esplorazione della base di codice
Quickstart: crea il tuo primo subagent
I subagent sono definiti in file Markdown con frontmatter YAML. Puoi crearli manualmente o utilizzare il comando slash/agents.
Questa procedura ti guida attraverso la creazione di un subagent a livello utente con il comando /agent. Il subagent esamina il codice e suggerisce miglioramenti per la base di codice.
1
Apri l'interfaccia dei subagent
In Claude Code, esegui:
2
Crea un nuovo agente a livello utente
Seleziona Create new agent, quindi scegli User-level. Questo salva il subagent in
~/.claude/agents/ in modo che sia disponibile in tutti i tuoi progetti.3
Genera con Claude
Seleziona Generate with Claude. Quando richiesto, descrivi il subagent:Claude genera il prompt di sistema e la configurazione. Premi
e per aprirlo nel tuo editor se vuoi personalizzarlo.4
Seleziona gli strumenti
Per un revisore di sola lettura, deseleziona tutto tranne Read-only tools. Se mantieni tutti gli strumenti selezionati, il subagent eredita tutti gli strumenti disponibili per la conversazione principale.
5
Seleziona il modello
Scegli quale modello utilizza il subagent. Per questo agente di esempio, seleziona Sonnet, che bilancia capacità e velocità per analizzare i pattern di codice.
6
Scegli un colore
Scegli un colore di sfondo per il subagent. Questo ti aiuta a identificare quale subagent è in esecuzione nell’interfaccia utente.
7
Salva e prova
Salva il subagent. È disponibile immediatamente (non è necessario riavviare). Provalo:Claude delega al tuo nuovo subagent, che scansiona la base di codice e restituisce suggerimenti di miglioramento.
Configura i subagent
Usa il comando /agents
Il comando/agents fornisce un’interfaccia interattiva per gestire i subagent. Esegui /agents per:
- Visualizzare tutti i subagent disponibili (integrati, utente, progetto e plugin)
- Creare nuovi subagent con configurazione guidata o generazione Claude
- Modificare la configurazione del subagent esistente e l’accesso agli strumenti
- Eliminare subagent personalizzati
- Vedere quali subagent sono attivi quando esistono duplicati
Scegli l’ambito del subagent
I subagent sono file Markdown con frontmatter YAML. Archiviali in posizioni diverse a seconda dell’ambito. Quando più subagent condividono lo stesso nome, la posizione con priorità più alta vince.| Posizione | Ambito | Priorità | Come creare |
|---|---|---|---|
Flag CLI --agents | Sessione corrente | 1 (massima) | Passa JSON quando avvii Claude Code |
.claude/agents/ | Progetto corrente | 2 | Interattivo o manuale |
~/.claude/agents/ | Tutti i tuoi progetti | 3 | Interattivo o manuale |
Directory agents/ del plugin | Dove il plugin è abilitato | 4 (minima) | Installato con plugin |
.claude/agents/) sono ideali per subagent specifici di una base di codice. Archiviali nel controllo della versione in modo che il tuo team possa utilizzarli e migliorarli in modo collaborativo.
I subagent utente (~/.claude/agents/) sono subagent personali disponibili in tutti i tuoi progetti.
I subagent definiti da CLI vengono passati come JSON quando avvii Claude Code. Esistono solo per quella sessione e non vengono salvati su disco, rendendoli utili per test rapidi o script di automazione:
--agents accetta JSON con gli stessi campi del frontmatter. Usa prompt per il prompt di sistema (equivalente al corpo markdown nei subagent basati su file). Vedi il riferimento CLI per il formato JSON completo.
I subagent plugin provengono dai plugin che hai installato. Appaiono in /agents insieme ai tuoi subagent personalizzati. Vedi il riferimento dei componenti plugin per i dettagli sulla creazione di subagent plugin.
Scrivi file subagent
I file subagent utilizzano frontmatter YAML per la configurazione, seguito dal prompt di sistema in Markdown:I subagent vengono caricati all’inizio della sessione. Se crei un subagent aggiungendo manualmente un file, riavvia la tua sessione o usa
/agents per caricarlo immediatamente.Campi frontmatter supportati
I seguenti campi possono essere utilizzati nel frontmatter YAML. Soloname e description sono obbligatori.
| Campo | Obbligatorio | Descrizione |
|---|---|---|
name | Sì | Identificatore univoco utilizzando lettere minuscole e trattini |
description | Sì | Quando Claude dovrebbe delegare a questo subagent |
tools | No | Strumenti che il subagent può utilizzare. Eredita tutti gli strumenti se omesso |
disallowedTools | No | Strumenti da negare, rimossi dall’elenco ereditato o specificato |
model | No | Modello da utilizzare: sonnet, opus, haiku, o inherit. Predefinito a sonnet |
permissionMode | No | Modalità di autorizzazione: default, acceptEdits, dontAsk, bypassPermissions, o plan |
skills | No | Skill da caricare nel contesto del subagent all’avvio. Il contenuto completo della skill viene iniettato, non solo reso disponibile per l’invocazione. I subagent non ereditano le skill dalla conversazione principale |
hooks | No | Hook del ciclo di vita limitati a questo subagent |
Scegli un modello
Il campomodel controlla quale modello AI utilizza il subagent:
- Alias del modello: Usa uno degli alias disponibili:
sonnet,opus, ohaiku - inherit: Usa lo stesso modello della conversazione principale (utile per la coerenza)
- Omesso: Se non specificato, utilizza il modello predefinito configurato per i subagent (
sonnet)
Controlla le capacità del subagent
Puoi controllare cosa possono fare i subagent attraverso l’accesso agli strumenti, le modalità di autorizzazione e le regole condizionali.Strumenti disponibili
I subagent possono utilizzare qualsiasi strumento interno di Claude Code. Per impostazione predefinita, i subagent ereditano tutti gli strumenti dalla conversazione principale, inclusi gli strumenti MCP. Per limitare gli strumenti, usa il campotools (allowlist) o il campo disallowedTools (denylist):
Modalità di autorizzazione
Il campopermissionMode controlla come il subagent gestisce i prompt di autorizzazione. I subagent ereditano il contesto di autorizzazione dalla conversazione principale ma possono sovrascrivere la modalità.
| Modalità | Comportamento |
|---|---|
default | Controllo di autorizzazione standard con prompt |
acceptEdits | Auto-accetta modifiche ai file |
dontAsk | Auto-nega prompt di autorizzazione (gli strumenti esplicitamente consentiti funzionano ancora) |
bypassPermissions | Salta tutti i controlli di autorizzazione |
plan | Modalità piano (esplorazione di sola lettura) |
bypassPermissions, questo ha la precedenza e non può essere sovrascritto.
Regole condizionali con hook
Per un controllo più dinamico sull’utilizzo degli strumenti, usa gli hookPreToolUse per convalidare le operazioni prima che vengono eseguite. Questo è utile quando hai bisogno di consentire alcune operazioni di uno strumento mentre ne blocchi altre.
Questo esempio crea un subagent che consente solo query di database di sola lettura convalidando i comandi prima dell’esecuzione:
$TOOL_INPUT e esce con un codice diverso da zero per bloccare le operazioni di scrittura. Vedi Definisci hook per i subagent per ulteriori opzioni di configurazione degli hook.
Disabilita subagent specifici
Puoi impedire a Claude di utilizzare subagent specifici aggiungendoli all’arraydeny nelle tue impostazioni. Usa il formato Task(subagent-name) dove subagent-name corrisponde al campo name del subagent.
--disallowedTools:
Definisci hook per i subagent
I subagent possono definire hook che vengono eseguiti durante il ciclo di vita del subagent. Ci sono due modi per configurare gli hook:- Nel frontmatter del subagent: Definisci hook che vengono eseguiti solo mentre quel subagent è attivo
- In
settings.json: Definisci hook che vengono eseguiti nella sessione principale quando i subagent si avviano o si fermano
Hook nel frontmatter del subagent
Definisci gli hook direttamente nel file markdown del subagent. Questi hook vengono eseguiti solo mentre quel subagent specifico è attivo e vengono puliti quando finisce.| Evento | Input del matcher | Quando si attiva |
|---|---|---|
PreToolUse | Nome dello strumento | Prima che il subagent utilizzi uno strumento |
PostToolUse | Nome dello strumento | Dopo che il subagent utilizza uno strumento |
Stop | (nessuno) | Quando il subagent finisce |
PreToolUse ed esegue un linter dopo le modifiche ai file con PostToolUse:
Stop nel frontmatter vengono automaticamente convertiti in eventi SubagentStop.
Hook a livello di progetto per gli eventi del subagent
Configura gli hook insettings.json che rispondono agli eventi del ciclo di vita del subagent nella sessione principale. Usa il campo matcher per indirizzare tipi di agente specifici per nome.
| Evento | Input del matcher | Quando si attiva |
|---|---|---|
SubagentStart | Nome del tipo di agente | Quando un subagent inizia l’esecuzione |
SubagentStop | Nome del tipo di agente | Quando un subagent completa |
db-agent si avvia e si ferma:
Lavora con i subagent
Comprendi la delega automatica
Claude delega automaticamente le attività in base alla descrizione dell’attività nella tua richiesta, al campodescription nelle configurazioni del subagent e al contesto attuale. Per incoraggiare la delega proattiva, includi frasi come “use proactively” nel campo description del tuo subagent.
Puoi anche richiedere un subagent specifico esplicitamente:
Esegui i subagent in primo piano o in background
I subagent possono essere eseguiti in primo piano (bloccante) o in background (concorrente):- Subagent in primo piano bloccano la conversazione principale fino al completamento. I prompt di autorizzazione e le domande di chiarimento (come
AskUserQuestion) vengono passati a te. - Subagent in background vengono eseguiti contemporaneamente mentre continui a lavorare. Ereditano le autorizzazioni del principale e auto-negano qualsiasi cosa non pre-approvata. Se un subagent in background ha bisogno di un’autorizzazione che non ha o ha bisogno di fare domande di chiarimento, quella chiamata di strumento fallisce ma il subagent continua. Gli strumenti MCP non sono disponibili nei subagent in background.
- Chiedere a Claude di “eseguire questo in background”
- Premere Ctrl+B per mettere in background un’attività in esecuzione
Pattern comuni
Isola operazioni ad alto volume
Uno degli usi più efficaci per i subagent è isolare le operazioni che producono grandi quantità di output. L’esecuzione di test, il recupero della documentazione o l’elaborazione dei file di log possono consumare un contesto significativo. Delegando questi a un subagent, l’output dettagliato rimane nel contesto del subagent mentre solo il riassunto rilevante ritorna alla tua conversazione principale.Esegui ricerche parallele
Per indagini indipendenti, genera più subagent per lavorare simultaneamente:Concatena i subagent
Per flussi di lavoro multi-step, chiedi a Claude di utilizzare i subagent in sequenza. Ogni subagent completa la sua attività e restituisce i risultati a Claude, che poi passa il contesto rilevante al subagent successivo.Scegli tra i subagent e la conversazione principale
Usa la conversazione principale quando:- L’attività ha bisogno di frequenti scambi o affinamento iterativo
- Più fasi condividono un contesto significativo (pianificazione → implementazione → test)
- Stai facendo un cambiamento rapido e mirato
- La latenza è importante. I subagent iniziano da zero e potrebbero aver bisogno di tempo per raccogliere il contesto
- L’attività produce output dettagliato che non hai bisogno nel tuo contesto principale
- Vuoi applicare restrizioni di strumenti specifici o autorizzazioni
- Il lavoro è autonomo e può restituire un riassunto
I subagent non possono generare altri subagent. Se il tuo flusso di lavoro richiede delega annidata, usa Skill o concatena i subagent dalla conversazione principale.
Gestisci il contesto del subagent
Riprendi i subagent
Ogni invocazione di subagent crea una nuova istanza con contesto fresco. Per continuare il lavoro di un subagent esistente invece di ricominciare da capo, chiedi a Claude di riprenderlo. I subagent ripresi mantengono la loro cronologia di conversazione completa, incluse tutte le precedenti chiamate di strumenti, risultati e ragionamento. Il subagent riprende esattamente da dove si era fermato piuttosto che ricominciare da zero. Quando un subagent completa, Claude riceve il suo ID agente. Per riprendere un subagent, chiedi a Claude di continuare il lavoro precedente:~/.claude/projects/{project}/{sessionId}/subagents/. Ogni trascrizione è archiviata come agent-{agentId}.jsonl.
Per l’utilizzo programmatico, vedi Subagent in Agent SDK.
Le trascrizioni dei subagent persistono indipendentemente dalla conversazione principale:
- Compattazione della conversazione principale: Quando la conversazione principale si compatta, le trascrizioni dei subagent non sono interessate. Vengono archiviate in file separati.
- Persistenza della sessione: Le trascrizioni dei subagent persistono all’interno della loro sessione. Puoi riprendere un subagent dopo aver riavviato Claude Code riprendendo la stessa sessione.
- Pulizia automatica: Le trascrizioni vengono pulite in base all’impostazione
cleanupPeriodDays(predefinito: 30 giorni).
Auto-compattazione
I subagent supportano la compattazione automatica utilizzando la stessa logica della conversazione principale. Quando il contesto di un subagent si avvicina al suo limite, Claude Code riassume i messaggi più vecchi per liberare spazio mantenendo il contesto importante. Gli eventi di compattazione vengono registrati nei file di trascrizione del subagent:preTokens mostra quanti token erano stati utilizzati prima che si verificasse la compattazione.
Subagent di esempio
Questi esempi dimostrano pattern efficaci per la costruzione di subagent. Usali come punti di partenza, o genera una versione personalizzata con Claude.Revisore di codice
Un subagent di sola lettura che esamina il codice senza modificarlo. Questo esempio mostra come progettare un subagent focalizzato con accesso limitato agli strumenti (nessun Edit o Write) e un prompt dettagliato che specifica esattamente cosa cercare e come formattare l’output.Debugger
Un subagent che può sia analizzare che correggere i problemi. A differenza del revisore di codice, questo include Edit perché correggere i bug richiede la modifica del codice. Il prompt fornisce un flusso di lavoro chiaro dalla diagnosi alla verifica.Data scientist
Un subagent specifico del dominio per il lavoro di analisi dei dati. Questo esempio mostra come creare subagent per flussi di lavoro specializzati al di fuori dei tipici compiti di codifica. Imposta esplicitamentemodel: sonnet per un’analisi più capace.
Prossimi step
Ora che comprendi i subagent, esplora queste funzionalità correlate:- Distribuisci i subagent con i plugin per condividere i subagent tra team o progetti
- Esegui Claude Code a livello programmatico con Agent SDK per CI/CD e automazione
- Usa i server MCP per dare ai subagent l’accesso a strumenti e dati esterni