Subagentes

Crie e use subagentes de IA especializados no Claude Code para fluxos de trabalho específicos de tarefas e gerenciamento de contexto aprimorado.

Subagentes personalizados no Claude Code são assistentes de IA especializados que podem ser invocados para lidar com tipos específicos de tarefas. Eles permitem resolução de problemas mais eficiente fornecendo configurações específicas de tarefas com prompts de sistema personalizados, ferramentas e uma janela de contexto separada.

O que são subagentes?

Subagentes são personalidades de IA pré-configuradas para as quais o Claude Code pode delegar tarefas. Cada subagente:

• Tem um propósito específico e área de especialização
• Usa sua própria janela de contexto separada da conversa principal
• Pode ser configurado com ferramentas específicas que tem permissão para usar
• Inclui um prompt de sistema personalizado que orienta seu comportamento

Quando o Claude Code encontra uma tarefa que corresponde à especialização de um subagente, ele pode delegar essa tarefa ao subagente especializado, que trabalha independentemente e retorna resultados.

Principais benefícios

Preservação de contexto

Cada subagente opera em seu próprio contexto, evitando poluição da conversa principal e mantendo-a focada em objetivos de alto nível.

Especialização

Subagentes podem ser ajustados com instruções detalhadas para domínios específicos, levando a taxas de sucesso mais altas em tarefas designadas.

Reutilização

Uma vez criados, subagentes podem ser usados em diferentes projetos e compartilhados com sua equipe para fluxos de trabalho consistentes.

Permissões flexíveis

Cada subagente pode ter diferentes níveis de acesso a ferramentas, permitindo que você limite ferramentas poderosas a tipos específicos de subagentes.

Início rápido

Para criar seu primeiro subagente:

1. Abra a interface de subagentes

   Execute o seguinte comando:

   /agents
   

2. Selecione 'Create New Agent'

   Escolha se deseja criar um subagente de nível de projeto ou de usuário

3. Defina o subagente

   • Recomendado: Gere com Claude primeiro, depois personalize para torná-lo seu
   • Descreva seu subagente em detalhes e quando deve ser usado
   • Selecione as ferramentas às quais deseja conceder acesso (ou deixe em branco para herdar todas as ferramentas)
   • A interface mostra todas as ferramentas disponíveis, facilitando a seleção
   • Se estiver gerando com Claude, você também pode editar o prompt do sistema em seu próprio editor pressionando e
4. Salve e use

   Seu subagente agora está disponível! Claude o usará automaticamente quando apropriado, ou você pode invocá-lo explicitamente:

   > Use the code-reviewer subagent to check my recent changes
   

Configuração de subagentes

Localizações de arquivos

Subagentes são armazenados como arquivos Markdown com frontmatter YAML em duas localizações possíveis:

Tipo	Localização	Escopo	Prioridade
Subagentes de projeto	.claude/agents/	Disponível no projeto atual	Mais alta
Subagentes de usuário	~/.claude/agents/	Disponível em todos os projetos	Mais baixa

Quando nomes de subagentes entram em conflito, subagentes de nível de projeto têm precedência sobre subagentes de nível de usuário.

Formato de arquivo

Cada subagente é definido em um arquivo Markdown com esta estrutura:

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
---

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

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

Campos de configuração

Campo	Obrigatório	Descrição
name	Sim	Identificador único usando letras minúsculas e hífens
description	Sim	Descrição em linguagem natural do propósito do subagente
tools	Não	Lista separada por vírgulas de ferramentas específicas. Se omitido, herda todas as ferramentas da thread principal

Ferramentas disponíveis

Subagentes podem receber acesso a qualquer uma das ferramentas internas do Claude Code. Consulte a documentação de ferramentas para uma lista completa das ferramentas disponíveis.

Recomendado: Use o comando /agents para modificar o acesso a ferramentas - ele fornece uma interface interativa que lista todas as ferramentas disponíveis, incluindo quaisquer ferramentas de servidor MCP conectadas, facilitando a seleção das que você precisa.

Você tem duas opções para configurar ferramentas:

• Omitir o campo tools para herdar todas as ferramentas da thread principal (padrão), incluindo ferramentas MCP
• Especificar ferramentas individuais como uma lista separada por vírgulas para controle mais granular (pode ser editado manualmente ou via /agents)

Ferramentas MCP: Subagentes podem acessar ferramentas MCP de servidores MCP configurados. Quando o campo tools é omitido, subagentes herdam todas as ferramentas MCP disponíveis para a thread principal.

Gerenciando subagentes

Usando o comando /agents (Recomendado)

O comando /agents fornece uma interface abrangente para gerenciamento de subagentes:

/agents

Isso abre um menu interativo onde você pode:

• Ver todos os subagentes disponíveis (integrados, de usuário e de projeto)
• Criar novos subagentes com configuração guiada
• Editar subagentes personalizados existentes, incluindo seu acesso a ferramentas
• Excluir subagentes personalizados
• Ver quais subagentes estão ativos quando existem duplicatas
• Gerenciar facilmente permissões de ferramentas com uma lista completa de ferramentas disponíveis

Gerenciamento direto de arquivos

Você também pode gerenciar subagentes trabalhando diretamente com seus arquivos:

# Create a project subagent
mkdir -p .claude/agents
echo '---
name: test-runner
description: Use proactively to run tests and fix failures
---

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

# Create a user subagent
mkdir -p ~/.claude/agents
# ... create subagent file

Usando subagentes efetivamente

Delegação automática

Claude Code delega tarefas proativamente com base em:

• A descrição da tarefa em sua solicitação
• O campo description nas configurações do subagente
• Contexto atual e ferramentas disponíveis

Para encorajar mais uso proativo de subagentes, inclua frases como “use PROACTIVELY” ou “MUST BE USED” em seu campo description.

Invocação explícita

Solicite um subagente específico mencionando-o em seu comando:

> Use the test-runner subagent to fix failing tests
> Have the code-reviewer subagent look at my recent changes
> Ask the debugger subagent to investigate this error

Exemplos de subagentes

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

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

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

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

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

Include specific examples of how to fix issues.

Depurador

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

You are an expert debugger specializing in root cause analysis.

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

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

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

Focus on fixing the underlying issue, not just symptoms.

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

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.

Melhores práticas

• Comece com agentes gerados pelo Claude: Recomendamos altamente gerar seu subagente inicial com Claude e depois iterar sobre ele para torná-lo pessoalmente seu. Esta abordagem oferece os melhores resultados - uma base sólida que você pode personalizar para suas necessidades específicas.

• Projete subagentes focados: Crie subagentes com responsabilidades únicas e claras em vez de tentar fazer um subagente fazer tudo. Isso melhora o desempenho e torna os subagentes mais previsíveis.

• Escreva prompts detalhados: Inclua instruções específicas, exemplos e restrições em seus prompts de sistema. Quanto mais orientação você fornecer, melhor o subagente irá performar.

• Limite o acesso a ferramentas: Conceda apenas ferramentas que são necessárias para o propósito do subagente. Isso melhora a segurança e ajuda o subagente a focar em ações relevantes.

• Controle de versão: Faça check-in dos subagentes de projeto no controle de versão para que sua equipe possa se beneficiar e melhorá-los colaborativamente.

Uso avançado

Encadeamento de subagentes

Para fluxos de trabalho complexos, você pode encadear múltiplos subagentes:

> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

Seleção dinâmica de subagentes

Claude Code seleciona subagentes inteligentemente com base no contexto. Torne seus campos description específicos e orientados para ação para melhores resultados.

Considerações de desempenho

• Eficiência de contexto: Agentes ajudam a preservar o contexto principal, permitindo sessões gerais mais longas
• Latência: Subagentes começam com uma lousa limpa cada vez que são invocados e podem adicionar latência enquanto coletam o contexto necessário para fazer seu trabalho efetivamente.

Documentação relacionada

• Comandos slash - Aprenda sobre outros comandos integrados
• Configurações - Configure o comportamento do Claude Code
• Hooks - Automatize fluxos de trabalho com manipuladores de eventos