Subagentes no Claude Code: quando dividir tarefas e como limitar

Subagentes no Claude Code: quando dividir tarefas e como limitar

Subagentes no Claude Code são assistentes especializados que o agente principal aciona para tarefas bem delimitadas, cada um com contexto próprio, instruções próprias e um conjunto definido de ferramentas. Eles ajudam quando a tarefa pode ser separada, quando gera muito material intermediário que poluiria a conversa principal ou quando exige permissões diferentes. A forma mais segura de limitá-los é listar, para cada subagente, apenas as ferramentas que a função dele realmente precisa.

Principais pontos

• Um subagente trabalha em um contexto separado e devolve ao agente principal só o resultado, o que preserva a conversa principal para as decisões.
• Dividir compensa em tarefas independentes, de leitura intensa ou com perfis de permissão diferentes. Tarefas pequenas e sequenciais costumam ficar melhores em uma conversa só.
• A restrição de ferramentas é o controle mais importante: o revisor lê e não escreve, o pesquisador consulta e não executa comandos.
• A descrição de cada subagente define quando ele é acionado, então precisa ser específica e testada com casos reais.
• Comece com um ou dois subagentes em um fluxo real, com registro do que fizeram e um critério de sucesso combinado antes.

O que é um subagente e o que ele muda na prática

Neste texto, separamos três tipos de afirmação: o que vem da documentação oficial, o que é recomendação de prática de implementação e o que é hipótese a validar. Sobre a mecânica, a documentação do Claude Code descreve subagentes como arquivos de texto com um cabeçalho de configuração (nome, descrição, ferramentas permitidas e, opcionalmente, modelo) seguido de instruções em linguagem natural. Eles podem ficar na pasta do projeto, versionados junto com o código, ou na pasta do usuário. Confira a documentação da versão que vocês usam, porque nomes de campos e comandos mudam com o tempo.

Na prática, três coisas mudam quando você usa um subagente em vez de pedir tudo na mesma conversa.

• Contexto separado: o subagente lê arquivos, testa hipóteses e descarta o que não serve. A conversa principal recebe apenas o resumo.
• Instruções especializadas: um revisor de segurança pode ter um roteiro próprio, diferente do roteiro de quem implementa.
• Permissões próprias: cada subagente pode ter uma lista de ferramentas diferente da lista do agente principal.

O primeiro ponto conecta com o que a Anthropic descreve sobre engenharia de contexto para agentes: arquiteturas com subagentes servem para que um trabalhador explore bastante e devolva um resumo curto, em vez de encher a janela de contexto do agente principal. O padrão de um coordenador que distribui trabalho a outros também aparece no texto sobre como construir agentes eficazes, com a ressalva de que a complexidade extra só se justifica quando o resultado melhora de forma observável.

Quando dividir uma tarefa ajuda, e quando atrapalha

Dividir tem custo: mais instruções para manter, mais pontos de falha e uma passagem de informação entre agentes que pode perder detalhes. Por isso a pergunta útil não é se dá para dividir, e sim se a divisão traz algo concreto. Um guia de decisão simples:

• Divida se a tarefa exige ler muito material e só o resumo importa, como mapear onde uma regra de negócio aparece em um repositório grande.
• Divida se partes do trabalho são independentes e não dependem do resultado uma da outra.
• Divida se uma etapa precisa de permissões menores que as das demais, como uma revisão que não pode editar arquivos.
• Divida se você quer uma segunda leitura sem o viés da conversa que produziu a mudança.
• Não divida se a tarefa é curta e cada passo depende do anterior.
• Não divida se você ainda não sabe descrever, em uma frase, o que o subagente deve devolver.
• Não divida só para parecer sofisticado. Um fluxo com menos peças é mais fácil de auditar.

Um sinal prático de que a divisão está errada: o agente principal gasta mais tempo explicando o contexto ao subagente do que o subagente gasta trabalhando. Nesse caso, a tarefa provavelmente pertence à conversa principal.

Outro ponto é o consumo. Como cada subagente tem seu próprio contexto, o total de trabalho processado pode crescer. Isso não é necessariamente ruim, mas deve ser medido no piloto, e não presumido.

Como restringir as ferramentas de cada subagente

O princípio vem da segurança clássica: privilégio mínimo e negação por padrão, como descreve o guia de autorização da OWASP. Aplicado a subagentes, significa que a lista de ferramentas é escrita por inclusão. Você diz o que o subagente pode usar, e não o que ele não pode.

Segundo a documentação, quando o campo de ferramentas é omitido o subagente herda as ferramentas da conversa principal. Para um piloto, isso é o oposto do que se quer. Verifique esse comportamento na versão que vocês usam e, por padrão, sempre preencha a lista explicitamente.

Alguns perfis que costumam funcionar como ponto de partida (recomendação de prática, a ajustar ao seu contexto):

• Pesquisador de código: leitura, busca por padrão e listagem de arquivos (por exemplo Read, Grep e Glob). Sem escrita, sem execução de comandos.
• Revisor: as mesmas ferramentas de leitura, mais a possibilidade de rodar testes, se necessário. Sem edição de arquivos.
• Implementador: leitura e edição, limitadas à área do projeto que a tarefa envolve. Sem acesso à rede e sem credenciais.
• Executor de testes: execução de comandos previamente combinados, sem edição.

Três cuidados que fazem diferença:

• A ferramenta de execução de comandos é ampla. Se um subagente precisa dela, combine com as regras de permissão do projeto para limitar quais comandos podem rodar, e não confie apenas na instrução escrita no texto.
• Ferramentas vindas de servidores externos (por exemplo via Model Context Protocol) entram na mesma conta. Dê a cada subagente só as que a função exige.
• Quando o modelo é configurável por subagente, tarefas simples de leitura podem usar um modelo mais leve. Trate isso como hipótese e compare a qualidade no piloto.

A qualidade da descrição das ferramentas também importa. O texto da Anthropic sobre como escrever ferramentas para agentes mostra que nomes claros e escopo estreito reduzem erro de uso. O mesmo vale para a descrição do próprio subagente: ela é o que o agente principal lê para decidir se deve acioná-lo. Uma descrição vaga como ajuda com código faz o subagente ser acionado na hora errada ou nunca. Uma descrição como revisa mudanças já feitas e aponta riscos, sem editar arquivos deixa a fronteira clara.

Cenário ilustrativo: ajustar a regra de transbordo de um agente de atendimento

Imagine, como cenário ilustrativo, uma empresa que mantém o código de um agente de atendimento no WhatsApp e precisa mudar a regra que decide quando a conversa passa para uma pessoa. A mudança toca em vários arquivos e precisa de revisão cuidadosa. Uma divisão possível:

• Mapeador: lê o repositório e devolve uma lista curta dos pontos onde a regra aparece, com os trechos relevantes. Só ferramentas de leitura.
• Implementador: recebe a lista e faz a alteração apenas nos arquivos indicados. Pode editar, não acessa rede.
• Revisor: lê o resultado, compara com a regra combinada e roda os testes existentes. Não edita.

O ganho aqui não é velocidade, e sim separação de papéis. Quem revisa não é quem escreveu, e quem mapeia não tem como alterar nada por engano. Para saber o que a regra de transbordo deveria fazer, vale partir de um material de negócio, como o playbook de transbordo humano em agentes de WhatsApp, e não deixar o agente inferir a política.

Um cuidado de LGPD: nenhum desses subagentes precisa ler conversas reais de clientes. Use exemplos sintéticos ou anonimizados nos testes, e mantenha dados pessoais fora do repositório e do contexto do agente.

Plano para introduzir subagentes na equipe

O método que aplicamos em projetos de IA vale aqui, em escala pequena: mapear, limitar, pilotar e transferir. Sem hype, são quatro etapas verificáveis.

• Mapear: escolha um fluxo de trabalho real e repetido, como revisão de mudanças ou levantamento de impacto. Registre como ele é feito hoje, quanto tempo leva e onde aparecem retrabalho e erro. Sem esse ponto de partida, não há como saber se melhorou.
• Limitar: para cada subagente, escreva a função em uma frase, a lista explícita de ferramentas e o que ele deve devolver. Decida o que exige aprovação humana, por exemplo qualquer escrita fora da pasta da tarefa. O modelo de política de aprovação para agentes ajuda a organizar essa decisão.
• Pilotar: rode o fluxo com um ou dois subagentes, guardando o que cada um leu, executou e devolveu. Combine antes o critério de sucesso. O texto sobre como medir um piloto de automação detalha métricas e pontos de decisão.
• Transferir: documente os arquivos de subagentes no repositório, defina quem os mantém e decida em conjunto se vale expandir, ajustar ou parar. Parar é um resultado legítimo de piloto.

Se a equipe ainda está começando com a ferramenta como um todo, o guia de adoção do Claude Code para equipes cobre a base antes dos subagentes: permissões, revisão e rotina de uso.

Riscos e erros comuns ao usar subagentes

A maior parte dos problemas vem de excesso de permissão e de falta de registro, não de falha do modelo. Os mais frequentes:

• Herdar todas as ferramentas por omissão e só perceber quando algo é alterado fora do esperado.
• Dar a um subagente que lê conteúdo externo (páginas, tickets, e-mails, documentos de terceiros) também uma ferramenta de escrita ou de rede. Instruções escondidas nesse conteúdo podem tentar desviar o comportamento. A lista da OWASP sobre riscos em aplicações com LLMs trata disso como injeção de prompt e autonomia excessiva.
• Descrições de subagente genéricas, que fazem o agente principal acioná-los sem critério.
• Subagentes demais, sem dono, que ninguém atualiza quando o projeto muda.
• Aceitar o resumo do subagente como verdade sem checagem. O resumo é uma síntese, e pode omitir algo importante. Para decisões de risco, peça as evidências, como trechos de arquivo e saídas de teste.
• Não guardar registro. Sem log do que foi lido e executado, não existe auditoria possível.

Uma regra simples ajuda: se um subagente pode ler algo não confiável, ele não deve poder agir sobre nada sensível. Separar leitura de ação em subagentes diferentes é, muitas vezes, o melhor uso da divisão.

Perguntas frequentes

Subagentes substituem a revisão humana? Não. Um subagente revisor dá uma segunda leitura útil, mas não assume responsabilidade pela mudança. Mantenha uma pessoa aprovando o que vai para produção, principalmente em código que toca dados de clientes ou envia mensagens.

Um subagente pode acionar outros subagentes? Pela documentação do Claude Code, subagentes não criam outros subagentes, e a coordenação fica com o agente principal. Como esse comportamento pode mudar entre versões, confirme na documentação atual antes de desenhar um fluxo que dependa disso.

Usar subagentes aumenta o consumo? Pode aumentar, porque cada um trabalha em um contexto próprio e o total processado cresce. Em contrapartida, a conversa principal fica mais limpa. Meça os dois efeitos no piloto antes de decidir se a divisão compensa.

Preciso de subagentes para começar com Claude Code? Não. Comece com a ferramenta em tarefas simples, com permissões conservadoras, e só crie um subagente quando houver um papel repetido e bem definido, como revisar ou mapear impacto. Subagente é um recurso de organização, e não um requisito de entrada.

Fontes

• Anthropic: Effective context engineering for AI agents
• Anthropic: Building effective agents
• OWASP: Authorization Cheat Sheet
• OWASP Top 10 for LLM Applications