Gerenciamento da janela de contexto: o que 50 sessões me ensinaram sobre desenvolvimento com IA

Medi o consumo de tokens em 50 sessões de desenvolvimento com o Claude Code. O padrão foi consistente: a qualidade das respostas degrada por volta de 60% de utilização do contexto, muito antes do limite rígido acionar a compactação.¹

TL;DR

O esgotamento da janela de contexto degrada silenciosamente a qualidade da codificação com IA. Após acompanhar 50 sessões construindo minha infraestrutura do Claude Code e meu sistema de qualidade para o blog, encontrei três padrões que mantêm a qualidade das respostas em sessões longas: compactação proativa após cada subtarefa, memória baseada em sistema de arquivos que persiste entre limites de contexto e delegação para subagentes que mantém o contexto principal enxuto. A conclusão principal: trate a janela de contexto como um recurso escasso, não como um thread de conversa sem fundo.

Como a degradação realmente se manifesta

Cada leitura de arquivo, saída de ferramenta e turno de conversa consome tokens. Uma única leitura de arquivo grande (2.000 linhas) pode consumir de 15.000 a 20.000 tokens. Após ler 10 arquivos e executar vários comandos, a janela de contexto contém mais saída de ferramentas do que instruções propriamente ditas.²

A degradação é sutil. O Claude não anuncia “meu contexto está 80% cheio”. Em vez disso, o modelo começa a: - Esquecer instruções estabelecidas 20 minutos antes - Repetir sugestões já rejeitadas três turnos atrás - Ignorar padrões estabelecidos anteriormente na conversa - Produzir alterações multi-arquivo menos coerentes

Percebi esse padrão ao construir meu sistema de deliberação. Uma sessão que começou com edições precisas em múltiplos arquivos, abrangendo 8 módulos Python, degradou para uma visão de túnel em arquivo único por volta dos 90 minutos. O agente parou de referenciar a arquitetura que havia lido antes porque esse contexto já tinha sido comprimido.

Estratégia 1: Compactação proativa

O comando /compact do Claude Code resume a conversa e libera espaço de contexto. O sistema preserva decisões-chave, conteúdo de arquivos e estado das tarefas enquanto descarta saídas verbosas de ferramentas.³

Quando compactar: - Após completar uma subtarefa distinta (funcionalidade implementada, bug corrigido) - Antes de começar uma nova área do codebase - Quando o Claude começa a repetir ou esquecer contexto anterior

Eu compacto aproximadamente a cada 25-30 minutos durante sessões intensas. Durante a construção da infraestrutura de deliberação (9 PRDs, 3.455 linhas de Python), compactei após a conclusão de cada PRD. Cada compactação preservou as decisões arquiteturais enquanto liberava contexto para a próxima fase de implementação.

Estratégia 2: Sistema de arquivos como memória

A memória mais confiável entre limites de contexto reside no sistema de arquivos. O Claude Code lê o CLAUDE.md e os arquivos de memória no início de cada sessão e após cada compactação.⁴

Meu diretório .claude/ funciona como um palácio da memória estruturado:

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

O arquivo MEMORY.md captura erros, decisões e padrões entre sessões. Atualmente contém 54 falhas documentadas com padrões de aprendizado entre domínios. Quando descubro que ((VAR++)) falha com set -e no bash quando VAR é 0, eu registro. Três sessões depois, ao encontrar um caso extremo semelhante com inteiros em Python, a entrada no MEMORY.md traz o padrão à tona.⁵

O efeito composto entre domínios: Um erro de escape em bash no desenvolvimento de hooks informou uma melhoria de regex no meu linter Python para o blog. Uma lacuna em tokens CSS (--spacing-2xs não existe) desencadeou uma auditoria sistemática de todas as referências a propriedades customizadas. Cada entrada conecta domínios que, de outra forma, permaneceriam isolados dentro de contextos de sessões individuais.

Estratégia 3: Handoff de sessão

Para tarefas que abrangem múltiplas sessões, crio documentos de handoff que capturam o estado completo:

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

Meu diretório ~/.claude/handoffs/ contém 49 documentos de handoff de tarefas multi-sessão. Iniciar uma nova sessão com claude -c (continuar) ou ler o documento de handoff fornece à sessão sucessora o contexto completo com custo mínimo de tokens.⁶

O padrão de handoff me salvou durante a construção da deliberação. O PRD-4 (extensões de recursion-guard) exigia compreensão das decisões dos PRDs 1-3. Sem o handoff, a nova sessão teria que reler todos os arquivos modificados. Com o handoff, a sessão começou com o contexto arquitetural e foi direto para a implementação.

Estratégia 4: Delegação para subagentes

Subagentes rodam em janelas de contexto independentes. Delegar tarefas de pesquisa ou revisão para subagentes preserva o contexto da sessão principal para o trabalho de implementação.⁷

Meu sistema de recursion-guard gerencia isso automaticamente:

# From recursion-guard.sh - spawn budget enforcement
MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

Cada subagente retorna um resumo em vez de saída bruta, mantendo o contexto principal enxuto. Durante reescritas de posts do blog, delego tarefas de exploração (coletar dados CSS, ler código de hooks, mapear estruturas de diretórios) para subagentes. O contexto principal permanece focado na escrita enquanto os subagentes cuidam da pesquisa.

O orçamento de spawn foi aprendido da maneira difícil: uma sessão inicial sem limites gerou subagentes recursivos que, por sua vez, geraram mais subagentes. O hook de recursion-guard agora impõe limites de profundidade com validação segura de inteiros e orçamentos configuráveis.⁸

Os antipadrões que aprendi na prática

Ler arquivos inteiros quando você precisa de 10 linhas. No início do meu uso do Claude Code, eu lia arquivos inteiros de 2.000 linhas para uma única função. Use offsets de linha: Read file.py offset=100 limit=20 economiza mais de 15.000 tokens por leitura.

Manter saídas de erro verbosas no contexto. Após depurar o problema do orçamento de spawn, meu contexto continha mais de 40 stack traces de iterações falhas. Um único /compact após corrigir o bug liberou esse peso morto.

Começar cada sessão lendo todos os arquivos. Minhas primeiras sessões pré-carregavam 8 a 10 arquivos “para contexto”. Agora deixo que as ferramentas glob e grep do Claude Code encontrem os arquivos relevantes sob demanda, economizando mais de 100.000 tokens de pré-carregamento desnecessário.

Conclusões principais

Para desenvolvedores individuais: - Compacte após cada subtarefa concluída, não quando o Claude forçar a compactação; compactação proativa em intervalos de 25-30 minutos mantém a qualidade das respostas - Registre decisões-chave em arquivos de memória no sistema de arquivos conforme a sessão avança; meu MEMORY.md tem 54 entradas que persistem através de centenas de sessões - Use subagentes para tarefas de pesquisa que poluiriam o contexto principal; uma consulta de pesquisa em 5 arquivos custa mais de 75.000 tokens no contexto principal, mas apenas um resumo de 500 tokens via subagente

Para equipes: - Padronize o formato dos documentos de handoff para tarefas multi-sessão; meus 49 handoffs seguem a mesma estrutura Status/Arquivos/Decisão/Bloqueio/Próximo passo - Configure arquivos CLAUDE.md no nível do projeto com contexto arquitetural que é carregado automaticamente em cada sessão — para a hierarquia de 7 camadas que surgiu desses princípios de gestão de tokens, veja Contexto é arquitetura

Perguntas frequentes

O que acontece quando a janela de contexto de um LLM enche?

Quando a janela de contexto se aproxima da capacidade máxima (cerca de 95% de utilização), o Claude Code dispara a compactação automática: um processo de resumo que condensa o histórico da conversa para liberar espaço. A qualidade das respostas, porém, já se degrada bem antes disso. Nas minhas medições ao longo de 50 sessões, a degradação começa por volta de 60% de utilização do contexto: o modelo esquece instruções anteriores, repete sugestões já descartadas e produz mudanças em vários arquivos com menos coerência. Além disso, cada compactação descarta contexto que pode ter guardado decisões importantes — quanto menos compactações, mais coerente a sessão.

Como gerenciar o contexto de um LLM em sessões longas?

Quatro estratégias sustentam a qualidade das respostas em sessões de várias horas. A compactação proativa depois de cada subtarefa concluída (a cada 25 a 30 minutos) evita a degradação silenciosa. A memória baseada no sistema de arquivos (CLAUDE.md, MEMORY.md, documentos de handoff) preserva o estado crítico entre os limites de contexto. A delegação para subagentes empurra as tarefas de pesquisa para janelas de contexto independentes e devolve resumos em vez de saídas brutas. E leituras dirigidas com deslocamento de linhas (Read file.py offset=100 limit=20) economizam mais de 15.000 tokens por leitura em comparação com carregar o arquivo inteiro. Para o modelo de compressão em três camadas, veja Contexto é a nova memória.

O que é compactação de contexto no Claude Code?

A compactação de contexto é o mecanismo nativo do Claude Code que resume o histórico da conversa quando a janela de contexto se aproxima da capacidade máxima. O comando /compact a aciona manualmente, e a compactação automática entra em cena por volta de 95% de utilização. O processo preserva decisões-chave, conteúdo de arquivos e o estado das tarefas, descartando as saídas de ferramentas mais prolixas. Um circuit breaker interrompe tudo após três falhas consecutivas de compactação, o que evita laços infinitos de nova tentativa. Antes dessa proteção existir, 1.279 sessões acumularam mais de 50 falhas seguidas e desperdiçaram cerca de 250.000 chamadas de API por dia, como documenta a análise do vazamento do código-fonte.

Quantos tokens bastam para um desenvolvimento produtivo com IA?

Uma janela de contexto de 200K tokens é suficiente quando bem administrada. Minha configuração comprimida mantém cerca de 78% da janela (156.000 tokens) livres para o raciocínio, o que rende de 40 a 60 turnos produtivos antes de bater no limite de compactação. Uma configuração sem compressão deixa apenas 26% (53.000 tokens) para raciocinar e chega à compactação em 15 a 20 turnos. O tamanho útil de uma janela depende mais do que a preenche do que do seu tamanho total: uma janela de 200K bem comprimida supera uma hipotética de 500K entupida de saídas de ferramentas sem compressão. Comprimir o prompt do sistema, desenhar as ferramentas com a CLI em primeiro lugar e iniciar agentes novos são as otimizações de maior alavancagem.

Como os documentos de handoff ajudam no desenvolvimento com IA em várias sessões?

Um documento de handoff registra o estado completo de uma tarefa para a próxima sessão: situação atual, arquivos alterados, decisões tomadas, bloqueios e próximos passos. Começar uma sessão lendo esse documento entrega todo o contexto arquitetural a um custo mínimo de tokens (em geral, menos de 500), em vez de exigir que o agente releia todos os arquivos alterados. Meus 49 documentos de handoff seguem sempre a mesma estrutura Status/Files/Decision/Blocked/Next. Durante a construção do sistema de deliberação, eles permitiram que cada sessão de um PRD começasse com as decisões de arquitetura anteriores já carregadas, sem carregar junto o histórico de conversa dos PRDs anteriores.

Referências