Se você já passou algumas horas desenvolvendo com um agente de IA no terminal, conhece bem o inimigo: o context window. Aquela conversa que começou limpa e objetiva vira, lá pelo meio do dia, um amontoado de logs de teste, conteúdo de arquivos e resultados de busca. E você nunca mais vai reler nada daquilo. Pior: quanto mais entulhada a janela de contexto, mais cara fica a sessão e pior fica a qualidade das respostas.

É exatamente esse problema que os subagents no Claude Code e no Antigravity CLI do Google, resolvem. Recentemente, as duas ferramentas passaram a oferecer subagentes, mas com filosofias quase opostas. Por isso, neste post, quero mostrar o que são, quais são as vantagens reais e como usar cada uma das duas abordagens. Spoiler: entender a diferença entre elas é o que vai te ajudar a escolher a ferramenta certa para cada tarefa.

O que é um subagent?

Um subagent (ou subagente) é um assistente de IA especializado que roda em uma janela de contexto isolada. Além disso, cada um tem um system prompt próprio, acesso a ferramentas específicas e permissões independentes.

A ideia é simples. Quando uma tarefa secundária ameaça poluir a conversa principal, rodar a suite de testes, vasculhar a documentação ou processar um log gigante, o agente principal delega essa missão para um subagente. Em seguida, o subagente faz o trabalho pesado no seu contexto e devolve apenas o resumo. Em outras palavras, o ruído fica do lado de fora; só o resultado relevante entra.

A analogia que eu gosto de usar é simples. O agente principal é o seu parceiro de pair programming. Já os subagentes são especialistas que você “contrata” para uma missão pontual: eles entram na sala, resolvem o problema e saem, sem deixar bagunça no seu histórico.

As principais vantagens

Independentemente da ferramenta, os subagentes entregam cinco benefícios claros:

• Preservam o contexto: a exploração e o trabalho braçal ficam fora da conversa principal, que continua enxuta e focada.
• Impõem restrições: você pode limitar quais ferramentas um subagente acessa (um revisor de código, por exemplo, não precisa de permissão de escrita).
• Especializam o comportamento: cada subagente tem um system prompt focado em um domínio específico, o que melhora a qualidade dos resultados.
• Controlam custos: dá para rotear tarefas simples para modelos mais rápidos e baratos, como o Haiku, e reservar o modelo potente para o que importa.
• Rodam em paralelo: investigações independentes podem ocorrer simultaneamente, reduzindo o tempo total.

De fato, esse último ponto merece destaque. Como cada subagente tem um contexto próprio, você consegue disparar várias investigações simultâneas. Em outras palavras, é algo impossível em uma única linha de conversa.

Subagents no Claude Code: você monta o time

A filosofia do Claude Code é declarativa: você define seus subagentes como arquivos, e o Claude decide quando usá-los. Pense neles como membros permanentes do seu time, prontos para serem chamados para qualquer projeto.

Os subagentes nativos

Antes de criar os seus, vale conhecer os que já vêm prontos:

• Explore — agente read-only otimizado para busca. Roda no Haiku (rápido e barato) e não tem acesso à escrita. O Claude delega a ele quando precisa entender o código sem alterá-lo.
• Plan — usado no plan mode para pesquisar o codebase antes de apresentar um plano. Também é read-only.
• general-purpose — o mais completo, com acesso a todas as ferramentas, para tarefas que combinam exploração e modificação.

Criando um subagent customizado

Um subagente é só um arquivo Markdown com frontmatter YAML seguido do system prompt no corpo. A forma mais fácil de criar é com o comando /agents, que abre uma interface guiada. Mas dá para escrever o arquivo à mão. E aqui vai a parte que mais rende: em vez de um único agente “faz-tudo”, monte um pequeno time e alinhe o modelo de cada um à complexidade da tarefa.

Veja três exemplos, do mais simples ao mais complexo, pensados para um fluxo real de blog no WordPress.

1. Auditor de SEO (tarefa mecânica → modelo barato):

---
name: seo-auditor
description: Audita um rascunho em busca de problemas de SEO e legibilidade — densidade da frase-chave, meta description, tamanho de frases e headings. Use após escrever ou editar um post.
tools: Read, Grep, Glob
model: haiku
---

Você é um auditor de SEO on-page e legibilidade que segue as regras do Yoast.

Ao ser invocado:
1. Leia o rascunho e identifique a frase-chave.
2. Rode a checklist abaixo.
3. Devolva um relatório — não edite os arquivos.

Checklist:
- Frase-chave no título, no primeiro parágrafo e em ao menos um H2
- Densidade da frase-chave entre 0,5% e 2,5%
- Meta description de 120 a 156 caracteres
- No máximo 25% das frases com mais de 20 palavras
- Pelo menos um link interno e um externo

Para cada item, marque OK ou FALHA, cite o trecho e sugira a correção.Code language: JavaScript (javascript)

2. Desenvolvedor de tema (construção → modelo equilibrado):

---
name: theme-builder
description: Implementa e ajusta componentes de block theme do WordPress (theme.json, templates e patterns). Use ao construir ou modificar a interface do tema.
tools: Read, Write, Edit, Bash, Glob, Grep
model: sonnet
---

Você é um desenvolvedor de block themes do WordPress.

Ao ser invocado:
1. Leia o theme.json e os templates existentes antes de mudar qualquer coisa.
2. Implemente a mudança reaproveitando os tokens (cores, tipografia, espaçamento) já definidos.
3. Valide os blocos do Gutenberg e rode os checks do projeto.

Princípios:
- O theme.json é a fonte da verdade — nada de CSS solto fora do padrão.
- Prefira patterns e template parts a marcação duplicada.
- Garanta marcação semântica e acessível (headings em ordem, contraste, foco visível).

Ao final, resuma os arquivos alterados e como testar a mudança.Code language: JavaScript (javascript)

3. Revisor editorial (julgamento sutil → modelo potente):

---
name: revisor-editorial
description: Revisa rascunhos em PT-BR com olhar editorial — clareza, ritmo, tom e coerência —, sinaliza trechos com "cara de IA" e sugere reescritas. Use no passe final antes de publicar.
tools: Read, Edit
model: opus
---

Você é um editor sênior de conteúdo técnico em PT-BR. Sua prioridade é preservar a voz do autor.

Ao ser invocado:
1. Leia o rascunho inteiro antes de tocar em qualquer trecho.
2. Avalie clareza, ritmo, coerência e tom (direto e técnico-acessível).
3. Sinalize clichês de IA ("não é apenas... é", "no mundo de hoje", entusiasmo genérico) e repetições.

Diretrizes:
- Mantenha os termos técnicos em inglês; corrija só o que agrega.
- Proponha reescritas trecho a trecho, com o original e a sugestão lado a lado.
- Justifique cada mudança em uma linha. Na dúvida, pergunte em vez de reescrever.Code language: JavaScript (javascript)

Repare no padrão: cada agente declara o seu model, e a escolha segue a complexidade da tarefa. O seo-auditor faz um trabalho de checklist. Por isso roda no Haiku, rápido e barato e sem permissão de escrita, já que só audita. O theme-builder precisa construir código e tomar decisões técnicas: Sonnet, com o conjunto completo de ferramentas. Já o revisor-editorial exige julgamento fino de linguagem e reescrita de qualidade, o tipo de tarefa que justifica o Opus. Em resumo: gaste a inteligência cara onde ela rende e jogue o mecânico no modelo barato.

Precisa de inspiração? A coleção awesome-claude-code-subagents, da VoltAgent, reúne dezenas de agentes prontos para clonar e adaptar. E, não por acaso, cada um já vem com o seu model definido.

Onde você salva o arquivo define o escopo:

• .claude/agents/ — subagentes do projeto. Versione no Git para o time inteiro usar e melhorar de forma colaborativa.
• ~/.claude/agents/ — subagentes pessoais, disponíveis em todos os seus projetos.

No frontmatter, apenas name e description são obrigatórios. Os demais campos dão um controle fino e poderoso:

• tools: lista branca de ferramentas. Se omitido, o subagente herda todas as ferramentas da conversa principal.
• model: qual modelo usar — haiku, sonnet, opus, fable, um ID completo (ex: claude-opus-4-8) ou inherit. É aqui que você controla custo.
• disallowedTools: lista negra — herda tudo, menos o que você bloquear.
• permissionMode: como o subagente lida com prompts de permissão (plan, acceptEdits, etc.).

Dica de sênior: o campo description não é decorativo. O Claude usa exatamente esse texto para decidir quando delegar para o subagente. Por isso, seja específico e inclua gatilhos como “use proativamente após…”. Uma descrição vaga significa um subagente que nunca é chamado.

Como invocar

Há três níveis, do mais sutil ao mais explícito:

1. Delegação automática: o Claude lê a sua tarefa, compara com as descrições dos subagentes e delega sozinho.
2. Linguagem natural ou @-mention: você pede diretamente (“use o subagent seo-auditor no rascunho de hoje”) ou digita @ e seleciona o subagente para garantir que ele rode.
3. Sessão inteira: com a flag --agent, a sessão toda assume o system prompt, as ferramentas e o modelo daquele subagente.

# A sessão inteira roda como o subagent theme-builder
claude --agent theme-builderCode language: PHP (php)

Subagents no Antigravity CLI: o orquestrador monta o time por você

Aqui a filosofia se inverte completamente. No Antigravity CLI, você não define os subagentes, quem faz isso é o orquestrador. Você descreve o objetivo, e ele decide como decompor o trabalho e quais especialistas criar na hora.

Na prática, é uma abordagem dinâmica: não há arquivos de configuração, nem definições manuais. O orquestrador raciocina sobre a tarefa, quebra em subtarefas e dispara os subagentes, cada um com sua janela de contexto isolada e rodando em paralelo.

Um exemplo concreto: ao receber um único pedido para limpar, analisar e visualizar dados de vendas, o orquestrador criou sozinho três subagentes, data_cleaner, data_analyzer e data_visualizer. Os nomes saíram diretamente da descrição do objetivo. Depois de um perfilamento inicial, ele despachou os subagentes restantes simultaneamente. Vale sempre consultar a documentação oficial, porque os comandos evoluem rápido.

Duas filosofias, uma escolha

A diferença fundamental é esta:

	Claude Code	Antigravity CLI
Quem cria os subagentes	Você (arquivos Markdown)	O orquestrador (dinâmico)
Reutilização	Alta — versionados no Git	Efêmera — criados por tarefa
Controle	Fino (tools, model, permissões)	Automático
Melhor para	Fluxos repetíveis e padronizados	Tarefas pontuais e exploratórias

Nenhuma das duas é “melhor”. O modelo do Claude brilha quando você tem fluxos repetíveis que valem o esforço de padronizar: um revisor de código, um especialista em testes, um agente de migração que o time inteiro reutiliza. Já o modelo do Antigravity brilha na conveniência: você joga um objetivo complexo e deixa a ferramenta descobrir a decomposição, sem gastar tempo configurando nada.

Dicas de especialista

Independente da ferramenta, algumas práticas valem ouro:

• Use subagentes para operações verbosas. Rodar testes, ler documentação extensa, processar logs — tudo que gera muito output é candidato ideal para delegar. O resumo volta limpo.
• Cuidado com o efeito bumerangue. Quando muitos subagentes retornam resultados detalhados de uma vez, esse volume todo pode encher o contexto principal de novo. Peça resumos objetivos.
• Roteie por custo. Com os subagents no Claude Code, jogue tarefas simples e paralelas para o haiku. Não há motivo para queimar tokens do modelo caro mapeando a estrutura de pastas.
• Restrinja ferramentas por segurança. Um subagente de análise não precisa de permissão de escrita. Menos ferramentas significa menos chance de um efeito colateral indesejado.
• Saiba quando NÃO usar. Para mudanças rápidas e pontuais, ou tarefas que exigem muito vai e volta com você, a conversa principal continua sendo o caminho mais eficiente. O subagente começa do zero e leva tempo para reunir contexto.

Conclusão

Os subagentes representam uma mudança importante na forma como desenvolvemos com IA: em vez de uma única conversa que cresce até estourar, montamos um time de especialistas com contextos isolados. O Claude Code te dá o controle de definir esse time arquivo por arquivo; o Antigravity CLI te dá a conveniência de deixar o orquestrador montá-lo na hora.

Minha sugestão? Experimente os dois. Comece com um subagent simples no Claude Code, um seo-auditor no Haiku, por exemplo, e suba para Sonnet e Opus conforme a tarefa pedir. Depois, jogue uma tarefa de dados no Antigravity com /goal e veja a decomposição automática acontecendo. Aliás, se os conceitos de agentes ainda são novos para você, recomendo antes a leitura do meu guia sobre rules, skills e MCP. No fim, como sempre defendo: a IA acelera, mas o critério de quando delegar (e para quem) ainda é seu.