Subagenti

​

Cosa sono i subagenti?

• 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

​

Vantaggi principali

​

Avvio rapido

/agents

> Usa il subagente code-reviewer per controllare i miei recenti cambiamenti

​

Configurazione del subagente

​

Posizioni dei file

​

Agenti plugin

• Gli agenti plugin appaiono in /agents insieme ai tuoi agenti personalizzati
• Possono essere invocati esplicitamente: “Usa l’agente code-reviewer dal security-plugin”
• Possono essere invocati automaticamente da Claude quando appropriato
• Possono essere gestiti (visualizzati, ispezionati) tramite l’interfaccia /agents

​

Configurazione basata su CLI

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

• Test rapidi delle configurazioni dei subagenti
• Subagenti specifici della sessione che non devono essere salvati
• Script di automazione che necessitano di subagenti personalizzati
• Condivisione di definizioni di subagenti nella documentazione o negli script

​

Formato del file

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
model: sonnet  # Optional - specify model alias or 'inherit'
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

Include specific instructions, best practices, and any constraints
the subagent should follow.

​

Campi di configurazione

​

Selezione del modello

• Alias del modello: Utilizza uno degli alias disponibili: sonnet, opus o haiku
• 'inherit': Utilizza lo stesso modello della conversazione principale (utile per la coerenza)
• Omesso: Se non specificato, utilizza il modello predefinito configurato per i subagenti (sonnet)

​

Strumenti disponibili

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

​

Gestione dei subagenti

​

Utilizzo del comando /agents (Consigliato)

/agents

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

​

Gestione diretta dei file

# Crea un subagente di progetto
mkdir -p .claude/agents
echo '---
name: test-runner
description: Use proactively to run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively run the appropriate tests. If tests fail, analyze the failures and fix them while preserving the original test intent.' > .claude/agents/test-runner.md

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

​

Utilizzo efficace dei subagenti

​

Delega automatica

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

​

Invocazione esplicita

> Usa il subagente test-runner per correggere i test non superati
> Chiedi al subagente code-reviewer di guardare i miei recenti cambiamenti
> Chiedi al subagente debugger di investigare questo errore

​

Subagenti integrati

​

Subagente Plan

• Modello: Utilizza Sonnet per un’analisi più capace
• Strumenti: Ha accesso agli strumenti Read, Glob, Grep e Bash per l’esplorazione del codebase
• Scopo: Cerca file, analizza la struttura del codice e raccoglie il contesto
• Invocazione automatica: Claude utilizza automaticamente questo agente quando è in modalità piano e ha bisogno di ricercare il codebase

User: [In plan mode] Help me refactor the authentication module

Claude: Let me research your authentication implementation first...
[Internally invokes Plan subagent to explore auth-related files]
[Plan subagent searches codebase and returns findings]
Claude: Based on my research, here's my proposed plan...

​

Subagenti di esempio

​

Code reviewer

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

​

Debugger

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not just symptoms.

​

Data scientist

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

​

Best practice

• Inizia con agenti generati da Claude: Ti consigliamo vivamente di generare il tuo subagente iniziale con Claude e quindi iterare su di esso per renderlo personalmente tuo. Questo approccio ti dà i migliori risultati - una base solida che puoi personalizzare in base alle tue esigenze specifiche.
• Progetta subagenti focalizzati: Crea subagenti con responsabilità singole e chiare piuttosto che cercare di fare tutto con 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, migliore sarà le prestazioni del subagente.
• 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 della versione: Controlla i subagenti di progetto nel controllo della versione in modo che il tuo team possa beneficiarne e migliorarli in modo collaborativo.

​

Utilizzo avanzato

​

Concatenamento di subagenti

> Usa prima il subagente code-analyzer per trovare problemi di prestazioni, quindi usa il subagente optimizer per correggerli

​

Selezione dinamica dei subagenti

​

Subagenti riprendibili

• Ogni esecuzione del subagente viene assegnata a un agentId univoco
• La conversazione dell’agente viene archiviata in un file di trascrizione separato: agent-{agentId}.jsonl
• Puoi riprendere un agente precedente fornendo il suo agentId tramite il parametro resume
• Quando ripreso, l’agente continua con il contesto completo dalla sua conversazione precedente

> Usa l'agente code-analyzer per iniziare a rivedere il modulo di autenticazione

[Agent completes initial analysis and returns agentId: "abc123"]

> Riprendi l'agente abc123 e ora analizza anche la logica di autorizzazione

[Agent continues with full context from previous conversation]

• Ricerca di lunga durata: Suddividi l’analisi del codebase di grandi dimensioni in più sessioni
• Perfezionamento iterativo: Continua a perfezionare il lavoro di un subagente senza perdere il contesto
• Flussi di lavoro multi-step: Fai lavorare un subagente su attività correlate in sequenza mantenendo il contesto

• Le trascrizioni degli agenti vengono archiviate nella directory del tuo progetto
• La registrazione è disabilitata durante la ripresa per evitare di duplicare i messaggi
• Sia gli agenti sincroni che asincroni possono essere ripresi
• Il parametro resume accetta l’ID dell’agente da un’esecuzione precedente

{
  "description": "Continue analysis",
  "prompt": "Now examine the error handling patterns",
  "subagent_type": "code-analyzer",
  "resume": "abc123"  // Agent ID from previous execution
}

​

Considerazioni sulle prestazioni

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

​

Documentazione correlata

• Plugin - Estendi Claude Code con agenti personalizzati tramite plugin
• Comandi slash - Scopri altri comandi integrati
• Impostazioni - Configura il comportamento di Claude Code
• Hook - Automatizza i flussi di lavoro con gestori di eventi