Claude Code agents: o que são e quando usar subagentes no seu projeto

Fala aí, beleza? Você já deve ter vivido isso: a conversa com o Claude Code começa afiada, você joga mais uma tarefa, mais um log de erro, mais um arquivo gigante… e do nada ele parece que ficou meio burro

Não é impressão, é contexto poluído

A conversa principal virou um depósito de coisa que já não importa pra decisão atual, e cada resposta nova nasce em cima daquela bagunça

Subagente é justamente a saída pra isso: tirar o trabalho barulhento da conversa principal e mandar rodar num lugar separado, que devolve só o que interessa

Neste post eu explico o que são os Claude Code agents, como um subagente funciona por dentro, quando vale delegar de verdade e quando é melhor deixar na conversa mesmo 🙂

Como funciona um subagente por dentro

Antes do como criar, o porquê: se você não entende o ciclo de vida, você escreve o prompt errado e culpa o modelo

Subagentes são instâncias especializadas do Claude, cada uma com janela de contexto própria, system prompt customizado e permissões de ferramenta independentes, como descreve a documentação oficial de subagentes

O ciclo é esse aqui:

1. O contexto do subagente começa VAZIO. Ele não herda o histórico da sua conversa principal, o único conteúdo que chega até ele é o texto do prompt que foi passado na chamada

E aqui mora o erro comum número um: você pede "corrige aquele bug do login" achando que ele viu a conversa toda

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Ele não viu nada, beleza? Caminho de arquivo, mensagem de erro completa e decisões que vocês já tinham tomado precisam estar ESCRITAS dentro do prompt, senão o coitado começa do zero e chuta

2. Ele trabalha isolado. As chamadas de ferramenta intermediárias que o subagente faz não voltam pro pai

É como contratar alguém pra fazer um levantamento: você não acompanha cada aba que a pessoa abriu, você recebe o relatório

O erro comum aqui é esperar acompanhar o passo a passo. Se você precisa ver cada movimento pra decidir junto, essa tarefa não é de subagente

3. O pai recebe só a mensagem final. O retorno da chamada é o resultado, e mais nada

Ou seja: a qualidade do que volta depende de você ter pedido explicitamente o FORMATO do que quer de volta (lista de arquivos, diagnóstico, patch aplicado). Prompt vago volta resumo vago

4. Desde a v2.1.198, subagente roda em segundo plano por padrão. O Claude segue trabalhando enquanto o subagente executa e é notificado quando ele termina, segundo as notas da versão 2.1.198

Isso muda o jeito de trabalhar: o que você acompanha é o resultado chegando, não a digitação

Quando usar subagentes no seu projeto

A Anthropic aponta cinco situações que pedem subagente. Vou traduzir cada uma com o tipo de tarefa que cai nela

Isolar contexto de tarefa ruidosa:

Aquele trabalho que gera montanha de saída: rodar a suíte de testes inteira, ler log de build, varrer output de linter

Se isso entra na conversa principal, você queima janela com texto que não vai influenciar mais nada depois do diagnóstico

Manda pro subagente e recebe de volta só o veredito

Levantar contexto lendo muitos arquivos:

"Onde fica a lógica de autenticação nesse projeto?" é a pergunta clássica

A resposta útil tem umas 5 linhas, mas pra chegar nela alguém precisa abrir dezenas de arquivos

Delegar essa parte é o uso mais fácil de justificar

Tocar frentes paralelas sem dependência entre si:

Três peças que não se cruzam: migração de um módulo, atualização de testes de outro, ajuste de documentação

Como cada subagente tem contexto próprio, dá pra rodar as frentes sem uma poluir a outra

Se é isso que você quer explorar mais a fundo, eu já escrevi um post inteiro sobre programação paralela com múltiplos agentes

Obter revisão independente:

Esse é sutil e MUITO massa: quem escreveu o código está enviesado pelo próprio raciocínio

Um subagente que só recebe o diff e a instrução de revisar não sabe as suas justificativas, então ele não compra a sua desculpa

Separar fases sequenciais da tarefa:

Pesquisar, depois planejar, depois implementar, depois verificar

Cada fase entrega um artefato limpo pra próxima em vez de arrastar todo o rascunho junto

O gatilho prático:

A própria Anthropic dá um número pra você parar de filosofar: tarefa que exige explorar dez ou mais arquivos, ou que envolve três ou mais frentes independentes de trabalho

Bateu isso? Delega. Não bateu? Provavelmente resolve na conversa principal mesmo

Como criar um subagente customizado

Agora a parte prática. Subagente customizado é só um arquivo Markdown com frontmatter YAML, nada de mágica

1. Escolha o escopo. .claude/agents/ é escopo de projeto (vale só naquele repositório) e ~/.claude/agents/ é escopo de usuário (vale em todos os seus projetos)

O erro comum aqui é jogar tudo no escopo de usuário. Agente que sabe as convenções específicas de UM projeto não deveria estar te seguindo em todos os outros

2. Crie o arquivo com o frontmatter. Só name e description são obrigatórios, tools e model são opcionais

---
name: revisor-de-migration
description: Revisa arquivos de migration em busca de operação destrutiva, índice faltando e lock perigoso. Use sempre que uma migration nova for criada ou alterada.
tools: Read, Grep, Glob
model: sonnet
---

Você revisa migrations de banco de dados.

Para cada arquivo, verifique: operação que apaga ou renomeia coluna, ausência de índice em coluna usada em filtro, e alteração que pega lock em tabela grande.

Responda em lista, uma linha por achado, com o caminho do arquivo e a linha.

3. Escreva o corpo pensando que ele É o system prompt. Todo o texto abaixo do frontmatter vira a instrução base daquele agente

É ali que você coloca convenção do projeto, formato de saída e o que ele NÃO deve fazer

4. Capriche na description, sério. É por ela que o Claude decide sozinho quando acionar aquele subagente

O erro comum deste passo é description genérica do tipo "ajuda com código": com isso ou ele nunca delega, ou delega na hora errada

Descreva o QUANDO, não só o o quê. E, se quiser garantir, dá pra chamar o agente explicitamente pelo nome dentro do seu prompt

5. Deixe tools e model de fora quando não tiver certeza. Se você omite tools, o subagente herda todas as ferramentas disponíveis para subagentes

Se você omite model, o padrão é inherit, ou seja: ele usa o mesmo modelo da conversa principal

Agora um aviso de estado atual pra você não ficar procurando menu que não existe mais: o assistente interativo do /agents foi removido na versão 2.1.198 do Claude Code

Hoje o caminho é pedir pro próprio Claude criar ou atualizar o subagente, ou editar os arquivos na mão mesmo

E tem ainda um jeito mais efêmero: dá pra definir subagentes por flag de CLI, passando JSON no lançamento do Claude Code

Esses valem só naquela sessão e não são gravados em disco, então servem pra experimento, não pra padrão do time

Os subagentes que já vêm embutidos (e como sobrescrever)

Antes de sair criando os seus, se liga que o Claude Code já traz alguns embutidos, entre eles Explore, Plan e general-purpose

Normalmente eles são acionados de forma automática, sem você pedir nada

O Explore é o mais interessante de entender: ele é somente leitura, voltado a busca e análise de código, e aceita um nível de profundidade definido pelo Claude na hora da chamada (quick, medium ou very thorough)

Faz sentido ele ser read-only, né? Descoberta de arquivo não precisa de permissão de escrita, e agente sem permissão que não precisa é agente que não te dá dor de cabeça

E aqui vai um truque bem legal: se você definir um subagente seu chamado Explore, no escopo de usuário ou de projeto, ele sobrescreve o embutido e mantém o próprio campo model

Na prática isso quer dizer que dá pra manter toda a exploração de codebase num modelo mais barato, tipo model: haiku, enquanto a conversa principal continua no modelo forte

Exploração é leitura e filtragem, não é raciocínio de arquitetura. Faz sentido pagar barato por isso

E quando o mesmo nome existe em níveis diferentes, a ordem de precedência é essa:

1. managed
2. flag de CLI
3. projeto (.claude/agents/)
4. usuário (~/.claude/agents/)
5. plugin

Tome cuidado com isso: se um agente seu parece estar sendo ignorado, provavelmente tem outro com o mesmo nome ganhando no nível de cima

O que muda na prática quando o trabalho roda em background

Teoria é bonita, mas quero te mostrar como isso se parece numa execução real

No vídeo abaixo eu mostro esse encadeamento: primeiro eu gerei um documento de plano de implementação, com tarefas em ordem, dependências e critérios de aceitação

Depois pedi pro Claude Code executar aquele plano usando subagentes com TDD (teste primeiro, implementação depois), porque isso ajuda a sair com uma execução já testada, principalmente em projeto maior e com mais regra de negócio

Detalhe que salva: mesmo com o plano ali no contexto, eu referencio o arquivo do plano explicitamente com @, pra garantir que ele execute o documento certo

A execução fechou 14 tarefas do plano

E quando eu mostro a tela, uma das etapas já estava rodando havia quase 10 minutos

Esse é exatamente o ponto conceitual da coisa: enquanto aquilo rodava, o que eu acompanhava era o andamento, não cada chamada de ferramenta lá dentro

O app subiu em localhost:3000 e eu testei na mão: criar conta, login e lançar um gasto

Cadastrei uma despesa de R$ 1.000 em alimentação só pra validar que autenticação e cadastro estavam de pé

Mas não foi um mar de rosas, e eu não vou vender isso como se fosse

Ao abrir o app no navegador, o cadastro deu erro e eu tive que colar a mensagem de volta no Claude Code pra ele analisar e corrigir

Durante a execução também teve MUITO aceite manual, a ponto de eu comentar que valeria considerar pular as confirmações na fase de criação de arquivo e setup

O que eu tiro disso: a execução automatizada cobre pontos de arquitetura que eu provavelmente não teria pensado no começo, ao custo de mais tempo e mais tokens

E a decisão de rodar assim depende do tamanho do projeto. Não é bala de prata, é escolha

Ah, e a interface saiu genérica, aquele visual sem alma… isso eu resolvi depois com uma skill de front-end, não com subagente

Subagente, skill, agent view, agent teams e dynamic workflows

Esses nomes se misturam MUITO na cabeça de quem está começando, então bora separar

A confusão mais comum é skill com subagente:

Resumindo: skill é expertise que se aplica, subagente é execução que se delega

Se você ainda embaralha esses conceitos com comandos, vale ler a comparação de skills, comandos e subagentes com calma

E tem outra coisa que confunde: subagente é só UMA das formas de paralelizar no Claude Code

O agent view abre pelo comando claude agents no terminal, e é bem útil quando você tem coisa rodando em mais de um lugar e não sabe qual delas está te esperando

Vale delegar sempre? O critério honesto

Não, e quem diz que sim está vendendo alguma coisa

Subagente não é ganho automático, ele tem um preço claro: a janela começa zerada e o único conteúdo que chega é o prompt

Isso significa que TODO o contexto necessário tem que ser reescrito por você ou pelo Claude na hora da chamada

E, do outro lado, volta só a mensagem final

Então delegar tende a ser pior quando:

• a tarefa é pequena e você resolveria em duas mensagens
• a tarefa depende fortemente do histórico da conversa (aquele monte de decisão que vocês tomaram juntos)
• você precisa acompanhar cada passo pra corrigir o rumo no meio

E tende a compensar quando:

• bate o gatilho de escala (dez ou mais arquivos, três ou mais frentes independentes)
• o trabalho gera saída ruidosa que não precisa morar na conversa principal
• você quer uma revisão independente, feita por quem não conhece a sua justificativa

É um trade-off de contexto, não um upgrade grátis

Conclusão

Os Claude Code agents resolvem um problema bem específico: conversa principal virando depósito de contexto que não ajuda mais

O subagente roda com janela própria, system prompt customizado e permissões de ferramenta independentes, recebe só o que você escreveu no prompt, trabalha sozinho e devolve o resultado final

E, desde a v2.1.198, isso acontece em segundo plano por padrão, então o modo de trabalhar muda: você acompanha resultado, não digitação

Seu próximo passo é bem concreto: cria UM arquivo em .claude/agents/ pra uma tarefa repetitiva do seu projeto, aquela que você pede toda semana

Capricha no name (minúsculas e hifens) e principalmente na description, deixando claro QUANDO aquele agente deve entrar

Aí segue trabalhando normal e observa se o Claude delega sozinho na hora certa

Se ele não delegar, quase sempre a description é o problema, não o agente 😀

até o próximo post!