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 prompt de sistema do agente, equivalente ao corpo markdown em subagentes baseados em arquivo. prompt pode estar vazio. Se você selecionar um agente com um prompt vazio e nenhum campo memory como o agente da sessão com --agent, o prompt de sistema da sessão é deixado inalterado. Um prompt vazio requer Claude Code v2.1.281 ou posterior.
• Campos de frontmatter: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, 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 subagente

---
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 git para o checkout principal.
• Ele recusa um comando quando não consegue verificar a partir do texto do comando que qualquer git que o comando executa permanece dentro do worktree, por exemplo quando o nome do comando é calculado em tempo de execução.

​

Referência de frontmatter

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

​

Arquivos de subagente que Claude Code pula

• Sem name: Claude Code trata o arquivo como documentação mantida ao lado de seus agentes.
• Um --- de abertura que não é a primeira linha do arquivo: Claude Code lê o arquivo como não tendo frontmatter e o trata como documentação.
• Um name que começa com - ou contém :: Claude Code pula o arquivo e escreve um erro no log de debug. Veja a linha name na tabela acima.
• Um name mas sem description: Claude Code pula o arquivo e escreve o motivo no log de debug.
• YAML que não analisa: Claude Code não lê campos do arquivo, o pula e escreve o erro de análise no log de debug.

​

Escolher um modelo

• Alias de modelo: use um dos aliases disponíveis: sonnet, opus, haiku, ou fable
• ID de modelo completo: use um ID de modelo completo como claude-opus-5-5 ou claude-sonnet-5. Aceita os mesmos valores que o flag --model
• inherit: use o mesmo modelo que a conversa principal

1. O parâmetro model por invocação
2. O frontmatter model da definição do subagente, onde inherit seleciona o modelo da conversa principal
3. A variável de ambiente CLAUDE_CODE_SUBAGENT_MODEL, quando você a define para um alias de modelo ou ID de modelo
4. O modelo da conversa principal

• O modelo da conversa principal pertence a essa família: o subagente é executado no modelo exato da conversa principal, incluindo qualquer sufixo [1m], portanto obtém a mesma janela de contexto estendido que a conversa principal.
• Claude Code não consegue dizer a família do modelo da conversa principal, em um provedor diferente da API Anthropic: isso pode acontecer com um ARN de perfil de inferência de aplicação no Amazon Bedrock que Claude Code não resolveu para um modelo de suporte. Este caso cobre apenas o alias opus, e não se aplica quando você define ANTHROPIC_DEFAULT_OPUS_MODEL, já que opus então se resolve para o modelo que você definiu.

• Quando o valor bloqueado é um alias de família como opus, Claude Code executa o subagente na versão mais recente dessa família que a lista de permissões permite, seguindo as mesmas regras de substituição e escopo de provedor que /model. Antes da v2.1.222, Claude Code executava o subagente no modelo herdado para um alias de família bloqueado também.
• Para qualquer outro valor bloqueado, em provedores onde essa substituição não opera, ou quando a lista de permissões não permite nenhuma versão da família, Claude Code executa o subagente no modelo herdado em vez disso. Se você definir CLAUDE_CODE_SUBAGENT_MODEL, Claude Code tenta esse modelo primeiro, sob essas mesmas regras.

​

Executar cada subagente em um modelo

• Se você definir ambas as variáveis, subagentes são executados no modelo em CLAUDE_CODE_SUBAGENT_MODEL.
• Se você definir apenas CLAUDE_CODE_SUBAGENT_MODEL_FORCE, subagentes são executados no modelo da conversa principal.

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

• Uma bifurcação
• Uma skill que é executada em um subagente com model: inherit

​

Controlar capacidades do subagente

​

Ferramentas disponíveis

• Agent, quando o subagente está no limite de profundidade; em uma bifurcação a ferramenta permanece listada mas retorna um erro em vez de gerar
• AskUserQuestion
• EndConversation, que pode encerrar apenas a conversa principal; veja comportamento da ferramenta EndConversation
• EnterPlanMode
• ExitPlanMode, a menos que o permissionMode do subagente seja 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
---

​

Restringir quais subagentes podem ser gerados

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

tools: Agent, Read, Bash

​

Escopo de MCP servers para 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.

• Confiança que não conta: confiança de uma pasta pai, e a confiança automática que uma sessão -p ou SDK obtém para hooks em arquivos de configurações
• Até então: Claude Code pula cada servidor inline naquele arquivo de agente e escreve a chave exata projects["<path>"].hasTrustDialogAccepted para ~/.claude.json no log de debug
• Diretórios --add-dir: um diretório fora do repositório do espaço de trabalho confiável de sua organização precisa de sua própria entrada de confiança, já que seus arquivos .claude/agents/ não herdam a confiança do seu espaço de trabalho

• 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

• --strict-mcp-config e --bare
• Configuração de MCP gerenciada pela empresa
• Políticas allowedMcpServers e deniedMcpServers

​

Modos de permissão

• Quando a conversa principal está em bypassPermissions, acceptEdits, ou modo auto, o subagente é executado nesse mesmo modo e Claude Code ignora o permissionMode que você definiu. Sob modo auto, o classificador avalia as chamadas de ferramentas do subagente com as regras de bloqueio e permissão da conversa principal. Quando o subagente termina, o classificador também revisa seu trabalho e seu relatório final antes do relatório ser entregue, conforme Como o modo auto lida com subagentes descreve.
• Quando a conversa principal está em default, dontAsk, ou modo plan, o subagente é executado no modo de permissão que você definiu, exceto bypassPermissions. Um subagente que declara bypassPermissions mantém o modo da conversa principal em vez disso. A exceção bypassPermissions requer Claude Code v2.1.267 ou posterior.

​

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 prompt de sistema do subagente inclui instruções para ler e escrever no diretório de memória.
• O prompt de sistema do subagente também inclui as primeiras 200 linhas ou 25KB de MEMORY.md no diretório de memória, o que for menor, com instruções para curar MEMORY.md se exceder esse limite.
• Ferramentas Read, Write e Edit são automaticamente habilitadas para que o subagente possa gerenciar seus arquivos de memória.

• 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: “Review this PR, and check your memory for patterns you’ve seen before.”
• Peça ao subagente para atualizar sua memória após completar uma tarefa: “Now that you’re done, save what you learned to your memory.” Ao longo do tempo, isso constrói 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 específico está ativo
• Em settings.json: defina hooks em toda a sessão que também disparam dentro de subagentes. Eventos de ferramentas como PreToolUse e PostToolUse disparam para as chamadas de ferramentas do subagente da mesma forma que na conversa principal, e SubagentStart e SubagentStop disparam quando um subagente inicia 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 $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

​

Hooks no nível do projeto para eventos de subagente

{
  "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 usa o prompt do sistema, restrições de ferramentas e modelo desse subagente via sinalizador --agent ou configuração agent

Use o subagente test-runner para corrigir testes com falha
Peça ao subagente code-reviewer para analisar minhas mudanças recentes

@"code-reviewer (agent)" analise as mudanças de autenticação

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.

• Se um colega de equipe de agentes em processo gerou o subagente, Claude Code o executa em primeiro plano. Claude Code recusa com um erro para gerar um subagente de colega cuja definição define background: true. Onde o modo fork está desativado e você não desativou tarefas em segundo plano, Claude Code também recusa com um erro quando um colega define run_in_background: true.
• Se você definir CLAUDE_CODE_DISABLE_BACKGROUND_TASKS como 1, Claude Code executa o subagente em primeiro plano, em todo tipo de sessão e independentemente de o modo fork estar ativado.
• Onde o modo fork está ativado, como é por padrão em uma sessão interativa, Claude Code executa o subagente em segundo plano, subagentes fork e não-fork, e Claude não pode pedir o primeiro plano.
• Onde o modo fork está desativado, Claude executa o subagente em segundo plano por padrão e em primeiro plano quando precisa do resultado antes de continuar. O modo fork está desativado no modo não interativo com -p e no Agent SDK a menos que você o ative. Para manter um subagente particular em segundo plano mesmo quando Claude quer o resultado, defina seu campo frontmatter background como true.

• Onde o modo fork está desativado, peça a Claude para executar uma tarefa em segundo plano ou em primeiro plano
• Pressione Ctrl+B para colocar uma tarefa em execução em segundo plano

• Quando um subagente termina com sucesso, Claude Code remove sua linha imediatamente e, exceto no modo leitor de tela, mostra /tasks para ver subagentes 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 limite de taxa, 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. Na v2.1.199, um limite de taxa, sobrecarga ou erro de servidor que interrompeu a forma de chamadas de ferramenta apenas retornou um resultado parcial vazio contendo apenas a nota de interrupção.
• 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.

​

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 um subagente para executar o conjunto de testes e relatar apenas os testes com falha com suas mensagens de erro

​

Executar pesquisa paralela

Pesquise os módulos de autenticação, banco de dados e API em paralelo usando subagentes separados

​

Encadear subagentes

Use o subagente code-reviewer para encontrar problemas de desempenho, depois use o subagente optimizer para corrigi-los

​

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

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

• Prompt do sistema: o próprio prompt do agente mais detalhes de ambiente que Claude Code acrescenta, não o prompt do sistema 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 tirado no início da sessão pai. Ausente quando o diretório de trabalho não é um repositório Git ou quando includeGitInstructions é false. Explore e Plan pulam independentemente.
• 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. Requer Claude Code v2.1.206 ou posterior. 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 prompt do sistema, 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. Para subagentes que retornam um ID de agente, Claude Code também observa no resultado que Claude pode mensagear o subagente para continuar de onde parou.

Use o subagente code-reviewer para revisar o módulo de autenticação
[Agent completes]

Continue essa revisão de código e agora analise a lógica de autorização
[Claude retoma o subagente com contexto completo da conversa anterior]

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

​

Auto-compactação

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

​

Bifurcar a conversa atual

/subtask draft unit tests for the parser changes so far

​

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

​

Como bifurcações diferem de outros subagentes

​

Ativar ou desativar o modo de bifurcação

• Claude pode gerar uma bifurcação solicitando o tipo de subagente fork. Quando Claude não solicita um tipo, ele obtém o subagente general-purpose, se a sessão ainda tiver esse tipo. Subagentes gerados a partir de uma definição, como Explore, funcionam como de costume.
• Claude Code executa os subagentes que Claude gera em background, bifurcações e subagentes não-bifurcados, além dos casos que permanecem em foreground. Claude Code também remove o parâmetro run_in_background da ferramenta Agent, para que Claude não possa solicitar o foreground.

• 1 ativa o modo de bifurcação em modo não-interativo e no Agent SDK também
• 0 desativa o modo de bifurcação em todo tipo de sessão

​

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