Uma hora de trabalho numa tarefa, e o agente de repente sugere uma opção que o(a) senhor(a) recusou meia hora atrás. Ou recapitula um arquivo que já foi corrigido à mão. Parece esquecimento, mas na verdade é assim que o trabalho funciona: o agente olha para uma janela de tamanho limitado e ali não enxerga o projeto inteiro, só o que entrou nessa janela.
Vamos ver o que ocupa a janela, como consultá-la com o comando /context e o que fazer quando quase não sobra espaço livre.
O contexto e o seu limite
Contexto é a informação disponível para o modelo no próximo passo: as mensagens do(a) senhor(a), as respostas do agente, o código já lido, a saída de comandos, as instruções do projeto. A janela de contexto define o limite de quanto disso cabe ao mesmo tempo. Não é espaço livre em disco nem a memória RAM do seu computador.
Daí vem a distinção que mais costuma gerar confusão. Três coisas fáceis de confundir entre si:
- arquivos em disco - o conteúdo do projeto, que as ferramentas conseguem ler;
- o histórico salvo da sessão - o registro da conversa, que fica em disco e pode ser reaberto;
- o contexto atual - o que está disponível para o modelo agora mesmo.
Os conjuntos estão relacionados, mas não coincidem. Um arquivo pode estar numa pasta e nunca entrar na conversa. E a conversa pode manter a versão de um arquivo de meia hora atrás. Por isso a frase "mas a gente já discutiu isso" não significa, por si só, que o agente está com a informação atualizada.
- Arquivo do projeto
- Leitura por uma ferramenta
- Informação para a resposta
Entre o arquivo existir e o agente saber dele, há um passo de leitura. O Claude Code dá esse passo sozinho: faz buscas no projeto, abre o que precisa, passa para o código relacionado. Não é preciso listar cada caminho de antemão. Mas enquanto esse passo não acontece, o arquivo não existe para a conversa.
Tudo isso é medido em tokens - os pedaços de texto em que o modelo divide tanto o seu pedido quanto o código lido. Um token pode ser uma palavra inteira ou só parte dela, então contar tokens pelo número de palavras não funciona.
O que ocupa a janela antes da primeira pergunta
A janela já está ocupada antes mesmo de o(a) senhor(a) digitar a primeira palavra. O comando /context mostra exatamente o quê:
A sessão mal começou e 4k de 200k tokens já estão ocupados, só com overhead: System prompt são as instruções do próprio agente, Memory files são o CLAUDE.md e as regras do projeto já carregados, Skills é a lista de skills disponíveis. A linha Messages, ou seja, a conversa em si, ainda está vazia.
E veja como fica o quadro depois de uma hora de trabalho, ainda com um par de servidores MCP conectados:
/context
System prompt 3.2k ( 2%) instruções básicas do agente
System tools 12.1k ( 6%) descrições das ferramentas embutidas
MCP tools 21.4k (11%) servidores externos conectados
Memory files 1.8k ( 1%) CLAUDE.md, rules, auto memory
Messages 45.2k (22%) sua conversa, arquivos, logs
Free space 116.3k (58%)Isso é um esquema, não a saída de uma versão específica: o conjunto de linhas e o layout na tela dependem da versão do Claude Code e do que está conectado no projeto, e o tamanho da janela depende do modelo. Mas o quadro é sempre mais ou menos o mesmo, e dele saem conclusões práticas:
- o mínimo obrigatório - as instruções do agente e as descrições das suas ferramentas embutidas - está sempre lá, e o(a) senhor(a) não tem controle sobre isso;
- cada servidor MCP conectado acrescenta à janela pelo menos a lista das suas ferramentas, mesmo que nunca sejam usadas. Conectar um servidor "por via das dúvidas" significa pagar por ele em cada sessão;
- um
CLAUDE.mdque cresceu demais também é pago de novo a cada início. Mais um motivo para mantê-lo curto; - ao longo do trabalho, cresce basicamente uma linha - a de mensagens. É ela que vale a pena acompanhar.
Se o Claude Code estiver à mão: rode /context, peça ao agente para ler um par de arquivos e rode de novo. A linha de mensagens vai crescer na hora, e vai ficar claro quanto custa uma única leitura.
O que se acumula ao longo do trabalho
Dali em diante é o(a) senhor(a) que preenche a janela - e não só com palavras. Tudo que o agente lê e recebe a seu pedido entra no contexto:
| Fonte | O que exatamente ocupa espaço |
|---|---|
| A conversa | suas mensagens, as respostas do agente, inclusive as opções recusadas |
| Arquivos lidos | o conteúdo inteiro ou só os trechos necessários |
| Resultados de ferramentas | a saída de um comando, as linhas encontradas, observações do navegador |
| Material de skills e MCP | a instrução de uma skill que entrou em ação, a descrição de uma ferramenta chamada |
O pedido e o contexto que ele traz de volta são duas grandezas bem diferentes. "Mostre o log inteiro" tem quatro palavras, e o resultado chega a milhares de linhas. É justamente por isso que uma saída grande pode prejudicar mais do que uma pergunta longa.
Daí o hábito de entregar as fontes de forma pontual. O símbolo @ antes de um caminho traz o arquivo para a conversa, e o autocompletar funciona enquanto o(a) senhor(a) digita o caminho: Leia @src/reward-flow.js e explique onde o número de pontos é definido. Mencionar uma pasta com @ também não deve ser interpretado como carregar o conteúdo de todos os arquivos dela: a referência a uma pasta dá uma lista de arquivos. Escolha a fonte de acordo com a pergunta. É exatamente essa distinção entre referenciar um arquivo e referenciar uma pasta que a documentação sobre como passar arquivos descreve.
Mais um detalhe pequeno. Se depois disso o(a) senhor(a) trocar dez por vinte manualmente, a resposta anterior não se atualiza sozinha. Peça ao agente para ler o conteúdo atual antes de tirar uma nova conclusão. Uma referência a um arquivo lido uma vez não transforma o texto antigo da conversa numa cópia viva do arquivo em disco.
Quando o espaço acaba
A janela não é elástica, mas a sessão também não é interrompida no meio de uma frase. À medida que a janela vai enchendo, o Claude Code executa uma compactação: substitui o histórico detalhado por um resumo e libera espaço. Isso acontece automaticamente, e o momento depende do modelo e das configurações.
O(a) senhor(a) também pode iniciar a compactação por conta própria, com o comando /compact. A vantagem de fazer isso manualmente é que o(a) senhor(a) escolhe o momento - por exemplo, antes de um bloco grande de trabalho novo - e pode dizer o que é importante manter:
/compact Mantenha o objetivo da tarefa e os limites da edição,
a opção rejeitada com um handler separado
e o próximo passo: verificar a limpeza do campo de busca.O principal sobre a compactação: o que fica na janela é um resumo, não a conversa. Um detalhe que não entrou no resumo saiu da janela, e discutir "mas você concordou com isso vinte minutos atrás" depois de uma compactação não leva a lugar nenhum - é mais fácil resgatar o fato de novo a partir do arquivo. As instruções do projeto, porém, não se perdem: o CLAUDE.md raiz é carregado de novo.
O segundo comando, /clear, não compacta nada. Ele abre uma nova conversa: a anterior continua salva e acessível via /resume, os arquivos do projeto não mudam, e as instruções do projeto são carregadas normalmente.
| Comando | O que faz | Quando escolher |
|---|---|---|
/context | mostra o que está ocupando a janela | não está claro para onde foi o espaço |
/compact | reduz o histórico a um resumo | a tarefa é a mesma, mas o histórico já cresceu muito |
/clear | recomeça a conversa | a tarefa mudou |
A regra de escolha é simples: mesma tarefa - compacte; tarefa diferente - abra uma nova conversa. Não é preciso limpar depois de cada comando: enquanto o(a) senhor(a) está resolvendo um único problema, as observações e os ajustes dele continuam trabalhando a seu favor. Mas antes de um novo tema vale anotar a conclusão necessária em poucas linhas: "a recompensa é definida em src/reward-config.js e concedida em src/reward-flow.js". É uma pista de para onde voltar, sem reescrever a conversa inteira.
Como gastar a janela com mais economia
Nenhum dos três comandos vai ser tão necessário se a janela não se encher de coisa desnecessária desde o início. Alguns hábitos que fazem a maior diferença:
- Pergunte de forma específica. Diante de um pedido vago, o agente sai explorando: lê arquivos desnecessários, testa várias opções. Indicar o arquivo e dizer o que se espera economiza espaço e tempo.
- Não despeje tudo de uma vez. Uma pergunta sobre um teste que falhou precisa das linhas ao redor do erro, não do log inteiro.
- Mantenha as instruções do projeto curtas. O
CLAUDE.mdé carregado em cada sessão. Material de referência extenso vive melhor em arquivos separados, lidos só quando necessário. - Desligue servidores MCP desnecessários. Um servidor conectado "por via das dúvidas" ocupa espaço em cada início, e o retorno é zero.
- Delegue investigações grandes a um subagente. Ele trabalha na própria janela e devolve um resumo, enquanto as dezenas de arquivos lidos ficam com ele.
O que ter em mente
Contexto é o que o(a) senhor(a) colocou na mesa, não o que "existe no projeto". Um arquivo em disco, um registro no histórico e a informação na janela atual são três coisas diferentes, e a confusão entre elas explica boa parte das respostas estranhas.
A partir daí tudo se resume a três ações: ver o quanto a janela está cheia com /context, entregar a fonte necessária com @ e decidir a tempo se é melhor compactar a conversa ou começar uma nova. Escolha conforme a situação - uma compactação não substitui a leitura do arquivo necessário, e um arquivo entregue não verifica o raciocínio do agente no seu lugar.
GO TO FULL VERSION