CLAUDE.md

O Claude lê três manuais, de cima para baixo, e soma os três

Funciona como as normas de uma empresa com filiais: o código de conduta vale em todas, a norma da regional vale para as lojas dela, e o aviso na parede vale só naquela loja; ninguém reimprime o código de conduta no aviso da parede. Aqui é igual. Existe um manual seu, que vale em qualquer pasta (ele fica em ~/.claude/, a pasta de configurações do Claude no seu computador). Um da pasta-mãe, a pasta que guarda as outras, que vale para tudo dentro de uma área (um cliente, uma frente de trabalho). E um de cada projeto. Abrindo a conversa dentro do projeto, os três entram juntos, antes de você digitar nada. Por isso o do projeto herda os de cima e não precisa repeti-los. Ligue e desligue as camadas; depois, faça o do projeto repetir uma regra do seu com outra redação.

Os tamanhos são de uma área de trabalho real (84, 270 e 102 linhas); os nomes de pasta e as regras são exemplos. A mesma lógica de camadas que se somam aparece no chat e nos projetos da ferramenta: onde a regra mora. O 00-aqui-paramos.md da última linha do projeto é a memória: o arquivo que diz onde o trabalho parou.

Cada camada só carrega o que é verdade nela

Pense no que vai no seu contrato de trabalho e no que vai na ordem de serviço de um cliente: um vale em qualquer trabalho, a outra só naquele. O corte é uma pergunta: isso vale em qualquer pasta, ou só aqui? O jeito de trabalhar (escopo da entrega, mudança pequena, dizer o que é dado e o que é opinião) vai no seu. O que só é verdade num lugar (o modelo de documento, o caminho dos arquivos, o que ler primeiro, o que não se pode tocar) vai no da pasta.

Duplicata não reforça. Dilui, e cobra espaço em toda conversa.

Um trecho real de um manual de área, do tipo que só vale ali: pedido ambíguo de lugar (“arruma isso”, “limpa isso”) se resolve na pasta do projeto ativo; se lá já está em ordem, diga que está em ordem e pare.

O que um manual de projeto costuma ter, em 102 linhas

O manual de integração que o RH entrega costuma ter sempre as mesmas partes: o que a empresa faz, o que ler primeiro, como as coisas andam, onde fica cada coisa, a quem recorrer. O do Claude também. Um exemplo curto e bom, medido: 102 linhas, cinco partes. Clique em cada uma. O conteúdo abaixo é de um projeto inventado (as propostas comerciais de uma área); a forma é a do exemplo real.

Três hábitos que aparecem em todos os bons

O manual nasce do erro: uma linha entra quando você corrigiu a mesma coisa duas vezes

Norma interna costuma nascer de um erro que se repetiu: o segundo boleto pago em duplicidade vira uma linha no procedimento do financeiro. No chat, a correção fica na conversa e morre com ela. Por isso o mesmo erro volta amanhã. Corrigiu duas vezes a mesma coisa, vira uma linha. E a linha descreve comportamento, não intenção; de preferência, com um número que dá para contar. Troque a redação e veja o que o Claude consegue conferir sozinho, no fim de uma sessão longa (horas de trabalho na mesma conversa).

O que ele consegue contar, ele cumpre no fim do dia. O que precisa interpretar, não.

Como transformar a correção numa linha (os seis desvios com nome, a linha que dá para apagar amanhã) está em toda correção vira regra. Aqui o assunto é o arquivo onde essa linha mora.

Cada linha passa por uma pergunta: se eu tirar, ele erra?

Formulário com campo que ninguém preenche só atrasa quem usa; na revisão, o campo sai. Aqui, a revisão é a pergunta do título, linha por linha. Se não erra, a linha sai. Se é algo que muda toda semana, não é manual: é estado, e vai para a memória. Dez linhas candidatas de um manual de projeto. O manual de usuário deste exemplo já diz “responda em português, frases curtas”.

O que o manual não consegue garantir

O manual é texto, e texto é interpretado. Peça nele “depois de salvar um arquivo, rode o formatador” (o programa que arruma o espaçamento do arquivo): quase sempre ele roda. Para o que precisa acontecer toda vez, o Claude Code tem o gancho (hook, em inglês). É uma ação que a ferramenta executa sozinha num momento fixo, como depois de todo arquivo salvo, sem depender de o Claude lembrar.

Como separar o que é texto do que precisa virar trava, com exemplos fora do Claude Code: quando a regra vira trava.

O manual diz como é. A história mora em outro lugar

O regimento do condomínio diz a regra que vale hoje; a assembleia que a mudou fica no livro de atas, não no regimento. Três regras de manutenção, escritas no manual de uma área real, que dizem quem muda o quê sem perguntar e onde fica o registro da mudança.

v4 · da v3 para a v4: entra a seção 10, padrão visual, que aponta para o documento da área; nada das seções 1 a 9 mudou

Um rodapé real, adaptado. Quem abre o arquivo depois sabe o que mudou sem comparar versões.

O manual que só cresce passa a obedecer a regra velha

Sabe a pasta de procedimentos que ninguém revisa, com o aviso de 2019 ao lado do de 2024 que o contradiz? Quem chega não sabe qual vale. Acrescentar é fácil; ninguém sente falta de uma linha nova. O problema aparece quando a regra nova convive com a velha que ela substituiu, e as duas estão lá. Mova os meses e troque o hábito.

Leia o CLAUDE.md desta pasta inteiro. Para cada linha, me diga:
1. Se é regra, estado do trabalho ou história.
2. Se repete algo que já está no meu manual de usuário ou no da pasta-mãe.
3. Se, sem ela, você faria alguma coisa diferente. Seja honesto: se faria igual, diga.
4. Se contradiz outra linha do mesmo arquivo.
Não apague nada. Me mostre a lista e eu decido o que sai, o que fica e o que vai para a memória.

O primeiro manual cabe em cinco linhas

O primeiro procedimento de um setor costuma caber num lembrete colado no monitor: quem faz, onde ficam as coisas, os dois cuidados que não podem falhar. Comece pequeno: o papel do Claude ali, as pastas, duas regras que não mudam e a linha que manda ler a memória. O resto entra quando você corrigir alguma coisa pela segunda vez. Preencha e copie.

Durante a semana: um arquivo aberto ao lado. Toda correção que eu fizer pela segunda vez, anoto.
No fim da semana: cada anotação vira uma linha do CLAUDE.md, com verbo e comportamento ("nome de pessoa sai só da lista de pessoas"), nunca adjetivo ("cuidado com os nomes").
Uma vez por mês: leio o manual inteiro com uma pergunta por linha: se eu tirar, ele erra? Se não erra, sai.
Toda mudança: versão, data e motivo no rodapé.

Três ideias

CLAUDE.md

Arquivo de texto que o Claude Code lê antes da primeira mensagem, em toda conversa aberta naquela pasta.

Camada

Cada um dos manuais que se somam: o do usuário (vale em qualquer pasta), o da pasta-mãe e o do projeto.

Limiar contável

Regra escrita com um número que dá para conferir: “mais de 3 arquivos” em vez de “mudança grande”.

Poda

A revisão do manual inteiro com a pergunta “se eu tirar, ele erra?”, para cortar o que não muda comportamento.

Gancho (hook)

Ação que o Claude Code executa sozinho num momento fixo, como depois de todo arquivo salvo. O manual molda; o gancho garante.

Memória

O arquivo com o estado do trabalho, reescrito toda sessão. O manual manda ler; o manual não é ela.

Simplificação didática: o nome dos arquivos e onde cada camada fica podem mudar entre versões da ferramenta; a soma de cima para baixo continua. Os tamanhos (84, 270 e 102 linhas; 252 para 83; 583) foram medidos em projetos reais, sem nome; mostram a forma do problema, não uma meta de tamanho. Pastas, regras e projetos dos exemplos são inventados. Família Claude Code; irmãs: pasta, onde paramos, handoff, referência, modelo, Obsidian.