CLAUDE.md: o arquivo que entra em toda conversa, e o que cabe nele

O CLAUDE.md é um arquivo de texto com as instruções que você não quer repetir. Como nomear as coisas, qual comando roda o teste, o que nunca mexer.

A frase que muda tudo está na documentação oficial: ele é carregado no contexto no começo de toda sessão, consumindo tokens junto com a sua conversa. Não é sob demanda, não é quando precisa. É sempre, inteiro, antes de você digitar a primeira palavra.

Então cada linha que você acrescenta é uma linha que ele relê em toda conversa nova pelo resto do projeto. É por isso que arquivo inchado não é só desorganização — é custo fixo. E é por isso que a doc recomenda menos de 200 linhas, dizendo o motivo na mesma frase: arquivo mais longo consome mais contexto e reduz a adesão às instruções.

A armadilha do "vou dividir em vários arquivos"

A reação natural de quem descobre isso é quebrar o arquivo em pedaços e importar só o que interessa. A sintaxe existe: @caminho/para/arquivo dentro do CLAUDE.md puxa outro arquivo.

Só que ela não resolve o problema de contexto, e a doc diz isso com todas as letras: dividir em imports ajuda a organizar, mas não reduz contexto, porque os arquivos importados carregam no início da sessão do mesmo jeito.

Divida para se organizar. Não divida achando que economizou token — não economizou.

Detalhes do import que valem saber:

• Importado pode importar outro, até quatro saltos de profundidade.
• Caminho relativo resolve a partir do arquivo que importa, não de onde você abriu o terminal.
• Para citar um caminho sem importar, use crase: `@README` fica literal, @README importa.

Os quatro lugares onde ele vive

A doc lista em ordem de carregamento, do escopo mais amplo para o mais específico:

Aqui está o mal-entendido mais comum, e ele importa: um arquivo não sobrescreve o outro. A palavra que a doc usa é concatenados — todos entram no contexto, em ordem, sem que nenhum anule o anterior.

Dentro da árvore de diretórios, a ordem vai da raiz do sistema até a pasta onde você abriu o Claude Code — ou seja, a instrução mais próxima de onde você está é lida por último. Dentro de cada pasta, o CLAUDE.local.md vem depois do CLAUDE.md.

Consequência prática: se dois arquivos se contradizem, não existe um "vencedor" por regra. A doc avisa que, havendo contradição, ele pode escolher uma arbitrariamente — e recomenda revisar os arquivos de tempos em tempos para tirar o que ficou velho ou conflitante.

A política gerenciada é a única que não dá para excluir, de propósito: garante que a regra da organização valha independente da configuração de cada um.

Subdiretório é a exceção

Um detalhe que quase ninguém conhece: CLAUDE.md em pastas acima de onde você abriu o terminal carrega no início. Em subpastas, não — esses carregam sob demanda, quando ele for ler algum arquivo daquela pasta.

Isso dá uma saída real para instrução que só vale num canto do projeto: em vez de engordar o arquivo da raiz, ponha um CLAUDE.md dentro da subpasta. Ele só custa contexto quando o assunto aparece.

O critério oficial do que tirar

Essa é a parte que mais enxuga arquivo, e ela vem da própria ferramenta. O /doctor propõe cortes no CLAUDE.md, e o critério dele é explícito:

Corta o que ele consegue descobrir sozinho lendo o código — estrutura de pastas, lista de dependências, visão geral de arquitetura.

Mantém armadilhas, o motivo das coisas, e convenções que diferem do padrão da ferramenta.

Faz sentido quando você olha: descrever a árvore de diretórios é gastar contexto para contar algo que um ls responde. Já "não use npm, este projeto é pnpm" é informação que nenhuma leitura de código entrega com segurança.

O que colocar, com o exemplo da doc

A doc é direta sobre o critério de adicionar: escreva ali o que você teria de re-explicar. Acrescente quando —

• ele cometer o mesmo erro pela segunda vez;
• uma revisão pegar algo que ele deveria saber sobre este código;
• você digitar de novo a mesma correção que digitou na sessão passada;
• alguém novo no time precisar do mesmo contexto para produzir.

E sobre como escrever, a recomendação é ser concreto o bastante para verificar. Os exemplos são da própria documentação:

Use cabeçalhos e listas para agrupar. A doc justifica: ele varre a estrutura do mesmo jeito que um leitor varre — seção organizada é mais fácil de seguir que parágrafo denso.

O que não pertence a esse arquivo

Duas coisas saem dali, e a doc diz para onde vão.

Procedimento de vários passos ou instrução que só vale para uma parte do código: vira uma skill, ou uma regra com escopo de caminho. O CLAUDE.md é para fato que vale em toda sessão — comando de build, convenção, regra do tipo "sempre faça X".

Coisa que precisa acontecer sempre, num ponto fixo — antes de todo commit, depois de toda edição: vira hook. E aqui está a frase mais importante do assunto inteiro:

Ele trata essas instruções como contexto, não como configuração obrigatória.

Ou seja, o CLAUDE.md pede. Não garante. Para bloquear uma ação independente do que ele decidir, o caminho é um hook PreToolUse, que roda como comando de shell num evento fixo e vale independente da decisão dele.

Escrever "NUNCA faça X" em caixa alta no CLAUDE.md não é uma trava. É um pedido enfático.

Conferindo o que de fato carregou

Dois comandos, e eles respondem coisas diferentes:

• /memory lista os locais dos arquivos de memória, nos escopos de usuário e projeto, inclusive os que ainda não existem — escolher um deles abre no editor, e escolher um inexistente cria antes.
• /context mostra o que realmente entrou na sessão atual.

O segundo é o que resolve discussão. Arquivo que você acha que está valendo e não aparece no /context não está valendo.

Dois números para não confundir

Circula por aí um limite de "200 linhas ou 25KB" que não é do CLAUDE.md — é do MEMORY.md, da memória automática, e a doc marca que aquele limite se aplica só a ele.

Do CLAUDE.md, os números são outros: alvo de 200 linhas por arquivo, e um teto duro de 4 MiB — acima disso ele pula o arquivo inteiro. Pular em silêncio é o pior caso possível, porque tudo parece normal e nenhuma instrução está valendo.

Documentação oficial: https://code.claude.com/docs/en/memory