Tem um padrão que se repete em quase todo time que começa a trabalhar sério com agentes: o prompt vai crescendo. Começa com um AGENTS.md razoável, aí entra a documentação do módulo, depois três arquivos relacionados, mais o histórico da conversa, mais o output de um script, mais “por segurança” o schema do banco inteiro. Em algumas semanas, a janela está cheia e o agente raciocina pior do que quando tinha metade daquilo.
O reflexo natural é pensar “preciso de uma janela maior”. Quase nunca é isso. O problema não é tamanho de janela. É que contexto está sendo tratado como pilha, quando deveria ser tratado como orçamento. Este post é sobre como decidir, por tarefa, quais fatias realmente mudam a saída do agente e carregar só aquelas.
Por que empilhar contexto degrada a saída#
Quando você joga tudo no prompt, três coisas acontecem ao mesmo tempo, e nenhuma é boa.
A primeira é diluição. O sinal que importa para a tarefa específica compete com centenas de linhas que não importam. O modelo continua “vendo” tudo, mas a chance de ele ancorar no trecho certo cai.
A segunda é inconsistência entre sessões. Quando metade do prompt é coisa que alguém colou sem critério, a saída deixa de ser reproduzível. Duas execuções da mesma tarefa podem divergir só porque o ruído era diferente.
A terceira é custo escondido. Tokens que não afetam a resposta ainda pagam latência, custo de API e tempo humano de revisão. Pior: quando dá errado, você não sabe qual pedaço do contexto foi responsável, porque tem contexto demais para inspecionar.
Contexto é orçamento, não pilha#
A mudança mental que resolve isso é tratar o contexto como um orçamento por tarefa. Não é “o que cabe na janela”. É “o que muda a saída o suficiente para justificar o espaço que ocupa”.
Se um arquivo não altera a decisão do agente, ele não deveria estar ali, independente de caber. Se um pedaço de doc só repete o que já está na constituição do projeto, ele está ocupando espaço duas vezes. Se um log de 2 mil linhas tem a informação útil em cinco, só aquelas cinco entram.
A pergunta operacional deixa de ser “o que eu posso incluir?” e vira “o que eu posso tirar sem piorar a resposta?”.
Três camadas de contexto#
Na prática, dá para organizar o contexto que um agente vê em três camadas com comportamentos diferentes.
| Camada | O que é | Frequência de mudança | Onde mora |
|---|---|---|---|
| Estável | Constituição do projeto, convenções, comandos, regras de ouro | Mudanças raras | AGENTS.md, CLAUDE.md, regras por escopo |
| Da tarefa | Specs, ACs (acceptance criteria), arquivos-alvo, ADRs (architecture decision records) relacionados, trechos de schema relevantes | A cada nova tarefa | Story, tech-spec, seleção explícita |
| Efêmera | Output de comando, stack trace, diff, resultado de busca, trecho de log | Dentro de uma execução | Mensagens da sessão |
A camada estável é pequena e vale manter em toda sessão. A camada da tarefa deveria ser escolhida com critério, não arrastada por hábito. A camada efêmera é a mais perigosa: é onde o prompt engorda sem ninguém perceber, porque cada comando que roda joga mais tokens na pilha.
A regra prática é simples: quanto mais efêmero o contexto, mais curto o tempo de vida dele deveria ser. Stack trace resolveu o bug? Some com ele. Output de ls ajudou a escolher um arquivo? Só o nome do arquivo precisa continuar.
O que carregar, o que resumir, o que linkar, o que deixar fora#
Aqui entra a parte operacional. Para cada pedaço candidato a entrar no contexto, tem quatro destinos possíveis, não um.
| Destino | Quando usar | Exemplos |
|---|---|---|
| Carregar inteiro | O agente precisa do texto exato para decidir ou editar | Arquivo que vai ser modificado, AC da story em execução, ADR citado |
| Resumir | A informação importa, mas o texto original tem muito ruído | Histórico longo da conversa, doc extensa onde só três regras importam, transcrição de reunião |
| Linkar | Pode ser útil depois, mas não muda a tarefa atual | Docs adjacentes, ADRs históricos, manuais de referência |
| Deixar fora | Não muda a saída para essa tarefa | Código de módulos não relacionados, schema de tabelas não tocadas, logs de outra feature |
O erro clássico é tratar tudo como “carregar inteiro” por via das dúvidas. A dúvida é o sinal de que aquele pedaço talvez nem precisasse estar ali.
Um critério honesto: antes de incluir um bloco, responda em uma frase o que muda na saída se esse bloco não entrar. Se você não consegue responder, o bloco provavelmente não precisa entrar.
Falhas comuns quando contexto é mal gerido#
Quatro padrões aparecem com frequência suficiente para valer nome próprio.
Bloat. O prompt cresce sessão após sessão porque ninguém poda. Cada nova tarefa herda lixo das anteriores. O sintoma é respostas mais lentas e menos focadas, mesmo em tarefas pequenas.
Contexto obsoleto. Algum trecho colado há dias não reflete mais o estado do código ou da spec. O agente decide baseado em informação errada e produz código que “fazia sentido” na versão antiga. O sintoma é conflito entre o que o agente afirma e o que o repositório realmente contém.
Lost-in-the-middle. Quando o prompt fica muito longo, informação no meio costuma receber menos atenção do que o início e o fim. Na prática, isso significa que colocar a regra crítica lá no meio de um bloco gigante é o mesmo que não tê-la. O sintoma é o agente ignorar restrição que “está escrita”.
Envenenamento de contexto. Saída errada de uma iteração vira entrada da próxima. Uma alucinação citada como se fosse fato contamina as decisões seguintes. O sintoma é o agente defender uma informação com convicção crescente enquanto ela piora a cada passo.
Nenhum desses problemas é resolvido com janela maior. Todos são resolvidos com curadoria.
Um fluxo para decidir o contexto antes de rodar o agente#
Antes de disparar a tarefa, vale passar pelo fluxo abaixo. Ele é propositalmente curto: a ideia é bloquear o reflexo de colar tudo.
Na prática, a maior parte do valor vem das duas primeiras perguntas. “Que decisão o agente precisa tomar?” filtra por intenção. “Que informação muda essa decisão?” filtra por relevância. O resto é poda.
Um checklist curto antes de cada tarefa#
Se o fluxo acima ainda parece abstrato, este é o formato que funciona bem como hábito.
- A constituição do projeto (
AGENTS.md,CLAUDE.mdou equivalente) está carregada e atualizada. - A story ou tech-spec da tarefa está explícita, com ACs verificáveis.
- Os arquivos-alvo foram nomeados, não inferidos.
- ADRs realmente citados pela decisão foram incluídos, os demais foram deixados de fora.
- Output de comando entrou só no trecho útil, não o log inteiro.
- Histórico anterior foi resumido ou descartado se não informa a tarefa atual.
- Nada do contexto atual contradiz o estado real do repositório.
Cinco minutos aqui poupam horas de revisão depois, especialmente em tarefas longas.
Trade-offs honestos#
Curadoria de contexto tem custo. Vale deixar o trade-off explícito:
- Seleção manual é mais trabalho por tarefa do que colar tudo.
- Resumir bem exige conhecer o material.
- Links dependem do agente conseguir acessá-los quando precisar, o que nem sempre é garantido.
- Em tarefas exploratórias, você de fato quer mais contexto amplo, não menos.
A resposta não é “sempre minimizar”. É ajustar o orçamento à natureza da tarefa. Bug fix isolado pede contexto cirúrgico. Discovery em módulo desconhecido pede contexto mais amplo, ainda que com poda forte depois.
Por onde começar hoje#
Se seu time já trabalha com agentes e o prompt anda crescendo sem controle, três passos resolvem a maior parte do problema:
- Separar o que é estável do que é efêmero. Tudo que é regra do projeto sai da mensagem e vira arquivo de constituição carregado uma vez.
- Pedir seleção explícita de arquivos-alvo. Antes de executar, listar os arquivos que entram. “Incluir pasta inteira” é sinal de que a tarefa ainda não está bem definida.
- Podar efêmero agressivamente. Stack trace, output, diff: só o trecho que muda a decisão. O resto some.
O resumo operacional é curto: trate contexto como orçamento, não como pilha. Pergunte o que muda a saída. Carregue pouco, resuma bem, linke o que pode esperar, deixe de fora o que não importa. Prompt menor, raciocínio melhor, falha mais reproduzível.
Comentários
Os comentários usam Disqus e só são carregados se você clicar no botão abaixo.