O problema de nomes: o que as pessoas querem dizer com “agente no Claude Code”
Existe um momento que qualquer pessoa que usa Claude Code vai encontrar: o modelo começa a “esquecer” detalhes que você mencionou lá atrás, segue a instrução errada, confunde variáveis, ignora restrições que estavam claras no início da conversa. Isso tem nome. Chama context rot, e é o problema central que os subagentes do Claude Code foram desenhados para resolver.
Mas antes de chegar nas soluções, vale ser honesto sobre um problema de vocabulário que atrapalha todo mundo que está começando.
A palavra agente no ecossistema do Claude Code significa pelo menos quatro coisas diferentes ao mesmo tempo, e misturar esses conceitos é o caminho mais rápido para se perder.
O Claude Code em si já é um ambiente agêntico. Ele tem ferramentas, um loop de execução e capacidade de planejar e agir em múltiplos passos sem esperar por um comando a cada etapa. Isso já é o padrão, antes de qualquer configuração.
Subagentes são a primitiva de agente customizável dentro do produto. Quando alguém diz “estou construindo um agente no Claude Code”, quase sempre está falando de subagente. São assistentes especializados que rodam em seu próprio contexto, com seu próprio system prompt, suas próprias ferramentas e permissões próprias.
Agent teams são uma camada diferente, multi-sessão, experimental e desabilitada por padrão. Não são subagentes mais poderosos. São instâncias independentes do Claude Code que se comunicam via lista de tarefas compartilhada. Um nível acima na arquitetura, mas com custo e complexidade proporcionalmente maiores.
O Claude Agent SDK é o quarto nível: as mesmas ferramentas e o mesmo loop de agente do Claude Code, expostos como biblioteca programática em Python e TypeScript para quem está construindo aplicações customizadas fora do CLI.
Este artigo trata do segundo item: subagentes. É onde a maioria das pessoas encontra valor real antes de precisar ir mais fundo.
Por que os subagentes existem: o fenômeno do context rot
Modelos de linguagem têm uma janela de contexto finita. Cada chamada de ferramenta, cada leitura de arquivo, cada análise parcial ocupa espaço nessa janela e fica lá. À medida que a sessão cresce, a janela se enche de trabalho intermediário que foi necessário para chegar a um resultado, mas que não é mais útil de manter visível.
O que acontece é o que pesquisadores chamam de context rot: o modelo começa a ignorar restrições definidas no início, pesa demais o que foi dito recentemente, confunde entidades, acumula erros que as próximas respostas amplificam. Não é falha do modelo. É física do transformer: atenção e recall não são uniformes em contextos longos.
A documentação oficial da Anthropic sobre context engineering descreve o problema com precisão: “Context engineering é a arte e ciência de curar o que vai para a janela de contexto limitada.” Cada peça de trabalho intermediário compete por atenção com o que realmente importa.
Subagentes mudam essa geometria. Em vez de a investigação acontecer na thread principal, ela acontece em uma janela de contexto separada. Você recebe de volta apenas o resultado limpo. A thread principal nunca absorveu o ruído de dezenas de leituras de arquivo e buscas intermediárias.
Há três razões secundárias que reforçam o caso:
Especialização. Um subagente tem seu próprio system prompt. Um revisor de código com as diretrizes específicas do seu time é mais confiável do que um assistente geral tentando manter essas diretrizes junto com todo o resto que sabe.
Controle de permissões. Você declara exatamente quais ferramentas um subagente pode usar. Um agente de revisão que só pode ler arquivos, sem escrever e sem executar shell, tem um perfil de risco completamente diferente do assistente principal. As restrições são declaradas e aplicadas.
Controle de custo. Subagentes podem rodar em modelos diferentes. Direcionar tarefas leves para o Haiku enquanto a sessão principal roda no Sonnet é uma alavanca de custo prática que a maioria das pessoas só descobre depois de se surpreender com a conta.
O que um subagente é na prática
Um subagente é um arquivo Markdown com frontmatter YAML. Ele fica em uma de duas localizações: dentro do projeto em .claude/agents/ para agentes específicos de um repositório, ou em ~/.claude/agents/ para agentes pessoais disponíveis em todos os projetos.
A estrutura mínima tem dois campos obrigatórios. O name é o identificador único, em letras minúsculas com hifens. O description é o campo mais importante do arquivo inteiro, e merece atenção especial.
O description é a interface de roteamento do agente. Claude lê esse campo para decidir quando delegar uma tarefa. Ele não lê o corpo do arquivo antes de tomar essa decisão. Se você colocar os critérios de ativação apenas no corpo do prompt, o agente nunca vai ser acionado no momento certo.
Escreva o description de forma comportamental: o que o agente faz e quando usá-lo. A frase “use proativamente após mudanças significativas no código” é um padrão documentado pela Anthropic que sinaliza ao Claude para ativar o agente sem esperar por uma solicitação explícita. Deixe essa indicação de fora se quiser ativação apenas por solicitação direta.
O campo tools restringe o acesso a ferramentas. Um revisor de código precisa de leitura, não de escrita, não de execução de shell, não de chamadas de rede. Essa restrição é tanto uma prática de segurança quanto de clareza: um conjunto pequeno de ferramentas torna o comportamento do agente previsível e os modos de falha finitos e conhecíveis.
O campo model roteia o agente para um modelo específico: sonnet, opus, haiku ou um ID completo. Omita e o agente herda o modelo da sessão principal.
Subagente versus Skill: a distinção que muda tudo
A confusão entre subagentes e skills é compreensível. Ambos usam estrutura de pasta dentro de .claude/. Ambos usam frontmatter YAML com o campo description como mais importante. Ambos são, na essência, um conjunto de instruções.
A diferença está em onde o trabalho acontece.
Uma skill carrega na conversa atual. Suas instruções, templates e referências se tornam parte do contexto ativo. Claude as segue na mesma thread, e cada passo se acumula na sua janela principal.
Um subagente roda separado, em sua própria janela de contexto. Faz o trabalho, consome seu próprio orçamento de tokens, e a conversa principal recebe de volta apenas um resultado.
Uma frase captura a distinção com clareza: uma skill muda o que Claude sabe ou como deve abordar um fluxo de trabalho. Um subagente muda quem está fazendo o trabalho, em que contexto, e com quais ferramentas.
Um exemplo concreto torna isso tangível. Imagine aplicar os padrões de revisão de código do seu time.
Se você quer que Claude conheça esses padrões ao longo de uma sessão, os aplique ao escrever código, os referencie nas sugestões e sinalize violações inline, isso é uma skill. Escreva os padrões uma vez e Claude os carrega no contexto quando relevante.
Se você quer revisar 40 arquivos em uma passada sem a thread principal encher de leituras de arquivo, comentários intermediários e resultados de busca, isso é um subagente. Você configura um agente code-reviewer, ele roda a revisão em sua própria janela e devolve um resumo estruturado. Sua conversa principal recebe apenas o resultado, não o trabalho que o produziu.
Boas práticas para quem está começando
O description é a interface de roteamento, não a identidade do agente. Evite escrever descrições que descrevam a personalidade do agente. “Você é um revisor expert com 20 anos de experiência” pertence ao system prompt. O description existe para o modelo de roteamento, não para o agente em si.
Restrinja ferramentas intencionalmente. Um agente que herda todas as ferramentas da sessão principal é um agente que você não consegue raciocinar quando algo dá errado. Conceda apenas o que a tarefa exige.
Uma tarefa por agente. Três arquivos separados, cada um com um escopo claro, superam um arquivo tentando lidar com quatro modos de operação simultaneamente. Claude pode rotear de forma inconsistente para um agente com descrição ambígua, e o system prompt tentando fazer quatro coisas ao mesmo tempo vai errar em pelo menos uma.
Use o campo model como alavanca de custo. Definir model: haiku nos agentes de tarefas leves reduz custo substancialmente quando múltiplos agentes estão rodando em uma sessão. O padrão (inherit) significa que cada agente roda no modelo mais poderoso disponível, independente de precisar disso.
O fluxo que a comunidade praticante convergiu é direto: o agente principal clarifica os critérios de aceitação e lista os arquivos relevantes, um subagente planejador faz a análise e mapeia riscos, o agente principal implementa, um subagente revisor retorna o que precisa ser corrigido, um subagente de testes propõe e executa os testes mínimos, e o agente principal integra e entrega o resumo final.
Quando subagentes são a ferramenta errada
Subagentes adicionam overhead de coordenação. Para uma tarefa que cabe confortavelmente em uma única thread sem degradação de contexto, criar um subagente é complexidade sem benefício.
O sinal prático é este: se a tarefa é curta, o contexto intermediário é mínimo, e você não precisa de restrições de permissão específicas, execute na thread principal. Reserve subagentes para investigações que consomem dezenas de leituras de arquivo, para verificações que precisam de permissões restritas, ou para trabalho paralelo em componentes independentes.
Agent teams existem no horizonte, mas valem um artigo separado. São sessões independentes do Claude Code que se comunicam entre si via lista de tarefas compartilhada. Adicionam muito mais overhead de tokens e complexidade de coordenação. Experimentais, desabilitados por padrão, requerem variável de ambiente para ativar. Se você ainda está mapeando como subagentes funcionam, agent teams não são o próximo passo agora.
A habilidade de construir sistemas de agentes colaborativos está se tornando cada vez mais central para quem trabalha com IA aplicada a negócios. A Associação Brasileira de Ciência de Dados e IA, a ABRACD, tem acompanhado de perto como essas arquiteturas estão sendo adotadas no contexto brasileiro, especialmente em ambientes corporativos onde governança de contexto e controle de permissões são requisitos críticos.
Para quem está levando isso a sério do ponto de vista de estratégia tecnológica, estruturar bem essa camada de orquestração é exatamente o tipo de decisão que define se a adoção de IA vai escalar ou vai acumular débito técnico invisível. Esse é o tipo de orientação que um CTO as a Service da Cappei traz para o processo, antes que os problemas apareçam em produção.
Se você quer ir mais fundo nesse tema e acompanhar as movimentações práticas no mundo de desenvolvimento assistido por IA, assine a newsletter sobre Vibe Coding — tem coberto exatamente essas transições em linguagem acessível para quem está no dia a dia do desenvolvimento. E se você quer aprender na prática, a plataforma Replitfy tem conteúdo direto ao ponto sobre desenvolvimento assistido por IA.
Você já percebeu degradação de performance no Claude Code em sessões longas? Como está lidando com isso hoje?
