Janela de contexto do agente de IA: o que entra nela e por que o agente esquece as regras

O que é a janela de contexto de um LLM

A janela de contexto de um LLM é todo o texto que o modelo recebe como entrada para gerar a próxima resposta. O modelo não tem memória no sentido humano: tudo o que ele «sabe» sobre a sua tarefa naquele momento está nessa janela. O que não está nela, para o modelo, não existe.

O tamanho da janela é medido em tokens — pedaços de palavras. Em português, um token costuma ser mais curto do que em inglês, então a mesma instrução fica mais cara em tokens. Os modelos atuais têm janelas de centenas de milhares de tokens, e parece que há espaço para tudo. Na prática, o espaço do agente acaba mais rápido do que se espera, e a qualidade do trabalho começa a cair ainda antes.

O que entra na janela de contexto do agente

Um agente de programação tem exatamente três fontes de informação: o prompt de sistema com a descrição da tarefa, o conteúdo dos arquivos que ele leu e a saída das ferramentas que ele chamou. As três vivem na mesma janela e disputam espaço.

O ponto central: nada disso desaparece sozinho. O log de testes que falharam, útil vinte passos atrás, continua na janela e tira atenção do passo atual. A sessão longa é uma pilha que só cresce, e nela fica cada vez mais difícil achar a agulha.

Por que o agente esquece as regras em uma sessão longa

Uma queixa frequente: no começo da sessão, o agente segue com cuidado as regras do CLAUDE.md, e uma hora depois passa a violá-las. Ele não as «esqueceu» no sentido literal — o texto das regras ainda está na janela. O problema está em como o modelo distribui a atenção por um texto longo.

Lost in the middle

Um estudo de Liu e coautores, de 2023, mostrou que modelos de linguagem usam bem melhor as informações do início e do fim de um contexto longo do que as do meio. O arquivo de instruções é carregado no começo da sessão, mas, conforme a conversa avança, se acumula cada vez mais texto acima e abaixo dele. A regra que estava em evidência acaba caindo na zona onde o modelo «enxerga» pior.

A fatia das regras na janela encolhe

Em uma sessão recém-iniciada, as instruções são uma parte considerável do contexto. Depois de uma centena de chamadas de ferramentas, elas viram um pequeno fragmento diante de logs, diffs e código lido. O sinal é o mesmo, mas o ruído ao redor cresceu dezenas de vezes.

Exemplos recentes pesam mais que regras antigas

O modelo se apoia fortemente no que aconteceu há pouco na conversa. Se o agente fez algo contornando uma regra algumas vezes seguidas e isso passou despercebido, esse padrão no histórico passa a pesar mais do que uma linha de instrução lá no início.

Context rot: a degradação da qualidade antes do limite

Context rot («apodrecimento do contexto») é o nome do efeito em que a qualidade das respostas cai conforme a janela se enche, mesmo muito antes do limite técnico. O modelo formalmente aceita 200 mil tokens, mas com 150 mil trabalha pior do que com 20 mil: erra mais os detalhes, repete decisões já descartadas e perde instruções.

Sinais de que a sessão «apodreceu»:

• o agente propõe uma abordagem que vocês descartaram juntos meia hora antes;
• confunde nomes de arquivos e funções já discutidos;
• deixa de rodar verificações que rodava no início;
• as respostas ficam mais longas e vagas, surgem «já que estava aqui, também corrigi…».

Tentar resolver isso acrescentando mais uma regra não adianta: a nova regra também se perde no mesmo ruído. É preciso reduzir o ruído.

Compactação de contexto

Compactação é a condensação do histórico da sessão: o modelo escreve um resumo do que aconteceu, e a conversa continua a partir desse resumo, e não do histórico completo. A janela é liberada, e a essência do trabalho, em tese, é preservada.

No Claude Code, existe o comando /compact, ao qual se pode passar uma dica sobre o que priorizar na compactação. Quando a janela se aproxima do limite, o Claude Code também faz a compactação automaticamente. O comando /clear apaga todo o histórico e recomeça do zero, e o /context mostra como a janela está ocupada no momento.

/context
/compact preserve: objetivo da tarefa, decisões tomadas com os motivos, lista de arquivos alterados, o que falta verificar
/clear

Por que a compactação é perigosa

Um resumo sempre perde detalhes. Na síntese pode não entrar a opção descartada e o motivo da recusa, a formulação exata de um requisito ou uma nuance combinada de passagem. Depois da compactação, o agente trabalha com o resumo da própria sessão, escrito por outra pessoa. Por isso, o que é importante deve ficar não no histórico da conversa, e sim em arquivos que sobrevivam a qualquer compactação.

Compactar ou abrir uma sessão nova

Como economizar a janela de contexto

Economizar contexto não é uma questão de preço por token, e sim de qualidade do trabalho. Quanto menos ruído na janela, mais atenção sobra para a tarefa e para as regras.

1. Arquivo de instruções curto, como roteador

O CLAUDE.md ou o AGENTS.md de entrada é lido por inteiro em toda sessão. Um arquivo de 600 linhas representa algo como 10 a 20 mil tokens de custo fixo. Mantenha nele os comandos de verificação, as restrições rígidas e o mapa do projeto, e coloque os detalhes por tema em documentos separados, que o agente abre apenas quando precisa.

2. Conhecimento carregado sob demanda

Nos skills do Claude Code, a arquitetura é tal que, no contexto, entra primeiro apenas a descrição curta; o texto completo da instrução é carregado quando o skill é necessário para a tarefa. É uma forma cômoda de manter procedimentos raros — deploy, migrações, release — à mão, sem pagar por eles em cada sessão.

3. Subagentes para o trabalho barulhento

Um subagente trabalha em uma janela de contexto própria e devolve à sessão principal apenas o resultado. Busca em código grande, análise de um log extenso, estudo de um módulo desconhecido — tudo isso pode ser delegado a um subagente, que devolve alguns parágrafos de conclusões em vez de milhares de linhas de saída bruta.

4. Saída silenciosa das ferramentas

A saída de comandos é o maior consumidor da janela. Configure os comandos de verificação para imprimir uma única linha quando dão certo, e só o essencial quando falham: o teste que caiu e a sua mensagem, e não o log completo do build.

# barulhento: milhares de linhas na janela a cada execução
pytest -v

# silencioso: em caso de sucesso, uma linha; em caso de falha, só os testes que caíram
pytest -q --tb=short

# log não inteiro, mas só o final e os erros
tail -n 50 app.log | grep -i error

5. Uma tarefa por sessão

Não arraste uma mesma sessão por três tarefas sem relação. O histórico da primeira não serve para a terceira, mas ocupa espaço e confunde o agente. Terminou — registre o resultado — abra uma nova sessão.

6. Estado em arquivos, não no histórico

Tudo o que precisa sobreviver a uma compactação ou a uma sessão nova deve ser escrito no repositório: o objetivo, as decisões com os motivos, as alternativas descartadas, o que foi feito e como foi verificado, o próximo passo. Por exemplo, em PLAN.md e PROGRESS.md. Assim, a sessão nova começa não com um resumo, e sim com um documento preciso, e você pode limpar o histórico sem medo.

# PROGRESS.md
## Objetivo
Passar o cálculo de descontos para centavos inteiros

## Feito (verificado)
- app/payments/discount.py: float → int, make test verde
- Migração 041 adicionada, aplicada localmente

## Decisões
- Arredondamento — bancário, como no provedor de pagamento

## Descartado
- Decimal no modelo: quebra a serialização dos webhooks

## Próximo passo
Atualizar o cenário E2E de finalização de pedido e rodar make e2e

Regras críticas: não podem depender só da janela

Mesmo um contexto bem organizado não garante que as regras serão seguidas: o texto na janela influencia o modelo, mas não é uma proibição executável. Se uma violação é inaceitável, a regra precisa ser verificada mecanicamente. No Claude Code, para isso existem os hooks — comandos disparados em eventos do agente que podem bloquear uma ação — e as configurações de permissão, que proíbem determinadas ferramentas ou comandos. Linters, testes e CI funcionam independentemente do que está acontecendo na janela do agente.

Uma boa regra de harness: tudo o que pode ser verificado automaticamente é verificado automaticamente, e na janela só fica o que exige julgamento.

Resumo

A janela de contexto de um LLM é o único lugar onde o agente vê a sua tarefa, e ela enche mais rápido do que parece: instruções, histórico, arquivos lidos e saída de comandos se acumulam até o fim da sessão. A qualidade cai muito antes do limite técnico, as regras do meio de um contexto longo se perdem, e a compactação salva espaço ao custo de detalhes. Mantenha as instruções curtas, carregue o conhecimento raro sob demanda, delegue o trabalho barulhento a subagentes, guarde o estado em arquivos e reforce as regras críticas com hooks e verificações. O trabalho com o contexto do agente é tratado na prática no curso de harness engineering.