Subagenti

I subagenti personalizzati in Claude Code sono assistenti AI specializzati che possono essere invocati per gestire tipi specifici di attività. Consentono una risoluzione dei problemi più efficiente fornendo configurazioni specifiche per le attività con prompt di sistema personalizzati, strumenti e una finestra di contesto separata.

​

Cosa sono i subagenti?

I subagenti sono personalità AI preconfigurate a cui Claude Code può delegare attività. Ogni subagente:

• Ha uno scopo specifico e un’area di competenza
• Utilizza la propria finestra di contesto separata dalla conversazione principale
• Può essere configurato con strumenti specifici che è autorizzato a utilizzare
• Include un prompt di sistema personalizzato che guida il suo comportamento

Quando Claude Code incontra un’attività che corrisponde all’expertise di un subagente, può delegare quell’attività al subagente specializzato, che lavora indipendentemente e restituisce risultati.

​

Vantaggi principali

​

Avvio rapido

Per creare il tuo primo subagente:

/agents

> Usa il subagente code-reviewer per controllare le mie modifiche recenti

​

Configurazione dei subagenti

​

Posizioni dei file

I subagenti sono memorizzati come file Markdown con frontmatter YAML in due possibili posizioni:

Quando i nomi dei subagenti sono in conflitto, i subagenti a livello di progetto hanno la precedenza sui subagenti a livello utente.

​

Formato del file

Ogni subagente è definito in un file Markdown con questa struttura:

---
name: your-sub-agent-name
description: Descrizione di quando questo subagente dovrebbe essere invocato
tools: tool1, tool2, tool3  # Opzionale - eredita tutti gli strumenti se omesso
---

Il prompt di sistema del tuo subagente va qui. Questo può essere di più paragrafi
e dovrebbe definire chiaramente il ruolo, le capacità e l'approccio del subagente
per risolvere i problemi.

Includi istruzioni specifiche, migliori pratiche e qualsiasi vincolo
che il subagente dovrebbe seguire.

​

Campi di configurazione

​

Strumenti disponibili

I subagenti possono ottenere l’accesso a qualsiasi degli strumenti interni di Claude Code. Vedi la documentazione degli strumenti per una lista completa degli strumenti disponibili.

Hai due opzioni per configurare gli strumenti:

• Ometti il campo tools per ereditare tutti gli strumenti dal thread principale (predefinito), inclusi gli strumenti MCP
• Specifica strumenti individuali come lista separata da virgole per un controllo più granulare (può essere modificato manualmente o tramite /agents)

Strumenti MCP: I subagenti possono accedere agli strumenti MCP dai server MCP configurati. Quando il campo tools è omesso, i subagenti ereditano tutti gli strumenti MCP disponibili al thread principale.

​

Gestione dei subagenti

​

Utilizzo del comando /agents (Raccomandato)

Il comando /agents fornisce un’interfaccia completa per la gestione dei subagenti:

/agents

Questo apre un menu interattivo dove puoi:

• Visualizzare tutti i subagenti disponibili (integrati, utente e progetto)
• Creare nuovi subagenti con configurazione guidata
• Modificare subagenti personalizzati esistenti, incluso il loro accesso agli strumenti
• Eliminare subagenti personalizzati
• Vedere quali subagenti sono attivi quando esistono duplicati
• Gestire facilmente i permessi degli strumenti con una lista completa degli strumenti disponibili

​

Gestione diretta dei file

Puoi anche gestire i subagenti lavorando direttamente con i loro file:

# Crea un subagente di progetto
mkdir -p .claude/agents
echo '---
name: test-runner
description: Usa proattivamente per eseguire test e correggere fallimenti
---

Sei un esperto di automazione dei test. Quando vedi modifiche al codice, esegui proattivamente i test appropriati. Se i test falliscono, analizza i fallimenti e correggili preservando l\'intento originale del test.' > .claude/agents/test-runner.md

# Crea un subagente utente
mkdir -p ~/.claude/agents
# ... crea file subagente

​

Utilizzo efficace dei subagenti

​

Delegazione automatica

Claude Code delega proattivamente le attività basandosi su:

• La descrizione dell’attività nella tua richiesta
• Il campo description nelle configurazioni dei subagenti
• Contesto corrente e strumenti disponibili

​

Invocazione esplicita

Richiedi un subagente specifico menzionandolo nel tuo comando:

> Usa il subagente test-runner per correggere i test falliti
> Fai controllare al subagente code-reviewer le mie modifiche recenti
> Chiedi al subagente debugger di investigare questo errore

​

Esempi di subagenti

​

Revisore di codice

---
name: code-reviewer
description: Specialista esperto nella revisione del codice. Rivede proattivamente il codice per qualità, sicurezza e manutenibilità. Usa immediatamente dopo aver scritto o modificato codice.
tools: Read, Grep, Glob, Bash
---

Sei un revisore senior di codice che assicura alti standard di qualità e sicurezza del codice.

Quando invocato:
1. Esegui git diff per vedere le modifiche recenti
2. Concentrati sui file modificati
3. Inizia immediatamente la revisione

Lista di controllo per la revisione:
- Il codice è semplice e leggibile
- Funzioni e variabili sono ben nominate
- Nessun codice duplicato
- Gestione appropriata degli errori
- Nessun segreto o chiave API esposta
- Validazione dell'input implementata
- Buona copertura dei test
- Considerazioni sulle prestazioni affrontate

Fornisci feedback organizzato per priorità:
- Problemi critici (da correggere)
- Avvertimenti (dovrebbero essere corretti)
- Suggerimenti (considera di migliorare)

Includi esempi specifici di come correggere i problemi.

​

Debugger

---
name: debugger
description: Specialista nel debugging per errori, fallimenti dei test e comportamenti inaspettati. Usa proattivamente quando incontri qualsiasi problema.
tools: Read, Edit, Bash, Grep, Glob
---

Sei un esperto debugger specializzato nell'analisi delle cause radice.

Quando invocato:
1. Cattura messaggio di errore e stack trace
2. Identifica i passaggi di riproduzione
3. Isola la posizione del fallimento
4. Implementa una correzione minima
5. Verifica che la soluzione funzioni

Processo di debugging:
- Analizza messaggi di errore e log
- Controlla le modifiche recenti al codice
- Formula e testa ipotesi
- Aggiungi logging di debug strategico
- Ispeziona gli stati delle variabili

Per ogni problema, fornisci:
- Spiegazione della causa radice
- Evidenza che supporta la diagnosi
- Correzione specifica del codice
- Approccio di testing
- Raccomandazioni per la prevenzione

Concentrati sulla correzione del problema sottostante, non solo sui sintomi.

​

Data scientist

---
name: data-scientist
description: Esperto di analisi dati per query SQL, operazioni BigQuery e insights sui dati. Usa proattivamente per attività di analisi dati e query.
tools: Bash, Read, Write
---

Sei un data scientist specializzato in analisi SQL e BigQuery.

Quando invocato:
1. Comprendi il requisito di analisi dati
2. Scrivi query SQL efficienti
3. Usa strumenti da riga di comando BigQuery (bq) quando appropriato
4. Analizza e riassumi i risultati
5. Presenta i risultati chiaramente

Pratiche chiave:
- Scrivi query SQL ottimizzate con filtri appropriati
- Usa aggregazioni e join appropriati
- Includi commenti che spiegano la logica complessa
- Formatta i risultati per la leggibilità
- Fornisci raccomandazioni basate sui dati

Per ogni analisi:
- Spiega l'approccio della query
- Documenta eventuali assunzioni
- Evidenzia i risultati chiave
- Suggerisci i prossimi passi basati sui dati

Assicurati sempre che le query siano efficienti e convenienti.

​

Migliori pratiche

• Inizia con agenti generati da Claude: Raccomandiamo vivamente di generare il tuo subagente iniziale con Claude e poi iterare su di esso per renderlo personalmente tuo. Questo approccio ti dà i migliori risultati - una base solida che puoi personalizzare per le tue esigenze specifiche.

• Progetta subagenti focalizzati: Crea subagenti con responsabilità singole e chiare piuttosto che cercare di far fare tutto a un subagente. Questo migliora le prestazioni e rende i subagenti più prevedibili.

• Scrivi prompt dettagliati: Includi istruzioni specifiche, esempi e vincoli nei tuoi prompt di sistema. Più guida fornisci, meglio il subagente performerà.

• Limita l’accesso agli strumenti: Concedi solo gli strumenti necessari per lo scopo del subagente. Questo migliora la sicurezza e aiuta il subagente a concentrarsi su azioni rilevanti.

• Controllo versione: Controlla i subagenti di progetto nel controllo versione così il tuo team può beneficiarne e migliorarli collaborativamente.

​

Utilizzo avanzato

​

Concatenazione di subagenti

Per flussi di lavoro complessi, puoi concatenare più subagenti:

> Prima usa il subagente code-analyzer per trovare problemi di prestazioni, poi usa il subagente optimizer per correggerli

​

Selezione dinamica dei subagenti

Claude Code seleziona intelligentemente i subagenti basandosi sul contesto. Rendi i tuoi campi description specifici e orientati all’azione per i migliori risultati.

​

Considerazioni sulle prestazioni

• Efficienza del contesto: Gli agenti aiutano a preservare il contesto principale, abilitando sessioni complessive più lunghe
• Latenza: I subagenti iniziano con una tabula rasa ogni volta che vengono invocati e possono aggiungere latenza mentre raccolgono il contesto di cui hanno bisogno per svolgere efficacemente il loro lavoro.

​

Documentazione correlata

• Comandi slash - Impara altri comandi integrati
• Impostazioni - Configura il comportamento di Claude Code
• Hook - Automatizza i flussi di lavoro con gestori di eventi