Janela de contexto do Claude Code: guia prático

A janela de contexto do Claude Code é tudo o que o modelo vê num turno: o system prompt, os nomes das ferramentas, o seu CLAUDE.md, cada mensagem, cada arquivo que o Claude leu e cada saída de comando da sessão. Para gerenciá-la, confira o que está nela com /context, compacte sessões longas com /compact (ou deixe o auto-compact fazer isso), comece trabalhos sem relação com /clear, mantenha o CLAUDE.md curto e mande investigações pesadas para subagentes, para que só o resumo deles volte. O resto deste guia mostra como cada um funciona e quando usar.

O que enche a janela de contexto

Uma janela de contexto é medida em tokens, e no Claude Code ela enche por dois lados: o que carrega antes de você digitar qualquer coisa e o que a sessão vai acumulando enquanto trabalha.

Carregado na inicialização

Segundo a documentação do Claude Code, isto já está no contexto antes do seu primeiro prompt:

• O system prompt e as ferramentas embutidas.
• Os arquivos CLAUDE.md (do projeto, do usuário e de pastas acima) e a memória automática. O AGENTS.md pode carregar no lugar do CLAUDE.md.
• Os nomes das ferramentas MCP e as instruções dos servidores. As definições completas das ferramentas são adiadas por padrão e carregam quando uma ferramenta é usada.
• As descrições das skills. O corpo de uma skill só carrega quando ela é invocada.

Medimos essa base no nosso post sobre uso de tokens: cerca de 34,4k tokens na primeira requisição com uma configuração padrão, caindo para cerca de 13,3k com uma enxuta. Essa base é reenviada a cada turno.

Adicionado durante a sessão

É daqui que vem a maior parte do crescimento:

Uma única sessão de depuração ou exploração do código pode gerar dezenas de milhares de tokens. Isso importa porque, como diz a documentação do Claude Code, o desempenho de um LLM cai conforme o contexto enche: o Claude pode começar a esquecer instruções anteriores ou a errar mais.

Qual é o tamanho da janela?

Depende do modelo. A documentação de configuração de modelos do Claude Code lista uma janela de contexto de 1M de tokens para modelos recentes (os modelos Fable, Sonnet 5 e posteriores, Haiku 5.5, Opus 4.7 e posteriores rodam com ela por padrão). O Opus 4.6 e o Sonnet 4.6 só chegam a 1M pela variante [1m]; fora isso, trabalham com um limite de 200K.

Uma janela maior dá espaço, não imunidade. Uma sessão com 600k tokens de exploração antiga continua mais lenta, mais cara por turno e mais ruidosa do que uma que carrega só o que a tarefa atual precisa.

Leia o medidor: /context

Antes de mudar qualquer coisa, olhe. O /context mostra uma divisão em tempo real do que está usando a janela, agrupada por categoria, com sugestões. Ele também lista quais arquivos CLAUDE.md e de memória foram carregados, que é o jeito mais rápido de achar um arquivo de instruções esquecido numa pasta acima.

/context

Alguns comandos relacionados ajudam aqui:

• /memory abre os arquivos de memória carregados para você editar.
• /mcp lista os servidores conectados e deixa você desativar os que não está usando.
• /usage mostra o uso de tokens da sessão, incluindo uma linha de prompt cache.

Você também pode colocar o uso de contexto numa status line personalizada, para ver sem precisar perguntar.

Compacte: /compact e auto-compact

O /compact troca a conversa até ali por um resumo e continua na mesma sessão. O Claude Code também faz isso sozinho quando você se aproxima do limite; isso é o auto-compact.

Direcione o resumo

Um /compact simples deixa o Claude decidir o que manter. Você tem resultados melhores quando diz a ele:

/compact Focus on the API changes and the list of files we modified

Você pode tornar isso permanente com uma seção # Compact instructions no CLAUDE.md, por exemplo: “Ao compactar, sempre preserve a lista completa de arquivos modificados e os comandos de teste.”

Para compactar só uma parte da conversa, pressione Esc duas vezes ou rode /rewind, escolha uma mensagem e selecione Summarize from here ou Summarize up to here.

Defina quando o auto-compact roda

Por padrão, o Claude Code compacta quando a conversa atinge o limite de contexto do modelo; modelos rodando com uma janela nativa de 1M compactam um pouco antes, por volta de 967K tokens. Se você prefere compactar mais cedo, defina a sua própria janela:

/autocompact 500k
/autocompact auto

O primeiro salva uma janela de 500k para o modelo atual; o segundo volta ao padrão. A mesma configuração existe como autoCompactWindow no settings.json e como a variável de ambiente CLAUDE_CODE_AUTO_COMPACT_WINDOW para scripts. São aceitos valores de 100K a 1M.

O que sobrevive à compactação

A documentação lista o que é reposto depois de um compact: o system prompt, o CLAUDE.md da raiz do projeto, as regras sem escopo, a memória automática e o plano atual do plan mode. Os arquivos modificados recentemente são relidos, e os CLAUDE.md aninhados e as regras com escopo de caminho recarregam quando o Claude volta a trabalhar naquelas pastas. O que não sobrevive literalmente é a conversa em si, então uma instrução que você só digitou no chat pode perder detalhes. Se ela importa, coloque no CLAUDE.md.

Um custo para ter em mente: o /compact lê a conversa inteira para resumir, então o próprio compact é uma requisição grande.

Recomece: /clear

O /clear esvazia a conversa e não custa nada. Use quando passar para um trabalho sem relação. As boas práticas do Claude Code citam dois padrões de falha que ele resolve:

• A sessão “pia da cozinha”. Você começa uma tarefa, pergunta algo sem relação e depois volta. O contexto fica cheio de material irrelevante.
• Corrigir de novo e de novo. Depois de duas correções que falharam no mesmo problema, o contexto fica poluído de abordagens fracassadas. Limpe e escreva um primeiro prompt melhor, incluindo o que você aprendeu.

Se talvez queira a sessão de volta, dê um nome a ela antes com /rename e depois rode /clear; o /resume a traz de volta mais tarde. Para uma pergunta rápida que não precisa ficar no histórico, o /btw responde sem adicionar nada à conversa.

Mantenha o CLAUDE.md pequeno

O CLAUDE.md carrega em toda sessão, então cada linha é paga a cada turno. A documentação do Claude Code sugere mantê-lo abaixo de umas 200 linhas e perguntar, para cada linha, se removê-la causaria erros. Se não causaria, corte. Um arquivo inchado tem um segundo custo além dos tokens: regras importantes se perdem no ruído e o Claude as ignora.

O que fazer com o resto:

• Passe instruções específicas de fluxos de trabalho (como fazer um release, como escrever uma migration) para skills. Só as descrições curtas delas carregam na inicialização; o corpo carrega quando a skill é usada.
• Coloque links para documentação detalhada em vez de colar o conteúdo.
• Apague o que o Claude já faz certo sem ninguém pedir, ou transforme em hook se precisa acontecer sempre.

Aprofundamos a estrutura no guia de CLAUDE.md e AGENTS.md.

Use subagentes para manter o contexto principal limpo

Pesquisa é o clássico destruidor de contexto: para responder “como a nossa autenticação lida com a renovação de tokens?”, o Claude pode ler vinte arquivos. Um subagente roda na própria janela de contexto, faz essa leitura lá e devolve só um resumo para a sua sessão principal.

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

Bons candidatos para um subagente:

• Explorar o código antes de uma mudança.
• Ler logs longos ou saídas de teste para achar a única falha que importa.
• Revisar o diff num contexto novo, o que também evita o viés a favor do código que a sessão principal acabou de escrever.

Subagentes não são de graça. Eles gastam os próprios tokens, e a documentação do Claude Code observa que equipes de agentes usam cerca de 7 vezes mais tokens que uma sessão única. O ganho é qualidade e foco na conversa principal, nem sempre uma conta menor.

Quanto custam os servidores MCP

O Model Context Protocol costumava ser um dos maiores custos de inicialização, porque todas as definições de ferramentas de todos os servidores carregavam logo de cara. Hoje o Claude Code adia as definições de ferramentas por padrão (tool search), então, até uma ferramenta ser usada, só o nome dela e as instruções do servidor estão no contexto.

Isso muda o conselho, mas não o elimina:

• Desative com /mcp os servidores que você não está usando neste projeto.
• Prefira ferramentas de CLI como gh, aws, gcloud ou sentry-cli quando existirem. A documentação as chama de o jeito mais eficiente em contexto para acessar serviços externos.
• Fique de olho nos resultados das ferramentas, não só nas definições. Uma consulta ao banco de dados ou um snapshot de página devolvido por uma ferramenta MCP cai inteiro no contexto.

Sinais de context rot

“Context rot” é o nome informal para uma sessão que piorou sem alarde porque o contexto está cheio demais ou ruidoso demais. Sinais típicos:

• O Claude esquece uma regra que você disse antes na conversa, ou uma do CLAUDE.md.
• Ele relê arquivos que já leu, ou pergunta coisas que já sabe.
• Ele repete uma abordagem que você já rejeitou.
• As respostas ficam mais vagas e as edições caem no lugar errado.
• Cada turno parece mais lento e o contador de tokens sobe mais rápido.

Quando vir dois ou mais desses sinais, rode /context. Se a conversa é o grosso, compacte com um foco; se a sessão vagou por várias tarefas, limpe. Note também que, depois de uma pausa sem atividade, o prompt cache expira, então a próxima mensagem reprocessa o contexto inteiro a preço cheio. Uma sessão grande e parada há muito tempo é um bom momento para compactar ou limpar antes de continuar.

Hábitos que mantêm as sessões saudáveis

• Uma tarefa por sessão. Dê um nome, termine, limpe.
• Aponte, não navegue. Referencie arquivos com @path e cite funções pelo nome em vez de pedir ao Claude para “dar uma olhada”.
• Delimite as investigações. “Ache onde os rate limits são aplicados em src/api” é melhor que “investigue o rate limiting”. Ou entregue isso a um subagente.
• Corte a saída de comandos. Rode testes individuais em vez da suíte inteira e filtre os logs antes de o Claude lê-los.
• Compacte com um foco, cedo. Um compact que você direciona, antes de a janela estar quase cheia, costuma manter os detalhes certos melhor do que um automático no limite.
• Revise o CLAUDE.md como se fosse código. Faça uma poda quando o Claude começar a ignorar regras.

Onde o AgentVera entra

O AgentVera roda Claude Code, Codex e outros agentes CLI lado a lado num app de desktop. Ele não substitui os hábitos acima, mas tira de você parte do controle manual quando você roda vários agentes ao mesmo tempo. Tudo isso está na página de economia de tokens:

• Tamanho do contexto em tempo real no painel de cada agente, medido pelo próprio histórico da CLI, então funciona além do Claude Code e do Codex.
• Auto-compact ligado por padrão num limite de 150k tokens, usando o comando de cada CLI (/compact, /compress, /summarize, /smol). Mude em Settings → Token savings.
• Perfis de contexto (Standard, Balanced, Lean) que reduzem a base de inicialização por agente.
• Uma proteção de leitura, mais as smart tools para o Claude Code, que recusam a releitura de um arquivo que não mudou e entregam ao agente primeiro um outline de um arquivo grande.
• Um mapa de projeto para os agentes acharem os arquivos relevantes sem lê-los um por um.
• O gerenciador de MCP, cujo teste de conexão mostra um custo aproximado em tokens por ferramenta.

Mesmo assim, vale aprender /context, /compact e /clear por conta própria. Eles funcionam do mesmo jeito com ou sem o AgentVera.