--- title: "I subagent di Claude Code spiegati (con esempi)" description: "Cosa sono i subagent di Claude Code, quando usarli e come crearne uno in .claude/agents con un frontmatter YAML. Subagent integrati, esempi e il comando /agents." type: "guide" locale: "it" category: "Claude Code" canonical: "https://agenticschool.dev/it/guide/claude-code-subagents" datePublished: "2026-06-13" dateModified: "2026-06-13" --- # I subagent di Claude Code spiegati (con esempi) - Category: Claude Code - Keywords: claude code subagents, claude code agents, how to create a subagent, claude code agent teams, subagent vs main agent - Canonical URL: https://agenticschool.dev/it/guide/claude-code-subagents - Locale: it > Cosa sono i subagent di Claude Code, quando usarli e come crearne uno in .claude/agents con un frontmatter YAML. Subagent integrati, esempi e il comando /agents. Un subagent Claude Code e un assistente specializzato a cui l'agente principale delega un compito mirato, che gira nella propria context window separata con il proprio system prompt e il proprio set ristretto di tool. Invece che la sessione principale faccia tutto e si riempia di output rumoroso, passa un lavoro (rivedi questo codice, ricerca questa domanda, esegui questi test) a un subagent che lavora in isolamento e restituisce solo un riassunto pulito. Questa guida spiega cosa sono i subagent, quando valgono la pena, quali subagent integrati fornisce Claude Code e esattamente come crearne di tuoi con il comando /agents o un file Markdown in .claude/agents. ## 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. ```markdown --- 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. ``` Un vero subagent code reviewer read-only sotto .claude/agents/code-reviewer.md. Solo name e description sono obbligatori. 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. ## Steps ### 1. Aprire l'interfaccia dei subagent In una sessione Claude Code, esegui /agents per aprire l'interfaccia guidata di creazione e gestione dei subagent. ### 2. 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. 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. 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. 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. ## FAQ ### Cos'e un subagent Claude Code? E un assistente specializzato a cui l'agente principale delega un compito mirato. Ogni subagent gira nella propria context window con il proprio system prompt, tool ristretti e permessi indipendenti, fa il lavoro in isolamento e restituisce solo un riassunto, cosi la conversazione principale resta pulita. ### Dove vivono i subagent Claude Code? I subagent di progetto vivono in .claude/agents/ nel tuo repo (fai commit di questi cosi la tua squadra li condivide). I subagent personali vivono in ~/.claude/agents/ e sono disponibili su tutti i tuoi progetti. Ognuno e un file Markdown con un frontmatter YAML. ### Come creo un subagent in Claude Code? Esegui /agents per aprire l'interfaccia guidata, scegli uno scope (project o personal), scrivi una descrizione chiara, restringi tool e modello, e salva. Puoi anche creare il file Markdown a mano in .claude/agents/, con name e description nel frontmatter, poi riavviare la sessione perche venga caricato. ### Quando dovrei usare un subagent invece dell'agente principale? Usane uno quando un compito accessorio inonderebbe la tua conversazione principale di output che non riusi, come leggere, cercare o rivedere tanti file. Il subagent assorbe quel rumore nel proprio contesto e restituisce solo il risultato, mantiene la tua finestra principale pulita ed evita la falesia di contesto. ### Un subagent condivide il contesto dell'agente principale? No. Un subagent gira in una context window separata e vede solo il proprio system prompt e il compito delegato, non tutta la tua conversazione. Questo isolamento e tutto il punto: impedisce al contesto principale di riempirsi di rumore. ### Un subagent puo usare un modello piu economico del mio agente principale? Si. Metti il campo model nel frontmatter del subagent su haiku (o sonnet, opus o inherit). Dirigere i compiti ristretti di estrazione o review verso un modello veloce ed economico mentre il tuo agente principale usa un modello piu potente e un buon modo di pilotare i costi.