O que é exatamente um subagente no Claude Code?

É uma sessão do Claude independente que o agente principal lança para resolver uma tarefa concreta. Tem o seu próprio contexto (não herda a tua conversa) e, ao terminar, devolve uma única mensagem de resultado ao agente que o lançou. Serve para delegar trabalho pesado —investigar muitos ficheiros, executar uma tarefa longa— sem saturar a conversa principal com todo o processo intermédio.

Em que se distingue um subagente de continuar a falar na mesma sessão?

Na mesma sessão, tudo o que o Claude lê e escreve fica no contexto e disputa a atenção do modelo. Um subagente isola esse trabalho: faz o trabalho sujo à parte e traz-te apenas o destilado. Ganhas duas coisas: contexto limpo na conversa principal e a possibilidade de lançar vários subagentes ao mesmo tempo para trabalho que não depende entre si.

Como lanço vários subagentes em paralelo?

Pedindo, numa mesma mensagem, que as tarefas se repartam entre agentes independentes. O Claude despacha-as ao mesmo tempo e espera que todas terminem antes de sintetizar. A chave é que as tarefas sejam realmente independentes: se o resultado de uma alimenta a seguinte, não há paralelo possível e é melhor fazê-las em cadeia.

Quando NÃO convém usar um subagente?

Quando a tarefa é minúscula (fá-la mais depressa do que a explicas), quando há dependências em cadeia (B precisa da saída de A), quando exige idas e voltas contigo a meio do caminho, ou quando já sabes exatamente que ficheiro e que dado precisas. Delegar tem um custo fixo de contexto e arranque; abaixo de um certo tamanho não compensa.

O subagente pode modificar os meus ficheiros ou só investigar?

Depende do tipo. Há subagentes de apenas leitura, pensados para investigar e devolver achados sem tocar em nada, e há-os com permissões completas para executar mudanças. Para varrer o código à procura de algo, usa um de leitura; para que isole uma tarefa de escrita longa, um com permissões, idealmente no seu próprio ramo ou worktree se o teu setup o permitir.

Subagentes no Claude Code: trabalhar em paralelo sem sujar o contexto

Chega um ponto em que o Claude Code fica curto numa só conversa. Pedes-lhe que reveja meia dúzia de ficheiros para encontrar algo, e a sessão enche-se de despejos de código de que já não precisas. Ou queres que investigue três coisas ao mesmo tempo e acabas por fazê-las uma atrás da outra, à espera. A ferramenta para romper esse teto chama-se subagente, e a maioria não a usa porque não entende quando ajuda e quando atrapalha.

Este guia é para isso: entender o que é um subagente a sério, como paralelizar trabalho, como escrever o encargo para que volte com algo útil e —tão importante como o anterior— quando NÃO lhe tocar.

Nota

Um subagente é uma sessão do Claude dentro da tua sessão do Claude. O agente principal lança um filho com o seu próprio contexto, dá-lhe uma tarefa, e o filho trabalha por conta própria e devolve uma só mensagem com a conclusão. Todo o processo intermédio fica no filho, não na tua conversa.

O que é um subagente (e porque não é "abrir outro separador")

A tentação é pensar num subagente como uma segunda janela de chat. Não é. A diferença chave está no contexto: o subagente arranca limpo, não vê a tua conversa, faz o seu trabalho e devolve-te um destilado. Não te traz os 40 ficheiros que leu; traz-te a frase que resume o que encontrou.

Isso muda o modelo mental. Numa sessão normal, tudo o que o Claude lê fica a ocupar espaço e a disputar a sua atenção. Quanto mais ruído acumulas, pior raciocina sobre o que importa. O subagente é a forma de fazer o trabalho sujo fora e ficares só com a resposta.

Há diferentes tipos consoante as permissões: os de apenas leitura, pensados para investigar e procurar sem tocar em nada, e os que têm permissões completas para executar mudanças. Escolhe o mais restritivo que sirva: para descobrir onde está definida uma função, um de leitura; para que isole uma refatorização longa, um com permissões.

Para que servem: os três usos que valem a pena

Nem tudo se delega. Estes são os três cenários onde um subagente ganha de longe:

Investigar sem sujar o contexto. "Encontra em que ficheiros se usa este padrão e diz-me quais é preciso tocar." O subagente lê 30 ficheiros e devolve-te uma lista de 5. A tua conversa não fica a par da varredura, só do resultado.
Paralelizar trabalho independente. Três perguntas que não dependem entre si lançam-se ao mesmo tempo e voltam juntas. É isto que de verdade multiplica: não é que o Claude trabalhe mais depressa, é que trabalha em três frentes em simultâneo.
Isolar uma tarefa longa e autónoma. Uma migração, uma varredura de testes, uma tradução em massa. Algo que tem um objetivo claro, não precisa de supervisão a meio e produz um entregável fechado.

O fio comum aos três: tarefas com um objetivo nítido e um final claro. Se não sabes descrever quando o subagente "terminou", provavelmente não é candidato a ser delegado.

Como os lançar: em série e em paralelo

Para lançar um subagente, descreves a tarefa ao agente principal e pedes-lhe que a delegue. A peça que quase ninguém aproveita é o paralelo: se pedes várias tarefas independentes numa mesma mensagem, o Claude reparte-as entre subagentes que correm ao mesmo tempo e espera que todas acabem antes de sintetizar.

Três subagentes em paralelo

Preciso de três investigações independentes, lança-as EM PARALELO (um subagente cada uma) e depois junta tudo:

1. Onde e como se valida o formulário de newsletter neste repositório (ficheiros + função).
2. Que fornecedor de e-mail está ligado atualmente e onde se configura a chave da API.
3. Se há testes que cubram a inscrição de um subscritor, e quais.

Cada subagente devolve apenas: caminhos de ficheiro absolutos + 2-3 linhas de conclusão. Nada de despejar código inteiro.

Repara em dois detalhes do encargo. Primeiro, "EM PARALELO": estás a deixar claro que as três são independentes e podem correr juntas. Segundo, o formato de saída ("caminhos + 2-3 linhas, nada de despejar código"): sem isto, cada subagente devolve-te uma parede de texto e perdes a vantagem de ter o contexto limpo.

O reverso: quando uma tarefa depende do resultado de outra (B precisa do que produziu A), não há paralelo possível. Isso vai em cadeia, na mesma conversa ou com subagentes sequenciais, não ao mesmo tempo.

Boas práticas: o encargo é tudo

Um subagente é tão bom quanto o seu briefing. Como não vê a tua conversa, tudo o que não lhe disseres, ele não sabe. Três regras:

Objetivo, âmbito e formato de saída, explícitos. O que queres, até onde pode ir e como to devolve. "Encontra X" é vago; "encontra X em src/, ignora os testes, devolve-me caminhos absolutos e uma linha por achado" é acionável.
Pede o destilado, não o processo. O valor do subagente é que filtra. Se o deixas devolver tudo o que leu, trocaste um contexto sujo por outro. Exige conclusão, não transcrição.
Uma tarefa, um subagente. O mesmo princípio que rege uma sessão saudável: um objetivo por agente. Se metes três temas díspares num só encargo, o subagente fá-los pela metade.

Dica

Se vais lançar um subagente de escrita sobre uma tarefa longa, dá-lhe o seu próprio espaço isolado (um ramo de Git, ou um worktree se o teu fluxo o suportar). Assim trabalha sem pisar o que tens a meio, e tu revês o resultado de uma vez em vez de veres mudanças a aparecer ao vivo.

E uma prática de ouro para a investigação: não dupliques o trabalho. Se delegaste uma pesquisa a um subagente, não a faças também tu "por via das dúvidas" enquanto esperas. Espera pelo resultado. O erro clássico é lançar o subagente e, ansioso, pores-te a ler os mesmos ficheiros: puxas duas vezes pelo mesmo fio.

Quando NÃO usar subagentes

Esta secção importa tanto como as anteriores, porque o abuso de subagentes é tão comum como o desuso. Não os uses quando:

A tarefa é minúscula. Se a fazes mais depressa do que a explicas, explicá-la é perder tempo. Delegar tem um custo fixo de arranque e contexto; abaixo de um certo tamanho, não compensa.
Há dependências em cadeia. Se o passo B precisa da saída do A, não há nada para paralelizar. Forçá-lo só acrescenta atrito.
Precisa de idas e voltas contigo. O subagente trabalha de um só fôlego e devolve uma única resposta. Se a tarefa exige que decidas a meio do caminho, mantém-na na conversa principal onde podes intervir.
Já sabes o ficheiro e o dado exato. Para olhar UM valor num ficheiro que já tens localizado, abri-lo é instantâneo. Mandar um subagente procurar o que já sabes onde está é burocracia.

A regra resumida: delega quando o trabalho é grande, independente e de objetivo claro; fá-lo tu quando é pequeno, dependente ou exploratório em aberto.

O modelo mental que muda tudo

Deixa de pensar no Claude Code como "um assistente" e começa a pensar nele como "um assistente que pode contratar outros". Tu diriges; os subagentes executam frentes paralelas e trazem-te relatórios. O teu trabalho deixa de ser fazer, e passa a ser repartir e sintetizar.

Quando interiorizas isso, a pergunta em cada tarefa muda. Já não é "como o faço?", mas "isto faço-o eu ou delego-o, e se delego, o que precisa de saber para voltar com algo útil?". Essa segunda pergunta —objetivo, âmbito, formato de saída— é a que separa quem usa subagentes para acelerar a sério de quem só acrescenta ruído. Começa por uma só delegação bem escrita: um encargo de investigação, com o seu formato de saída claro. Quando vires voltar o destilado limpo em vez da parede de texto, já não vais querer trabalhar de outra forma.