Claude responde demais? Crie sua própria equipe de IA com Subagents

Você pede ao Claude uma revisão de segurança do código e ele aproveita para trazer sugestões de refatoração, análise de desempenho e casos de teste — tudo isso em 3.000 linhas. O problema não é a IA entregar demais, mas a falta de uma forma de dizer a ela para se concentrar em uma única coisa.

Subagent é o mecanismo criado para resolver esse problema. Cada Subagent tem escopo de tarefa, permissões de ferramentas e escolha de modelo próprios, definidos no diretório .claude/agents/ do projeto. Precisa revisar código? Chame o Subagent de revisão. Precisa escrever documentação? Chame o Subagent de documentação. Os limites da tarefa ficam definidos no arquivo de configuração, evitando desvios de escopo e de assunto.

Este artigo explica como configurar e chamar Subagents e como usar modos de colaboração Multi-Agent. No final, há um caso prático de um sistema de produção de conteúdo para blog.

O que é um Subagent, afinal?

Em termos simples, um Subagent é um assistente personalizado que você cria para o Claude. Cada assistente tem seu próprio escopo de tarefa, permissões de ferramentas e até mesmo um modelo diferente.

Eles ficam no diretório .claude/agents/ do projeto, e cada arquivo representa um assistente. A estrutura do arquivo é simples: uma configuração YAML na parte superior e instruções detalhadas em Markdown logo abaixo.

---

name: code-reviewer
description: Assistente especializado em revisar a qualidade e a segurança do código
tools: [Read, Grep, Glob]
model: haiku

---

Você é especialista em revisão de código e deve se concentrar nestes problemas:
- Vulnerabilidades de segurança, como injeção de SQL e XSS
- Gargalos de desempenho
- Problemas de padrões de código
Você só precisa apontar os problemas. Não altere o código.

Em comparação com uma conversa comum com o Claude, um Subagent tem três diferenças claras:

Foco — ele faz apenas o que você definiu e não foge do assunto. Se a tarefa for revisar código, ele se limita à revisão, sem aproveitar para refatorar.

Limitações — você determina as permissões de ferramentas, e o agente não pode usar aquilo que não foi autorizado. Um assistente de revisão com acesso somente leitura simplesmente não consegue alterar seus arquivos.

Reutilização — o arquivo de configuração fica no projeto e pode ser usado por toda a equipe. Quando uma pessoa nova entra no time, basta chamar @code-reviewer para começar.

Por que usar Subagents?

Para ser sincero, no começo achei que isso fosse uma complicação desnecessária — não seria mais fácil conversar diretamente com o Claude?

Depois de usar por algum tempo, percebi como é útil.

Foco

O Claude é versátil demais. Quando você faz uma pergunta sobre código, ele pode aproveitar para explicar boas práticas, recomendar frameworks e até escrever documentação. Às vezes isso ajuda, mas na maioria dos casos é apenas ruído.

Um Subagent permite concentrar o Claude em uma única tarefa. Um assistente especializado em revisão de código não vai escrever um plano de refatoração; um assistente especializado em testes não vai questionar o projeto da sua arquitetura.

Otimização de custos

Muita gente talvez não perceba isto: nem toda tarefa exige o modelo mais caro.

Para pesquisa, conversão de formatos e análises simples, o Haiku é suficiente e custa cerca de um terço do Sonnet. Ao longo de um mês de trabalho em equipe, a economia pode ser considerável.

Processamento paralelo

Para mim, esta é a melhor parte.

Você pode iniciar várias tarefas ao mesmo tempo e executá-las em paralelo. Depois de concluir uma funcionalidade, por exemplo, pode pedir a um assistente para executar os testes unitários, a outro para revisar o código e a um terceiro para escrever a documentação. Na prática, o ganho de eficiência é bem perceptível.

Reutilização

Depois de criar um bom arquivo de configuração, basta enviá-lo para o repositório Git e toda a equipe poderá usá-lo. Assim, o conhecimento acumulado no projeto se transforma em uma configuração executável.

"O principal valor dos Subagents está no foco e na reutilização. Um generalista se transforma em uma equipe de especialistas, e cada um cuida apenas daquilo que faz melhor."

Configuração YAML em detalhes

Depois de toda essa explicação, como escrever o arquivo de configuração?

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Uma configuração completa de Subagent tem vários campos, mas apenas dois são obrigatórios:

---

name: blog-writer          # Obrigatório: identificador único do assistente
description: Especialista em escrever rascunhos para o blog  # Obrigatório: descrição curta que influencia o acionamento automático
tools: [Read, Write, Grep]  # Opcional: permissões de ferramentas; o padrão é acesso total
model: sonnet              # Opcional: escolha do modelo; por padrão, herda o modelo da conversa principal

---

# As instruções ficam abaixo do YAML
Você é um redator profissional para blogs...

name — é o ID do assistente, usado para identificá-lo nas chamadas. Prefira um nome que deixe a função evidente à primeira vista, como code-reviewer ou test-writer.

description — este campo é muito importante. O Claude usa a descrição para decidir quando acionar o assistente automaticamente. Se você escrever “assistente genérico para várias tarefas”, provavelmente ele nunca será acionado dessa forma.

Uma descrição ruim:

description: Um assistente

Uma descrição boa:

description: Pesquisa um tema de blog em profundidade e gera um documento estruturado de planejamento de conteúdo

tools — lista de permissões de ferramentas. Quando esse campo não é configurado, o padrão é permitir todas as ferramentas, o que não costuma ser uma boa ideia — falaremos disso a seguir.

model — define qual modelo será usado. haiku é barato e rápido, sonnet é a opção equilibrada padrão, e opus oferece a maior qualidade pelo preço mais alto.

Controle de permissões de ferramentas

Já cometi um erro nessa parte, por isso vale tratá-la separadamente.

No começo, por conveniência, deixei todos os Subagents com acesso total, que é o padrão. Em certa ocasião, um assistente que deveria apenas analisar o código acabou alterando alguns arquivos — e fez isso de forma errada.

Desde então, passei a tratar as permissões de ferramentas com cuidado. O princípio é simples: conceda somente as permissões necessárias.

Combinações comuns de permissões:

Veja uma comparação prática.

Configuração ruim: permissões demais para o assistente de revisão de código.

---

name: code-reviewer
tools: []  # Array vazio = acesso total; não é muito seguro

---

Configuração boa: apenas permissões de leitura.

---

name: code-reviewer
tools: [Read, Grep, Glob]

---

Um assistente de revisão com acesso somente leitura simplesmente não consegue alterar seu código por engano. Essa restrição também funciona como proteção.

Três formas de chamar um Subagent

Depois de configurar tudo, como chamar o assistente? Há três formas.

Acionamento automático

Se a description for clara o suficiente, o Claude decide automaticamente quando deve chamar o assistente. Por exemplo, se a descrição disser “processa todas as solicitações relacionadas à revisão de código”, o pedido “revise este PR” acionará o agente automaticamente.

@-mention

A forma mais direta é usar @agent-name:

@code-reviewer Veja se há algum problema nesta função

Ferramenta Task

É uma chamada programática, adequada para cenários mais complexos:

Task(subagent_type="code-reviewer", prompt="Revise todos os arquivos do diretório src/")

Pessoalmente, uso mais o @-mention porque é simples e direto. O acionamento automático às vezes interpreta o pedido de forma errada, e a ferramenta Task costuma ser necessária apenas em fluxos mais complexos.

Colaboração Multi-Agent

Até aqui, vimos apenas como usar um único assistente. O verdadeiro potencial dos Subagents aparece quando vários deles colaboram.

Modo sequencial

O modo que mais uso é o sequencial, especialmente em fluxos de produção de conteúdo:

Usuário informa o tema
    |
@blog-planner pesquisa e cria a estrutura
    | gera o documento de planejamento
@blog-writer lê a estrutura e escreve o rascunho
    | gera o rascunho
@blog-editor lê o rascunho e prepara a versão para publicação
    | gera a versão final

Cada assistente cuida de uma etapa, e a saída de um é a entrada do próximo. O fluxo fica claro, controlável e fácil de depurar.

Modo paralelo

O modo paralelo é ainda mais interessante. Depois de concluir uma funcionalidade, você pode iniciar ao mesmo tempo:

• @test-writer para escrever testes unitários;
• @code-reviewer para revisar o código;
• @doc-writer para escrever a documentação.

As três tarefas são executadas em paralelo e não interferem entre si. Algo que antes levaria 30 minutos em sequência pode ficar pronto em 10 minutos.

Modo HITL (Human In The Loop)

Há também um modo adequado para cenários que exigem confirmação humana:

@planner gera o plano
    |
Usuário confirma ou altera
    |
@executor executa o plano

A vantagem desse modo é manter uma pessoa no controle dos pontos de decisão importantes, evitando que o fluxo fique totalmente sem supervisão.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Sete dicas para criar bons Subagents

Depois de alguns meses usando Subagents, reuni sete dicas para criar configurações mais úteis.

Dica 1: seja preciso na descrição

A description influencia diretamente a precisão do acionamento automático.

Descrição vaga — dificilmente será acionada automaticamente:

description: Um assistente genérico

Descrição precisa — deixa o escopo bem definido:

description: Especialista em revisar vulnerabilidades de segurança e problemas de desempenho em código Python

Dica 2: escreva instruções específicas

Não diga apenas “você é especialista em revisão de código”. Explique exatamente como a revisão deve ser feita.

Instrução genérica demais:

Você é especialista em revisão de código. Ajude o usuário a revisar o código.

Orientação específica:

Você é especialista em revisão de segurança de código Python.
## Pontos da revisão
1. Risco de injeção de SQL — verifique todas as operações de banco de dados
2. Vulnerabilidades XSS — verifique o tratamento das entradas do usuário
3. Exposição de informações confidenciais — verifique logs e tratamento de erros
## Formato da saída
Informe cada problema neste formato:
- Arquivo: xxx
- Linha: xxx
- Nível de risco: alto/médio/baixo
- Descrição do problema: xxx
- Sugestão de correção: xxx

Dica 3: minimize as ferramentas

Como vimos antes, conceda apenas as permissões necessárias. Dar menos permissões não torna o assistente menos inteligente; apenas limita o que ele pode fazer.

Dica 4: escolha o modelo certo

Use o Haiku para tarefas simples e o Sonnet para tarefas complexas. Mais especificamente:

• O Haiku é indicado para: pesquisa e síntese, conversão de formatos, análises simples e organização de dados;
• O Sonnet é indicado para: lógica complexa, conteúdo criativo, geração de código e análises que exigem raciocínio.

Dica 5: teste bem

Depois de criar a configuração, experimente várias formas de chamada. O acionamento automático funciona bem? O @-mention responde como esperado? Como o agente trata casos extremos?

Dica 6: documente com clareza

As próprias instruções funcionam como documentação. Quando são claras, qualquer pessoa da equipe entende de imediato o que o assistente faz e como usá-lo.

Dica 7: itere com frequência

Não tente deixar tudo perfeito na primeira versão. Comece com algo funcional, use por algum tempo e faça ajustes graduais com base no feedback.

Sete erros comuns e como evitá-los

Depois das dicas, veja alguns erros que já cometi.

Erro 1: descrição vaga demais

Com uma descrição como “assistente genérico”, o Claude não sabe quando deve chamá-lo. Explique claramente qual é a responsabilidade do agente.

Ruim:

description: Assistente que ajuda o usuário

Melhor:

description: Quando o usuário mencionar "testes" ou "testes unitários", gera casos de teste automaticamente

Erro 2: permissões de ferramentas em excesso

Conceder acesso total por conveniência pode fazer o assistente realizar ações que você não queria. Pense com cuidado antes de conceder a permissão Write.

Ruim:

name: format-converter
tools: []  # Array vazio = acesso total

Melhor:

name: format-converter
tools: [Read, Write]

Erro 3: instruções longas demais

As instruções do Subagent também consomem tokens. Se você escrever milhares de palavras, todos esses tokens serão consumidos a cada chamada. Seja conciso e inclua apenas as informações necessárias.

Erro 4: esquecer de definir o modelo

Se o campo model não for definido, o Subagent herdará o modelo da conversa principal, que normalmente é o Sonnet. Isso aumenta o custo de tarefas simples sem necessidade.

Sem definir o modelo:

name: text-extractor
tools: [Read]

Com o modelo definido:

name: text-extractor
tools: [Read]
model: haiku

Erro 5: chamadas em ciclo

O Agent A chama o Agent B, e o Agent B chama o Agent A. Esse ciclo infinito continuará até atingir o tempo limite ou ser interrompido à força.

Correto: A -> B -> C

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

Errado: A -> B -> A

Erro 6: não tratar erros

Subagents também podem falhar. Adicione tratamento de erros ao fluxo para detectar rapidamente qualquer falha.

Erro 7: configuração fora do controle de versão

Envie os arquivos de configuração para o Git. Assim, se uma alteração causar problemas, será possível voltar à versão anterior.

Caso prático: sistema de produção de conteúdo para blog

Depois de tanta teoria, vamos a um exemplo real.

O sistema de produção de conteúdo para blog que uso tem três Subagents.

Arquitetura do sistema

Usuário informa o tema
    |
blog-planner: pesquisa + planejamento (20 minutos)
    | saída: docs/[tema]-documento-de-planejamento.md
blog-writer: escreve o rascunho (40 minutos)
    | saída: docs/[tema]-rascunho.md
blog-editor: revisa e aprimora (20 minutos)
    | saída: docs/[tema]-versao-final.md

blog-planner (planejador)

---

name: blog-planner
description: Pesquisa um tema em profundidade e cria um documento de planejamento de conteúdo
tools: [Read, Write, Grep, WebSearch, WebFetch]
model: sonnet

---

Você é responsável pelo planejamento de conteúdo e deve:
1. Usar WebSearch para pesquisar as tendências mais recentes do tema
2. Analisar o público-alvo e suas dificuldades
3. Planejar a estrutura do artigo e a estratégia de SEO
4. Salvar o documento de planejamento no diretório docs/

blog-writer (redator)

---

name: blog-writer
description: Escreve um rascunho de blog com base no documento de planejamento
tools: [Read, Write, Grep]
model: sonnet

---

Você é responsável pela redação de conteúdo e deve:
1. Ler o documento de planejamento
2. Escrever um rascunho completo de acordo com a estrutura
3. Garantir que o texto seja natural e não pareça gerado por IA
4. Salvar o rascunho no diretório docs/

blog-editor (editor)

---

name: blog-editor
description: Edita o rascunho e aprimora a naturalidade do texto
tools: [Read, Edit]
model: haiku

---

Você é responsável pela edição de conteúdo e deve:
1. Ler o rascunho
2. Identificar e eliminar trechos que pareçam gerados por IA
3. Tornar o texto mais natural e fácil de ler
4. Salvar a versão final no diretório docs/

O fluxo de trabalho é simples:

# Etapa 1: planejamento
@blog-planner Dicas para usar Subagents no Claude Code
# Etapa 2: redação
@blog-writer
# Etapa 3: edição
@blog-editor

Cada etapa tem entradas e saídas bem definidas, o que facilita encontrar a origem de qualquer problema.

Dicas para otimizar custos

Por fim, vamos falar sobre custos.

A diferença de preço entre o Haiku e o Sonnet é de cerca de três vezes — consulte o site oficial da Anthropic para ver os valores exatos. Em uma tarefa típica de produção de conteúdo para blog, distribuir os modelos de forma adequada pode gerar uma boa economia.

Estratégia de escolha do modelo

Minha recomendação é a seguinte.

Quando usar o Haiku

• Pesquisa e síntese de informações
• Conversão simples de formatos
• Organização e classificação de dados
• Revisão de código com análise somente leitura

Quando usar o Sonnet

• Produção de conteúdo, como blogs e documentação
• Geração de código complexo
• Análises que exigem raciocínio
• Cenários com alta exigência de qualidade

Comparação dos modelos

Quase nunca uso o Opus, exceto em tarefas especialmente importantes e com exigência muito alta de qualidade. Para o trabalho cotidiano, o Sonnet é suficiente.

Regras simples para economizar

Lembre-se destas recomendações:

• Se o Haiku for suficiente, não use o Sonnet.
• Se puder limitar as ferramentas, não conceda All tools.
• Se puder simplificar as instruções, não as torne longas demais.
• Se puder limitar a saída, não deixe o agente responder sem restrições.

Para concluir

Em resumo, Subagent não é nenhuma tecnologia misteriosa. É apenas uma forma de dividir os recursos do Claude conforme a necessidade. Um generalista se transforma em uma equipe de especialistas, e cada um cuida apenas daquilo que faz melhor.

Se você ainda usa “um único Claude para tudo”, recomendo experimentar os Subagents. Meia hora investida na criação de algumas configurações pode poupar muitos momentos em que “o Claude fugiu do assunto de novo”.

Os princípios essenciais são estes:

1. Cada agent deve cuidar de apenas uma tarefa.
2. Conceda somente as permissões de ferramentas necessárias.
3. Use o Haiku para tarefas simples.
4. Escreva instruções específicas e claras.
5. Em fluxos com vários agents, use documentos para transmitir informações.

Se algo der errado, não se preocupe: na maioria das vezes, o problema está na configuração. Compare seu caso com estas sete dicas e estes sete erros comuns; isso costuma ser suficiente para encontrar a solução.

E uma última recomendação: não tente criar uma configuração perfeita. Comece a usar e melhore aos poucos.

Boa sorte ao montar sua própria equipe de IA!