Gestão de Contexto: Não deixe que ele sofra de "amnésia" nem queime seus tokens
📚 Navegação da Série: O artigo anterior 18 Guia do CLAUDE.md ensinou como colocar as regras do projeto naquele "manual de integração". Este artigo vai um nível acima — este manual, juntamente com suas conversas e os arquivos lidos, fica todo espremido em uma bancada de trabalho chamada "janela de contexto". Como gerenciar essa bancada e evitar que ela transborde é o tema de hoje.
Quando você começa a usar o Claude Code, é muito fácil cometer um erro bobo.
Ao assumir um projeto de médio porte desconhecido, pensando "vou fazer ele ler o repositório inteiro primeiro para que ele entenda o quadro geral antes de agir", você joga a seguinte frase: "Leia todos os arquivos deste projeto e depois me diga qual é a arquitetura."
O resultado? Ele realmente lê arquivo por arquivo, a tela do terminal rola sem parar, e depois de ler uns vinte arquivos, ele fica visivelmente mais lento e letárgico. Quando você começa a pedir para ele corrigir um bug de login, ele surpreendentemente pergunta "em qual arquivo está esse módulo de auth que você mencionou" — um arquivo que ele leu há apenas dez minutos. O trabalho não terminou, mas ele já teve "amnésia", e uma montanha de tokens foi queimada.
Depois de entender como funciona, você percebe: a janela de contexto não é melhor quanto mais cheia; quando fica cheia, ela o deixa mais estúpido. Hoje vamos explicar detalhadamente essa "bancada de trabalho" — o que ela é, o que acontece quando enche, como usar /compact e /clear para limpar, como verificar o uso em tempo real e como economizar tokens desde a origem.
Após ler este artigo, você terá:
- Uma analogia para entender perfeitamente o que é a "janela de contexto" e o que realmente acontece quando ela fica cheia
- Uma tabela clara sobre quando usar
/compact(comprimir),/clear(limpar) ou abrir uma nova sessão - Como usar
/contexte/usagepara ficar de olho na ocupação específica das ações + saída esperada - Cinco hábitos diários para economizar tokens, cada um vindo de tropeços reais
- Um entendimento de como a "compressão automática" (auto-compact) funciona nos bastidores, para não se assustar quando for interrompido repentinamente
01 Janela de Contexto: Qual é o tamanho da "bancada" do Claude?
Primeiro, vamos estabelecer o conceito central.
Janela de contexto (context window) — é a capacidade total de todo o conteúdo que o Claude pode "ver" simultaneamente nesta sessão, medido em tokens (a menor unidade de cobrança de processamento de texto do modelo).
O que ela guarda não é apenas o que você digita, mas todo um amontoado de coisas. O documento oficial context-window.md destrincha isso claramente, vou traduzir para humanos:
| O que entra na bancada | Quando entra | Quanto ocupa |
|---|---|---|
| Prompt do sistema (regras de comportamento do Claude) | A cada inicialização, você não vê | Uma parte fixa |
| Seu CLAUDE.md (global + projeto) | Carregado integralmente na inicialização | Depende do tamanho do arquivo |
| Memória automática (auto memory) | Carregada na inicialização (tem um limite) | Médio |
| Cada frase que você digita | Você envia, ela entra | Geralmente muito pouco |
| Cada arquivo que ele lê | Ele anexa a cada leitura | A maior parte, queima mais rápido |
| Saídas de comandos, resultados de ferramentas | Anexado após a chamada da ferramenta | Logs / Arquivos grandes são muito rápidos |
Entendeu? Você pensa que a conversa é principalmente "o que você fala", mas a maior parte são os arquivos que ele lê e as saídas de comandos. Naquela vez que você mandou ele ler vinte arquivos, foi como se você enchesse a bancada dele de plantas de engenharia, sobrando pouquíssimo espaço vazio para o "trabalho real".
Analogia: O tamanho de uma bancada de trabalho. Pense no Claude como um carpinteiro trabalhando em uma bancada. A bancada tem um tamanho fixo, as plantas, as ferramentas, as peças semi-acabadas, os post-its que você passa para ele, tudo tem que ser espalhado ali. Uma bancada grande permite que ele cuide de muitas coisas simultaneamente; mas, se a bancada ficar lotada, ele terá que empurrar as plantas mais antigas para o lado — as informações naquelas plantas, ele "esquece".
Qual o tamanho dessa bancada? Depende do modelo que você usa. A maioria dos modelos está na faixa de 200 mil tokens, enquanto alguns modelos (como aqueles com o identificador [1m]) chegam a 1 milhão. Mas lembrar-se desta frase é mais útil do que números:
A bancada, por maior que seja, tem limites; quanto mais cheia, mais bobo ele fica.
💡 Resumo em uma frase: A janela de contexto é a bancada de trabalho do Claude, o volume maior consiste nos arquivos que ele lê e não no que você fala; a bancada tem limites, e quando enche, ele começa a "deixar cair" as informações anteriores.
02 O que acontece quando a bancada enche: Ele fica mais lento, mais burro, e até tem "amnésia"
Este é o julgamento mais importante deste artigo: O contexto não é melhor quando está cheio; quando chega a um certo nível, o desempenho do Claude cai de forma perceptível a olho nu.
Por quê? Quanto mais coisas na bancada, mais fina a "atenção" do modelo se torna, e conteúdos irrelevantes anteriores começam a interferir na tarefa atual. A indústria chama esse fenômeno de "degradação do contexto" (context rot).
Como saber se está "degradando"? Resumi alguns sintomas da linha de frente, se acertar qualquer um, fique alerta:
- Ele começa a se contradizer, esquecendo a solução que vocês já tinham concordado
- As respostas ficam vagas e genéricas, com cada vez menos detalhes e muita conversa mole correta
- Ele repete perguntas que você já respondeu (como no início: "onde está o arquivo de auth?")
- Sobre a mesma pergunta, você o corrige duas vezes e ele continua girando em círculos
Por exemplo, ao escrever um script de migração de dados, após mais de uma hora de depuração, mais tarde ele lhe oferece novamente a solução incorreta que vocês rejeitaram na primeira meia hora. Não foi a capacidade dele que diminuiu, é que o contexto foi poluído por uma hora de lixo de depuração.
E o que o Claude faz se a bancada realmente ficar cheia? Ele irá comprimir automaticamente (auto-compact) — abordaremos em detalhes na Seção 05. Por agora apenas saiba: é uma ação defensiva passiva, o momento não depende de você, e ele pode interrompê-lo repentinamente no meio de uma tarefa crítica.
Então a postura correta é: não espere a compressão automática, gerencie de forma proativa. Como gerenciar? Continue lendo.
💡 Resumo em uma frase: Encher o contexto desencadeia a "degradação do contexto" — contradições, generalizações, perguntas repetidas; em vez de ficar corrigindo numa bancada poluída, é melhor limpar ativamente.
03 Duas Vassouras: /compact (comprimir) vs /clear (limpar)
Para arrumar a bancada, o Claude Code lhe dá duas vassouras, seus propósitos são completamente diferentes, jamais confunda.
/compact: "Empacota e esmaga" as coisas na bancada, mas mantém
A função do /compact (comprimir) é: pegar todo este longo histórico de conversa, resumi-lo numa síntese curta, e depois substituir o registro literal por este resumo, continuando a trabalhar na mesma tarefa.
Analogia: Transformar uma mesa cheia de rascunhos numa página de pontos principais. Você discutiu com um colega por duas horas, a mesa cheia de desenhos falhos. /compact pega toda essa rascunhada e faz uma página dizendo: "Decidimos A, vetamos B, o próximo passo é C". A mesa está limpa, mas a conclusão continua lá.
Ponto chave: ele permite que você dê instruções indicando o que manter como prioridade:
/compact Mantenha as decisões de arquitetura do fluxo de autenticação e os formatos de API já confirmados, descarte as tentativas inválidas da depuraçãoO exemplo em inglês do costs.md oficial é /compact Focus on code samples and API usage (Foque em exemplos de código e uso de API), é a mesma ideia.
Quando usar /compact: Quando a tarefa não terminou, mas o contexto está quase cheio e o que foi conversado antes será necessário depois. Por exemplo, no meio de uma funcionalidade, as decisões de arquitetura iniciais não podem ser perdidas, mas as saídas de comandos das tentativas e erros no meio do caminho podem ser jogadas fora.
/clear: Limpa tudo, começa do zero
O /clear (limpar) é mais drástico: apaga o histórico da conversa inteira, como se iniciasse uma sessão completamente nova.
Mas não se preocupe — o /clear não mexe no seu CLAUDE.md nem na memória automática, os dois carregarão automaticamente na nova sessão. O que você perde é apenas "o que foi falado nesta sessão"; as regras do projeto e as memórias de longo prazo permanecem intactas.
Analogia: Ao mudar para uma tarefa totalmente nova, é melhor limpar a mesa antes de começar a trabalhar. A tarefa anterior terminou, a próxima não tem relação alguma com a anterior, então limpar a mesa é mais limpo do que manter a interferência da tarefa passada.
O próprio costs.md oficial aconselha: Quando mudar para um trabalho não relacionado, use /clear para recomeçar, pois "o contexto obsoleto gasta tokens em cada mensagem subsequente".
Aqui tem uma regra de ouro que vale a pena estabelecer: Se você corrigiu o mesmo problema duas vezes e ele ainda não acertou, não perca mais tempo nesta sessão, use logo o /clear, e, com as lições dessas duas tentativas, reescreva um prompt mais preciso e pergunte do zero. Uma bancada limpa + um prompt melhor, quase sempre superam a insistência num contexto poluído — esta é a dica mais valiosa dos testes práticos.
💡 Resumo em uma frase:
/compacté "empacotar e esmagar para continuar usando",/clearé "limpar tudo e recomeçar numa nova tarefa"; corrigiu duas vezes e ainda errou, não hesite:/clear.
04 Monitorando o uso: Use /context e /usage para ver quanto resta da bancada
Julgar por instinto "se está quase cheio" é muito abstrato. O Claude Code fornece dois comandos para você ver os números reais; não misture os nomes.
/context: Veja o que está enchendo a bancada
/context/context vai visualizar a ocupação em tempo real do contexto atual através de um gráfico de grade colorido, e listá-la por categoria — quanto o prompt do sistema ocupa, quanto o CLAUDE.md ocupa, quanto cada serviço MCP ocupa, quanto o histórico da conversa ocupa, e ainda fornecerá sugestões de otimização. A documentação oficial context-window.md é clara: Se quiser saber o uso real do seu contexto a qualquer momento, execute /context.
Um hábito válido a se criar: Dê uma olhada no /context para conferir a base antes de iniciar uma grande tarefa. Se você descobrir que um serviço MCP está ocupando um grande espaço à toa, ou que o CLAUDE.md está bizarramente inchado, limpe isso antes de trabalhar.
Tem também um comando complementar
/memory, usado para verificar exatamente quais arquivos CLAUDE.md e de memória automática foram carregados na inicialização — use-o quando suspeitar que ele "lembrou errado" de algo.
/usage: Veja quantos tokens / dólares essa sessão queimou
/usageO bloco Session no topo do /usage fornece as estatísticas de uso de token da sessão atual, convertidas em dólares segundo uma estimativa local. A aparência mostrada no costs.md oficial é mais ou menos assim:
Total cost: $0.55
Total duration (API): 6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes: 0 lines added, 0 lines removedExplicação da saída esperada: Total cost é o custo estimado desta sessão (calculado localmente, podendo divergir da fatura real; o número autoritativo é no Claude Console); Total duration (API) é o tempo gasto na invocação do modelo; Total duration (wall) é o tempo total em que a sessão esteve aberta.
⚠️ Aviso: O custo da sessão para usuários Pro / Max está incluído na assinatura, esse valor em dólares não tem relação direta com sua fatura, olhe só para ter noção da magnitude relativa. Abordamos planos e cobranças específicos no Artigo 06; este foca no token da perspectiva do "contexto".
Acha incômodo ter que digitar isso manualmente toda vez? A versão oficial permite que o uso do contexto permaneça fixado na barra de status (statusline), mantendo-o constantemente na tela. Veja o método de configuração no documento oficial de statusline, que não será detalhado aqui.
💡 Resumo em uma frase:
/contextvê "o que está ocupando a bancada",/usagevê "quantos tokens / dinheiro foram queimados nesta vez"; antes de começar grandes tarefas, olhe o/context.
05 Compressão automática (auto-compact): Ele vai se proteger, mas não conte com isso
Mencionamos "compressão automática" várias vezes, vamos esclarecer o que é.
auto-compact (compressão automática) — é o mecanismo de proteção integrado do Claude Code: quando o contexto se aproxima do limite da janela, ele resumirá automaticamente o histórico da conversa, abrindo espaço para continuar trabalhando, evitando que você dê de cara num erro. O documento oficial costs.md coloca-o junto ao prompt caching, como um dos dois meios do Claude Code de "otimizar automaticamente os custos".
Analogia: O descarregamento automático em uma esteira. A esteira está quase cheia, o sistema consolida e compacta o material antigo para evitar o travamento de toda a linha. Você não precisa fazer nada, é acionado automaticamente.
Parece atencioso, mas aconselho a não depender disso, por duas razões:
Primeiro, o momento de acionamento não depende de você. Pode ser que no meio de um passo crítico que você o colocou para fazer, a bancada encha e ele pare de repente para comprimir — seu ritmo é totalmente quebrado.
Segundo, a compressão automática é uma "compressão sem instruções". O momento em que ela é acionada é exatamente quando o contexto está mais cheio e o modelo mais lerdo. Neste momento ele mesmo decide o que descartar e o que guardar, e é bem provável que ele jogue fora algo que você acha importante.
Então, a atitude correta é agir proativamente: quando sentir que a conversa ficou longa, e o /context mostrar que o uso está alto, faça você o /compact primeiro e adicione instruções apontando as prioridades. A compressão ativa tem duas vantagens — o momento é você quem escolhe, o que guardar também é você quem escolhe.
E tem uma tática mais despreocupada ainda: escrever as preferências de compressão direto no CLAUDE.md. O costs.md recomenda adicionar este trecho:
# Compact instructions
When you are using compact, please focus on test output and code changes(Instruções de compressão: Quando usar a compressão, por favor foque na saída dos testes e mudanças no código)
Dessa forma em toda compressão (manual ou automática), ele priorizará o conteúdo que você estipulou, é como colocar um seguro na compressão automática. Por exemplo, em um projeto, adicione "Na compressão, mantenha as decisões da solução já aprovada e os contratos de API" no CLAUDE.md, poupando a necessidade de repetir isso toda hora.
💡 Resumo em uma frase: A compressão automática serve para salvar o processo, mas pode lhe interromper, e possivelmente suprimir pontos-chave; em vez de esperar por ela, é melhor intervir proativamente com
/compactseguido de instrução, ou definir as diretrizes no CLAUDE.md.
06 Cinco Dicas para Salvar Tokens: Como prevenir que a bancada lote logo de cara
Limpar a bancada é o conserto, evitar que ela encha rapidamente é a melhor estratégia. Estas cinco técnicas são úteis diariamente, e abordam sob a ótica do "contexto", independentemente da fatura.
Dica Um: Não treine com grandes projetos. Como falamos no Artigo 07 — na fase de testes, crie um projetinho de brinquedo com três a cinco arquivos. Poucos arquivos, ele lê menos, a bancada fica limpa, e você consegue enxergar o que ele faz. Aquela história do "ler vinte arquivos e ter amnésia" do começo, a raiz do problema é que de cara foi jogado um projeto médio e desconhecido para ele.
Dica Dois: Use @ apontando o arquivo exato, não o deixe zanzando à procura na base inteira. Em vez de dizer "corrija um bug no login" fazendo-o revirar arquivos, seja direto @src/api/auth.ts corrija o problema de 401. O documento costs.md afirma de modo explícito: pedidos amplos geram buscas genéricas, os pedidos exatos o levam direto ao ponto com a leitura mínima de arquivos. O @ fixa os olhos do Claude diretamente no arquivo.
Dica Três: Evite solicitar dezenas de tarefas ao mesmo tempo. Jogar cinco demandas de uma só vez não funciona, a vasta leitura de arquivos e geração de output rebentam a janela. Divida em cinco pequenas perguntas, complete-as em turnos, a mesa estará sempre refrescada.
Dica Quatro: Subdivida grandes tarefas e limpe ao finalizar cada etapa. Uma funcionalidade enorme não deve tentar durar de ponta a ponta na mesma sessão. Concluindo um bloco mais segmentado, engula tudo num /compact; partindo para outra área, jogue limpo com /clear.
Dica Cinco: Entregue as manipulações maçantes e enormes para subagentes (subagents). Rodar um bando de testes, esquadrinhar pilhas de logs, ler grandes documentações e retornar uma carga colossal de coisas — largue essas prazerosas atividades pros subagentes — o agente faz a bagunça na mesa dele, só traz os resultados destilados e precisos pra o seu bate-papo. O context-window.md ilustra que um subagente puxa 6100 tokens, e na janela principal só gasta 420. Há uma área própria no artigo dos subagentes pra lidar com isso (link será complementado).
Vamos ver a balança "Conserto" e "Prevenção", e você saberá onde concentrar forças:
| O que Fazer | Essência | Momento Certo |
|---|---|---|
/compact | Conserto · Esmiuçar pra continuar | Tarefa pendente, uso alto de Token, história no meio serve para algo |
/clear | Conserto · Zerar para mudar rumo | Assunto totalmente novo, ou poluição pesadíssima |
Fechar a sessão (sair e retornar claude) | Prevenção · Novo Recomeço Limpo | Zero rastro passado |
@ Foco Exato | Prevenção · Reduz Arquivos Gulosos | A principal prática de qualquer pedido a todo instante |
| Usar Projeto de Brinquedo | Prevenção · Minimizando Custo no Início | Fases Iniciais de Domínio e Teste |
| Delegar aos Subagentes | Prevenção · Isola a Imensa Saída Suja | Testes, varreduras de logs e leitura intensa de documentos longos |
💡 Resumo em uma frase: Limpar o prato é remediação, direcionar bem os arquivos, diminuir escopo de uma pergunta, jogar prum subagente, isso sim é profilático; A melhor memória muscular que você construirá aqui: Usar o
@pra mirar o arquivo-alvo, sem delongas.
07 Passo a Passo: Tres etapas para o controle de contexto
Sem ação, não dá para assimilar nada. Use a linha mestra a seguir, no mais singelo projeto, a fim de observar de pertinho como ele consome token e com o /compact amassa os dados de volta. Numa pasta de sua escolha rode claude. Siga isso:
Passo Um: Examine o quadro inicial
Aberto o Claude, comece com isto:
/contextO Esperado: Será despejada no terminal uma avaliação analítica — verás o prompt de sistema e os dados CLAUDE.md pegando algum espacinho (ter algum gasto de token antes de iniciar uma conversa, é totalmente aceitável e rotineiro), mais sugestões no rodapé. Guarde esse montante inicial do Total Use.
Passo Dois: Propositalmente "Encha-o" e verifique a diferença
Mande ele revirar os arquivos e responder a um monte de coisa. Algo do tipo:
Dê uma lida atenta aos arquivos centrais deste projeto, e resuma para mim a estruturaAo findar toda a leitura e apresentar as respostas, invoque isto de novo:
/contextO Esperado: A ocupação da janela explodiu de verdade, histórico do bate-papo e o custo na seção dos arquivos aumentaram imenso. Esse é o tal do "pico", onde ele abarrota o contexto — eis ali os números.
Passo Três: Use o /compact para empurrá-lo de volta
/compact Concentre o contexto somente na conclusão geral de como a arquitetura do projeto está desenhada, jogue as análises arquivo-a-arquivo originais pela janela.O Esperado: Surgirá "Conversation compacted" ou a indicação de comprimido. É executado no plano de fundo de modo silencioso e sem relatórios quilométricos em tela. Depois lance logo em seguida outro /context, e as colunas de histórico do chat despencarão o seu custo. A compreensão da estrutura ele reteve; os textos literais que lhe deu nos arquivos ele torceu de volta.
Controle Empírico: Jogue o /context antes e depois, observe a flutuação. Havendo sucesso, se perguntar por que estrutura ele respondeu previamente, ele te provará que nada esqueceu.
⚠️ Atenção a este ponto: O Compactar é "Losty", perde partes no caminho, há descarte irreversível de conteúdos não demarcados por você (como retornos puros de ferramentas). As peças de mais elevado calibre? Passe tudo lá para o seu CLAUDE.md conforme vimos no Artigo 18, jogando para que ele "junte a diretriz ao CLAUDE.md", ou então com a mão, usando
/memory. Muito mais certeiro.
💡 Resumo em uma frase: Jogue um
/context→ Entregue conteúdo →/compact→ Lance/context, vês assim o balão inflando de tokens e se desinflando aos seus comandos.
08 Conclusão
Este tópico abriu a caixa para examinarmos de fora a dentro o "Mundo da Janela de Contexto" da bancada do Claude:
| O que você Fixou | Sumário |
|---|---|
| Janela de Contexto O que é | A Mesa-bancada, arquivos carregados nela valem 10x mais pesos que o próprio bate-papo |
| Carga Lotação Extrema | Eleva ao grau de deterioração: Lento, genérico, falha-de-memória das pontas passadas e repetidor assíduo |
/compact | Fio-terra de resumir os pedaços velhos na hora de necessidade com direções focais |
/clear | Zera total e limpa pra mudar percurso, ele guarda os seus setups do CLAUDE.md ilesos |
/context e /usage | O de cima mira: O Que ocupa espaço |
| Auto-compact (Automático) | Salvaguarda contra esgotamento final; jogue ativamente e crie prioridades. Seu acionamento a esmo apaga pontas vitais. |
| Cinco dicas | Minimiza projetos de treino / Ferramente o @ para evitar buscas vagas / Desfaleça os trabalhos titânicos / Transborda e delega em subagentes! |
Tudo o que se necessita saber de antemão agora é teu: Ter um faro visual do que ocupa peso, notar quando ele decai devido a poluição mental da janela, lançar a "compressão e o expurgo" nas melhores brechas com /compact e /clear, varrer os gastos por /usage, mas principalmente; Nunca, e jamais saturar e abarrota as mãos dele sem necessidade e não focar, poupando os canais por prevenção e precisão, para deixar o espaço de tela focado no serviço central.
Numa simples lição resumida, Administrar essa mesa se consagra em algo: Focar e gastar o olhar curto e estreito do Claude em algo que verdadeiramente te dá resposta, sem ser sugado pelas baboseiras laterais e sucatas irrelevantes no passado imediato.
Este diagrama representa a Janela de Contexto ilustrativamente como a bancada: Empanturrado aos 92% pelas conversas passadas e aberturas repetidas, ele se livra ao agir de /compact (comprimindo 10 fls numa conclusão folha-única, para rodar) ou pela guilhotina do /clear que desaloja todas as peças e cria área ampla. Um assegura as chaves, o outro a assepsia completa do terreno!
Próximo Capítulo — 20 · Configuração de Permissões — Até aqui mantivemos o foco no nível "A Memória - Seu peso"; Chega de memória e foco cognitivo! A Lição vai incidir e apertar os freios na autonomia da Ação e a sua Periculosidade de Acesso. "Posso alterar isto? Devo ler aquele sistema vital?". Vamos ditar quando e em qual proporção do fluxo, tu irás travar ele exigindo o teu Ok e Permitir. A Grande pergunta antes: Você suportaria confiar o Git Push diretamente ao toque robótico na sua própria Codebase na ausência total da tua concordância?