Subagentes Claude Code e Agent Teams: Um Guia Prático

Você viu as palavras "subagentes", "Agent Teams", "orquestração", e você se pergunta se você está perdendo alguma coisa. Resposta curta: para a maioria de suas tarefas, não. Mas em grande trabalho, sim, e vale a pena compreender.

Vamos desembaraçar 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 atinge uma subtarefa bem definida, ele a delega a um agente. Esse subagente funciona em sua própria janela de contexto, faz seu trabalho, e retorna apenas o resultado. O agente principal não tem toda a sua história poluindo o seu contexto, obtém a conclusão.

Esse é o ponto: manter o contexto do agente principal limpo. Em vez de um agente afogar-se em 50.000 fichas de busca de arquivos, você tem um subagente que faz a busca e reporta 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 do sistema.

---
name: test-writer
description: Use when tests need to be written or fixed
---
You write tests. You aim for edge-case coverage,
not the happy path. You never touch production code.

Agent Teams, o próximo passo

Agent Teams é o orquestrador multi-agentes incorporado no Claude Code. Ainda experimental, desativado por padrão, mas um ponto de entrada sólido.

A idéia: um agente líder divide uma grande tarefa, delega cada peça para um agente especialista (com seu próprio modelo, prompts, ferramentas), os especialistas trabalham em paralelo em um sistema de arquivos compartilhados, e os resultados voltam ao lead.

Se "delegar a um especialista" soa como subagentes, isso é normal. Agent Teams é essa ideia empurrada todo o caminho para executar vários agentes verdadeiramente em paralelo, não apenas um após o outro.

Além do incorporado, existem orquestradores de terceiros como Multiclaude e Gas Town. Eles são opinados, 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 você não precisa)

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

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

Você precisa dele quando:

• O projeto se divide em peças genuinamente independentes que tocam arquivos diferentes.
• Uma única janela de contexto não pode segurar tudo.
• Você quer paralelizar um refator amplo ou uma migração ampla.

Você não precisa dele para uma correção de bug, um recurso focado, ou qualquer coisa que se encaixa em uma cabeça.

A armadilha está a montar uma equipa de dez agentes para algo que um agente faria em cinco minutos. Você paga em fichas e complexidade por um paralelismo que a tarefa nunca pediu.

O verdadeiro problema: visibilidade

Eis o que não se fala o suficiente. No momento em que você executar vários agentes ou uma equipe agente, você perde o fio.

Um representante principal para cinco especialistas. Qual deles está a funcionar? Que terminou? Que está à espera de uma decisão? Em um terminal você vê uma parede de texto de rolagem, e você não pode dizer quem está fazendo o quê.

É aqui que um painel visual muda tudo. O AgentsRoom mostra cada agente e cada subagente como seu próprio azulejo, com seu status especificado. Você vê a delegação acontecer, você vê quem está esperando pela sua resposta, você vê quem caiu. A parede do texto torna-se um mapa legível.

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

Por onde começar

Não saltes directamente para uma equipa de oito agentes.

Comece com um ou dois subagentes para tarefas precisas e repetitivas: um que escreve testes, um que pesquisa a base de códigos. Você vai rapidamente sentir o ganho no contexto do seu agente principal.

Uma vez que o mecânico se sinta natural, ligue Agent Teams para o trabalho que se divide de forma limpa. Fique de olho em quem está fazendo o que, aprovar planos antes da execução, e parar a revisão momento torna-se seu gargalo.

Multi-agente recompensa as pessoas que estruturam antes de lançar. Não os que lançam mais agentes.