Subagentos

​

O que são subagentos?

• Tem um propósito específico e área de expertise
• Usa sua própria janela de contexto separada da conversa principal
• Pode ser configurado com ferramentas específicas que pode usar
• Inclui um prompt de sistema personalizado que guia seu comportamento

​

Benefícios principais

​

Início rápido

/agents

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

​

Configuração de subagentos

​

Locais de arquivo

​

Agentes de plugin

• Agentes de plugin aparecem em /agents junto com seus agentes personalizados
• Podem ser invocados explicitamente: “Use the code-reviewer agent from the security-plugin”
• Podem ser invocados automaticamente pelo Claude quando apropriado
• Podem ser gerenciados (visualizados, inspecionados) através da interface /agents

​

Configuração baseada em CLI

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

• Teste rápido de configurações de subagentos
• Subagentos específicos de sessão que não precisam ser salvos
• Scripts de automação que precisam de subagentos personalizados
• Compartilhamento de definições de subagentos em documentação ou scripts

​

Formato de arquivo

---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
model: sonnet  # Optional - specify model alias or 'inherit'
---

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

​

Seleção de modelo

• Alias de modelo: Use um dos aliases disponíveis: sonnet, opus ou haiku
• 'inherit': Use o mesmo modelo da conversa principal (útil para consistência)
• Omitido: Se não especificado, usa o modelo padrão configurado para subagentos (sonnet)

​

Ferramentas disponíveis

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

​

Gerenciando subagentos

​

Usando o comando /agents (Recomendado)

/agents

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

​

Gerenciamento direto de arquivo

# 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 subagentos efetivamente

​

Delegação automática

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

​

Invocação explícita

> 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

​

Subagentos integrados

​

Subagentos de plano

• Modelo: Usa Sonnet para análise mais capaz
• Ferramentas: Tem acesso às ferramentas Read, Glob, Grep e Bash para exploração de base de código
• Propósito: Pesquisa arquivos, analisa estrutura de código e reúne contexto
• Invocação automática: Claude usa automaticamente este agente quando em modo de plano e precisa pesquisar a base de código

User: [In plan mode] Help me refactor the authentication module

Claude: Let me research your authentication implementation first...
[Internally invokes Plan subagent to explore auth-related files]
[Plan subagent searches codebase and returns findings]
Claude: Based on my research, here's my proposed plan...

​

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

​

Melhores práticas

• Comece com agentes gerados por Claude: Recomendamos altamente gerar seu subagentos 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 subagentos focados: Crie subagentos com responsabilidades únicas e claras em vez de tentar fazer um subagentos fazer tudo. Isso melhora o desempenho e torna subagentos 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 subagentos funcionará.
• Limite o acesso a ferramentas: Conceda apenas ferramentas necessárias para o propósito do subagentos. Isso melhora a segurança e ajuda o subagentos a focar em ações relevantes.
• Controle de versão: Verifique subagentos de projeto no controle de versão para que sua equipe possa se beneficiar e melhorá-los colaborativamente.

​

Uso avançado

​

Encadeamento de subagentos

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

​

Seleção dinâmica de subagentos

​

Subagentos retomáveis

• Cada execução de subagentos recebe um agentId único
• A conversa do agente é armazenada em um arquivo de transcrição separado: agent-{agentId}.jsonl
• Você pode retomar um agente anterior fornecendo seu agentId via parâmetro resume
• Quando retomado, o agente continua com contexto completo de sua conversa anterior

> Use the code-analyzer agent to start reviewing the authentication module

[Agent completes initial analysis and returns agentId: "abc123"]

> Resume agent abc123 and now analyze the authorization logic as well

[Agent continues with full context from previous conversation]

• Pesquisa de longa duração: Divida análise de base de código grande em múltiplas sessões
• Refinamento iterativo: Continue refinando o trabalho de um subagentos sem perder contexto
• Fluxos de trabalho de múltiplas etapas: Tenha um subagentos trabalhar em tarefas relacionadas sequencialmente mantendo contexto

• Transcrições de agentes são armazenadas em seu diretório de projeto
• Gravação é desabilitada durante retomada para evitar duplicar mensagens
• Agentes síncronos e assíncronos podem ser retomados
• O parâmetro resume aceita o ID do agente de uma execução anterior

{
  "description": "Continue analysis",
  "prompt": "Now examine the error handling patterns",
  "subagent_type": "code-analyzer",
  "resume": "abc123"  // Agent ID from previous execution
}

​

Considerações de desempenho

• Eficiência de contexto: Agentes ajudam a preservar contexto principal, permitindo sessões gerais mais longas
• Latência: Subagentos começam com uma folha em branco cada vez que são invocados e podem adicionar latência conforme reúnem contexto que precisam para fazer seu trabalho efetivamente.

​

Documentação relacionada

• Plugins - Estenda Claude Code com agentes personalizados através de plugins
• Comandos de barra - Aprenda sobre outros comandos integrados
• Configurações - Configure o comportamento do Claude Code
• Hooks - Automatize fluxos de trabalho com manipuladores de eventos