Melhores Práticas de Gerenciamento de Contexto

Estes são os padrões que fazem as ferramentas de gerenciamento de contexto do Claude Code realmente funcionarem para você em um projeto, desde o primeiro CLAUDE.md até uma base de código de longa duração e multissessão.

Como Usar Esta Lista

• Trate as práticas de CLAUDE.md como fundamentais - acerte-as primeiro, pois todo o resto se baseia em um arquivo de memória de projeto sólido.
• Revise as práticas de @menções e higiene de sessão como hábitos, não como configuração única.
• As práticas de aninhamento e auditoria são mais importantes à medida que um projeto cresce - não as force em um repositório pequeno e de pilha única.
• Volte a esta lista sempre que um novo membro da equipe entrar ou a estrutura de um projeto mudar significativamente.

A - Fundamentos do CLAUDE.md

• Comece com /init em vez de um arquivo em branco. Deixe o Claude Code rascunhar a primeira passagem estrutural (pilha, layout de pastas, comandos existentes) para que você esteja escrevendo apenas o que ele não conseguiu inferir.
• Escreva regras como declarações concretas e verificáveis. "Use zod para validar toda a entrada externa" é seguível; "escreva código limpo" não é - a especificidade é o que faz uma regra ser realmente obedecida.
• Dê às regras rígidas sua própria seção. Isole os imperativos genuínos ("nunca faça commit em main") das convenções gerais para que sejam impossíveis de perder.
• Aponte regras para um arquivo de exemplo real, quando possível. Uma convenção emparelhada com "veja src/repositories/OrderRepository.ts" é mais fácil de aplicar corretamente do que a mesma regra declarada em abstrato.
• Respalde regras críticas com aplicação fora do modelo também. CLAUDE.md é contexto sobre o qual o agente raciocina, não um sistema de permissões - combine regras genuinamente críticas com uma verificação de CI ou proteção de branch.
• Mantenha-o o mais curto possível, mantendo a especificidade. CLAUDE.md carrega em todas as sessões; preenchimento custa orçamento de contexto repetidamente sem adicionar orientação real.

B - Mantendo o CLAUDE.md Atualizado

• Reexecute /init quando a estrutura do projeto mudou significativamente. Ele atualiza o arquivo com base no estado atual em vez de duplicá-lo, dando a você uma linha de base estrutural fresca para revisar.
• Compare CLAUDE.md após qualquer regeneração ou edição importante. Confirme se as regras rígidas escritas à mão e as convenções da equipe sobreviveram à atualização antes de prosseguir.
• Trate CLAUDE.md como um documento vivo, não como uma etapa de configuração única. Uma regra desatualizada é confiada como contexto atual por padrão, portanto, um arquivo impreciso pode enganar ativamente o agente.
• Faça o commit das alterações do CLAUDE.md através do mesmo processo de revisão do código. Como é um arquivo normal no repositório, as alterações nele devem receber o mesmo escrutínio que qualquer outra convenção compartilhada.

C - Usando Bem as @menções

• Mencione arquivos que você realmente sabe que são relevantes, não arquivos que você pode precisar. Cada menção carrega o conteúdo completo do arquivo para o contexto - menções reflexivas são uma fonte comum e evitável de inchaço.
• Prefira prosa a uma menção quando apenas parte de um arquivo grande importa. Descrever a função ou seção específica geralmente custa menos contexto do que mencionar o arquivo inteiro.
• Encadeie um pequeno número de menções direcionadas para tarefas genuinamente multianuais. Algumas menções precisas superam uma descrição vaga de todo o codebase quando você já sabe quais arquivos estão envolvidos.
• Deixe o Claude Code pesquisar quando você genuinamente não sabe onde algo está. Menções são para alvos conhecidos; tarefas exploratórias ou de "encontrar onde X acontece" são para o que serve a pesquisa.

D - Gerenciando a Janela de Contexto

• Use /compact quando uma tarefa ainda estiver ativa, mas a conversa ficou longa. Ele preserva a essência enquanto libera espaço, para que você possa manter o ímpeto no trabalho em andamento.
• Use /clear ao mudar para algo não relacionado. Arrastar até mesmo uma versão resumida de uma tarefa concluída ou não relacionada para a frente apenas adiciona ruído à próxima.
• Compacte proativamente em vez de esperar até que as coisas pareçam críticas. Uma execução de /compact mais cedo em uma sessão longa tende a produzir um resumo mais limpo e útil do que uma executada sob pressão.
• Trate /clear como um hábito rotineiro entre as tarefas, não apenas como um movimento de recuperação. Limpar ao terminar uma tarefa, da mesma forma que você fecharia uma aba do navegador, mantém as sessões focadas por padrão.
• Observe as fontes usuais de inchaço à medida que uma sessão avança. Arquivos grandes lidos na íntegra, uma lista crescente de @menções e saídas de ferramentas verbosas são os culpados recorrentes que valem a pena notar antes que se acumulem.

E - Escalando para Projetos Maiores

• Mude para arquivos CLAUDE.md aninhados assim que as áreas divergem genuinamente. Um monorepo, uma divisão clara de backend/frontend ou uma área de exceção legada são sinais de que um arquivo apenas raiz está começando a ficar sobrecarregado.
• Deixe os arquivos aninhados assumirem o contexto do arquivo raiz em vez de reafirmá-lo. Um CLAUDE.md aninhado deve adicionar apenas o que é específico para seu próprio escopo, não explicar novamente as convenções de todo o projeto já cobertas acima dele.
• Declare exceções às regras raiz explicitamente, não implicitamente. Se um subdiretório realmente quebrar uma convenção de todo o projeto, diga isso diretamente em seu arquivo aninhado, juntamente com o motivo - não deixe que o agente perceba por conta própria.
• Audite periodicamente em projetos de longa duração ou amplamente reutilizados. Verifique arquivos grandes lidos repetidamente, conteúdo CLAUDE.md desatualizado ou excessivamente grande e hábitos de menção que surgiram ao longo do tempo, mesmo sem um sintoma óbvio.
• Não aninhe ou divida prematuramente. A primeira correção para um arquivo único inchado é geralmente apará-lo - o aninhamento é para conteúdo genuinamente específico de escopo, não apenas de comprimento.

FAQs

Relacionado

• O que CLAUDE.md Realmente Faz - o conceito fundamental por trás das seções A e B.
• Escrevendo um Arquivo CLAUDE.md Que Realmente é Seguido - o padrão completo por trás de regras concretas e verificáveis.
• Auditoria do que Está Consumindo Sua Janela de Contexto do Claude Code - o fluxo de trabalho detalhado de auditoria por trás da seção E.
• Arquivos CLAUDE.md Aninhados e Como Funciona a Herança de Escopo - a mecânica completa por trás da orientação de aninhamento da seção E.
• Por que /compact e /clear Existem - o raciocínio por trás da orientação de reinicialização da seção D.

Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos do produto mudam rapidamente - verifique as especificações atuais em platform.claude.com/docs antes de confiar nelas.