Como fazer o subagente do Claude Code devolver uma resposta curta e não encher o contexto principal

Fala aí, beleza? Se tu já saiu criando subagente pra tudo quanto é tarefa, talvez tenha notado uma coisa curiosa: o trabalho pesado fica isolado, mas a conversa principal continua enchendo…

O motivo: cada subagente roda na própria janela de contexto, só que o texto que ele devolve no final entra na conversa principal

Com vários subagentes mandando relatório detalhado, o contexto principal lota rapidinho

Aqui a ideia é fixar o formato desse retorno no prompt de sistema do subagente, com um modelo curto de três campos 🙂

O que você precisa antes de configurar o retorno do subagente

Basicamente o Claude Code instalado, um projeto aberto e saber onde o arquivo do subagente vive:

• .claude/agents/: subagentes do projeto
• ~/.claude/agents/: subagentes de usuário, que valem em todos os seus projetos

Existem outros escopos (organização, sessão via flag --agents e plugin), mas pra este tutorial os dois acima resolvem

Como é o arquivo de um subagente?

É um arquivo Markdown com frontmatter YAML no topo, como descreve a documentação oficial de subagents

Só dois campos são obrigatórios: name e description

O description explica quando o Claude deve delegar a tarefa pra esse subagente

E o corpo, tudo que vem abaixo do frontmatter, vira o prompt de sistema dele

Por que o subagente não herda nenhuma regra de brevidade?

Se liga nisso: o subagente recebe só o prompt de sistema dele e detalhes básicos do ambiente, como o diretório de trabalho

Ele NÃO recebe o prompt de sistema do Claude Code

Ou seja, se tu não escrever no corpo do arquivo como ele deve responder, ninguém vai fazer isso por você

Como definir o formato de resposta curta do subagente, passo a passo

A abordagem é toda em texto, dentro do prompt de sistema

Não existe, pelo que a documentação mostra, um campo de frontmatter específico pra formato de saída, então o trabalho é escrever bem o corpo do arquivo

1. Crie ou abra o subagente

O comando /agents abre uma interface pra ver, criar, editar e apagar subagentes

Pra criar, vai em Create new agent e escolhe se ele fica no nível de usuário (User-level, que salva em ~/.claude/agents/) ou de projeto

Tem também a opção Generate with Claude, que gera o subagente pra você

Se preferir, dá pra abrir ou criar o arquivo direto em .claude/agents/ no editor

Erro comum deste passo: achar que o description resolve o formato do retorno. Ele define QUANDO delegar, não COMO responder

E se usou o Generate with Claude, abre o arquivo gerado e confere se tem alguma instrução de formato de saída, porque é isso que vamos adicionar agora

2. Escreva a seção de formato de saída no corpo do arquivo

Os exemplos oficiais fazem exatamente isso: descrevem o formato da resposta em texto, dentro do prompt

O exemplo code-improver, por exemplo, diz: "For each issue you find, explain the problem, show the current code, and provide an improved version"

A gente vai seguir o mesmo padrão, só que apontando pro resumo mais enxuto possível

O arquivo abaixo é um exemplo didático pra tu adaptar, não um teste executado:

---
name: investigador-de-bug
description: Investiga a causa de bugs lendo arquivos, buscas e logs do projeto. Use quando a investigação exigir muita leitura de código ou de logs.
---

Você investiga bugs neste projeto. Leia os arquivos e logs que precisar,
faça as buscas necessárias e, quando pedido, aplique a correção.

## Formato da resposta final

Responda SOMENTE com estes três blocos, nesta ordem:

Feito: uma ou duas linhas dizendo o que você fez e o que concluiu.

Arquivos tocados:
- caminho/de/cada/arquivo/alterado/ou/criado

Pendências:
- o que ficou em aberto, ou "nenhuma"

Não cole logs, resultados de busca nem conteúdo de arquivos na resposta.
Esses detalhes ficam com você. Só o resumo volta para quem delegou.

Por que esses três campos?

O Feito diz o resultado, as Pendências dizem o que o agente principal ainda precisa resolver e os Arquivos tocados mostram onde mexer pra conferir

Essa lista de caminhos também ajuda a saber quem escreveu o quê, coisa que pesa muiiito quando tem outro agente no mesmo projeto

Erro comum deste passo: escrever só "seja breve" e parar por aí

"Breve" pra um modelo pode virar três parágrafos haha

Com campos fixos e uma ordem definida, fica claro o que entra e o que não entra

3. Diga explicitamente o que NÃO volta

A documentação descreve o subagente fazendo o trabalho no próprio contexto e devolvendo só o resumo

Por isso a última instrução do exemplo é tão importante: ela separa o que fica com o subagente (logs, buscas, conteúdo de arquivo) do que volta pra conversa principal

O frontmatter tem campos opcionais como tools e maxTurns, entre outros

Mas nada na documentação indica que eles controlem o tamanho da resposta final, então não conte com eles pra isso: quem manda no formato é o texto do prompt

4. Faça a checagem com uma tarefa real

Peça ao Claude Code uma tarefa que case com o description do subagente, pra ele delegar

Quando o subagente terminar, leia o que chegou na conversa principal

Confira:

• Vieram só os três blocos (Feito, Arquivos tocados, Pendências)?
• Não tem nenhum log, resultado de busca ou trecho de arquivo colado?
• Os caminhos listados batem com o que mudou no projeto?

Se algum log ou trecho de código escapou, volta no corpo do arquivo e deixa a proibição mais explícita, de preferência repetindo-a no fim da seção de formato

E quem usa o Agent SDK?

No Agent SDK, o campo prompt da definição do agente é o prompt de sistema, equivalente ao corpo Markdown do arquivo, segundo a documentação de subagents do SDK

Então o mesmo modelo de três campos vai ali dentro =)

Quando o retorno curto do subagente faz mais diferença

A própria documentação aponta o cenário clássico: tarefas que inundariam a conversa principal com resultados de busca, logs ou conteúdo de arquivos

Investigar bug, varrer o código atrás de um padrão, ler um log enorme… tudo isso é perfeito pra subagente, desde que o retorno venha enxuto

O outro cenário é rodar muitos subagentes em paralelo

Quando eles terminam, os resultados voltam pra conversa principal, e vários retornos detalhados juntos consomem bastante contexto

A documentação sobre agentes fala exatamente disso: dá pra pedir resumos curtos de volta pra que vinte resultados não encham o contexto

Controlar o que entra na janela principal é context engineering na prática, e o formato de retorno é uma das alavancas mais simples que existem

O resumo curto zera o custo do subagente?

Não, e vale ser honesto aqui

O custo dos subagentes é principalmente em tokens, e cada um faz requisições próprias que contam no mesmo uso da conversa principal

O resumo curto reduz o que entra no contexto principal, mas o trabalho que o subagente faz lá dentro continua custando

Vídeo: Claude Code com vários agentes trabalhando juntos

Se quiser ver como fica um projeto com o Claude Code coordenando vários agentes, esse vídeo do canal mostra a criação de jogos com IA nesse esquema

É justamente o tipo de projeto em que os retornos de muitos agentes começam a pesar na conversa principal

Próximo passo: padronizar o retorno de todos os seus subagentes

Pega o modelo de três campos e aplica nos seus subagentes de usuário, em ~/.claude/agents/

Assim o mesmo padrão de retorno vale em todos os projetos, sem tu precisar lembrar disso a cada repo novo

Se a ideia de cortar enchimento da saída te soa familiar, é porque é a mesma lógica do estilo caveman no Claude Code, só que aplicada ao texto que o subagente devolve

Só uma ressalva: os 65% de redução em chat e cerca de 8,5% em trabalho agêntico da skill caveman são medidas daquela skill e não garantem ganho no retorno de subagentes

O jeito de saber é fazer a checagem do passo 4 nos seus próprios fluxos 😀

até o próximo post!

Quer aprender mais sobre inteligência artificial e programação na prática? Conheça o canal Hora de Codar no YouTube e acompanhe os próximos vídeos.