DEV Community

Cover image for Como Criar Subagentes de Código Personalizados para Claude (Guia Passo a Passo)
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Criar Subagentes de Código Personalizados para Claude (Guia Passo a Passo)

Há um limite que você atinge em qualquer sessão de codificação com IA: a janela de contexto. Se você coloca uma refatoração grande, três rodadas de testes e uma revisão de código na mesma conversa, o agente começa a perder foco. Os subagentes do Claude Code resolvem isso criando “trabalhadores” especializados, cada um com sua própria janela de contexto, instruções e permissões de ferramentas. Eles recebem uma tarefa, executam, retornam um resultado e mantêm o fluxo principal limpo.

Experimente o Apidog hoje

Este guia mostra como criar subagentes personalizados no Claude Code: onde colocar os arquivos, como configurar o frontmatter YAML, como escrever descrições que acionam delegação automática e como montar um fluxo prático em que um agente revisa código enquanto outro escreve testes de API em paralelo. Se você quiser primeiro a visão conceitual, veja o artigo sobre o que são e por que são importantes os subagentes do Claude Code. Aqui, o foco é implementação.

TL;DR

Para criar um subagente do Claude Code, escreva um arquivo Markdown em .claude/agents/ com frontmatter YAML:

  • name: identificador do subagente
  • description: regra que ajuda Claude a decidir quando delegar
  • tools: lista opcional de ferramentas permitidas
  • model: modelo opcional

O corpo do arquivo vira o prompt de sistema do subagente. Cada subagente roda em sua própria janela de contexto, com suas próprias ferramentas, o que permite isolamento, paralelismo e especialização. Claude pode delegar automaticamente com base na descrição, ou você pode invocar o subagente pelo nome. A referência oficial está na documentação de subagentes do Claude Code.

Subagentes em 60 segundos

Um subagente é uma instância separada para a qual o agente principal do Claude Code delega uma tarefa.

Pense assim:

  • O agente principal é o engenheiro líder.
  • Os subagentes são especialistas acionados sob demanda.
  • Cada especialista trabalha em uma conversa isolada.
  • Ao final, ele retorna apenas o resultado.

Três propriedades tornam subagentes úteis:

  1. Janela de contexto própria

    O subagente começa apenas com a tarefa atribuída. O fluxo principal não acumula leituras, tentativas, logs e raciocínio intermediário.

  2. Prompt de sistema personalizado

    Você define o comportamento: revisor adversarial, escritor de testes, auditor de segurança, documentador etc.

  3. Ferramentas configuráveis

    Você concede apenas o necessário. Um revisor pode ter acesso somente a leitura; um executor de testes pode receber acesso ao shell.

Essa é a mesma ideia de isolamento descrita na arquitetura de harness do agente Claude Code, aplicada ao nível de tarefas individuais.

Por que usar subagentes

1. Isolamento de contexto

Sessões longas degradam conforme a janela de contexto enche. Cada arquivo lido, comando executado ou teste com saída extensa consome tokens e reduz foco.

Delegar uma tarefa pesada para um subagente mantém esse ruído fora da conversa principal. O agente principal recebe um resumo limpo em vez de dezenas de milhares de tokens intermediários.

Isso também ajuda no custo, porque você evita arrastar um contexto inchado a cada turno. Veja também as notas sobre reduzir os custos de tokens do agente.

2. Paralelismo

Tarefas independentes não precisam rodar em sequência.

Exemplo:

  • um subagente revisa o módulo de pedidos;
  • outro escreve testes de API;
  • outro atualiza documentação.

O tempo total passa a se aproximar da tarefa mais lenta, não da soma de todas. Os fluxos de trabalho dinâmicos levam esse padrão para distribuições maiores.

3. Especialização

Um agente generalista pode fazer muita coisa, mas um subagente com prompt e ferramentas específicas tende a ser melhor em uma função delimitada.

Exemplos:

  • um revisor instruído a procurar bugs de segurança;
  • um escritor de testes que segue suas convenções de asserção;
  • um auditor que só lê arquivos e retorna riscos;
  • um agente de documentação que gera exemplos a partir da especificação.

Como criar um subagente personalizado

Subagentes são arquivos Markdown.

Use:

.claude/agents/
Enter fullscreen mode Exit fullscreen mode

para subagentes do projeto, ou:

~/.claude/agents/
Enter fullscreen mode Exit fullscreen mode

para subagentes pessoais.

Cada arquivo tem:

  1. frontmatter YAML;
  2. corpo em Markdown, usado como prompt de sistema.

Exemplo de subagente revisor:

---
name: revisor-de-codigo
description: "Revisa alterações de código em busca de bugs, problemas de segurança e violações de convenção. Use após escrever ou editar código."
tools: Read, Grep, Glob
model: sonnet
---

Você é um revisor de código sênior. Ao receber um diff ou um conjunto de arquivos:

1. Procure por bugs de correção, falhas de segurança e casos de borda perdidos.
2. Verifique se o código corresponde às convenções existentes do projeto.
3. Relate apenas problemas de alta confiança, classificados por gravidade.

Seja específico. Cite arquivo e linha. Não aprove sem revisar.
Enter fullscreen mode Exit fullscreen mode

Campos do frontmatter

name

Identificador usado para invocar o subagente.

Exemplo:

name: revisor-de-codigo
Enter fullscreen mode Exit fullscreen mode

Depois você pode pedir:

Use o subagente revisor-de-codigo para revisar as alterações no módulo de pedidos.
Enter fullscreen mode Exit fullscreen mode

description

É o campo mais importante para delegação automática. Claude usa essa descrição para decidir quando chamar o subagente.

Prefira descrições com gatilhos claros:

description: Revisa alterações de código em busca de bugs e problemas de segurança. Use após escrever ou editar código.
Enter fullscreen mode Exit fullscreen mode

Evite descrições vagas:

description: Revisor de código.
Enter fullscreen mode Exit fullscreen mode

tools

Lista de ferramentas permitidas.

Exemplo para um revisor somente leitura:

tools: Read, Grep, Glob
Enter fullscreen mode Exit fullscreen mode

Exemplo para um executor de testes:

tools: Read, Grep, Bash
Enter fullscreen mode Exit fullscreen mode

Se você omitir tools, o subagente pode herdar ferramentas do agente principal. Isso pode ser útil, mas também aumenta risco em execuções automatizadas.

model

Campo opcional para fixar o modelo.

Use modelos mais rápidos ou baratos para tarefas mecânicas e modelos mais fortes para tarefas que exigem raciocínio complexo.

model: sonnet
Enter fullscreen mode Exit fullscreen mode

Corpo do arquivo

O corpo é o prompt de sistema do subagente. Escreva como se estivesse instruindo um novo membro da equipe:

  • o que fazer;
  • o que priorizar;
  • o que evitar;
  • qual formato de saída usar;
  • quais critérios definem sucesso.

Se o projeto já usa um design.md ou AGENTS.md, referencie essas convenções para evitar duplicação.

Como invocar subagentes

Há duas formas principais.

1. Delegação automática

Claude lê o campo description dos subagentes disponíveis e delega quando a tarefa combina.

Exemplo: depois de editar código, Claude pode acionar automaticamente revisor-de-codigo se a descrição disser:

description: Revisa alterações de código em busca de bugs, problemas de segurança e violações de convenção. Use após escrever ou editar código.
Enter fullscreen mode Exit fullscreen mode

Por isso, descrições devem ser escritas como instruções de uso, não como títulos.

2. Invocação explícita

Você também pode chamar o subagente pelo nome:

Use o subagente revisor-de-codigo nas alterações do módulo de pedidos.
Enter fullscreen mode Exit fullscreen mode

Ou:

Use o subagente escritor-de-teste-api para criar testes para o novo endpoint POST /orders.
Enter fullscreen mode Exit fullscreen mode

Use invocação explícita quando quiser controlar exatamente qual especialista será acionado.

Para encadear subagentes em sequências mais determinísticas, comandos de barra e SDK dão mais controle do que prompts ad hoc. A visão geral do Claude Code cobre as opções de configuração.

Subagentes vs SDK do Agente vs fluxos de trabalho dinâmicos

Ferramenta Modelo de controle Melhor para
Subagentes O modelo decide quando delegar, ou você nomeia um subagente Especialização em sessão e paralelismo leve
Fluxos de trabalho dinâmicos O modelo orquestra uma distribuição maior dentro da sessão Muitas tarefas paralelas e varreduras amplas
SDK do Agente Você escreve o fluxo de controle em código Loops determinísticos, execuções agendadas ou não supervisionadas

Use subagentes quando estiver trabalhando interativamente no Claude Code e quiser especialistas focados.

Use o SDK do Agente Claude quando precisar de execução programática, agendada ou não supervisionada.

Se você está comparando uma opção hospedada com uma implementação própria, veja a comparação entre agentes gerenciados e SDK do Agente.

Exemplo prático: revisão e testes de API em paralelo

Imagine que o agente principal implementou um novo endpoint de pedidos.

Você quer duas coisas:

  1. revisar o código;
  2. criar e executar testes de API.

Essas tarefas são independentes, então podem rodar em paralelo.

Você já tem o subagente revisor-de-codigo. Agora crie um escritor de testes:

---
name: escritor-de-teste-api
description: Escreve casos de teste de API para endpoints novos ou alterados. Use após a implementação de um endpoint.
tools: Read, Grep, Write, Bash
model: sonnet
---

Você escreve testes de API contra a especificação OpenAPI do projeto.

1. Leia a especificação e a implementação do endpoint.
2. Escreva testes cobrindo sucesso, erros de validação e autenticação.
3. Afirme códigos de status e valide corpos de resposta contra o esquema.
4. Execute a suíte e relate aprovação/reprovação com motivos.
Enter fullscreen mode Exit fullscreen mode

Agora peça ao agente principal:

Use revisor-de-codigo para revisar as alterações do endpoint de pedidos.
Em paralelo, use escritor-de-teste-api para criar e executar testes de API para o mesmo endpoint.
Enter fullscreen mode Exit fullscreen mode

Resultado esperado:

  • o revisor lê o diff e retorna problemas por gravidade;
  • o escritor de testes lê a especificação, escreve cobertura e executa a suíte;
  • o agente principal recebe dois relatórios limpos.

Transforme o subagente de teste em uma porta de verificação

A parte crítica é executar testes reais.

Um subagente que apenas “olha” o endpoint pode parecer confiante e ainda errar. Um subagente que executa uma suíte de API vira uma porta de verificação: ele confirma se o endpoint funciona, se os códigos de status batem e se os corpos seguem o contrato.

Esse é o princípio dos loops de agente de codificação: a confiança do agente não basta; o veredito da verificação importa.

Para endpoints, conecte o subagente a uma plataforma de teste de API. Equipes usando Apidog podem apontar o subagente para cenários de teste Apidog, validar respostas contra esquemas e inspecionar chamadas por meio do depurador de agente de IA Apidog.

Você também pode envolver esse padrão em um loop para criar fluxos não supervisionados, como nos fluxos de trabalho Claude que funcionam sem você. Se quiser uma porta de teste ciente de esquema, baixe o Apidog.

Melhores práticas

1. Uma responsabilidade por subagente

Não crie um subagente que revisa, testa, documenta e corrige. Isso recria o agente principal com mais complexidade.

Prefira:

  • revisor-de-codigo
  • escritor-de-teste-api
  • auditor-seguranca
  • gerador-documentacao

2. Escreva descrições como gatilhos

Ruim:

description: Revisor de código.
Enter fullscreen mode Exit fullscreen mode

Melhor:

description: Revisa alterações de código em busca de bugs e problemas de segurança. Use após escrever ou editar código.
Enter fullscreen mode Exit fullscreen mode

3. Conceda privilégio mínimo

Um revisor normalmente não precisa escrever arquivos.

tools: Read, Grep, Glob
Enter fullscreen mode Exit fullscreen mode

Um executor de testes pode precisar de shell:

tools: Read, Grep, Bash
Enter fullscreen mode Exit fullscreen mode

Um escritor de testes pode precisar escrever arquivos:

tools: Read, Grep, Write, Bash
Enter fullscreen mode Exit fullscreen mode

4. Fixe o modelo certo para cada trabalho

Tarefas mecânicas podem usar modelos mais rápidos. Tarefas com raciocínio complexo podem usar modelos mais fortes.

Isso controla custo e latência.

5. Peça resultados estruturados

Inclua no prompt do subagente um formato de saída.

Exemplo para revisão:

Retorne no formato:

Veredito: aprovado | reprovado

Problemas:
1. Gravidade: alta | média | baixa
   Arquivo:
   Linha:
   Descrição:
   Correção sugerida:
Enter fullscreen mode Exit fullscreen mode

Exemplo para testes:

Retorne no formato:

Status: aprovado | reprovado

Testes executados:
- Nome:
  Resultado:
  Motivo:

Falhas:
- Endpoint:
  Esperado:
  Recebido:
Enter fullscreen mode Exit fullscreen mode

Saídas estruturadas são mais fáceis para o agente principal interpretar e para você agir.

6. Evite aninhamento excessivo

Subagentes chamando subagentes que chamam subagentes tornam o fluxo caro e difícil de depurar. Mantenha a hierarquia rasa.

Esses padrões são parecidos com os descritos em padrões e armadilhas de fiação de ferramentas de fluxo de trabalho agêntico.

Quando usar subagentes

Use um subagente quando a tarefa for:

  • delimitada: tem começo e fim claros;
  • independente: não depende de todo o estado da conversa principal;
  • barulhenta: envolve muita leitura, logs, testes ou análise intermediária.

Bons casos:

  • revisar um diff;
  • escrever testes para um endpoint;
  • reproduzir um bug;
  • auditar um módulo;
  • validar uma especificação OpenAPI;
  • gerar documentação a partir de arquivos existentes.

Quando não usar subagentes

Evite subagentes quando a tarefa for:

  • pequena;
  • rigidamente acoplada ao fluxo principal;
  • sequencial;
  • dependente de muito contexto já presente na conversa.

Exemplos:

  • renomear uma variável;
  • corrigir um typo;
  • ajustar uma linha;
  • fazer uma alteração em que o agente principal já tem todo o contexto visível.

Regra prática:

Delegue trabalho autocontido o suficiente para ser descrito em um parágrafo e valioso o suficiente para rodar em paralelo.

Um endpoint novo para revisar e testar se encaixa. Uma correção de erro de digitação não.

Quando você escala para muitos subagentes concorrentes, os padrões de fluxos de trabalho dinâmicos assumem mais importância.

Erros comuns

Descrições vagas

Se description for apenas um rótulo, a delegação automática será inconsistente.

Use descrições com gatilho de uso.

Subagente inchado

Um subagente que faz tudo perde especialização.

Divida por responsabilidade.

Herdar todas as ferramentas por padrão

Omitir tools pode dar acesso amplo demais. Em fluxos automatizados, liste permissões explicitamente.

Não ter subagente de verificação

Revisão sem teste ainda pode entregar código quebrado.

Inclua um subagente que execute testes reais.

Tratar subagentes como SDK

Subagentes são úteis dentro da sessão do Claude Code. Se você precisa de fluxo determinístico, agendado ou não supervisionado, use o SDK do Agente.

A ideia mais ampla aparece em Building Effective Agents, da Anthropic: estruturar o ambiente ao redor do modelo costuma ser melhor do que apenas escrever prompts maiores.

Perguntas frequentes

O que é um subagente do Claude Code?

É uma instância separada para a qual o agente principal delega tarefas. Cada subagente tem sua própria janela de contexto, prompt de sistema e ferramentas configuráveis. Ele executa uma tarefa focada e retorna o resultado.

Como crio um subagente do Claude Code?

Crie um arquivo Markdown em .claude/agents/ para o projeto ou ~/.claude/agents/ para uso pessoal. Adicione frontmatter YAML com name, description, tools opcionais e model opcional. Depois escreva o prompt de sistema no corpo do arquivo.

Como Claude decide qual subagente usar?

Claude lê o campo description dos subagentes disponíveis e delega automaticamente quando a tarefa combina. Você também pode invocar explicitamente pelo nome.

Qual a diferença entre subagentes e o SDK do Agente Claude?

Subagentes são acionados dentro da sessão do Claude Code, geralmente pelo próprio modelo. O SDK do Agente é programático: você escreve o fluxo de controle em código para execuções determinísticas, agendadas ou não supervisionadas.

Subagentes podem rodar em paralelo?

Sim. O agente principal pode despachar múltiplos subagentes para tarefas independentes, como revisão, testes e documentação.

Como subagentes ajudam no teste de API?

Você pode criar um subagente que escreve e executa testes de API contra uma especificação OpenAPI. Ele valida se o endpoint funciona de verdade, em vez de apenas parecer correto. Apontá-lo para uma plataforma como Apidog torna o feedback ciente do esquema e ajuda a validar respostas contra o contrato.

Conclusão

Subagentes do Claude Code resolvem um problema prático: uma única janela de contexto não consegue conter tudo. Ao dar contexto, instruções e ferramentas próprias para cada tarefa, você transforma um agente sobrecarregado em uma pequena equipe de especialistas.

Comece com dois subagentes:

  1. um revisor;
  2. um testador de API.

Escreva descrições claras para delegação automática, conceda apenas as ferramentas necessárias e faça o subagente de teste executar uma suíte real. Para endpoints, o Apidog fornece uma base ciente de esquema para essa verificação. Baixe o Apidog e deixe o subagente provar que o código funciona antes de você confiar no diff.

Top comments (0)