Gerenciamento de contexto no Claude Code: /context, /compact, CLAUDE.md e Obsidian

Você começa uma sessão do Claude Code com uma tarefa clara. Uma hora depois, o Claude relê arquivos que já examinou, retoma uma decisão descartada ou segue uma instrução antiga em vez da correção mais recente. Para quem está começando, parece que o modelo ficou menos capaz no meio do trabalho.

Na maioria das vezes, o problema é uma janela de contexto congestionada. Conversa, conteúdo de arquivos, saída de comandos, regras do projeto e respostas do próprio Claude dividem um espaço de trabalho limitado. Quando tentativas antigas e logs enormes ocupam esse espaço, os fatos úteis para a próxima decisão perdem destaque.

Gerenciar contexto não é apenas economizar tokens. É decidir o que o Claude precisa agora, o que deve virar orientação permanente do projeto, o que pode ser resumido e quando a conversa atual já deveria terminar. Este guia apresenta um fluxo prático mesmo para quem ainda não conhece termos como janela de contexto ou memória automática.

Decisões essenciais em poucos minutos

• Rode /context para descobrir o que ocupa a janela atual antes de culpar o modelo ou reiniciar tudo.
• Use /compact quando a tarefa continua a mesma, mas a pesquisa, os arquivos e os logs deixaram a conversa grande demais.
• Use /clear ao mudar para uma tarefa sem relação com a anterior. A conversa antiga continua salva e pode ser retomada.
• Use /memory para consultar e editar instruções persistentes e a memória automática. Para confirmar quais arquivos foram carregados, use /context.
• Use /usage para ver custo da sessão, limites do plano e atividade. /cost é um alias; /stats também encaminha para /usage e abre a aba de estatísticas.
• Antes de compactar ou entregar o trabalho, registre a decisão vigente, os arquivos alterados e o próximo comando de verificação.

A janela de contexto é a bancada de trabalho atual

A janela de contexto reúne as informações que o Claude consegue considerar no turno atual. Uma bancada organizada pode ter a tarefa, dois arquivos relevantes, uma mensagem de erro curta e o critério de aceite. Uma bancada lotada contém abordagens abandonadas, logs completos de build, leituras duplicadas e regras contraditórias.

O espaço não é ocupado apenas pelo texto visível na conversa:

Fonte	Como vira ruído	Hábito mais seguro
Histórico da conversa	Perguntas paralelas e decisões superadas permanecem	Separar tarefas independentes e registrar a decisão atual
Arquivos lidos	Diretórios inteiros ou arquivos gerados são carregados	Pesquisar primeiro e ler apenas arquivos ou trechos relevantes
Saída de ferramentas	Testes repetidos e logs longos se acumulam	Guardar a causa e o resultado final, não todas as repetições
CLAUDE.md e regras	Instruções amplas ou duplicadas voltam em cada sessão	Manter regras globais curtas e mover procedimentos específicos
Skills e ferramentas	Capacidades habilitadas também consomem contexto	Manter apenas as capacidades necessárias para o trabalho

O Claude Code pode compactar automaticamente quando a janela se aproxima do limite. Isso evita que a sessão simplesmente pare, mas a compactação automática ainda precisa escolher o que preservar. Antes de uma mudança importante de fase, uma compactação manual com foco explícito oferece um resumo mais útil.

O que cada comando realmente faz

Os comandos parecem próximos, mas resolvem problemas diferentes. Digite cada um no início de uma mensagem em uma sessão interativa do Claude Code.

/context: inspecionar a ocupação atual

/context mostra o uso do contexto em uma grade colorida e apresenta sugestões quando ferramentas, arquivos de memória ou avisos de capacidade estão pesando. /context all exibe o detalhamento ampliado por item.

/context
/context all

Rode o comando no começo de uma tarefa longa, depois de uma investigação grande e antes de /compact. Ele não remove conteúdo. Serve para mostrar o que ocupa espaço e orientar quais fatos devem receber prioridade no resumo.

/compact [instruções]: resumir e continuar a mesma tarefa

/compact substitui o histórico da conversa por um resumo estruturado. O texto opcional depois do comando informa ao resumidor o que não pode perder destaque.

/compact preserve o contrato de API aprovado, os arquivos alterados, o teste que falha, os comandos já executados e a próxima ação

Use quando o objetivo não mudou. Por exemplo, você ainda está corrigindo o mesmo erro de autenticação, porém a investigação gerou uma conversa extensa. Não espere que o resumo preserve cada frase. Regras indispensáveis já devem estar no CLAUDE.md, em uma especificação ou em uma nota de passagem.

/clear [nome]: começar outra conversa

/clear abre uma conversa com histórico conversacional vazio. O nome opcional identifica a conversa anterior.

/clear correcao-auth-concluida

A memória do projeto volta a ser carregada na nova conversa. O trabalho anterior não é apagado: ele permanece salvo e pode ser reaberto com /resume, claude --resume ou claude --continue. Use /clear quando o próximo pedido tiver objetivo, arquivos e decisões realmente diferentes.

/memory: administrar orientações persistentes

/memory lista os locais de CLAUDE.md e CLAUDE.local.md, permite abrir ou criar esses arquivos, mostra entradas da memória automática e oferece o controle dessa memória. Ele responde: “Onde esta informação reutilizável deve ficar?”

/memory

O comando não comprova que todos os arquivos listados estão ativos na janela atual. Use /context e confira a área de arquivos de memória. O CLAUDE.md do projeto pode ser versionado e compartilhado pela equipe. Já a memória automática guarda informações locais do repositório, compartilhadas entre worktrees desse mesmo repositório, mas não entre computadores.

/usage, /cost e /stats: consultar consumo, não conteúdo

/usage apresenta custo da sessão, limites do plano e estatísticas de atividade. Em assinaturas compatíveis, também pode detalhar consumo por skills, subagentes, plugins e servidores MCP. /cost é um alias de /usage; /stats também é um alias e abre a aba de estatísticas.

/usage
/cost
/stats

Esses comandos respondem a uma pergunta diferente de /context. Uso mostra consumo e limites; contexto mostra o que ocupa a área de trabalho atual. Limpar ou compactar a conversa não desfaz o consumo que já ocorreu.

A decisão depois da inspeção pode ser resumida em uma pergunta:

flowchart TD
  A["Executar /context"] --> B{"A tarefa continua a mesma?"}
  B -->|Sim| C["/compact com foco"]
  B -->|Não| D["/clear e novo briefing"]

Se o objetivo e o critério de aceite continuam iguais, /compact libera espaço sem romper o trabalho. Quando começa uma tarefa independente, /clear evita que decisões antigas contaminem a nova conversa.

Defina um orçamento de contexto antes de começar

Evite iniciar com “leia o repositório inteiro e conserte tudo”. Entregue um briefing curto com objetivo, escopo, exclusões, condição de pronto e comandos de verificação.

## Briefing da tarefa
- Objetivo: Corrigir o loop de redirecionamento de sessões expiradas.
- Dentro do escopo: src/auth/, tests/auth/session.test.ts
- Fora do escopo: redesenho da interface e troca do provedor de identidade
- Pronto quando: sessões expiradas redirecionarem uma vez para /login e o teste de regressão passar
- Verificar com: npm test -- tests/auth/session.test.ts
- Aprovação humana necessária para: mudar a duração do cookie ou o comportamento público da API

Pesquise de forma estreita antes de carregar arquivos. Os comandos abaixo podem ser copiados e adaptados ao seu repositório:

rg -n "expired session|redirect loop|set-cookie" src tests
git diff --stat
git status --short
npm test -- tests/auth/session.test.ts

A ordem evita retrabalho. rg aponta os arquivos prováveis. git diff --stat e git status revelam alterações existentes que não podem ser sobrescritas. O teste focado cria uma linha de chegada verificável. Assim, o Claude recebe poucos artefatos relevantes em vez de uma cópia do projeto inteiro.

Deixe um recibo antes de compactar

Antes de /compact, /clear ou da passagem para outra sessão, escreva um recibo curto. Ele não é uma cópia da conversa. É o estado mínimo para outra pessoa ou agente continuar sem repetir a investigação.

## Recibo de passagem
- Objetivo:
- Diagnóstico atual:
- Decisões já aprovadas:
- Arquivos alterados:
- Comandos executados e resultados:
- Alterações não commitadas que devem ser preservadas:
- Risco restante:
- Próxima ação:

Salve o recibo em um documento do projeto quando ele precisar ser compartilhado. Outra opção é colar a versão preenchida como foco do /compact. Registre resultados, não saída bruta. “Teste falha em session.test.ts:84 porque produz dois redirecionamentos” orienta a continuação; duzentas linhas repetidas de stack trace não.

O que sobrevive à compactação

Depois de /compact, cada tipo de informação tem um comportamento diferente:

Mecanismo	Comportamento depois de /compact
Prompt de sistema e estilo de saída	Permanecem, pois não fazem parte do histórico da conversa
CLAUDE.md da raiz e regras sem filtro de caminho	São reinjetados a partir do disco
Memória automática	É reinjetada a partir do disco
Regras com paths: no frontmatter	Ficam ausentes até o Claude ler um arquivo correspondente
CLAUDE.md dentro de subdiretório	Fica ausente até a leitura de um arquivo daquele subdiretório
Conteúdo de skills invocadas	É reinjetado dentro dos limites individuais e totais documentados
Hooks	Continuam executando como código; não são contexto conversacional

A categoria frágil é a informação mencionada apenas no chat. Ela pode aparecer no resumo, mas um detalhe pequeno pode ser descartado. Se uma regra precisa valer sempre, coloque-a no CLAUDE.md da raiz ou em outro arquivo persistente adequado. Se a regra vale apenas para um caminho, mantenha o escopo, sabendo que ela só retorna depois da leitura de um arquivo compatível.

Também é possível orientar a compactação pelo CLAUDE.md:

# CLAUDE.md

## Instruções de compactação
- Preserve o objetivo atual, as decisões aprovadas e o que está fora do escopo.
- Preserve arquivos alterados, comandos de verificação, resultados de testes e bloqueios.
- Mantenha apenas linhas de log que expliquem a causa raiz.
- Preserve alterações não commitadas de outras pessoas e a próxima ação segura.

Mantenha esse trecho enxuto. O próprio CLAUDE.md ocupa contexto no início de cada conversa. Transformá-lo em um manual completo do projeto recria o problema que ele deveria evitar.

Responsabilidades do agente e limites de aprovação humana

O Claude pode pesquisar, comparar arquivos, reduzir logs, executar testes e registrar fatos observados. Decisões com consequências que não podem ser deduzidas com segurança continuam sob responsabilidade humana.

O Claude Code pode assumir	Uma pessoa precisa decidir
Encontrar arquivos relevantes e reduzir logs à causa raiz	Objetivo de negócio e compensações aceitáveis
Informar pressão de contexto e sugerir compactação	Se duas tarefas realmente pertencem à mesma conversa
Criar um recibo a partir do trabalho observado	Operações destrutivas, uso de credenciais e mudanças em produção
Executar os comandos de verificação combinados	Mudanças em política de segurança, comportamento público ou retenção de dados
Atualizar uma regra depois de aprovação explícita	Resolver exigências contraditórias de diferentes responsáveis

Não peça ao agente para decidir sozinho o que nunca pode ser perdido e deixe essa decisão apenas no chat congestionado. A pessoa define as restrições duráveis; o agente registra no local acordado e confirma que elas foram carregadas.

Quatro casos de uso concretos

Caso de uso 1: refatoração de autenticação em vários arquivos

Cenário: A pesquisa envolve middleware, utilitários de cookie, testes de integração e configuração de deploy. Colocar todos os arquivos e todas as falhas na conversa prejudica a implementação.

Escopo do agente: Mapear o caminho da autenticação com busca, separar uma pesquisa documental extensa e devolver apenas o contrato escolhido, os arquivos-alvo e o teste focado para o contexto principal.

Aprovação humana: Duração do cookie, comportamento de logout e garantias de compatibilidade. Essas são decisões de produto e segurança.

Fluxo de trabalho: Escrever o briefing, rodar /context depois da investigação, registrar o desenho aprovado e compactar com foco antes de editar.

Caso de uso 2: diagnóstico de deploy com falha

Cenário: Várias tentativas produzem logs quase iguais. O primeiro erro causal fica escondido entre instalação de pacotes e avisos.

Escopo do agente: Comparar tentativas, isolar o primeiro erro causal e registrar ambiente e comando exato. Saída duplicada não precisa permanecer no resumo.

Aprovação humana: Alterar credenciais, configuração do provedor ou executar rollback. O agente pode diagnosticar, mas não deve ampliar acesso nem mudar política de produção sem autorização.

Caso de uso 3: criação e revisão de artigo técnico

Cenário: Pesquisa de fontes, regras editoriais, validação de código, notas de tradução e conferência visual lotam a conversa de escrita.

Escopo do agente: Manter fontes em uma nota de pesquisa, regras duráveis no CLAUDE.md e o artigo final no MDX. Levar ao contexto principal apenas fatos confirmados e dúvidas abertas.

Aprovação humana: Público, promessa comercial e CTA principal. O agente pode melhorar a redação, mas não pode inventar experiências pessoais, métricas ou resultados de clientes.

Caso de uso 4: trocar uma correção por um novo recurso

Cenário: O bug foi corrigido, mas o próximo pedido no mesmo terminal é um painel sem relação com ele.

Escopo do agente: Informar o diff final e o resultado do teste, depois sugerir uma fronteira limpa.

Aprovação humana: Confirmar que nenhuma pendência da correção pertence ao novo trabalho. Em seguida, usar /clear correcao-concluida. Se algum detalhe antigo voltar a ser necessário, reabrir a conversa com /resume.

Armadilhas concretas e como corrigir

Armadilha 1: tratar /compact como memória perfeita

O resumo é seletivo. Uma restrição citada uma única vez pode desaparecer.

Correção: Colocar regras duráveis no CLAUDE.md ou em uma especificação e registrar decisões aprovadas no recibo antes de compactar.

Armadilha 2: usar /clear durante uma tarefa ativa

Limpar cedo demais remove o conjunto de trabalho atual. A equipe pode gastar tempo reconstruindo o mesmo diagnóstico.

Correção: Se objetivo e teste de aceite continuam iguais, compacte com foco. Limpe apenas quando a fronteira da tarefa for real.

Armadilha 3: achar que /memory prova o que foi carregado

Arquivos aninhados e regras por caminho podem ainda não estar ativos depois de uma compactação.

Correção: Rode /context, confira os arquivos de memória e leia um arquivo correspondente quando uma regra restrita precisar voltar.

Armadilha 4: colocar barreiras de segurança apenas no CLAUDE.md

CLAUDE.md é orientação contextual, não bloqueio técnico rígido. Instruções vagas ou conflitantes podem ser aplicadas de modo inconsistente.

Correção: Use permissões e hooks para impedir ou validar ações que exigem garantia. Reserve o CLAUDE.md para regras curtas de trabalho.

Armadilha 5: usar a memória automática como documentação de equipe

A memória automática é local. Ela é compartilhada entre worktrees do mesmo repositório, mas não chega automaticamente aos computadores de colegas ou a ambientes na nuvem.

Correção: Mova convenções compartilhadas para CLAUDE.md versionado, regras ou documentos do projeto.

Armadilha 6: confundir consumo com contexto disponível

Uma sessão pode ter pouco contexto e já ter consumido bastante do plano. Também pode ter uma janela lotada antes de o custo parecer alto.

Correção: Use /context para decidir entre restringir, delegar, compactar ou limpar. Use /usage para acompanhar consumo e limites.

Como dividir informações entre CLAUDE.md, projeto e Obsidian

Nem toda nota útil precisa ser carregada em todas as sessões. O Obsidian funciona melhor para pesquisa longa, alternativas, atas e ideias futuras. O repositório é o lugar para instruções compartilhadas, especificações, recibos e conteúdo publicado.

Local	Conteúdo indicado
CLAUDE.md do projeto	Regras curtas necessárias na maioria das sessões
.claude/rules/	Instruções aplicáveis a um tipo de arquivo ou caminho
Documentos do projeto	Decisões, especificações e recibos compartilhados
Obsidian	Pesquisa longa, hipóteses, fontes e fila de ideias
Memória automática	Preferências locais e aprendizados recorrentes

Para aprofundar essa divisão, consulte o guia de boas práticas para CLAUDE.md, o guia de otimização de tokens e o fluxo entre Claude Code e Obsidian.

Uma rotina simples para sessões longas

1. Briefing: declarar objetivo, escopo, exclusões, teste de aceite e aprovações necessárias.
2. Restrição: pesquisar primeiro e carregar apenas arquivos e saídas úteis à próxima decisão.
3. Inspeção: rodar /context depois de pesquisa extensa ou quando o Claude começar a repetir trabalho.
4. Registro: anotar decisões, arquivos alterados, resultado da verificação e próxima ação.
5. Escolha: usar /compact para a mesma tarefa, /clear para uma nova e /resume ao voltar a um trabalho salvo.

Para reutilizar prompts e modelos operacionais desse fluxo, acesse o guia prático de prompts para Claude Code.

Fontes oficiais

• Entenda a janela de contexto
• Referência de comandos
• Como o Claude memoriza o projeto
• Gerenciamento e retomada de sessões

O que verificamos

Nesta revisão, conferimos os nomes dos comandos e o comportamento atual dos aliases na referência oficial: /cost e /stats levam a /usage, enquanto /stats abre a aba de estatísticas. Também verificamos na tabela oficial da janela de contexto quais instruções são reinjetadas depois de /compact e quais dependem da leitura de um arquivo correspondente. A documentação de sessões confirma que /clear inicia uma conversa nova sem apagar a anterior e que o trabalho salvo pode ser retomado pelos comandos de resume. Por fim, verificamos a sintaxe copiável dos comandos de shell e dos modelos em Markdown; caminhos e comandos de teste específicos ainda precisam ser adaptados ao repositório de cada pessoa.