Subagentes do Claude Code: isolamento de contexto, orquestrador e revisor, quando não são necessários

O que são os subagentes do Claude Code

Um subagente é mais uma instância do agente, que o agente principal inicia para uma tarefa separada. Ele tem a sua própria janela de contexto, o seu próprio prompt de sistema e a sua própria lista de ferramentas permitidas. O agente principal passa a ele a descrição da tarefa, o subagente trabalha de forma independente — lê arquivos, executa comandos — e devolve apenas a mensagem final.

A palavra-chave aqui é isolamento. Tudo o que o subagente leu pelo caminho — dezenas de arquivos, uma saída longa de testes, hipóteses sem saída — fica no contexto dele e não chega ao contexto da sessão principal. O agente principal vê um resultado curto: "o erro está na função X, a causa é tal, estes três pontos são afetados".

Os subagentes do Claude Code são um caso particular da ideia geral de sistemas multiagente: em vez de um único ciclo "pensou — fez — verificou", surge um grafo de vários nós, cada um com seu papel e sua responsabilidade.

Por que o isolamento de contexto importa

A janela de contexto é o principal recurso do agente. Nela cabem ao mesmo tempo as instruções do CLAUDE.md, o histórico do diálogo, o código lido e a saída dos comandos. Quando o agente passa meia hora procurando a causa de um bug, o contexto se enche de lixo: arquivos que não tinham nada a ver e logs dos quais só importa uma linha.

As consequências são conhecidas de quem trabalha com agentes há tempo: o modelo passa a respeitar pior as regras do projeto, confunde detalhes e, na compactação automática do histórico, perde o que era importante. O subagente resolve isso de forma estrutural: o trabalho pesado é feito em um contexto separado, que é descartado após a resposta.

• Busca e investigação. "Encontre todos os pontos em que a função de pagamento é chamada e descreva como eles funcionam" é uma tarefa típica para um subagente.
• Verificações barulhentas. Rodar os testes e analisar os que falharam — delegue ao subagente e receba a lista de causas.
• Leitura de documentos grandes. Uma especificação de centenas de páginas é necessária por alguns fatos — deixe o subagente extraí-los.

Como configurar um subagente: a pasta .claude/agents

Um subagente próprio é descrito por um arquivo Markdown com cabeçalho YAML. Os arquivos do projeto ficam em .claude/agents/ no repositório e estão disponíveis para toda a equipe pelo git; os pessoais ficam em ~/.claude/agents/ e funcionam em todos os seus projetos. Também é possível criar e editar um subagente interativamente, pelo comando /agents no Claude Code.

---
name: code-reviewer
description: Verifica as alterações de código quanto a erros e violações das regras do projeto. Use após concluir a tarefa, antes do commit.
tools: Read, Grep, Glob, Bash
---
Você é um revisor de código. Não precisa corrigir nada.

1. Veja as alterações: git diff.
2. Verifique cada alteração quanto a erros de lógica, tratamento de erros,
   segurança (SQL, escape de saída, segredos).
3. Confira com as regras do AGENTS.md.
4. Devolva a lista de observações: arquivo, linha, problema, por que isso importa.
   Se não houver observações, diga exatamente isso.

O que significam os campos:

O corpo do arquivo é o prompt de sistema do subagente. Ele não vê o histórico do seu diálogo, então tudo o que ele precisa saber sobre o papel e o formato da resposta deve estar no prompt ou na tarefa que o agente principal lhe passa.

Como chamar um subagente

O agente principal pode escolher o subagente sozinho, se a tarefa corresponder à sua description. É mais confiável pedir de forma explícita: "Use o subagente code-reviewer para verificar as alterações". Expressões como "use proativamente" na descrição aumentam a chance de o agente chamá-lo sem lembrete, mas não garantem isso.

Subagente pesquisador

Um segundo arquivo que vale criar em quase qualquer projeto é um pesquisador somente leitura. Ele responde perguntas sobre o código e não altera nada.

---
name: explorer
description: Procura na base de código respostas sobre onde e como algo está implementado. Use quando for preciso ler muitos arquivos para obter uma resposta curta.
tools: Read, Grep, Glob
---
Você investiga o código e não altera nada.
Devolva: uma resposta curta à pergunta, a lista de arquivos com linhas
em que ela se apoia, e o que não foi possível verificar.

Esse subagente é especialmente útil no início da tarefa: o agente principal recebe um mapa dos pontos relevantes sem gastar contexto lendo tudo, e a partir daí trabalha com arquivos concretos.

Esquema "orquestrador e executores"

O esquema multiagente mais comum: um agente orquestrador mantém o plano e a visão geral, e distribui os passos concretos entre os executores. O orquestrador não lê todo o código sozinho: ele formula as tarefas, recebe os resultados e decide o que fazer em seguida.

1. O orquestrador divide a tarefa em partes independentes e escreve, para cada uma, uma instrução autossuficiente: objetivo, onde procurar, o que considerar pronto, em que formato devolver a resposta.
2. Os executores realizam as instruções em seus próprios contextos.
3. O orquestrador reúne as respostas, verifica se as partes se encaixam e dispara o próximo passo ou um retorno ao anterior.

O ponto fraco do esquema é a passagem da tarefa. O subagente conhece apenas o que lhe foi escrito. A instrução "conserte aquele bug que discutimos" é vazia para ele: ele não viu a discussão. Uma boa instrução se lê como uma tarefa para um novo colega que acabou de abrir o repositório.

O que o executor deve devolver

Defina o formato da resposta de antemão: lista de arquivos, saída, causas encontradas, o que não foi possível verificar. Uma resposta curta e estruturada economiza o contexto do orquestrador, e o item "o que não foi verificado" protege contra a falsa segurança — o executor, como qualquer agente, tende a relatar sucesso.

Revisor separado: por que separar o juiz do executor

Quando o mesmo agente escreve o código e também o verifica, juiz e réu dividem a mesma cabeça. O agente lembra o que queria fazer e enxerga no código a sua intenção, e não o que está escrito. Além disso, ele tem interesse em terminar: a verificação vira formalidade.

O revisor em um contexto separado não tem esses problemas. Ele não conhece o histórico de decisões, vê apenas o diff e as regras do projeto, e avalia o resultado com um olhar novo. É o mesmo princípio de uma equipe real: o autor não aprova o próprio pull request.

• Dê ao revisor apenas ferramentas de leitura e de execução de verificações — sem permissão de editar arquivos. Assim ele não começa a "corrigir em silêncio" em vez de relatar o problema.
• Descreva explicitamente os critérios de verificação: o que é considerado erro, quais regras do projeto são obrigatórias.
• A decisão sobre o que fazer com as observações fica com o orquestrador ou com a pessoa. O revisor encontra, o executor corrige.

O revisor não substitui as verificações mecânicas. Testes, linter e checagem de tipos são nós determinísticos, e são mais confiáveis do que qualquer modelo. O revisor pega o que a mecânica não vê: lógica incorreta, violação de acordos, complexidade desnecessária.

Execução paralela de subagentes

O Claude Code pode executar vários subagentes ao mesmo tempo. Isso acelera o trabalho quando as partes da tarefa são de fato independentes: estudar três módulos, verificar as alterações sob três ângulos (segurança, desempenho, testes), reunir informações de várias fontes.

A paralelização funciona bem para leitura e mal para escrita. Se dois executores editam os mesmos arquivos ao mesmo tempo, eles sobrescrevem as alterações um do outro, e nenhum dos dois percebe. Em termos do grafo de agentes, isso é um estado compartilhado sem regra de junção. Regras práticas:

• Em paralelo: pesquisa, análise, revisão. Em sequência: edições em arquivos que se sobrepõem.
• Se os executores escreverem em paralelo, separe as zonas: cada um trabalha apenas nos próprios arquivos, ou na sua própria cópia do repositório (por exemplo, em um git worktree separado).
• Os resultados são reunidos por um nó só — o orquestrador, e não os executores entre si.

Quando os subagentes não são necessários

O esquema multiagente tem um custo: mais tokens, mais tempo, mais pontos em que a informação se perde na passagem. Os subagentes do Claude Code nem sempre compensam.

Antes de montar um grafo de agentes, responda a perguntas simples: quem é dono do objetivo comum, quem pode vetar e reverter uma alteração, quais métricas definem o sucesso. Sem essas respostas, vários agentes apenas multiplicam a confusão de um só.

Erros típicos com subagentes

Descrição vaga

A descrição "assistente para código" não ajuda o agente principal a escolher quando chamá-lo. Escreva um gatilho: "depois de alterações na pasta api/, antes do commit".

Instrução sem contexto

O subagente recebe a tarefa sem caminhos, sem critérios de conclusão e sem restrições — e gasta metade do trabalho tentando adivinhar o que se espera dele. A solução é um modelo de instrução: objetivo, dados de entrada, restrições, formato da resposta.

Permissões amplas demais

O pesquisador e o revisor não precisam de permissão para editar arquivos. A restrição de tools é uma forma barata de tornar o papel uma regra mecânica, e não um pedido no prompt.

Confiar no relatório sem verificar

"Todos os testes passaram" na resposta de um subagente é uma afirmação, não um fato. O orquestrador deve se apoiar no que pode ser verificado: saída do comando, código de retorno, linhas concretas.

Resumindo

Os subagentes do Claude Code são uma ferramenta para três tarefas: manter o contexto principal limpo, separar a verificação da execução e paralelizar trabalho independente. Eles são descritos em arquivos Markdown curtos em .claude/agents/, e a qualidade do trabalho depende quase inteiramente da descrição do papel, do conjunto de ferramentas e de quão autossuficiente é a instrução. Quando a tarefa é pequena ou está fortemente ligada ao diálogo, um único agente continua sendo melhor. A passagem de um ciclo único para um sistema de nós, arestas e estado compartilhado é explicada na prática no curso.