Criar subagentes personalizados

• Preservar contexto mantendo exploração e implementação fora de sua conversa principal
• Aplicar restrições limitando quais ferramentas um subagente pode usar
• Reutilizar configurações entre projetos com subagentes no nível do usuário
• Especializar comportamento com prompts de sistema focados para domínios específicos
• Controlar custos roteando tarefas para modelos mais rápidos e baratos como Haiku

Subagentes integrados

• Para bloquear um tipo integrado específico, adicione-o a permissions.deny conforme mostrado em Desabilitar subagentes específicos.
• Para impedir que Claude delegue a qualquer subagente, negue a ferramenta Agent em si com permissions.deny.
• Para remover apenas os subagentes integrados Explore e Plan, defina CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude lê e explora arquivos diretamente em vez de delegar para eles. Requer Claude Code v2.1.198 ou posterior.
• Em modo não interativo e no Agent SDK, defina CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 para remover todos os tipos integrados e fornecer apenas os seus próprios.

Quickstart: criar seu primeiro subagente

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

Configurar subagentes

Escolher o escopo do subagente

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: o system prompt do agente, equivalente ao corpo em markdown nos subagentes baseados em arquivo. prompt pode estar vazio. Se você selecionar um agente com prompt vazio e sem campo memory como o agente da sessão com --agent, o system prompt da sessão permanece inalterado. Um prompt vazio requer o Claude Code v2.1.281 ou posterior.
• Campos do frontmatter: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, effort, background, omitClaudeMd e isolation.
• Campos ignorados: color e experimental não são aceitos aqui e são ignorados em vez de rejeitados.

Escrever arquivos de subagentes

---
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.

• Ele bloqueia um comando que redireciona o git para o checkout principal.
• Ele recusa um comando quando não consegue verificar, a partir do texto do comando, que qualquer git executado pelo comando permanece dentro do worktree, por exemplo quando o nome do comando é calculado em tempo de execução.

Referência do frontmatter

• Para encontrar um campo com erro de digitação em um subagente que foi carregado, execute claude --debug no seu shell e pesquise does not recognize or apply no log de depuração em ~/.claude/debug/<session-id>.txt. O log de depuração nomeia até cinco campos de nível superior no arquivo do subagente que o Claude Code não reconhece, com o nome provavelmente pretendido quando um campo suportado é semelhante. Requer o Claude Code v2.1.296 ou posterior.
• Para descobrir por que um arquivo de subagente não foi carregado, consulte Arquivos de subagentes que o Claude Code ignora.

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

Arquivos de subagentes que o Claude Code ignora

• Sem name: o Claude Code trata o arquivo como documentação mantida ao lado dos seus agentes.
• Um --- de abertura que não está na primeira linha do arquivo: o Claude Code lê o arquivo como se não tivesse frontmatter e o trata como documentação.
• Um name que começa com -, contém : ou tem mais de 256 caracteres: o Claude Code ignora o arquivo e grava um erro no log de depuração.
• Um name mas sem description: o Claude Code ignora o arquivo e grava o motivo no log de depuração.
• YAML que não pode ser analisado: o Claude Code não lê nenhum campo do arquivo, ignora-o e grava o erro de análise no log de depuração.

Verificar um diretório agents antes de uma sessão

Escolher um modelo

• Alias de modelo: sonnet, opus, haiku ou fable
• ID de modelo completo: um valor que a flag --model aceita, como claude-opus-5-5 ou claude-sonnet-5
• inherit: o modelo da conversa principal ou, no caso de um subagente aninhado, o modelo do subagente que o criou

1. O parâmetro model por invocação, que o Claude pode passar ao iniciar o subagente. Em uma chamada da ferramenta Agent, o parâmetro aceita um alias de modelo, e não um ID de modelo completo nem inherit.
2. O campo model na definição do subagente, incluindo inherit
3. A variável de ambiente CLAUDE_CODE_SUBAGENT_MODEL
4. O modelo da conversa principal ou, no caso de um subagente aninhado, o modelo do subagente que o criou

Em qual modelo um subagente aninhado é executado

• Um subagente com model: inherit ou sem campo model
• Os subagentes integrados Explore, Plan e general-purpose
• Um fork

Verificar o modelo de um subagente

Executar todos os subagentes em um único modelo

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

• Um fork
• Uma skill executada em um subagente com model: inherit

Qual versão um alias de modelo seleciona

• Mesma família: por exemplo, se sua conversa principal é executada em claude-opus-4-7, um subagente com model: opus também é executado nessa versão. Para executar outra versão, defina um ID de modelo completo no campo model.
• Família desconhecida: o Claude Code não consegue identificar a família do modelo pai, como com um ARN do Amazon Bedrock que ele não consegue consultar. Este caso se aplica apenas ao alias opus em um provedor diferente da API da Anthropic. Para escolher a versão do Opus, defina ANTHROPIC_DEFAULT_OPUS_MODEL.

Quando uma allowlist bloqueia um modelo de subagente

1. Para um alias de família bloqueado, a versão permitida mais recente dessa família, em provedores que suportam essa substituição
2. O modelo em CLAUDE_CODE_SUBAGENT_MODEL, se você o definir, sob essas mesmas regras
3. O modelo da conversa principal ou, no caso de um subagente aninhado, o modelo do subagente que o criou

Pensamento estendido em subagentes

Escolher um nível de esforço

Quando um subagente não tem campo ou parâmetro effort

Controlar as capacidades dos subagentes

Ferramentas disponíveis

• Agent, quando o subagente está no limite de profundidade; em um fork, a ferramenta permanece listada, mas retorna um erro em vez de criar um subagente
• AskUserQuestion
• EndConversation, que só pode encerrar a conversa principal; consulte Comportamento da ferramenta EndConversation
• EnterPlanMode
• ExitPlanMode, a menos que o permissionMode do subagente seja plan
• ScheduleWakeup
• WaitForMcpServers
• Workflow

Restringir quais ferramentas um subagente pode usar

---
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
---

Nomes de servidores MCP que contêm um sublinhado duplo

• Em tools: escreva mcp__ seguido do nome completo do servidor e __*, como em mcp__reports__v2__*. Sem o __* final, mcp__reports__v2 não corresponde a nenhuma das ferramentas desse servidor.
• Em disallowedTools: procure mcp__reports ou mcp__reports__*, as entradas que retêm um servidor chamado reports. Com qualquer uma dessas entradas, o subagente também perde todas as ferramentas de reports__v2, porque esses nomes de ferramentas também começam com mcp__reports__. Para reter apenas as ferramentas do servidor reports, liste-as uma a uma, como mcp__reports__run_query.

Restringir quais subagentes podem ser criados

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

tools: Agent, Read, Bash

Restringir servidores MCP a um subagente

---
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
• Configuração de MCP gerenciada corporativa
• Políticas allowedMcpServers e deniedMcpServers

Confiança exigida para servidores MCP inline

• Confiança que não conta: a confiança de uma pasta pai e a confiança automática que uma sessão -p ou do SDK recebe para hooks em arquivos de configurações
• Até então: o Claude Code ignora todos os servidores inline nesse arquivo de agente e grava a chave exata projects["<path>"].hasTrustDialogAccepted para ~/.claude.json no log de depuração
• Diretórios --add-dir: um diretório fora do repositório do seu workspace confiável precisa de sua própria entrada de confiança, pois seus arquivos .claude/agents/ não herdam a confiança do seu workspace

• Um nome que referencia um servidor que você já configurou
• Um servidor inline em um arquivo de agente de ~/.claude/agents/, em um que você passa com --agents ou a opção agents do SDK, ou em um que as configurações gerenciadas fornecem

Modos de permissão

• Quando a conversa principal está em bypassPermissions, acceptEdits ou no modo auto, o subagente é executado nesse mesmo modo e o Claude Code ignora o permissionMode que você definiu. No modo auto, o classificador avalia as chamadas de ferramenta do subagente com as regras de bloqueio e de permissão da conversa principal. Quando o subagente termina, o classificador também revisa seu trabalho e seu relatório final antes que o relatório seja entregue, conforme descrito em Como o modo auto lida com subagentes. Se um subagente pedir permissão enquanto a conversa principal estiver em bypassPermissions, verifique se a chamada de ferramenta dele é uma das ações que nenhum modo aprova automaticamente.
• Quando a conversa principal está no modo plan, o subagente permanece no modo de planejamento independentemente do permissionMode que você definir, a menos que seja executado como colega de uma equipe de agentes sob as regras de equipes de agentes. Se você definir dontAsk, o subagente também não solicita sua confirmação: uma ação que o modo de planejamento pediria para você aprovar é negada.
• Quando a conversa principal está no modo default ou dontAsk, o subagente é executado no modo de permissão que você definiu. Em vez disso, ele mantém o modo de permissão da conversa principal nestes casos:
  • Você define bypassPermissions. A exceção de bypassPermissions requer o Claude Code v2.1.267 ou posterior.
  • Você define auto e o modo auto não está disponível para o subagente, como quando um arquivo de configurações define disableAutoMode ou o modelo do subagente não suporta o modo auto.

Pré-carregar skills em subagentes

---
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.

Habilitar memória 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.

• O system prompt do subagente inclui instruções para ler e gravar no diretório de memória.
• O system prompt do subagente também inclui as primeiras 200 linhas ou 25KB de MEMORY.md no diretório de memória, o que ocorrer primeiro, com instruções para organizar o MEMORY.md se ele exceder esse limite.
• As ferramentas Read, Write e Edit são habilitadas automaticamente para que o subagente possa gerenciar seus arquivos de memória.

Dicas de memória persistente

• project é o escopo padrão recomendado. Ele torna o conhecimento do subagente compartilhável via controle de versão.
• Peça ao subagente para consultar sua memória antes de começar o trabalho: “Revise este PR e verifique sua memória em busca de padrões que você já viu antes.”
• Peça ao subagente para atualizar sua memória após concluir uma tarefa: “Agora que você terminou, salve o que aprendeu na sua memória.” Com o tempo, isso cria uma base de conhecimento que torna o subagente mais eficaz.
• Inclua instruções de memória diretamente no arquivo markdown do subagente para que ele mantenha proativamente sua própria base de conhecimento:
  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.
  

Regras condicionais com 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

Desabilitar subagentes específicos

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

claude --disallowedTools "Agent(Explore)"

Definir hooks para subagentes

• No frontmatter do subagente: defina hooks que são executados apenas enquanto esse subagente está ativo
• Em settings.json: defina hooks de toda a sessão que também disparam dentro dos subagentes. Eventos de ferramentas como PreToolUse e PostToolUse disparam para as chamadas de ferramenta do subagente da mesma forma que na conversa principal, e SubagentStart e SubagentStop disparam quando um subagente começa ou termina

Hooks no frontmatter do subagente

---
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"
---

Hooks de nível de projeto para eventos de subagentes

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

Trabalhar com subagentes

Entender delegação automática

Invocar subagentes explicitamente

• Linguagem natural: nomeie o subagente em seu prompt; Claude decide se deve delegar
• @-mention: garante que o subagente seja executado para uma tarefa
• Em toda a sessão: toda a sessão é executada como esse subagente via flag --agent ou configuração 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"
}

Executar subagentes em primeiro plano ou segundo plano

• Subagentes em primeiro plano bloqueiam a conversa principal até a conclusão. Prompts de permissão são passados para você conforme surgem.
• Subagentes em segundo plano são executados simultaneamente enquanto você continua trabalhando. Quando um subagente em segundo plano atinge uma chamada de ferramenta que precisa de permissão, Claude Code exibe o prompt em sua sessão principal e nomeia o subagente que está pedindo. Aprove para deixar o subagente continuar, ou pressione Esc para negar essa chamada de ferramenta sem parar o subagente.

Quais subagentes são executados em segundo plano

• claude -p e o Agent SDK: Claude pode aguardar, por seu próprio julgamento ou quando você pede.
• Sessão interativa no terminal, VS Code e sessões do aplicativo desktop na sua máquina: para deixar Claude aguardar um subagente, desative o modo fork, que está ativado por padrão.

Deixar Claude aguardar um subagente

1. Desative o modo fork definindo CLAUDE_CODE_FORK_SUBAGENT como 0, por exemplo em settings.json:
   {
     "env": {
       "CLAUDE_CODE_FORK_SUBAGENT": "0"
     }
   }
   
2. Execute claude novamente a partir do seu shell, ou abra uma nova conversa no VS Code.
3. Peça a Claude para aguardar quando você precisar de um resultado primeiro, por exemplo “execute o subagente revisor e aguarde o relatório dele”.

Ferramentas, permissões e resultados de subagentes em segundo plano

Subagentes concluídos no painel e na lista de tarefas

• Quando um subagente termina com sucesso, Claude Code remove sua linha imediatamente e, exceto no modo leitor de tela, mostra /tasks to see subagents no rodapé por 30 segundos. Durante esses 30 segundos, execute /tasks e pressione Enter no subagente para abrir sua transcrição. Antes da v2.1.232, Claude Code mantinha a linha por 30 segundos após o subagente terminar, o mesmo que um com falha, e não mostrava dica de rodapé.
• Quando um subagente falha ou você o para, Claude Code mantém sua linha por 30 segundos. Para limpar a linha mais cedo, selecione-a e pressione x.

Nomes de subagentes

Erros de API em subagentes

• Primeiro plano: se um rate limit, sobrecarga ou erro de servidor interromper um subagente que já produziu saída de texto, a ferramenta Agent retorna essa saída parcial com uma nota de que o subagente foi interrompido e não completou sua tarefa. Um subagente que não produziu nada, ou cuja única saída foram chamadas de ferramenta, falha com Agent terminated early due to an API error, seguido pelo detalhe do erro.
• Segundo plano: o subagente é marcado como com falha, e a mensagem que Claude recebe quando termina nomeia o erro de API e inclui a última saída do subagente, para que o trabalho parcial não seja perdido.

⚠ This agent switched to <model> because its earlier model could not be used.

Verificação de saída de subagente

• Inserção de barra invertida: a verificação insere uma barra invertida em texto que imita a própria saída do Claude Code, como uma tag <system-reminder> ou uma linha começando com Human: ou Assistant:, para que a imitação seja lida como texto comum em vez de ser confundida com parte da conversa.
• Linha de marcador: a verificação prepara uma linha começando com [harness: subagent output matched instruction-shaped pattern(s): quando o relatório imita uma tag como <system-reminder> ou menciona configurações de permissão como bypassPermissions ou --dangerously-skip-permissions. Menções de configuração de permissão recebem a linha de marcador, mas o texto em si permanece como escrito.

Padrões comuns

Isolar operações de alto volume

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

Executar pesquisa paralela

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

Encadear subagentes

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

Escolher entre subagentes e conversa principal

• A tarefa precisa de frequente ida e volta ou refinamento iterativo
• Múltiplas fases compartilham contexto significativo, como planejamento, implementação e testes
• Você está fazendo uma mudança rápida e direcionada
• A latência importa. Um subagente que não é um fork começa do zero e pode precisar de tempo para reunir contexto

• A tarefa produz saída detalhada que você não precisa em seu contexto principal
• Você quer impor restrições de ferramentas ou permissões específicas
• O trabalho é autossuficiente e pode retornar um resumo

Deixar subagentes gerar seus próprios subagentes

• Sessão interativa no terminal: apenas o resumo do subagente de nível superior retorna para você, porque um subagente que lança subagentes em segundo plano aguarda seus resultados antes de terminar.
• claude -p e o Agent SDK: o subagente que gera aguarda enquanto o modo fork está ativado. Se você desativar o modo fork, os subagentes aninhados iniciam em segundo plano em vez disso. O subagente que gera não aguarda um subagente aninhado em segundo plano, que relata à sua conversa principal se durar mais que o subagente que o gerou.

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

Limite de subagente concorrente

• Um fork em sessão que você inicia com /subtask ocupa um slot enquanto é executado e nunca é bloqueado pelo limite.
• Retomar um subagente que já terminou ocupa um slot novo sem verificar o limite, para que retomadas possam empurrar a contagem em execução além dele.

Gerenciar contexto de subagente

O que é carregado na inicialização

• System prompt: o próprio prompt do agente mais detalhes de ambiente que Claude Code acrescenta, não o system prompt do Claude Code. Subagentes personalizados definem o seu no corpo markdown ou campo prompt. Agentes integrados têm prompts predefinidos.
• Mensagem de tarefa: o prompt de delegação que Claude escreve quando passa o trabalho.
• Arquivos CLAUDE.md: cada nível da hierarquia CLAUDE.md que a conversa principal carrega, incluindo ~/.claude/CLAUDE.md, regras do projeto, CLAUDE.local.md, arquivos de política gerenciada e qualquer arquivo AGENTS.md carregado como instruções do projeto. Os agentes Explore e Plan integrados pulam isso. Um subagente cuja definição define omitClaudeMd carrega apenas os arquivos de política gerenciada, ou nenhum quando a definição vem de configurações gerenciadas.
• Status Git: um snapshot que Claude Code lê do seu repositório quando o subagente é iniciado. Para um subagente em seu próprio worktree desse repositório, o snapshot mostra o branch, o status e os commits recentes do worktree. Ausente fora de um repositório Git ou sempre que o snapshot estiver desativado; consulte includeGitInstructions. Explore e Plan o pulam de qualquer forma.
• Skills pré-carregadas: conteúdo completo de qualquer skill nomeada no campo skills do agente. Agentes integrados não pré-carregam skills.
• Roster de irmãos: um lembrete do sistema listando main e cada outro agente nomeado na sessão, cada um um valor to válido para SendMessage. O roster aparece apenas quando as ferramentas do subagente incluem SendMessage e pelo menos um outro agente tem um nome, seja Claude o nomeou ao gerá-lo ou ele é executado como um colega de equipe de agentes. É um snapshot tirado quando o subagente começa, então agentes nomeados depois não aparecem.

• Estilo de saída: um subagente executa seu próprio system prompt, então seu estilo de saída não molda suas respostas, exceto em um fork.
• Memória automática: a memória automática da conversa principal não é carregada. Para dar a um subagente memória persistente de seu próprio, use o campo memory.
• Tamanho da janela de contexto: a janela de contexto de um subagente é dimensionada por seu próprio modelo, não pelo pai. Delegar a um modelo com uma janela menor dá a esse subagente a janela menor.

Retomar subagentes

• Quando um subagente é concluído, Claude recebe seu ID de agente.
• Os agentes Explore e Plan integrados são de uma única execução e não retornam um ID de agente, então Claude não pode retomá-los. Use general-purpose ou um subagente personalizado quando você precisa continuar o trabalho.
• Quando um subagente para em seu limite maxTurns, Claude Code marca a saída retornada como parcial, e Claude pode retomar o subagente para continuar seu trabalho.

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]

• Compactação da conversa principal: quando a conversa principal é compactada, as transcrições de subagentes não são afetadas. Elas são armazenadas em arquivos separados.
• Persistência de sessão: as transcrições de subagentes persistem dentro de sua sessão. Você pode retomar um subagente após reiniciar Claude Code retomando a mesma sessão.
• Limpeza automática: Claude Code deleta transcrições de subagentes após o período de retenção cleanupPeriodDays, 30 dias por padrão, seguindo as regras de varredura de retenção.

Mensagear um subagente pelo nome após uma reinicialização

Compactação automática

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

Definir a janela de compactação automática para um subagente

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

• O valor não está abaixo da janela de compactação automática que o subagente herdaria de outra forma: para compactar mais cedo, defina um valor abaixo dessa janela.
• Você executa toda a sessão como este subagente com --agent ou a configuração agent: o campo não tem efeito nesse caso. Para definir a janela da sessão, consulte Definir a janela de compactação automática.

Bifurcar a conversa atual

• Entrada: uma bifurcação vê o mesmo system prompt, ferramentas, modelo e histórico de mensagens que sua conversa pai
• Saída: as próprias chamadas de ferramenta da bifurcação ficam fora de sua conversa pai e apenas seu resultado final volta

/subtask draft unit tests for the parser changes so far

Observar e orientar bifurcações em execução

• /compact, /clear e /rewind atuam na conversa principal, então Claude Code pede que você confirme antes de executar um deles a partir desta visualização.
• /model e /fast definem o modelo e o modo rápido da conversa principal, não os do agente visualizado, então não são executados a partir desta visualização. Um aviso informa o motivo.

Como bifurcações diferem de outros subagentes

Desativar o modo de bifurcação

• Impedir apenas as bifurcações: adicione "Agent(fork)" a permissions.deny nas suas configurações.
• Desativar o modo de bifurcação: defina CLAUDE_CODE_FORK_SUBAGENT como 0, seguindo as etapas em Permitir que Claude aguarde um subagente.

Subagentes de exemplo

Revisor de código

---
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.

Cientista de dados

---
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.

Validador de consulta de banco de dados

---
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

Próximos passos

• Distribuir subagentes com plugins para compartilhar subagentes entre equipes ou projetos
• Executar Claude Code programaticamente com o Agent SDK para CI/CD e automação
• Usar MCP servers para dar aos subagentes acesso a ferramentas e dados externos