Creare subagent personalizzati

• Preservare il contesto mantenendo l’esplorazione e l’implementazione fuori dalla sua 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 ed economici come Haiku

​

Subagent integrati

• Per bloccare un tipo integrato specifico, aggiungetelo a permissions.deny come mostrato in Disabilitare subagent specifici.
• Per impedire a Claude di delegare a qualsiasi subagent, negate lo strumento Agent stesso con permissions.deny.
• Per rimuovere solo i subagent integrati Explore e Plan, impostate CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude legge ed esplora i file direttamente invece di delegare a loro. Richiede Claude Code v2.1.198 o successivo.
• In modalità non interattiva e in Agent SDK, impostate CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 per rimuovere tutti i tipi integrati e fornire solo i vostri.

​

Guida rapida: crea il tuo primo subagent

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Use the code-improver agent to suggest improvements in this project

​

Configuri i subagent

​

Scelga l’ambito del subagent

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"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

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"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

• prompt: il prompt di sistema dell’agente, equivalente al corpo markdown nei subagent basati su file. prompt può essere vuoto. Se seleziona un agente con un prompt vuoto e nessun campo memory come agente della sessione con --agent, il prompt di sistema della sessione rimane invariato. Un prompt vuoto richiede Claude Code v2.1.281 o successivo.
• Campi del frontmatter: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, effort, background, omitClaudeMd e isolation.
• Campi ignorati: color e experimental non vengono accettati qui e vengono ignorati piuttosto che rifiutati.

​

Scriva file subagent

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

• Blocca un comando che reindirizza git nel checkout principale.
• Rifiuta un comando quando non può verificare dal testo del comando che qualsiasi git che il comando esegue rimane all’interno del worktree, ad esempio quando il nome del comando viene calcolato al runtime.

​

Riferimento frontmatter

• Per trovare un campo scritto in modo errato in un subagent che è stato caricato, esegui claude --debug nella tua shell e cerca does not recognize or apply nel log di debug in ~/.claude/debug/<session-id>.txt. Il log di debug indica fino a cinque campi di primo livello nel file del subagent che Claude Code non riconosce, con il nome probabilmente previsto quando un campo supportato è simile. Richiede Claude Code v2.1.296 o successivo.
• Per scoprire perché un file di subagent non è stato caricato, consulta File di subagent che Claude Code salta.

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

​

File subagent che Claude Code salta

• No name: Claude Code tratta il file come documentazione mantenuta accanto ai suoi agenti.
• Un --- di apertura che non è la prima riga del file: Claude Code legge il file come non avente frontmatter e lo tratta come documentazione.
• Un name che inizia con -, contiene : o supera i 256 caratteri: Claude Code salta il file e scrive un errore nel log di debug.
• Un name ma nessuna description: Claude Code salta il file e scrive il motivo nel log di debug.
• YAML che non analizza: Claude Code non legge alcun campo dal file, lo salta e scrive l’errore di analisi nel log di debug.

​

Scelga un modello

• Alias modello: usi uno degli alias disponibili: sonnet, opus, haiku, o fable
• ID modello completo: usi un ID modello completo come claude-opus-5-5 o claude-sonnet-5. Accetta gli stessi valori del flag --model
• inherit: usi lo stesso modello della conversazione principale

1. Il parametro model per invocazione
2. Il frontmatter model della definizione del subagent, dove inherit seleziona il modello della conversazione principale
3. La variabile di ambiente CLAUDE_CODE_SUBAGENT_MODEL, quando la imposta su un alias modello o ID modello
4. Il modello della conversazione principale

• Il modello della conversazione principale appartiene a quella famiglia: il subagent viene eseguito sul modello esatto della conversazione principale, incluso qualsiasi suffisso [1m], quindi ottiene la stessa finestra di contesto esteso della conversazione principale.
• Claude Code non può dire la famiglia del modello della conversazione principale, su un provider diverso dall’API Anthropic: questo può accadere con un ARN del profilo di inferenza dell’applicazione su Amazon Bedrock che Claude Code non ha risolto a un modello di supporto. Questo caso copre solo l’alias opus, e non si applica quando imposta ANTHROPIC_DEFAULT_OPUS_MODEL, poiché opus allora si risolve al modello che imposta.

• Quando il valore bloccato è un alias di famiglia come opus, Claude Code esegue il subagent sulla versione più recente di quella famiglia che la lista di consentimento consente, seguendo le stesse regole di sostituzione e ambito del provider di /model. Prima di v2.1.222, Claude Code eseguiva il subagent sul modello ereditato anche per un alias di famiglia bloccato.
• Per qualsiasi altro valore bloccato, su provider dove quella sostituzione non opera, o quando la lista di consentimento non consente alcuna versione della famiglia, Claude Code esegue il subagent sul modello ereditato. Se imposta CLAUDE_CODE_SUBAGENT_MODEL, Claude Code prova prima quel modello, secondo le stesse regole.

​

Esegui ogni subagent su un modello

• Se imposta entrambe le variabili, i subagent vengono eseguiti sul modello in CLAUDE_CODE_SUBAGENT_MODEL.
• Se imposti solo CLAUDE_CODE_SUBAGENT_MODEL_FORCE, i subagent vengono eseguiti sul modello della conversazione principale, tranne il subagent integrato Explore, che viene eseguito sul modello indicato per esso in Subagent integrati.

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

• Un fork
• Una skill che viene eseguita in un subagent con model: inherit

​

Scegliere un livello di sforzo

​

Controlli le capacità del subagent

​

Strumenti disponibili

• Agent, quando il subagent è al limite di profondità; in un fork lo strumento rimane elencato ma restituisce un errore invece di generare
• AskUserQuestion
• EndConversation, che può terminare solo la conversazione principale; consulti Comportamento dello strumento EndConversation
• EnterPlanMode
• ExitPlanMode, a meno che la permissionMode del subagent non sia plan
• ScheduleWakeup
• WaitForMcpServers
• Workflow

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

​

Limiti quali subagent possono essere generati

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

tools: Agent, Read, Bash

​

Limiti i server MCP a un subagent

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

• --strict-mcp-config e --bare
• Configurazione MCP gestita aziendale
• Policy allowedMcpServers e deniedMcpServers

​

Fiducia richiesta per i server MCP inline

• Fiducia che non conta: la fiducia di una cartella principale, e la fiducia automatica che una sessione -p o SDK ottiene per hook nei file di impostazioni
• Fino ad allora: Claude Code salta ogni server inline in quel file agente e scrive la chiave esatta projects["<path>"].hasTrustDialogAccepted per ~/.claude.json nel log di debug
• Directory --add-dir: una directory al di fuori del repository dell’area di lavoro fidata ha bisogno della sua voce di fiducia, poiché i suoi file .claude/agents/ non ereditano la fiducia dell’area di lavoro

• Un nome che fa riferimento a un server che ha già configurato
• Un server inline in un file agente da ~/.claude/agents/, in uno che passa con --agents o l’opzione SDK agents, o in uno che le impostazioni gestite forniscono

​

Modalità di autorizzazione

• Quando la conversazione principale è in bypassPermissions, acceptEdits, o auto mode, il subagent viene eseguito in quella stessa modalità e Claude Code ignora il permissionMode che imposta. Sotto auto mode, il classificatore valuta le chiamate di strumenti del subagent con le regole di blocco e consentimento della conversazione principale. Quando il subagent finisce, il classificatore esamina anche il suo lavoro e il suo rapporto finale prima che il rapporto venga consegnato, come Come auto mode gestisce i subagent descrive.
• Quando la conversazione principale è in modalità default, dontAsk o plan, il subagent viene eseguito nella modalità di permesso che imposti. Mantiene invece la modalità di permesso della conversazione principale in questi casi:
  • Imposti bypassPermissions. L’eccezione per bypassPermissions richiede Claude Code v2.1.267 o successivo.
  • Imposti auto e la modalità auto non è disponibile per il subagent, ad esempio quando un file di impostazioni imposta disableAutoMode o il modello del subagent non supporta la modalità auto.

​

Precarichi skills nei subagent

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

​

Abiliti memoria persistente

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

• Il prompt di sistema del subagent include istruzioni per leggere e scrivere nella directory di memoria.
• Il prompt di sistema del subagent include anche le prime 200 righe o 25KB di MEMORY.md nella directory di memoria, a seconda di quale sia minore, con istruzioni per curare MEMORY.md se supera quel limite.
• Gli strumenti Read, Write e Edit vengono automaticamente abilitati in modo che il subagent possa gestire i suoi file di memoria.

• project è l’ambito predefinito consigliato. Lo rende condivisibile tramite controllo della versione.
• Chieda al subagent di consultare la sua memoria prima di iniziare il lavoro: “Review this PR, and check your memory for patterns you’ve seen before.”
• Chieda al subagent di aggiornare la sua memoria dopo aver completato un’attività: “Now that you’re done, save what you learned to your memory.” Nel tempo, questo costruisce una base di conoscenza che rende il subagent più efficace.
• Includa istruzioni di memoria direttamente nel file markdown del subagent in modo che mantenga proattivamente la sua stessa base di conoscenza:
  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.
  

​

Regole condizionali con hooks

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

chmod +x ./scripts/validate-readonly-query.sh

​

Disabiliti subagent specifici

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

claude --disallowedTools "Agent(Explore)"

​

Definisca hook per i subagent

• Nel frontmatter del subagent: definisca hook che vengono eseguiti solo mentre quel subagent è attivo
• In settings.json: definisca hook a livello di sessione che si attivano anche all’interno dei subagent. Gli eventi degli strumenti come PreToolUse e PostToolUse si attivano per le chiamate di strumenti del subagent allo stesso modo che nella conversazione principale, e SubagentStart e SubagentStop si attivano quando un subagent inizia o finisce

​

Hook nel frontmatter del subagent

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

​

Hook a livello di progetto per gli eventi dei subagent

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

​

Lavorare con i subagent

​

Comprendere la delega automatica

​

Invocare i subagent esplicitamente

• Linguaggio naturale: nomina il subagent nel tuo prompt; Claude decide se delegare
• @-mention: garantisce che il subagent venga eseguito per un’attività
• Per l’intera sessione: l’intera sessione viene eseguita come quel subagent tramite il flag --agent o l’impostazione agent

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@"code-reviewer (agent)" look at the auth changes

claude --agent code-reviewer

claude --agent security-reviewer

claude --agent my-plugin:security-reviewer

{
  "agent": "code-reviewer"
}

​

Eseguire i subagent in primo piano o in background

• I subagent in primo piano bloccano la conversazione principale fino al completamento. Le richieste di permesso ti vengono inoltrate man mano che si presentano.
• I subagent in background vengono eseguiti in parallelo mentre continui a lavorare. Quando un subagent in background arriva a una chiamata a uno strumento che richiede un permesso, Claude Code mostra la richiesta nella tua sessione principale e indica il subagent che la sta facendo. Approva per lasciare che il subagent continui, oppure premi Esc per negare quella singola chiamata allo strumento senza fermare il subagent.

• Se a generare il subagent è stato un membro in-process di un team di agenti, Claude Code lo esegue in primo piano. Claude Code rifiuta con un errore di avviare il subagent di un membro del team la cui definizione imposta background: true. Dove la modalità fork è disattivata e non hai disattivato le attività in background, Claude Code rifiuta con un errore anche quando un membro del team imposta run_in_background: true.
• Se imposti CLAUDE_CODE_DISABLE_BACKGROUND_TASKS su 1, Claude Code esegue il subagent in primo piano, in ogni tipo di sessione e indipendentemente dal fatto che la modalità fork sia attiva.
• Dove la modalità fork è attiva, come avviene per impostazione predefinita in una sessione interattiva, Claude Code esegue il subagent in background, sia che si tratti di fork sia di subagent non fork, e Claude non può chiedere il primo piano.
• Dove la modalità fork è disattivata, Claude esegue il subagent in background per impostazione predefinita e in primo piano quando ha bisogno del risultato prima di continuare. La modalità fork è disattivata in modalità non interattiva con -p e nell’Agent SDK, a meno che tu non la attivi. Per mantenere in background un particolare subagent anche quando Claude vuole il risultato, imposta su true il campo background nel suo frontmatter.

• Dove la modalità fork è disattivata, chiedi a Claude di eseguire un’attività in background o in primo piano
• Premi Ctrl+B per spostare in background un’attività in esecuzione

• Quando un subagent termina con successo, Claude Code rimuove subito la sua riga e, tranne che in modalità screen reader, mostra /tasks to see subagents nel footer per 30 secondi. Durante questi 30 secondi, esegui /tasks e premi Enter sul subagent per aprirne la trascrizione. Prima della v2.1.232, Claude Code manteneva la riga per 30 secondi dopo la fine del subagent, come per uno non riuscito, e non mostrava alcun suggerimento nel footer.
• Quando un subagent fallisce o lo fermi, Claude Code mantiene la sua riga per 30 secondi. Per rimuovere la riga prima, selezionala e premi x.

​

Nomi dei subagent

​

Errori API nei subagent

• Primo piano: se un rate limit, un sovraccarico o un errore del server interrompe un subagent che ha già prodotto output testuale, lo strumento Agent restituisce quell’output parziale con una nota che indica che il subagent è stato interrotto e non ha completato la sua attività. Un subagent che non ha prodotto nulla, o il cui unico output erano chiamate agli strumenti, fallisce con Agent terminated early due to an API error, seguito dal dettaglio dell’errore.
• Background: il subagent viene contrassegnato come non riuscito, e il messaggio che Claude riceve quando termina indica l’errore API e include l’ultimo output del subagent, così il lavoro parziale non va perso.

​

Scansione dell’output dei subagent

• Inserimento di backslash: la scansione inserisce un backslash nel testo che imita l’output di Claude Code stesso, come un tag <system-reminder> o una riga che inizia con Human: o Assistant:, in modo che l’imitazione venga letta come testo normale invece di essere scambiata per parte della conversazione.
• Riga marcatore: la scansione antepone una riga che inizia con [harness: subagent output matched instruction-shaped pattern(s): quando il rapporto imita un tag come <system-reminder> o menziona impostazioni dei permessi come bypassPermissions o --dangerously-skip-permissions. Le menzioni di impostazioni dei permessi ricevono la riga marcatore, ma il testo stesso resta com’è scritto.

​

Schemi comuni

​

Isolare le operazioni ad alto volume

Use a subagent to run the test suite and report only the failing tests with their error messages

​

Eseguire ricerche in parallelo

Research the authentication, database, and API modules in parallel using separate subagents

​

Concatenare i subagent

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

​

Scegliere tra subagent e conversazione principale

• L’attività richiede scambi frequenti o un perfezionamento iterativo
• Più fasi condividono molto contesto, come pianificazione, implementazione e test
• Stai facendo una modifica rapida e mirata
• La latenza è importante. Un subagent che non è un fork parte da zero e potrebbe aver bisogno di tempo per raccogliere il contesto

• L’attività produce output dettagliato che non ti serve nel contesto principale
• Vuoi imporre restrizioni specifiche sugli strumenti o sui permessi
• Il lavoro è autonomo e può restituire un riepilogo

​

Permettere ai subagent di avviare i propri subagent

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

​

Limite di subagent simultanei

• Un fork all’interno della sessione che avvii con /subtask occupa un posto mentre è in esecuzione e non viene mai bloccato dal limite.
• Riprendere un subagent che ha già terminato occupa un nuovo posto senza verificare il limite, quindi le riprese possono portare il numero di subagent in esecuzione oltre il limite.

​

Gestire il contesto dei subagent

​

Cosa viene caricato all’avvio

• Prompt di sistema: il prompt dell’agente stesso più i dettagli sull’ambiente che Claude Code aggiunge, non il prompt di sistema di Claude Code. I subagent personalizzati definiscono il proprio nel corpo markdown o nel campo prompt. Gli agenti integrati hanno prompt predefiniti.
• Messaggio dell’attività: il prompt di delega che Claude scrive quando passa il lavoro.
• File CLAUDE.md: ogni livello della gerarchia CLAUDE.md caricato dalla conversazione principale, inclusi ~/.claude/CLAUDE.md, le regole del progetto, CLAUDE.local.md, i file di policy gestiti ed eventuali file AGENTS.md caricati come istruzioni del progetto. Gli agenti integrati Explore e Plan li saltano. Un subagent la cui definizione imposta omitClaudeMd carica solo i file di policy gestiti, oppure nessuno quando la definizione proviene dalle impostazioni gestite.
• Stato Git: uno snapshot che Claude Code legge dal tuo repository all’avvio del subagent. Per un subagent nel proprio worktree di quel repository, lo snapshot mostra il branch, lo stato e i commit recenti del worktree. Assente al di fuori di un repository Git o quando lo snapshot è disattivato; consulta includeGitInstructions. Explore e Plan lo saltano in ogni caso.
• Skill precaricate: il contenuto completo di ogni skill indicata nel campo skills dell’agente. Gli agenti integrati non precaricano skill.
• Elenco degli agenti fratelli: un promemoria di sistema che elenca main e ogni altro agente con nome nella sessione, ciascuno un valore to valido per SendMessage. L’elenco compare solo quando gli strumenti del subagent includono SendMessage e almeno un altro agente ha un nome, sia che Claude gliel’abbia dato al momento dell’avvio, sia che venga eseguito come membro di un team di agenti. È uno snapshot acquisito all’avvio del subagent, quindi gli agenti che ricevono un nome in seguito non compaiono.

• Stile di output: un subagent esegue il proprio prompt di sistema, quindi il tuo stile di output non influenza le sue risposte, tranne che in un fork.
• Memoria automatica: la memoria automatica della conversazione principale non viene caricata. Per dare a un subagent una memoria persistente propria, usa il campo memory.
• Dimensione della finestra di contesto: la finestra di contesto di un subagent è dimensionata in base al suo modello, non a quello del padre. Delegare a un modello con una finestra più piccola dà a quel subagent la finestra più piccola.

​

Riprendere i subagent

• Quando un subagent termina, Claude riceve il suo ID agente.
• Gli agenti integrati Explore e Plan sono monouso e non restituiscono alcun ID agente, quindi Claude non può riprenderli. Usa general-purpose o un subagent personalizzato quando devi proseguire il lavoro.
• Quando un subagent si ferma al limite maxTurns, Claude Code contrassegna l’output restituito come parziale e Claude può riprendere il subagent per fargli proseguire il lavoro.

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

• Compattazione della conversazione principale: quando la conversazione principale viene compattata, le trascrizioni dei subagent non ne risentono. Sono salvate 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: Claude Code elimina le trascrizioni dei subagent dopo il periodo di conservazione cleanupPeriodDays, di 30 giorni per impostazione predefinita, secondo le regole di pulizia della conservazione.

​

Compattazione automatica

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

---
name: log-reader
description: Reads long log files and reports the errors it finds
autoCompactWindow: 200000
---

• Il valore non è inferiore alla finestra di compattazione automatica che il subagent erediterebbe altrimenti: per compattare prima, imposta un valore inferiore a quella finestra.
• Esegui l’intera sessione come questo subagent con --agent o con l’impostazione agent: in quel caso il campo non ha effetto. Per impostare la finestra della sessione, consulta Impostare la finestra di compattazione automatica.

​

Esegua il fork della conversazione corrente

/subtask draft unit tests for the parser changes so far

​

Osservi e dirija i fork in esecuzione

• /compact, /clear e /rewind agiscono sulla conversazione principale, quindi Claude Code ti chiede conferma prima di eseguirne uno da questa visualizzazione.
• /model e /fast impostano il modello e la modalità veloce della conversazione principale, non quelli dell’agente visualizzato, quindi non vengono eseguiti da questa visualizzazione. Un avviso ti spiega il motivo.

​

Come i fork differiscono dai subagent non-fork

​

Attivi o disattivi la modalità fork

• Claude può generare un fork richiedendo il tipo di subagent fork. Quando Claude non richiede un tipo, ottiene il subagent general-purpose, se la sessione ha ancora quel tipo. I subagent generati da una definizione, come Explore, funzionano come al solito.
• Claude Code esegue i subagent che Claude genera in background, sia i fork che i subagent non-fork, a parte i casi che rimangono in primo piano. Claude Code rimuove anche il parametro run_in_background dello strumento Agent, in modo che Claude non possa chiedere il primo piano.

• 1 attiva la modalità fork in modalità non interattiva e nell’Agent SDK
• 0 disattiva la modalità fork in ogni tipo di sessione

​

Subagent 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 clear 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 the 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.

​

Database query validator

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

chmod +x ./scripts/validate-readonly-query.sh

​

Passaggi successivi

• Distribuisca subagent con i plugin per condividere i subagent tra team o progetti
• Esegua Claude Code a livello di programmazione con l’Agent SDK per CI/CD e automazione
• Usi i server MCP per dare ai subagent accesso a strumenti e dati esterni