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."
  }
}
'@

​

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.

​

Campos de frontmatter suportados

​

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-4-8 ou claude-sonnet-5. Aceita os mesmos valores que o flag --model
• inherit: Use o mesmo modelo que a conversa principal
• Omitido: Se não especificado, padrão é inherit (usa o mesmo modelo que a conversa principal)

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

​

Controlar capacidades do subagente

​

Ferramentas disponíveis

• AskUserQuestion
• EnterPlanMode
• ExitPlanMode, a menos que o permissionMode do subagente seja plan
• ScheduleWakeup
• WaitForMcpServers

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

---
name: no-writes
description: Inherits every tool 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.

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

​

Modos de permissão

​

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

​

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 que são executados na sessão principal quando subagentes iniciam ou param

​

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 de sistema, restrições de ferramentas e modelo do 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 foreground ou background

• Subagentes em foreground bloqueiam a conversa principal até completar. Prompts de permissão são passados para você conforme surgem.
• Subagentes em background são executados concorrentemente enquanto você continua trabalhando. A partir da v2.1.186, quando um subagente em background atinge uma chamada de ferramenta que precisa de permissão, o prompt aparece 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. Antes da v2.1.186, subagentes em background auto-negavam qualquer chamada de ferramenta que teria solicitado.

• Peça a Claude para executar uma tarefa em background ou em foreground
• Pressione Ctrl+B para colocar uma tarefa em execução em background

​

Erros de API em subagentes

• Foreground: se um limite de taxa, sobrecarga ou erro de servidor corta 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 cortado 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 cortou a forma de chamadas de ferramenta apenas retornou um resultado parcial vazio contendo apenas a nota de corte em vez disso.
• Background: o subagente é marcado como falho, e a mensagem que Claude recebe quando termina nomeia o erro de API e inclui a última saída do subagente, então o trabalho parcial não é perdido.

​

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

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
• Latência importa. Subagentes começam do zero e podem precisar de tempo para reunir contexto

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

​

Gerar subagentes aninhados

​

Gerenciar contexto de subagente

​

O que carrega na inicialização

• Prompt de sistema: o prompt próprio do agente mais detalhes de ambiente que Claude Code acrescenta, não o prompt de sistema completo 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.
• CLAUDE.md e memória: cada nível da hierarquia de memória que a conversa principal carrega, incluindo ~/.claude/CLAUDE.md, regras de projeto, CLAUDE.local.md e arquivos de política gerenciados. Os agentes integrados Explore e Plan pulam isso.
• Status do 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 isso 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 de 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.

​

Retomar subagentes

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 se compacta, transcrições de subagente não são afetadas. Elas são armazenadas em arquivos separados.
• Persistência de sessão: Transcrições de subagente persistem dentro de sua sessão. Você pode retomar um subagente após reiniciar Claude Code retomando a mesma sessão.
• Limpeza automática: Transcrições são limpas baseado na configuração cleanupPeriodDays, que padrão é 30 dias.

​

Auto-compactação

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

​

Bifurcar a conversa atual

• Claude pode gerar uma bifurcação solicitando explicitamente o tipo de subagente fork. Gerações sem um tipo de subagente ainda usam o subagente general-purpose, e subagentes nomeados como Explore ainda geram como antes.
• Cada geração de subagente é executada em background, seja uma bifurcação ou um subagente nomeado. Defina CLAUDE_CODE_DISABLE_BACKGROUND_TASKS para 1 para manter gerações síncronas.

/fork draft unit tests for the parser changes so far

​

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

​

Como bifurcações diferem de subagentes nomeados

​

Limitações

​

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