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

Há um limite que você atinge com qualquer sessão de codificação de IA: a janela de contexto. Se você sobrecarregar uma conversa com uma refatoração extensa, três rodadas de saída de teste e uma revisão de código, o agente começa a perder o fio da meada. Os subagentes do Claude Code são a solução. Em vez de um agente que precisa lidar com tudo em um único contexto, você cria "trabalhadores" focados, cada um com sua própria janela de contexto, suas próprias instruções e suas próprias permissões de ferramentas. Eles fazem um trabalho, devolvem um resultado e mantêm o fluxo principal limpo.

Este é o guia prático de construção. Como criar um subagente personalizado como um arquivo de configuração, o que cada campo de frontmatter faz, como Claude decide delegar a ele e como configurar um ambiente prático onde um agente revisa o código enquanto outro escreve testes em paralelo. Se você quiser primeiro a visão geral conceitual, nosso artigo sobre o que são e por que são importantes os subagentes do Claude Code aborda o básico. Aqui, focamos em construí-los e no ângulo de teste de API que transforma um subagente de teste em uma etapa de verificação em que você pode confiar.

TL;DR

Você cria um subagente do Claude Code escrevendo um arquivo Markdown em .claude/agents/ com frontmatter YAML: um name, uma description que informa a Claude quando delegar, uma lista de permissões tools opcional e um model opcional. O corpo do arquivo se torna o prompt de sistema do subagente. Cada subagente é executado em sua própria janela de contexto com suas próprias ferramentas, proporcionando isolamento de contexto, paralelismo e especialização. Claude delega automaticamente com base na descrição, ou você invoca um subagente pelo nome. A referência oficial são os documentos de subagentes do Claude Code.

Subagentes em 60 segundos

Um subagente é uma instância de agente separada para a qual o agente principal do Claude Code atribui uma tarefa. O agente principal é o engenheiro líder; os subagentes são especialistas que ele aciona. O especialista trabalha em sua própria conversa, com sua própria janela de contexto e prompt de sistema, e depois retorna apenas o resultado. Três propriedades os tornam dignos de configuração:

• Sua própria janela de contexto. Um subagente começa do zero apenas com a tarefa que lhe foi atribuída, de modo que o fluxo principal nunca se enche com seu trabalho intermediário.
• Um prompt de sistema personalizado. Você molda como ele se comporta: um revisor que caça falhas de segurança, um escritor de testes que segue suas convenções.
• Ferramentas configuráveis. Você concede a cada subagente apenas as ferramentas de que ele precisa, de modo que um revisor não possa escrever e um executor de testes obtenha apenas acesso suficiente ao shell.

Essa é a base conceitual; a visão geral conceitual aprofunda o "porquê". O restante deste guia é sobre construí-los, que é o mesmo princípio por trás da arquitetura de harness do agente Claude Code aplicada ao nível de tarefas individuais.

Por que usar subagentes

Três razões, e elas se somam.

Isolamento de contexto. Uma sessão longa se degrada à medida que a janela de contexto se preenche. Cada arquivo lido, cada teste executado, cada tangente consome orçamento e dilui o foco. Delegar uma tarefa robusta a um subagente mantém todo esse trabalho no contexto do subagente, não no principal. O agente principal recebe um resumo limpo em vez de 50.000 tokens de ruído intermediário. Esse isolamento também é uma alavanca de custo, já que você não está arrastando um contexto inchado por cada turno. Nossas notas sobre reduzir os custos de tokens do agente abordam a economia.

Paralelismo. Tarefas independentes não precisam ser executadas uma após a outra. Um agente principal pode despachar vários subagentes de uma vez: revisar este módulo enquanto testa aquele e documenta um terceiro. O tempo real de execução cai para a tarefa única mais lenta em vez da soma. Os fluxos de trabalho dinâmicos do Claude Code levam isso ao seu limite, distribuindo centenas de subagentes paralelos a partir de uma única sessão.

Especialização. Um agente geral é bom em tudo e ótimo em nada. Um subagente com um prompt de sistema conciso e as ferramentas certas é ótimo em uma coisa. Um revisor instruído a ser "adversário" encontra mais bugs do que um generalista olhando o diff. Um escritor de testes que conhece seu estilo de asserção produz testes que você realmente manterá. Você constrói uma pequena equipe de especialistas em vez de um generalista sobrecarregado.

Como criar um subagente personalizado

Subagentes são arquivos Markdown simples. Coloque os de nível de projeto em .claude/agents/ e os pessoais em ~/.claude/agents/. Cada arquivo tem frontmatter YAML e um corpo que se torna o prompt de sistema do subagente.

Aqui está um revisor de código:

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

Os campos do frontmatter:

• name — o identificador que você usa para invocá-lo.
• description — este é o importante. Claude o lê para decidir quando delegar automaticamente. Escreva-o como um gatilho claro ("Use após escrever código"), não um rótulo vago.
• tools — a lista de permissões. Omita-o para herdar as ferramentas do agente principal, ou liste específicos para restringir. Um revisor que não pode escrever código não pode acidentalmente alterá-lo.
• model — opcionalmente fixe um modelo. Use um modelo mais barato e rápido para subagentes mecânicos e um mais forte para raciocínio complexo.

O corpo é o prompt de sistema. É aqui que reside a especialização, então escreva-o como você instruiria um novo contratado: o que fazer, o que priorizar, o que evitar. Combiná-lo com um design.md ou AGENTS.md do projeto dá ao subagente suas convenções sem repeti-las em cada arquivo.

Como invocar subagentes

Há duas maneiras de um subagente ser executado.

Delegação automática. Claude lê o campo description de cada subagente disponível e delega por conta própria quando uma tarefa corresponde. Termine de editar um arquivo e o agente principal pode entregar o diff ao seu revisor-de-codigo sem que lhe seja dito, porque a descrição diz "use após escrever código". Boas descrições impulsionam uma boa delegação.

Invocação explícita. Você também pode nomeá-lo diretamente: "use o subagente revisor-de-codigo nas alterações no módulo de pedidos". É assim que você força um especialista específico quando não quer deixar a delegação ao acaso.

De qualquer forma, o subagente é executado em seu próprio contexto, faz o trabalho e retorna um resultado para o fluxo principal. Você vê a passagem acontecer, e pode configurar quantos detalhes aparecem. Para encadear subagentes em sequências determinísticas e repetíveis, comandos de barra e o SDK dão mais controle do que prompts ad hoc; a visão geral do Claude Code cobre a superfície de configuração.

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

Estes se sobrepõem, então aqui está quando cada um se encaixa.

Subagentes são a opção conversacional em sessão: você está trabalhando no Claude Code e quer um especialista ou dois. Quando você precisa de um loop programático que é executado em um cronograma sem a presença humana, você recorre ao SDK do Agente Claude e escreve a orquestração você mesmo. Se você está avaliando uma opção hospedada versus criar a sua própria, nossa comparação de agentes gerenciados vs SDK do Agente detalha as vantagens e desvantagens. Os três não são tanto concorrentes quanto degraus em uma escada do interativo ao totalmente automatizado.

Um exemplo prático: revisão e escrita de testes em paralelo

Juntando tudo. Digamos que você acabou de fazer o agente principal implementar um novo endpoint de pedidos. Você quer que ele seja revisado e testado, e não há razão para que isso aconteça em sequência.

Defina dois subagentes. O revisor-de-codigo acima, mais 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.

Agora o agente principal despacha ambos de uma vez: o revisor lê o diff enquanto o escritor de testes lê a especificação e escreve a cobertura. Dois especialistas, dois contextos isolados, rodando em paralelo. O fluxo principal permanece limpo e recebe dois resumos: um relatório de revisão e um resultado de teste.

Esse resultado de teste é a parte que o torna confiável. Um subagente que executa sua suíte de API é uma porta de verificação, a checagem determinística que diz se o endpoint realmente funciona, em vez de se parece pronto. Esta é a ideia central dos loops de agente de codificação: a confiança do próprio agente não conta, o veredito da porta de verificação sim. Conecte o subagente de teste a uma plataforma de teste de API real e o feedback se tornará mais preciso. Equipes usando Apidog apontam o subagente para um cenário de teste Apidog para que cada resposta seja validada pelo esquema, e roteiam as chamadas de endpoint ao vivo do agente através do depurador de agente de IA Apidog para que ele inspecione as solicitações da mesma forma que um testador humano faria. Pegue essa mesma configuração, envolva-a em um loop, e você terá o fluxo de trabalho não supervisionado que construímos nos fluxos de trabalho Claude que funcionam sem você. Baixe o Apidog se quiser que a porta de teste seja ciente do esquema prontamente.

Melhores práticas

Alguns hábitos mantêm os subagentes úteis em vez de caóticos.

• Uma responsabilidade por subagente. Um revisor revisa. Um testador testa. Não construa um subagente que faça tudo; isso é apenas o agente principal com etapas extras.
• Escreva descrições para delegação. O campo description é como Claude decide chamar seu subagente. Faça dele um gatilho claro, não um título. "Use após editar código para revisar bugs" é melhor que "Revisor de código".
• Conceda o privilégio mínimo. Liste apenas as ferramentas de que cada subagente precisa. Um revisor sem acesso de escrita não pode alterar o que está revisando. Isso importa mais quando as execuções são não supervisionadas.
• Fixe o modelo certo por trabalho. Subagentes mecânicos podem ser executados em um modelo mais rápido e barato. Guarde o modelo mais forte para subagentes que fazem raciocínio complexo. Isso controla tanto a velocidade quanto o custo.
• Retorne resultados estruturados. Peça aos subagentes para relatar em um formato consistente (um veredito, uma lista de problemas, um aprovado/reprovado). A saída estruturada é mais fácil para o agente principal, e para você, agir.
• Não aninhe em excesso. Subagentes chamando subagentes que chamam subagentes se torna difícil de seguir e caro. Mantenha a hierarquia rasa.

Estes espelham os padrões de fiação que cobrimos em padrões e armadilhas de fiação de ferramentas de fluxo de trabalho agêntico, e eles valem quer você tenha dois subagentes ou vinte.

Quando usar subagentes (e quando não usar)

Subagentes são uma ferramenta, não um padrão. Saber quando ignorá-los mantém sua configuração rápida e barata.

Use um subagente quando uma tarefa for delimitada, independente e "barulhenta". Uma revisão de código é delimitada (tem um fim claro), independente (não precisa do estado de execução do fluxo principal) e "barulhenta" (gera muita leitura intermediária que você não quer que entupa o contexto principal). O mesmo vale para escrever uma suíte de testes, reproduzir um bug ou auditar um módulo em busca de problemas de segurança. Estas são delegações perfeitas: isole o trabalho, obtenha um veredito.

Ignore o subagente quando a tarefa for pequena, rigidamente acoplada ou sequencial com o trabalho principal. Renomear uma variável, corrigir um bug de uma linha ou qualquer coisa em que o agente principal já tenha o contexto necessário em vista não se beneficia de uma passagem de tarefa. Criar um subagente ali apenas adiciona latência e uma viagem de ida e volta de contexto sem ganho. Se o agente principal tivesse que explicar metade da conversa para instruir o subagente, mantenha-o no fluxo principal.

A regra geral: delegue trabalho que seja autocontido o suficiente para ser descrito em um parágrafo e valioso o suficiente para ser executado em paralelo. Um novo endpoint para revisar e testar se encaixa. Uma correção de erro de digitação não. À medida que você escala para muitos subagentes concorrentes, os padrões de orquestração em fluxos de trabalho dinâmicos assumem o controle, mas o mesmo julgamento se aplica: paralelize o independente, mantenha o trabalho acoplado junto.

Erros comuns

• Descrições vagas. Se a description for um rótulo, a delegação automática não será acionada quando você esperar. Escreva-a como um gatilho de uso.
• Um subagente inchado. Amontoar todas as tarefas em um único subagente mata o benefício da especialização. Divida por responsabilidade.
• Herdar todas as ferramentas por padrão. Deixar tools não definido dá a um subagente tudo o que o agente principal possui. Bom para trabalho confiável, arriscado para qualquer coisa automatizada. Liste as permissões deliberadamente.
• Nenhum subagente de verificação. Uma configuração de revisão e construção sem uma porta de teste entrega código que parece certo e quebra em casos de borda. Sempre inclua um subagente que realmente execute os testes.
• Tratar subagentes como o SDK. Subagentes são despachados pelo modelo e em sessão. Se você precisa de um fluxo de controle determinístico e agendado, esse é o trabalho do SDK do Agente, não de um monte de subagentes.

Faça isso corretamente e um punhado de subagentes bem definidos transforma o Claude Code de um único assistente ocupado em uma pequena equipe focada. O "building effective agents" da Anthropic defende o caso mais amplo: a estrutura em torno do modelo supera um prompt maior.

Perguntas frequentes

O que é um subagente do Claude Code? É uma instância de agente separada para a qual o agente principal do Claude Code delega tarefas. Cada subagente tem sua própria janela de contexto, um prompt de sistema personalizado e um conjunto configurável de ferramentas. Ele realiza uma tarefa focada e retorna o resultado, mantendo a conversa principal limpa e permitindo que você execute especialistas em paralelo.

Como eu crio um subagente do Claude Code? Crie um arquivo Markdown em .claude/agents/ (projeto) ou ~/.claude/agents/ (pessoal). Adicione frontmatter YAML com name, description, tools opcionais e model opcional, então escreva o prompt de sistema no corpo. A descrição informa a Claude quando delegar a ele automaticamente.

Como Claude decide qual subagente usar? Ele lê o campo description de cada subagente disponível e delega automaticamente quando uma tarefa corresponde. Você também pode invocar um explicitamente pelo nome, como "use o subagente revisor-de-codigo." Descrições claras, no estilo de gatilho, tornam a delegação automática confiável.

Qual a diferença entre subagentes e o SDK do Agente Claude? Subagentes são em sessão e despachados pelo modelo: você está trabalhando no Claude Code e ele aciona especialistas. O SDK do Agente é programático, onde você escreve o fluxo de controle em código para execuções determinísticas ou não supervisionadas. Use subagentes para especialização interativa, o SDK para loops agendados.

Subagentes podem ser executados em paralelo? Sim. O agente principal pode despachar múltiplos subagentes simultaneamente para tarefas independentes, de modo que revisão, teste e documentação aconteçam juntos em vez de em sequência. Para distribuição em larga escala, os fluxos de trabalho dinâmicos do Claude Code estendem isso para muitos subagentes paralelos em uma única sessão.

Como os subagentes ajudam no teste de API? Defina um subagente que escreve e executa seus testes de API contra a especificação OpenAPI. Ele se torna uma porta de verificação que verifica se um endpoint realmente funciona, e não apenas se parece pronto. Apontá-lo para uma plataforma como Apidog torna o feedback ciente do esquema, de modo que cada resposta é validada contra o contrato.

A conclusão

Subagentes do Claude Code resolvem o problema de que uma única janela de contexto não consegue conter tudo. Ao dar a cada tarefa seu próprio contexto, instruções e ferramentas, você troca um único agente sobrecarregado por uma pequena equipe de especialistas que trabalham em paralelo e reportam de forma limpa. A configuração é apenas um arquivo Markdown, e o benefício é foco, velocidade e a capacidade de colocar o modelo certo no trabalho certo.

Comece com dois: um revisor e um testador. Escreva descrições concisas para que Claude delegue por conta própria, conceda a cada um apenas as ferramentas de que precisa e transforme o testador em uma verdadeira porta de verificação, apontando-o para sua suíte de API. Para qualquer coisa que envolva endpoints, o Apidog fornece a essa porta um esquema para verificar; baixe-o e deixe um subagente de teste provar que seu código funciona antes mesmo de você ler o diff.