Escreva o CLAUDE.md como uma constituição: proibições, regras de conduta, decisões padrão. 92 commits em 5 dias sem desviar.
Em 5 dias fiz 92 commits e coloquei um produto em produção (github.com/defi-io/smarts). Sem capotamentos, sem rollbacks, sem grandes refatorações. Não foi porque o Claude é genial. Foi por causa das 565 linhas do CLAUDE.md na raiz do projeto.
Este post é sobre como escrever um CLAUDE.md que funciona como uma constituição, e o que acontece depois que você faz isso.
Muita gente escreve CLAUDE.md parecido com README — o que é o projeto, como rodar. É desperdício.
README é para humanos. CLAUDE.md é para o Claude. O Claude carrega automaticamente no início de cada sessão. Cada linha que você coloca ali vira pré-condição de toda decisão que ele toma depois.
No estilo README, você obtém: o Claude sabe mais ou menos o que é o projeto, sabe rodar os testes, mas toma cada decisão técnica do zero.
No estilo constituição, você obtém: o Claude sabe quais caminhos estão fechados, quais convenções são obrigatórias, para qual lado pender em cada bifurcação, e quando parar e perguntar.
A diferença: o primeiro vai "de quebra" puxar uma dependência nova, somar uma camada de abstração, mexer no Gemfile. O segundo não.
O projeto que tenho construído se chama smarts.md — uma plataforma que gera live docs e servidores MCP para smart contracts. Seu CLAUDE.md tem 565 linhas, divididas assim:
1. Identidade do projeto (5 linhas)
2. Núcleo do produto (definição em uma linha + diferenças estruturais vs concorrentes)
3. Stack técnica (restrições rígidas, formato YAML)
4. Lista de proibições (itens ❌ explícitos)
5. Escopo (fronteiras rígidas do MVP)
6. Arquitetura (com diagrama ASCII)
7. Estrutura de diretórios (responsabilidade por arquivo)
8. Convenções Ruby (com snippets de "faça / não faça")
9. Estratégia de cache (em tabela)
10. Requisitos de teste
11. Detalhes de deploy
12. Fluxo Git
13. Regras de uso do Claude Code (instruções de comportamento)
14. Marcos de 90 dias
15. Princípios centrais
Nenhuma seção é decoração. Abaixo escolho algumas e explico por que estão escritas assim.
A minha tem essa cara:
❌ Sem serviços TypeScript / Node.js
❌ Sem ethers.js / web3.js
❌ Sem Sidekiq (usar Solid Queue)
❌ Sem React / Vue / Svelte (usar Hotwire)
❌ Sem Redis (Solid Cache / Solid Queue / Solid Cable cobrem tudo)
❌ Sem contratos não verificados (somente verificados pela Etherscan)
❌ Sem Solana / Bitcoin / Move (somente EVM)
É um projeto Web3. O default do mundo Web3 é TypeScript + ethers.js + Redis + React. Estou indo na direção contrária. Tenho meus motivos, mas o Claude não conhece eles. Sem a lista de proibições, ele baseia recomendações no "senso comum da indústria" enterrado nos dados de treino — e quase certamente vai ser o caminho TypeScript.
Com a lista, o Claude para de perguntar "adicionamos um serviço Node para rodar web3.js?". Esse caminho está fechado por padrão.
A chave: cada item precisa ser explícito e absoluto. Não escreva "tente evitar TypeScript". Escreva "sem TypeScript". O que for vago, o Claude lê como negociável.
O último grande bloco do CLAUDE.md é "Regras de uso do Claude Code":
### Quando eu disser "comece a fazer X"
1. Primeiro verifique se as restrições do CLAUDE.md permitem essa abordagem
2. Depois verifique se já existe implementação relacionada (não reinvente)
3. Antes de escrever código, abra uma nova branch
4. Após a implementação, rode os testes
5. Não faça auto-commit — quando o código estiver escrito e os testes passarem,
pare e reporte. Aguarde eu dizer explicitamente "commit"
### Quando eu disser "tenho uma ideia"
Não escreva código imediatamente. Primeiro:
1. Confirme que entendeu (parafraseie)
2. Avalie contra as restrições do CLAUDE.md
3. Aponte problemas potenciais ou melhores alternativas
4. Aguarde minha confirmação antes de agir
### Quando enfrentar uma bifurcação técnica
Quando o CLAUDE.md não especifica:
1. Default para a opção mais "Rails-nativa"
2. Default para a opção com menos dependências
3. Default para a opção que deixe um dev solo iterar mais rápido
4. Em dúvida, pare e pergunte
Essa parte vale dez vezes mais do que "use snake_case".
Estilo de código o Claude aprende lendo código. Mas "quando parar e perguntar", "ao ouvir 'tenho uma ideia', primeiro parafrasear em vez de já escrever código" — são padrões de comportamento. Código sozinho não ensina isso.
A linha mais importante: para qual lado pender numa bifurcação. Essa única regra decide o que o Claude faz quando você não está na sala (você diz "comece com X" e sai). Escreva isso de forma clara e dá pra deixar ele trabalhar sem supervisão.
O topo do CLAUDE.md diz:
Este documento é a "fonte primária" do projeto. Carregado automaticamente no início de cada sessão do Claude Code. Quando mudar decisões técnicas, mude isto primeiro; o código vem depois.
É um contrato de fluxo de trabalho. Quando decido trocar alguma escolha técnica — digamos, subir o modelo principal de gpt-5-mini para gpt-5 — o primeiro passo não é mexer no initializer. O primeiro passo é editar este trecho do CLAUDE.md:
ai:
fast: gpt-5-mini # antes
fast: gpt-5 # depois
Aí deixo o Claude reler o CLAUDE.md e ajustar o código.
Por quê? Porque se você muda um valor no código e o CLAUDE.md fica para trás, da próxima vez que o Claude ler o CLAUDE.md ele vê o valor antigo e "gentilmente" reverte seu código. O conflito vem de um único ponto de falha — o CLAUDE.md desatualizado. Constituição atrasada em relação à realidade é como começam as guerras civis.
Tratar o CLAUDE.md como constituição significa: ele sempre corre na frente do código.
smarts.md, 5 dias, 92 commits:
Tempo médio de PR: 30 minutos. Sem refatorações grandes. Sem "espera, essa direção estava errada, rollback".
Não porque o Claude é mágico. Porque cada sessão dele rodou sobre 565 linhas de trilho. Ele sabia que não pode trazer TypeScript, sabia que Solid Queue é a fila padrão, sabia que funções view ficam em cache por 60s, sabia que cada service tem que implementar um método de classe call, sabia que precisava esperar minha confirmação antes do commit.
Tire metade dessas restrições e você terá: 30 minutos por dia explicando "por que não vamos usar X", 5 minutos revisando a dependência que ele puxou "de quebra", e um Gemfile que cai aos poucos.
Não comece de um arquivo em branco. Comece pela decisão mais recente que doeu.
Se ultimamente o Claude tem "puxado dependências novas o tempo todo", escreva a lista de proibições.
Se é "muda a arquitetura por qualquer motivo", escreva o diagrama + "novos microsserviços, troca de DB etc. exigem confirmação".
Se é "não escreve testes", escreva "o que deve ter teste unitário obrigatório".
Se é "commita rápido demais", escreva "sem auto-commit, espere instrução explícita".
Cada dor, uma entrada. O resto, por enquanto, não escreva.
Três meses depois você terá um CLAUDE.md de 500 linhas onde cada linha tem por trás um concreto "não quero que faça isso de novo". Esse documento vence qualquer template, porque está calibrado para o seu projeto, seu fluxo, sua equipe (mesmo que seja só você).
Uma constituição não se escreve de uma vez. Ela cristaliza, conflito por conflito.
Fonte: github.com/defi-io/smarts