Três arquivos de subagent que ainda valem a pena
Um subagent do Claude Code é um arquivo Markdown que define um ajudante com o próprio contexto novo. A Anthropic diz para usar menos subagents e os mantém em poucos casos, com um teste. Escrevemos os arquivos que ela ainda mantém, rodamos cada um em um repositório real e aplicamos o fold test a mais um agent. Ambiente: Claude Code 2.1.294 com Opus 5.5, execuções feitas em 2026-11-08, numa pequena API de faturas em TypeScript e no repositório do Hono.
O ponto é que o conselho popular manda apagar seus subagents, enquanto o artigo da Anthropic os mantém em casos específicos e traz um teste. Rodamos esse teste no agent que toda coleção traz, um test writer. Dobrado numa skill, ele passou em todas as doze execuções. Três arquivos sobrevivem: um scout somente leitura, um reviewer somente leitura que aprovou uma mudança verde e ainda assim apontou um risco que ninguém perguntou, e um builder isolado que entregou uma feature inteira na própria cópia do repositório enquanto a sessão principal continuava trabalhando.
O que é um arquivo de subagent e o teste da Anthropic
Um subagent é um ajudante com o próprio contexto novo. Num repositório grande, tudo o que sua sessão lê fica no contexto dela, que é a memória de trabalho, e essa memória enche. Um subagent funciona como um colega que recebe um ticket, lê metade da base de código e devolve uma nota curta.
Você cria uma pasta agents dentro da pasta .claude, e cada subagent é um arquivo Markdown nela. No topo você escreve um nome e uma descrição que diz quando usá-lo. Esses são os únicos campos obrigatórios. A descrição importa mais do que parece, porque é o que o Claude lê quando decide se vai chamar o ajudante. Quando digitamos o comando agents, o Claude Code avisou que o assistente tinha sido removido, então você escreve o arquivo você mesmo ou pede ao Claude. A documentação de sub-agents explica o formato.
O time de IA aplicada da Anthropic escreveu um artigo sobre dobrar subagents de volta no seu agent principal, voltado para a plataforma deles. Ele mantém subagents em três casos: seu contexto incha, você precisa de trabalho paralelo em contextos novos que serão descartados, ou seu agent não consegue escolher as ferramentas certas. Todo o resto geralmente pode ser uma skill, que são as mesmas instruções carregadas na sua sessão principal quando necessário. O teste: monte um eval pequeno, dobre o subagent e só mantenha o subagent se a versão dobrada tiver nota pior.
O custo de um subagent é que ele começa às cegas. Ele só sabe o que você coloca no prompt dele, e cada repasse pode perder um detalhe. Então, antes de escrever qualquer arquivo, dê nome ao caso que ele resolve.
O fold test da Anthropic em um quarto agent
O fold test é a forma da Anthropic de decidir se um subagent merece o próprio arquivo, e ele roda sobre um eval, um conjunto fixo de tarefas que você executa sempre do mesmo jeito, com uma regra de aprovação escolhida de antemão. Aplicamos ao test writer, o agent que quase todo mundo adiciona porque toda coleção traz um. É um subagent que escreve testes para um módulo, nunca toca no seu código-fonte e roda a suíte até ficar verde.
O método: mantenha o arquivo do agent como está, copie as mesmas instruções para uma skill e rode cada tarefa mais de uma vez com o agent. Depois mova o arquivo do agent para o lado e rode as mesmas tarefas com a skill. Nada se perde se o teste for contra o arquivo, porque você só move as instruções.
Rodamos isso na nossa pequena API de faturas com um prompt por módulo, como "add tests for the router", seis tarefas com duas execuções cada por variante. A regra de aprovação foi fixada antes: a suíte precisa estar verde, nenhum arquivo de código-fonte pode mudar e os novos testes precisam pegar um bug plantado. Um bug plantado é uma mudança minúscula no código que os testes antigos não detectaram, então um bom teste novo precisa falhar nele.
| Variante | Invocado | Aprovado | Custo médio | Tempo médio |
|---|---|---|---|---|
| Subagent | 12/12 | 11/12 | $0.410 | 72 s |
| Dobrado numa skill | 12/12 | 12/12 | $0.262 | 36 s |
O subagent errou uma vez. No router, ele tentou um comando de teste que as configurações do nosso projeto não permitiam, então ninguém rodou os novos testes e um deles estava vermelho. A versão dobrada levou cerca de metade do tempo, porque a sessão principal já conhecia o repositório e não precisou passar um briefing do zero para um ajudante. O test writer dobrado responde mais rápido e custa menos a cada pedido, e você não perde nada. O artigo irmão da Anthropic diz que setups com muitos agents costumam gastar bem mais tokens do que um único agent, e nossas execuções apontam na mesma direção.
O test writer falha no fold test, porque dobrado ele faz pelo menos o mesmo por menos. O limite é que este é um eval pequeno, de doze execuções por lado em um único repositório, e o erro foi em parte culpa das nossas permissões. Rode no seu repositório e leia qualquer execução que mude de resultado. Escrevemos a skill, rodamos as duas versões, e o arquivo do agent saiu, porque a versão dobrada nunca teve nota pior.
Arquivo um: o scout somente leitura
Um scout é um subagent que só pode ler e buscar, e devolve poucas linhas com a prova. Sem ele, uma pergunta que exige ler muitos arquivos faz sua sessão principal ler todos e carregar cada linha depois.
Você dá a ele as ferramentas de leitura e busca e mais nada, então ele não pode editar um arquivo nem iniciar ajudantes próprios. Você o coloca no Haiku, o modelo pequeno e barato da Anthropic, porque ler e buscar não exige o seu melhor modelo. Você também escreve um contrato de retorno, o formato da resposta que exige: primeiro a resposta, depois o arquivo e a linha que a provam, depois o que ele não encontrou. Na descrição, você diz ao Claude para usá-lo em perguntas que exigem ler muitos arquivos, um scout por pergunta, em paralelo.
Clonamos o Hono, um grande framework web de código aberto, e pedimos uma auditoria de como os vinte e sete middlewares embutidos rejeitam uma requisição. Rodamos a auditoria direto, sem agents, e depois com scouts em paralelo, cada um cuidando de uma parte das pastas. Os dois jeitos devolveram a mesma resposta, até os mesmos middlewares e os mesmos códigos de status. Duas execuções cada:
| Medida | Direto, execução 1 / execução 2 | Scouts, execução 1 / execução 2 |
|---|---|---|
| Contexto principal no fim (tokens) | 45,868 / 47,476 | 30,505 / 33,937 |
| Custo | $0.457 / $0.433 | $0.267 / $0.344 |
Com os scouts, a sessão principal terminou cerca de um terço mais leve, porque leu as notas curtas deles em vez de cada arquivo. Esse espaço importa quando você continua trabalhando na mesma sessão: sua próxima tarefa começa com menos bagunça e menos coisa para esquecer. Os scouts rodaram no modelo barato, então a execução inteira custou menos. Esse é o caso de manter que a Anthropic descreve: a leitura grande acontece num lugar que você descarta, e sua sessão guarda espaço para o trabalho que vem depois.
Agora o limite. Em perguntas pequenas, que precisam de poucos arquivos, os scouts quase não economizaram nada. Um benchmark no dev.to encontrou o mesmo em buscas comuns: abrir em paralelo não achou nada a mais e custou muito mais. A sessão principal também repassou a resposta dos scouts sem abrir os arquivos por conta própria, então confira as linhas de prova antes de agir sobre elas. Mande um scout quando a leitura for grande e sua sessão tiver mais trabalho depois, e pule-o numa consulta rápida.
Arquivo dois: o reviewer somente leitura
Um reviewer é um subagent com olhar novo que só pode ler. Quando seus testes estão verdes, é tentador fazer merge de uma mudança que ninguém leu, e a sessão que escreveu a mudança é a pior para julgá-la, porque já acredita no próprio plano. O reviewer vê a especificação e o diff, que é a lista de linhas que a mudança adiciona e remove.
Você dá a ele só as ferramentas de leitura e busca. Deixa de fora edit e write, para que ele não corrija o que encontra, e deixa de fora a ferramenta agent, para que ele não inicie ajudantes. A documentação da Anthropic diz exatamente isso: mantenha um reviewer somente leitura deixando a ferramenta agent de fora. Depois você escreve o formato da resposta no arquivo: um veredito, aprovado ou reprovado, depois cada achado com seu arquivo, sua linha e o código citado, depois o que ele não conseguiu provar. Mais uma regra o mantém honesto: nada de comentários de estilo e nenhum achado sem uma linha citada, de modo que cada achado venha com uma linha que você pode abrir e conferir.
Entregamos a ele uma mudança real, uma exportação em planilha das faturas em aberto escrita pelo nosso builder, com a especificação e o diff completo. Ele voltou em dezenove segundos com uma aprovação e um achado de baixa gravidade sobre um registro de cliente que poderia estar ausente. Em o que não conseguiu provar, apontou duas coisas que ninguém perguntou. Um nome de cliente que começa com um sinal de igual poderia ser executado como fórmula numa planilha, e as linhas eram ordenadas como texto, o que só funciona enquanto os números das faturas tiverem o mesmo tamanho. Isso é um reviewer aprovando uma mudança verde e ainda assim apontando um risco, sem tocar em nenhum arquivo.
Conferimos cada ponto nós mesmos. Nada apaga um cliente, então o achado do registro ausente não pode acontecer, mas o risco da fórmula e a ordenação valem a correção. O limite é que um reviewer só sabe o que consegue ler, então ele marca o resto como não provado, e você verifica cada achado antes de agir. Rode o reviewer depois da construção e antes do merge, e leia a lista de não provado com o mesmo cuidado que o veredito.
Arquivo três: o builder isolado
Um builder é um subagent que escreve código no próprio worktree, que é uma segunda cópia do seu repositório, numa branch própria, numa pasta própria. Serve para um trabalho que se sustenta sozinho e não deve bloquear sua sessão enquanto é construído.
Você define o campo isolation como worktree, e o Claude Code cria essa cópia para ele e a limpa se nada mudou. Você também define um limite de turnos, para que um builder que anda em círculos pare e devolva o que tem, marcado como parcial. Sem limite, um builder travado pode continuar gastando turnos no mesmo teste que falha enquanto você espera por nada. Nas instruções, você manda ele informar sua branch, rodar os testes e a checagem de tipos até os dois passarem, e fazer commit.
Pedimos ao nosso uma exportação em planilha das faturas em aberto, com nomes de clientes que podem conter vírgulas e aspas, testes incluídos. Ele foi para segundo plano e, enquanto trabalhava, fizemos à sessão principal outra pergunta: quais faturas podem ser anuladas e onde essa regra mora. A sessão principal respondeu com a linha exata no código, e o builder nunca atrapalhou. O builder voltou em cerca de um minuto e meio com um commit na própria branch e catorze novos testes, todos passando. Nossa branch principal não mudou até escolhermos fazer o merge. Só fizemos o merge depois que o reviewer aprovou, e a main simplesmente avançou até o commit do builder, sem nenhum commit de merge. Você sempre vê o trabalho do builder como uma branch que pode ler, testar e mesclar, ou descartar.
Um artigo sobre abrir em paralelo resume a regra numa linha: abra em paralelo para leituras, fique em um só para escritas. O limite é que o worktree parte da sua branch padrão, não de onde você está, então o trabalho que você ainda não commitou não está nele. Nunca o mande para código que sua sessão principal está editando, e nunca rode uma equipe de builders escrevendo ao mesmo tempo. Dê ao builder uma peça que se sustente sozinha, continue trabalhando e faça o merge depois da revisão.
Veredito: três arquivos e um teste
A Anthropic diz para usar menos subagents, e está certa, mas três arquivos ainda merecem seu lugar, cada um por um motivo que você consegue nomear. O scout mantém uma leitura grande fora da sua sessão principal. O reviewer dá a você um olhar novo que só pode ler. O builder escreve uma peça separada na própria cópia do repositório. Escreva esse motivo na descrição de cada arquivo, porque é isso que o Claude lê quando decide se vai chamá-lo. Se você não consegue escrever o motivo em uma única frase, isso costuma ser o sinal de que o agent deveria ser uma skill.
O test writer foi tão bem quanto skill, então o arquivo dele saiu, e o seu provavelmente também pode sair. Pule o subagent para uma pergunta rápida, para código que sua sessão já está editando e para qualquer persona sem motivo de contexto para existir. Nesses casos um ajudante custa um briefing, uma espera e um repasse, e não dá nada que sua sessão não pudesse fazer. Agent teams, que são sessões que trocam mensagens entre si, são outra coisa, e nada aqui precisa deles.
A regra única é a que a Anthropic escreveu: antes de qualquer agent novo ganhar um arquivo, dobre-o numa skill, rode os dois e mantenha o arquivo só se a skill tiver nota pior.
AIDive