CLAUDE.md: A Constituição do Projeto

Um README explica o projeto ao leitor; o CLAUDE.md mantém instruções recorrentes disponíveis para o Claude Code. Na documentação consultada em 17/10/2026, a Anthropic trata esses arquivos como contexto, não como configuração que imponha bloqueios. Escrever uma proibição no Markdown não substitui permissões, sandbox ou um hook.

Separe as instruções pessoais em ~/.claude/CLAUDE.md das regras do repositório em ./CLAUDE.md. Para conferir o que entrou na sessão, use /context e examine Memory files. Quando o time usa AGENTS.md, confirme sua descoberta na versão instalada; evite manter duas cópias divergentes de uma mesma regra.

Anatomia de um CLAUDE.md que funciona. Todos os blocos abaixo devem existir, mesmo que curtos, porque cada um fecha uma classe de erro conhecida:

Contexto do projeto. Uma linha de propósito e três de stack. O agente precisa saber se está em um projeto Next.js 16 App Router, em um worker Cloudflare ou em um pacote Python puro.

Estrutura de diretórios. Um mapa em árvore dos cinco ou seis diretórios principais. Evita que o agente procure arquivos nos lugares errados ou crie novos em pastas que já têm convenção estabelecida.

Comandos operacionais. Como rodar testes, build, lint, deploy. Precisa ser literal -- npm run verify, não 'rodar os testes'.

Convenções de código. Tipagem rigorosa, imports ordenados, sem emojis, acentuação completa, sem quebra de linha em URL. Cada regra corresponde a um incidente que você não quer repetir.

Variáveis de ambiente. Quais existem, para que servem, e quais são sensíveis. Impede que o agente logue token no console por acidente.

Checklists antes de commit. 'Antes de fazer push em src/: rodar npm run verify e confirmar que os 72 testes passam.' Três linhas que previnem o 90% dos incidentes de produção.

A evolução orgânica do CLAUDE.md é o que separa um arquivo morto de uma constituição viva. Toda vez que o agente comete um erro que você teve que corrigir duas vezes, adicione uma linha. Toda vez que uma peculiaridade do seu setup mordeu você, adicione a exceção. Em seis meses, o CLAUDE.md vira documentação executiva da arquitetura -- útil também para humanos que entram no projeto.

O CLAUDE.md do landing-page-geo da Brasil GEO tem hoje 270+ linhas, escritas ao longo de sete meses. Inclui regras sobre double-escape de Unicode em JSX (incidente real do Turbopack), proteção de slugs ASCII em scripts de acentuação (incidente de 55 hrefs corrompidos), hierarquia obrigatória do admin (dois incidentes graves de loop de login) e padrão de referência de API routes. Cada uma dessas regras custou horas de debug antes de virar uma linha de texto.

Laboratório de organização: avaliar uma skill antes de adicioná-la ao projeto. A Escola Horizonte recebeu uma skill de relatórios que pede instalar pacotes e executar um hook, embora a tarefa seja ler um CSV. A entrega do laboratório é uma decisão justificada: usar só a parte de instruções, revisar o código em ambiente isolado ou recusar a instalação. O pacote ainda não foi executado.

Modelo de decisão para copiar: "Entrada: pacote de relatórios fictício. Achados: dependência sem versão fixada e comando postinstall que chama setup.js. Evidência: package-demo.json. Decisão: usar o verificador local sem dependências deste laboratório; manter o pacote externo desativado até revisar os arquivos e testar em ambiente isolado. Custo de API: não acionado pelos scripts. Tamanho instalado, memória e tempo de início do pacote externo: não medidos, pois não foi instalado."