Subagentes

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

​

Início rápido

Para criar seu primeiro subagente:

/agents

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

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

​

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 de ferramentas disponíveis.

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

​

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 de 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 à 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 folha limpa cada vez que são invocados e podem adicionar latência enquanto coletam o contexto que precisam 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