Context engineering: os quatro pilares e por que a janela cheia atrapalha

Um modelo com janela de 200 mil tokens pode degradar de forma significativa em 50 mil.

Isso não é estouro de janela. Estouro acontece quando você passa do limite e o sistema recusa. A degradação começa muito antes, enquanto ainda sobra espaço, e ninguém avisa.

Em julho de 2025, uma equipe testou 18 modelos de quatro fornecedores e encontrou o mesmo comportamento em todos: a confiabilidade cai conforme a entrada cresce, inclusive em tarefas triviais.

A conclusão dos autores resume o assunto deste post: os modelos não usam o contexto de forma uniforme. Ter a informação lá dentro não é o mesmo que ele usá-la.

Context engineering é decidir o que entra na janela, quando entra e em que forma. Engenharia de prompt escolhe as palavras da instrução; engenharia de contexto administra tudo que acompanha a instrução.

A diferença fica clara pelo que cada uma controla. Prompt é uma decisão de redação, tomada uma vez. Contexto é uma decisão de arquitetura, tomada a cada passo: o que buscar, o que carregar, o que resumir, o que jogar fora.

Este post trata da arquitetura. O comportamento da janela no dia a dia do Claude Code, com os sintomas que aparecem numa sessão longa, está em por que seu agente esquece no meio da tarefa. Aqui a pergunta é outra: por que a degradação acontece, e quais são as famílias de solução.

O trabalho de referência é "Context Rot: How Increasing Input Tokens Impacts LLM Performance", de Kelly Hong, Anton Troynikov e Jeff Huber, publicado pela Chroma em 14 de julho de 2025 (trychroma.com, acesso em 28/08/2026).

Foram 18 modelos: cinco da Anthropic, sete da OpenAI, três do Google e três da Alibaba. Todos apresentaram degradação em todos os incrementos de comprimento testados.

Seis experimentos, e três achados mudam como você monta um prompt.

Um distrator já basta. Com uma única resposta plausível e errada inserida no contexto, a acurácia já cai em relação ao caso limpo. Com quatro, cai mais. E o efeito amplifica conforme o comprimento cresce, em todas as famílias de modelo testadas.

Focado ganha de completo, com folga. No LongMemEval, os pesquisadores compararam um contexto completo de 113 mil tokens com uma versão focada de 300 tokens. A diferença foi substancial. O Claude Opus 4 mostrou a maior disparidade e tendeu a se abster quando incerto; os modelos da OpenAI alucinaram mais na presença de distratores.

Degrada até sem raciocínio. Num teste de cópia literal de palavras, com comprimentos de 25 a 10 mil, o desempenho caiu conforme o texto crescia. Não havia inferência envolvida — só repetir. A acurácia foi maior quando as palavras únicas apareciam cedo na sequência.

Esse último resultado é o que fecha o argumento. Se a degradação aparece numa tarefa sem raciocínio, ela não é falha de compreensão. É propriedade de como a atenção se distribui sobre entradas longas.

O que conta como distrator no seu contexto

O achado do distrator merece tradução, porque "informação irrelevante" soa vago e o caso real é específico.

Distrator não é conteúdo aleatório. É conteúdo plausível, do mesmo assunto e errado para aquela pergunta. Texto sobre outro tema o modelo descarta com facilidade; texto sobre o mesmo tema, com a resposta de outro caso, é o que confunde.

Numa operação comum, os distratores costumam ser estes:

• Documentação de versão anterior carregada junto com a atual.
• Exemplos de código de um caso parecido, que respondem a outra pergunta.
• Histórico de tentativas que falharam, mantido no contexto "para o agente não repetir", e que na prática ensina o caminho errado com riqueza de detalhes.
• Arquivos inteiros quando só uma função importava.
• Resultado de ferramenta não filtrado, com cinquenta linhas quando três respondiam.

O terceiro item é o mais traiçoeiro, porque a intenção é boa. Manter o erro anterior à vista parece prudente, e coloca no contexto uma versão detalhada e plausível da resposta errada, no mesmo assunto. É a definição do distrator que a pesquisa mediu.

A regra prática que sai daí: quando for cortar, corte o que é parecido antes de cortar o que é diferente. O irrelevante distante custa tokens. O irrelevante próximo custa acurácia.

A regra que quase todo mundo aprendeu — coloque o essencial no começo — tem prazo de validade, e o prazo é a metade da janela.

Em "Positional Biases Shift as Inputs Approach Context Window Limits", Blerta Veseli, Julian Chibane, Mariya Toneva e Alexander Koller mediram como o viés de posição muda conforme a entrada ocupa mais da janela (arXiv 2508.07479, COLM 2025, agosto de 2025). A inovação metodológica foi usar comprimento relativo à janela de cada modelo, em vez de comprimento absoluto.

O resultado:

Enquanto a entrada ocupa até 50% da janela, aparece o padrão em U conhecido: o modelo recupera melhor o que está no começo e no fim, e pior o que está no meio. Acima de 50%, o viés de primazia enfraquece e o de recência se mantém estável. O padrão vira degradação por distância: quanto mais perto do fim estiver a informação relevante, melhor.

A consequência prática é direta. Numa sessão curta, a instrução crítica no topo funciona. Numa sessão longa, ela precisa ser repetida perto do fim, porque o topo perdeu a vantagem que tinha.

Isso explica um comportamento que muita gente atribui a esquecimento: o agente que ignorou a regra do início da conversa não a esqueceu. Ela ficou onde o modelo passou a olhar menos.

<!-- [UNIQUE INSIGHT] -->

Circulam duas formulações de quatro estratégias, com nomes diferentes. Elas descrevem as mesmas quatro coisas.

Quem topou com as duas listas em lugares diferentes sai achando que existem oito técnicas. São quatro.

Escrever

Tirar da janela o que precisa sobreviver a ela. Um arquivo de plano, um rascunho de progresso, uma lista de decisões tomadas.

O critério do que escrever é o mesmo que já apareceu no pilar deste cluster: guarde decisão e restrição, descarte transcrição. O histórico completo da conversa cresce sem limite e empurra para fora o que importa.

Selecionar

Buscar sob demanda em vez de despejar tudo por precaução.

O experimento do LongMemEval é o argumento: 300 tokens focados superaram 113 mil tokens completos. Carregar "por garantia" é a forma mais comum de piorar o resultado achando que se está ajudando.

Definição de ferramenta também ocupa janela em toda requisição, mesmo sem ser usada — o que o post sobre design de ferramentas mediu como um penhasco de acurácia.

Comprimir

Resumir o que já está na janela, preservando o essencial.

Aqui existe uma armadilha específica: a compactação resume tudo, inclusive as regras que não podem ser resumidas. Uma restrição de segurança que vira uma linha vaga no resumo deixou de ser restrição.

A prática que resolve é marcar um arquivo como persistente e não compactável, e instruir o agente a tratar aquele conteúdo como inalterável mesmo quando comprime o resto. É a mesma lógica da camada de guardrails: o que não pode falhar não fica sujeito a interpretação.

Isolar

Dar janela própria a cada subtarefa, para que uma não contamine a outra.

É o pilar mais caro e o mais eficaz quando a tarefa é grande. Cada subagente começa limpo, com o cardápio de ferramentas e o contexto do próprio escopo, e devolve só o resultado. O critério de quando vale está em quando delegar a um subagente.

Qual pilar usar primeiro

Os quatro não se aplicam na mesma hora. O sintoma indica por onde começar.

A ordem de custo também ajuda a decidir. Escrever e selecionar custam pouco e rendem no mesmo dia. Comprimir exige decidir o que nunca some no resumo, o que é uma decisão de risco. Isolar é o mais caro, porque muda a arquitetura e adiciona coordenação.

Comece pelos dois primeiros. Se o problema persistir com a janela ainda abaixo da metade, provavelmente ele não é de contexto, e insistir nos outros dois pilares vai custar arquitetura sem entregar resultado.

Escrever um AGENTS.md ou CLAUDE.md na raiz é a recomendação mais repetida sobre contexto. Um estudo de fevereiro de 2026 mostrou que ela vem com uma condição.

Pesquisadores do ETH Zurich montaram o AGENTbench, com 138 issues reais de 12 repositórios Python de nicho, todos com arquivo de contexto escrito pelos próprios desenvolvedores (arXiv 2602.11988). Testaram quatro agentes — Claude Code com Sonnet 4.5, Codex com GPT-5.2 e com GPT-5.1 mini, e Qwen Code com Qwen3-30B — em três cenários: sem arquivo, com arquivo gerado por LLM e com o arquivo do desenvolvedor.

A leitura correta não é "arquivo de contexto não funciona". É que quem escreve muda o sinal do resultado.

A explicação provável liga com a seção dos distratores. Um arquivo gerado automaticamente tende a documentar o que o agente já deduz sozinho lendo o repositório: a estrutura de pastas, os scripts do package.json, as dependências. Isso não informa nada novo e ocupa janela, que é a definição de distrator: conteúdo plausível e irrelevante.

Isso qualifica sem contradizer a anatomia de um bom CLAUDE.md, que este blog publicou antes do estudo existir. O critério de lá continua valendo, e agora tem medição: escreva o que é verdade sobre o projeto e não é dedutível do código.

<!-- [PERSONAL EXPERIENCE] -->

O AGENTS.md deste repositório tem três linhas. Ele diz que esta versão do Next.js traz mudanças que quebram, que APIs e convenções podem diferir do que o modelo aprendeu, e que a documentação local deve ser lida antes de escrever código.

É só isso. Nada sobre estrutura de pastas, nada sobre scripts, nada sobre stack.

Ele ficou assim por um motivo pouco nobre: um erro aconteceu. O agente escreveu código com a API antiga, o build quebrou, e a correção virou aquelas três linhas. É o formato que o estudo do ETH favorece, e chegou aqui por acidente, não por leitura de boas práticas.

Vale registrar o que não existe nesta operação, porque a lista é maior que a anterior.

Não há compactação automática. Quando a sessão fica longa, ela fica longa. Não há memória entre sessões: cada uma começa do zero, e o que sobrevive é o que está escrito em arquivo no repositório. Não há recuperação sob demanda — o contexto é montado à mão, por mim, a cada tarefa.

O custo disso aparece onde a pesquisa prevê. Em sessões longas, o começo perde força, e instruções dadas no início param de ser seguidas. A correção que uso é a mais simples e a menos elegante: recomeçar com um resumo escrito à mão, o que é o pilar "escrever" executado por uma pessoa em vez de por um sistema.

Dos quatro pilares, este blog usa um e meio.

Isso é honesto e também é suficiente para a escala em que opero. Três posts por semana, sessões de algumas horas, um repositório que cabe na cabeça. A ausência de compactação e de memória só começaria a doer com volume maior ou com mais gente mexendo no mesmo projeto. Registro a lacuna sem transformá-la em urgência que ela não tem.

Trabalho de contexto rende um resultado difícil de sentir: as coisas simplesmente falham menos. Três números tornam isso visível.

Tokens de entrada por tarefa. É a medida direta do que você está carregando. Se ela sobe sem a tarefa ficar maior, alguma coisa entrou na janela sem ser convidada — uma ferramenta nova, um arquivo carregado inteiro, um histórico que parou de ser podado.

Proporção da janela ocupada. Este é o número que o achado dos 50% torna acionável. Enquanto a média ficar abaixo da metade, a instrução no topo continua funcionando. Quando passar, você precisa repetir o que é crítico perto do fim.

Passos até concluir. Sobe quando o agente perde informação e refaz trabalho. É o mesmo indicador antecedente que aparece em observabilidade de agente, e aqui ele serve para pegar degradação de contexto antes de a qualidade cair.

Os três saem do rastro que você já tem, se instrumentou a camada anterior. Nenhum exige ferramenta nova.

Um teste barato fecha o diagnóstico: pegue uma tarefa que falhou numa sessão longa e repita numa sessão nova, com o contexto mínimo. Se passar, o problema era contexto e não capacidade. É o mesmo desenho do experimento que comparou 113 mil tokens com 300.

O que é context engineering?

É a prática de decidir o que entra na janela de contexto de um modelo, em que momento e em que formato. Inclui guardar informação fora da janela, buscar sob demanda, comprimir o que já está lá e separar tarefas em janelas distintas. A motivação é medida: em 18 modelos testados pela Chroma em 2025, o desempenho caiu conforme a entrada crescia, mesmo em tarefas simples e antes de a janela encher.

Qual a diferença para prompt engineering?

Engenharia de prompt escolhe as palavras da instrução, e é uma decisão de redação tomada uma vez. Engenharia de contexto administra tudo o que acompanha a instrução — documentos, histórico, resultados de ferramenta, memória — e é uma decisão de arquitetura, revisitada a cada passo do agente. A primeira melhora como você pede; a segunda decide o que o modelo tem em mãos ao responder.

Por que o agente piora com contexto longo?

Porque os modelos não usam o contexto de forma uniforme. A degradação aparece até em tarefas sem raciocínio, como copiar texto literalmente, o que indica propriedade da atenção e não falha de compreensão. Um único distrator já reduz a acurácia, e o efeito se amplifica conforme a entrada cresce. Isso acontece bem antes do limite da janela: um modelo com 200 mil tokens de capacidade pode degradar de forma relevante em 50 mil.

Vale a pena escrever um AGENTS.md?

Vale, se for você quem escreve. No estudo do ETH Zurich com 138 issues reais, arquivos escritos por desenvolvedores superaram os gerados por LLM nos quatro agentes testados, com cerca de 4 pontos de ganho. Os gerados automaticamente reduziram a taxa de sucesso em 5 de 8 cenários, acrescentaram de 2,45 a 3,92 passos por tarefa e elevaram o custo em mais de 20%. Escreva o que é verdade sobre o projeto e não é dedutível do código.

Preciso de banco vetorial para fazer isso?

Não para começar. Dos quatro pilares, apenas "selecionar" às vezes pede infraestrutura de busca, e mesmo ele funciona com meios simples: busca por texto no repositório, leitura de trecho em vez de arquivo inteiro, um índice de arquivos por assunto. Escrever, comprimir e isolar não dependem de banco nenhum. Vale montar recuperação vetorial quando o volume de material tornar a busca simples insuficiente, e não antes.

Janela maior resolve o problema?

Não resolve, e pode piorar a impressão do problema. A degradação é função do comprimento da entrada, não da distância até o limite, então uma janela maior apenas permite chegar mais longe na zona em que o desempenho já caiu. E acima de 50% de preenchimento o viés de posição muda, e a informação colocada no início perde a vantagem que tinha em contextos curtos.

• Context rot não é estouro. É a qualidade cair enquanto ainda sobra espaço, e apareceu nos 18 modelos testados.
• Um distrator já basta para reduzir a acurácia, e o efeito cresce com o comprimento.
• O "perdido no meio" vale até 50% da janela. Acima disso, vence quem está perto do fim — repita a instrução crítica.
• Os quatro pilares são escrever, selecionar, comprimir e isolar. As duas nomenclaturas descrevem as mesmas quatro.
• Arquivo de contexto escrito por humano rende; gerado por LLM custa. Escreva o que não é dedutível do código.

Os dois próximos posts do cluster abrem dois desses pilares: memória, que é o "escrever" levado a sério, e recuperação, com a pergunta de se RAG ainda faz sentido. O mapa das cinco camadas continua no pilar sobre harness engineering.