Subagents — IA especializada que não polui seu contexto
Tem um tipo particular de erro que eu costumava cometer com agentes de IA de código. Algo parecia estranho numa parte do codebase que eu não conhecia bem. Eu perguntava pro agente: “pode dar uma olhada nas implicações de segurança dessa mudança de auth?” O agente respondia com entusiasmo, abria dez arquivos, lia todos na íntegra, resumia cada um, cruzava com um conjunto de regras, e produzia um relatório detalhado.
E aí o resto da minha conversa tava arruinado.
O contexto do agente agora estava cheio daqueles dez arquivos, das regras de segurança, do relatório, e da cadeia de raciocínio que produziu tudo. Quando eu voltava a trabalhar na tarefa original — que não tinha nada a ver com segurança — o agente ficava puxando aquele material. A relação sinal-ruído caía. Depois de mais algumas trocas, eu tinha que começar uma conversa nova, perdendo todo o contexto específico do projeto que eu tinha construído antes.
Esse é o problema de poluição de contexto, e é uma das razões pelas quais comecei a usar subagents.
O que é um subagent
Um subagent é uma instância de IA separada, spawnada pela sua conversa principal, com sua própria janela de contexto. O agente pai invoca com uma descrição de tarefa; o subagent faz o trabalho isolado; retorna um resultado; o pai recebe o resultado e o subagent desaparece.
Da perspectiva do agente pai, chamar um subagent é conceitualmente similar a chamar uma função. Você não vê o que acontece dentro. Você não herda o work-in-progress. Você só recebe o valor de retorno.
A implementação parece mais ou menos assim — um arquivo Markdown numa pasta que o agente pai observa:
---
name: org-standards-security-review
description: >
Security and privacy review against the org standards.
Use when implementing or reviewing auth, APIs, data handling,
uploads, crypto, sessions, or infra. Use proactively for
sensitive features.
model: inherit
readonly: true
---
You review work against the org standards in `standards/rules/`.
## When invoked
1. From the parent prompt, infer scope (features, files, APIs).
2. Identify which topics under `standards/rules/` apply.
3. Read the relevant `standards/rules/*.md` files and compare
the implementation to the written rules.
4. Report by severity (Critical / High / Medium / Low).
Each finding must reference a rule file.Essa é toda a definição do subagent. O frontmatter declara o nome, quando deve ser invocado, qual modelo usar (herdar do pai nesse caso), e — crucialmente pra esse — que é read-only. O corpo é o system prompt com que o subagent roda.
O runtime do agente cuida do resto: spawnar o subagent com seu próprio contexto, passar a descrição de tarefa do pai, capturar a resposta, e trazê-la de volta.
As três propriedades que importam
Um subagent tem três propriedades que definem quando vale a pena usar.
Isolamento
O contexto do subagent é dele. O que ele lê, o pai não precisa ler. O que ele conclui, o pai recebe como resumo, não como a cadeia bruta de raciocínio. O contexto do pai fica focado na tarefa real do pai.
Especialização
Porque o subagent tem seu próprio system prompt, ele pode ser afinado pra um trabalho específico. O subagent de security-review não precisa ser bom em escrever código ou gerar testes; precisa ser bom em ler regras e comparar implementações com elas. Quanto mais estreita a especialização, mais limpa a saída.
Modo read-only opcional
A maioria dos subagents que escrevo são marcados readonly: true. Eles podem ler arquivos, rodar comandos shell, navegar o codebase — mas não podem escrever nada. Esse é o default certo pra trabalho de revisão e análise.
O modo read-only faz duas coisas: previne acidentes (um subagent que interpreta mal a tarefa não pode danificar nada), e muda meu modelo mental do que é seguro delegar. Eu spawno um subagent read-only pra qualquer tarefa de análise tranquilamente. Pensaria mais antes de spawnar um com permissão de escrita.
Quando usar um subagent
Três padrões onde subagents são claramente a ferramenta certa.
Leituras pesadas com retorno pequeno. Tarefas onde o agente precisa consumir muito material pra produzir uma resposta curta. Revisar uma mudança contra trinta arquivos de regras. Auditar uma feature contra um checklist. Buscar num codebase instâncias de um padrão. A parte de “consumir” é exatamente o que polui o contexto; a parte de “retornar uma resposta curta” é exatamente o que o pai realmente quer.
Especialização que não cabe no papel do pai. Code review, security review, auditorias de dependência, verificações de acessibilidade, escaneamento de licenças. Cada um desses se beneficia de um system prompt focado e um formato de output definido. Misturá-los no prompt de propósito geral do agente pai dilui ambos.
Trabalho paralelo. Quando duas investigações independentes precisam acontecer ao mesmo tempo, spawnar dois subagents em paralelo mantém cada um no próprio trilho. O pai espera os dois resultados. O contexto de cada subagent está limpo. O tempo total de relógio diminui porque as análises se sobrepõem.
Quando não usar um subagent
A tentação, depois de escrever o primeiro, é usar pra tudo. Resista.
Não use subagent pra trabalho trivial. Se a tarefa leva uma tool call e um parágrafo de análise, o overhead do subagent — spawning, passagem de contexto, sumarização — custa mais do que beneficia. Faça o trabalho no pai mesmo.
Não use subagent pra coisas que vão precisar de follow-up. O contexto de um subagent evapora depois que ele retorna. Se você pode querer perguntar “espera, por que você disse X sobre aquele arquivo?” dois minutos depois, o subagent não está lá pra responder. Use o pai pra tarefas que provavelmente terão follow-up.
Não use subagent pra contexto que você realmente quer poluído. Às vezes a “poluição” é exatamente o ponto. Se você está tentando construir o entendimento do pai sobre um sistema, fazer a leitura no pai é o correto. O subagent te dá um resumo; o pai te dá fluência. Necessidades diferentes.
O que o pai e o subagent cuidam de cada lado
O modelo mental mais limpo que encontrei:
| Preocupação | Pertence a | Por quê |
|---|---|---|
| O objetivo geral do usuário | Pai | O pai é dono do arco da conversa |
| A edição em andamento | Pai | Subagents são stateless entre turns |
| Ler arquivos de regra pra uma auditoria pontual | Subagent | Não polua o pai com material de referência |
| Cruzar uma mudança contra um padrão externo | Subagent | Especializado, leitura pesada, saída estreita |
| Escrever código | Pai | O pai é quem faz o trabalho |
| Revisar o código contra políticas | Subagent | Revisão especializada, leitura isolada |
| Rastrear contexto de projeto (decisões, pegadinhas) | Pai | Essa é a espinha dorsal da conversa |
O padrão: especializado e pesado em leitura vai pro subagent. A espinha dorsal da conversa fica no pai.
Algumas coisas que me surpreenderam
Subagents me fazem fazer perguntas melhores. Quando tenho que escrever — no prompt do subagent — exatamente o que quero que ele faça, percebo as perguntas que eu estava enrolando no chat. O ato de formalizar a tarefa numa definição de subagent frequentemente traz à tona ambiguidades que o pai estava absorvendo silenciosamente.
Subagents read-only mudam o que eu aceito automatizar. Um subagent com permissão de escrita me deixa cauteloso — quero revisar o que ele vai fazer antes de fazer. Um subagent read-only não tem essa pressão. Eu spawno um pra qualquer tarefa de “vai olhar isso e me diz o que encontrar” sem pensar duas vezes. A categoria de trabalho que eu delego expandiu no momento em que read-only virou o padrão.
O formato de saída é metade do valor. Um subagent que retorna um parágrafo de prosa livre é pouco melhor que o pai fazendo o mesmo trabalho. Um subagent que retorna um relatório estruturado — severidade, arquivo, citação de regra, número de linha — é qualitativamente diferente. O agente pai pode agir na saída estruturada, decidir quais findings endereçar primeiro, rotear pras edições certas. O formato é o que torna o resultado componível.
Subagents se tornam infraestrutura reutilizável. Escrevi um pra security review e acabei usando em todo projeto que trabalho. A especialização do subagent é portável de um jeito que um prompt avulso não é. Especialização compõe.
Como se encaixam com rules e skills
Esse é o terceiro vértice do triângulo, depois de rules e skills.
- Rules carregam automaticamente quando arquivos batem o padrão. Elas guiam o comportamento do pai em toda edição.
- Skills são procedimentos sob demanda que o pai invoca por nome. Rodam no contexto do pai.
- Subagents são instâncias de IA isoladas spawnadas pelo pai. Rodam no próprio contexto.
Normalmente você vai querer os três num projeto não-trivial: rules elevam o piso, skills dão procedimentos, e subagents cuidam do trabalho especializado pesado que o pai não deveria manter no próprio contexto.
Um pequeno conselho
Se você nunca escreveu um subagent, comece pelo formato de security-review: read-only, especialização estreita, saída estruturada. O post de amanhã mostra um que eu realmente uso.
Uma vez que você sentir como isso é diferente de fazer a mesma revisão no contexto do pai, vai começar a identificar outras tarefas que encaixam no mesmo formato.