📝 O que é contexto
O contexto é tudo que o modelo sabe no momento: sua mensagem, a conversa anterior, os arquivos que o agente leu, os resultados das ferramentas. É a "memória de trabalho" ativa da sessão — e tem limite.
📝 O que entra no contexto
- •System prompt: instruções internas do Claude Code (~2K tokens, fixo)
- •CLAUDE.md: suas instruções personalizadas do projeto (você controla)
- •Histórico: toda a conversa desde o início da sessão
- •Tool results: conteúdo de cada arquivo lido, saída de cada Bash
🔢 O que são tokens
Tokens são a unidade mínima de texto que modelos de linguagem processam. Não são exatamente palavras, nem letras — são fragmentos de texto que o tokenizer divide com base em frequência na língua.
📊 Referência de tokens
- 1 palavra em inglês ≈ 1.3 tokens
- 1 palavra em pt-BR ≈ 1.5-2 tokens
- 100 linhas de código ≈ 800-1.200 tokens
- 1 página A4 de texto ≈ 500-700 tokens
- arquivo de 1KB ≈ 250-400 tokens
- arquivo de 10KB ≈ 2.500-4.000 tokens
- arquivo de 100KB ≈ 25.000-40.000 tokens
- CLAUDE.md típico ≈ 500-2.000 tokens
✓ Token eficiente
- ✓Código em inglês/símbolos
- ✓Texto conciso e direto
- ✓Código sem comentários longos
- ✓JSON sem espaços extras
✗ Gasta muitos tokens
- ✗Copiar arquivos inteiros na mensagem
- ✗Textos em idiomas com palavras longas
- ✗Repetir o mesmo conteúdo várias vezes
- ✗Respostas verbosas do agente
🪟 Janela de contexto
A janela de contexto é o limite máximo de tokens que o modelo pode processar de uma vez. É como a RAM do computador — rápida, mas finita. O Claude 3 Sonnet tem 200K tokens.
🪟 200.000 tokens em perspectiva
Parece muito. E é — mas enche rápido em sessões longas com muita leitura de código.
- •≈ 500 páginas de texto denso
- •≈ 20.000 linhas de código
- •≈ 40-60 arquivos de código médios
Com uma sessão longa, você pode consumir isso em:
- ⚠️1 arquivo de 500KB lido = 125K tokens
- ⚠️10 arquivos de 50KB = mesma coisa
- ⚠️Sessão de 2h com muito debug = cheio
💡 Dica: Quando o contexto está cheio
Sintomas de janela quase cheia: o agente começa a "esquecer" instruções do início, faz coisas que você já disse para não fazer, ou as respostas ficam mais genéricas. Use /compact ou /clear.
📈 Por que o contexto enche
A janela não enche aleatoriamente. Há culpados comuns que consomem tokens desproporcionalmente — e identificá-los permite agir antes de perder contexto crítico.
Arquivos grandes lidos inteiros
Um arquivo de 500KB consome ~125K tokens — mais da metade da janela. O agente lê mais do que precisa quando não há instruções específicas.
Histórico de conversa longo
Cada mensagem fica no contexto. Uma sessão de 2h com muitas trocas acumula facilmente 30-50K tokens só no histórico.
Muitas tool calls com saída longa
Cada Bash(npm install) com output longo vai direto para o contexto. Logs de 10K linhas são comuns.
Respostas verbosas do agente
O agente explica cada passo em detalhes? Isso também enche o contexto. Configure no CLAUDE.md: "seja conciso nas respostas".
🗜️ Compactação de contexto
O Claude Code tem mecanismos para lidar com contextos cheios: o comando /compact (manual) e a compactação automática que acontece quando a janela está quase cheia.
✓ /compact — quando usar
- ✓Após resolver uma feature completa
- ✓Quando o histórico ficou muito longo
- ✓Antes de iniciar uma nova subtarefa
- ✓Quando perceber degradação de qualidade
✗ Cuidado com /compact
- ✗Detalhe de erros anteriores pode ser perdido
- ✗Não use no meio de uma tarefa crítica
- ✗O resumo pode perder nuances importantes
- ✗Alguns contextos são melhores mantidos íntegros
⌨️ Comandos de gestão de contexto
💡 Boas práticas de contexto
Gerir o contexto bem é uma das habilidades que mais diferencia usuários avançados de iniciantes. Algumas regras simples têm impacto enorme na qualidade e custo das sessões.
📋 As 5 regras de ouro do contexto
- 1.Sessões curtas e focadas: uma sessão por feature/bug, não por dia
- 2.CLAUDE.md para contexto fixo: stack, regras de código, convenções do projeto
- 3.Não cole código nas mensagens: diga "edite o arquivo X" em vez de copiar o conteúdo
- 4./compact proativo: use antes de começar uma nova tarefa, não quando a janela já está cheia
- 5.Peça concisão: inclua no CLAUDE.md "seja direto e conciso nas respostas"
💡 O CLAUDE.md perfeito para economizar contexto
Um bom CLAUDE.md tem 3 seções: (1) Contexto do projeto — tecnologias, estrutura, arquitetura; (2) Regras de código — estilo, convenções, padrões; (3) Instruções de sessão — "seja conciso", "pergunte antes de criar arquivos".
Isso elimina a necessidade de repetir o contexto em cada sessão e o agente começa produtivo imediatamente.
✅ Resumo do Módulo 1.3
Próximo Módulo:
1.4 — Terminal e CLI para iniciantes: do zero ao terminal em 40 minutos, incluindo os comandos que o Claude Code mais usa.