O que é o CLAUDE.md?

O que entra e o que fica de fora

O agente não tem memória entre sessões. Ele lê o código, conclui o que dá pra concluir e adivinha o resto, e adivinha de novo amanhã. Tudo que existe só na sua cabeça, a biblioteca que o projeto abandonou, a branch em que não se commita, o comando que roda o gate, é o que ele erra repetido. O CLAUDE.md existe pra tirar essas regras da sua cabeça e pôr onde ele lê.

O erro oposto é tão caro quanto. Quando o arquivo cresce até virar um calhamaço, o agente carrega tudo aquilo em toda sessão, e você paga contexto e tokens por página de texto que não muda decisão nenhuma. Tutorial da linguagem ou do framework, por exemplo, fica de fora: o modelo já sabe. A pergunta que decide cada linha é se ela muda o comportamento do agente.

O CLAUDE.md deste site

O arquivo que governa este site tem os comandos do projeto (dev, typecheck, build, contraste), o mapa da estrutura, as convenções que o código não denuncia sozinho (cor sempre por token, cada rota com o próprio CSS, travessão proibido em texto que a pessoa lê) e uma lista do que não fazer, com o motivo de cada item.

Ele abre com quatro regras de trabalho adaptadas das observações de Andrej Karpathy sobre onde as LLMs erram ao programar: pense antes de codar, simplicidade primeiro, mudanças cirúrgicas e execução orientada a objetivo. É a parte que muda mais comportamento por linha escrita.

Quando um arquivo só não basta

Projeto grande não cabe num arquivo, e a saída não é um arquivo maior. Aqui o CLAUDE.md é um mapa: diz onde as coisas estão e o que não pode, e aponta pra documentos separados que explicam o porquê do negócio, o sistema visual, o deploy e a API interna. O agente gasta o contexto no problema em vez de procurar onde as coisas estão, e a decisão de produto fica num lugar que ele lê antes de aparecer no meio do código.

Quando isso importa

• O agente refez a mesma besteira pela terceira sessão seguida e você quer que a correção fique gravada num lugar que ele leia.
• Você abriu um repositório, achou um CLAUDE.md na raiz e quer saber o que aquele arquivo manda o agente fazer.
• O seu CLAUDE.md passou de algumas páginas, a sessão ficou mais lenta e mais cara, e o agente não acerta mais por isso.

Nossa posição

A gente trata o CLAUDE.md como mapa, não como enciclopédia: ele diz onde as coisas estão e o que não pode, e aponta pra doc que explica o porquê em vez de repetir tudo. Linha que não muda decisão nenhuma sai, porque o agente paga por ela em toda sessão.