Subagentes e Equipes de Agentes Claude Code: Um Guia Prático

Você já viu as palavras "subagentes", "Equipes de Agentes", "orquestração" e se pergunta se está perdendo algo. Resposta curta: para a maioria das suas tarefas, não. Mas em trabalhos grandes, sim, e vale a pena entender.

Vamos desvendar isso sem o jargão.

O que realmente é um subagente

Um subagente é um assistente especializado com seu próprio contexto, seu próprio prompt e suas próprias permissões de ferramentas.

Quando o agente principal encontra uma subtarefa bem definida, ele a delega a um subagente. Esse subagente trabalha em sua própria janela de contexto, faz seu trabalho e retorna apenas o resultado. O agente principal não recebe todo o histórico poluindo seu contexto, ele recebe a conclusão.

Esse é o ponto: manter o contexto do agente principal limpo. Em vez de um agente se afogando em 50.000 tokens de busca de arquivo, você tem um subagente que faz a busca e relata três linhas úteis.

Você declara seus subagentes na pasta .claude/agents/ do seu projeto. Cada um tem um nome, uma descrição que diz quando usá-lo e um prompt de sistema.

---
name: test-writer
description: Use quando testes precisam ser escritos ou corrigidos
---
Você escreve testes. Você visa a cobertura de casos extremos,
não o caminho feliz. Você nunca toca no código de produção.

Equipes de Agentes, o próximo passo

Equipes de Agentes é o orquestrador multi-agente embutido no Claude Code. Ainda experimental, desativado por padrão, mas uma boa porta de entrada.

A ideia: um agente líder divide uma grande tarefa, delega cada parte a um agente especialista (com seu próprio modelo, prompts, ferramentas), os especialistas trabalham em paralelo em um sistema de arquivos compartilhado, e os resultados fluem de volta para o líder.

Se "delegar a um especialista" soa como subagentes, isso é normal. Equipes de Agentes é essa ideia levada ao extremo, executando vários agentes verdadeiramente em paralelo, não apenas um após o outro.

Além do embutido, há orquestradores de terceiros como Multiclaude e Gas Town. Eles têm opiniões, o que os torna bons pontos de partida quando você começa: eles decidem por você até que você tenha construído seus próprios hábitos.

Quando você precisa (e quando não precisa)

Vamos ser claros: a orquestração multi-agente é inútil para 95% das tarefas assistidas por agentes. Para a maioria do seu trabalho diário, um único agente é mais rápido e simples.

Atualmente, multi-agente ainda é uma maneira cara e experimental de atacar grandes projetos.

Você precisa disso quando:

• O projeto se divide em partes genuinamente independentes que tocam arquivos diferentes.
• Uma única janela de contexto não pode conter tudo.
• Você quer paralelizar uma ampla refatoração ou uma migração em todo o repositório.

Você não precisa disso para corrigir um bug, uma funcionalidade focada ou qualquer coisa que caiba em uma cabeça.

A armadilha é montar uma "equipe" de dez agentes para algo que um agente faria em cinco minutos. Você paga em tokens e complexidade por um paralelismo que a tarefa nunca pediu.

O verdadeiro problema: visibilidade

Aqui está o que não é falado o suficiente. No momento em que você executa vários subagentes ou uma Equipe de Agentes, você perde o fio.

Um líder delega a cinco especialistas. Qual está trabalhando? Qual terminou? Qual está esperando uma decisão? Em um terminal, você vê uma parede de texto rolando, e não consegue dizer quem está fazendo o quê.

É aqui que um painel visual muda tudo. AgentsRoom mostra cada agente e cada subagente como seu próprio bloco, com seu status detalhado. Você vê a delegação acontecendo, vê quem está esperando sua resposta, vê quem travou. A parede de texto se torna um mapa legível.

Sem essa visão, a orquestração multi-agente permanece uma demonstração impressionante que é ingovernável no dia a dia. Com ela, torna-se uma ferramenta que você realmente usa.

Por onde começar

Não comece direto com uma equipe de oito agentes.

Comece com um ou dois subagentes para tarefas precisas e repetitivas: um que escreve testes, outro que busca na base de código. Você rapidamente sentirá o ganho no contexto do seu agente principal.

Uma vez que essa mecânica pareça natural, ative as Equipes de Agentes para trabalhos que se dividem claramente. Fique de olho em quem está fazendo o quê, aprove planos antes da execução e pare no momento em que a revisão se tornar seu gargalo.

Multi-agente recompensa as pessoas que estruturam antes de lançar. Não aquelas que lançam o maior número de agentes.