CLAUDE.md é um arquivo markdown simples na raiz do seu projeto. Claude o lê automaticamente em cada sessão. Nível do projeto: ./CLAUDE.md. Global (todos os projetos): ~/.claude/CLAUDE.md. O projeto sobrescreve o global: o arquivo global contém seus padrões, o arquivo do projeto contém as especificidades deste repositório.
Pense nele como o documento de integração que você entrega a um contratado altamente qualificado que não sabe nada sobre seu projeto. Sem ele, cada sessão começa com Claude adivinhando sua stack, suas convenções de nomenclatura e suas decisões passadas. Adivinhações viram código, código vira bugs. CLAUDE.md encurta essa cadeia. Um arquivo é melhor do que um prompt inteligente porque funciona quer você se lembre ou não.
Cinco seções que valem a pena. Três a seis linhas de tópicos cada:
1. Stack: frameworks, DB, autenticação, e-mail, com versões. "Next.js 16, Postgres no Neon, Resend para e-mail, Stripe para pagamentos, Supabase para autenticação."
2. Rotas: onde as coisas vivem. "App em /app, server actions em /actions, API em /app/api/v2, componentes compartilhados em /components/ui."
3. Convenções: regras óbvias para você, invisíveis para Claude. "Dinheiro em centavos (int), datas UTC, nomes de arquivos kebab-case, IDs como UUID v4."
4. Regras de Segurança: coisas que nunca devem acontecer. "Nunca registre chaves de API. Parametrize todo o SQL. Limite a taxa de todos os endpoints públicos."
5. Não Faça Isso: armadilhas em que você já caiu. "Não adicione dependências sem perguntar. Não execute migrações locais contra produção."
Um modelo pronto. Troque pelos detalhes reais do seu projeto:
# Plinko Grant Tracker
## Stack
- Next.js 16, Postgres (Neon), Resend, Stripe
- Auth: Supabase Auth com Google OAuth
## Routes
- App em /app, actions em /actions, API em /app/api/v2
## Conventions
- Dinheiro em centavos (int), datas UTC, nomes de arquivos kebab-case
- IDs: UUID v4. Colunas booleanas: prefixo is_ ou has_
## Security Rules
- Nunca registre segredos, parametrize SQL
- Limite a taxa de todos os endpoints POST/PUT/DELETE (10/min por IP)
- Novas tabelas Supabase são enviadas com políticas RLS no mesmo commit
## Don't Do This
- Não adicione dependências sem perguntar
- Não execute migrações locais contra produção
- Não use select(*)Observe a especificidade. "10/min por IP" é acionável. "Use limitação de taxa" não é.
O erro mais caro: regras vagas que parecem específicas.
Fraco: "Lide com o dinheiro com cuidado." Claude lidará com o dinheiro da maneira que achar melhor, o que pode não corresponder ao seu sistema.
Forte: "Todos os valores monetários são centavos inteiros. Nunca floats. Nunca exiba centavos brutos; divida por 100 e formate com um símbolo de moeda." Tipo de armazenamento, regra de processamento, regra de exibição. Sem ambiguidade.
O segundo erro: escrever aspirações em vez de restrições. "Valorizamos código limpo e legível" é uma aspiração. "Arquivos com mais de 200 linhas são divididos em módulos" é uma restrição. Aspirações exigem julgamento; restrições produzem comportamento consistente. Preencha seu CLAUDE.md com restrições.
CLAUDE.md é um documento vivo. Três sinais de que precisa ser atualizado:
Você cola o mesmo contexto em um prompt pela segunda vez. Se você está dizendo de novo, pertence ao CLAUDE.md.
Claude comete um erro que uma regra teria evitado. O erro é a regra. Escreva-a antes da próxima sessão.
Você explica uma convenção a um colega. Se valeu a pena dizer em voz alta, vale a pena carregar automaticamente.
Disciplina de comprimento: três a seis tópicos por seção; após oito, divida a seção. Um CLAUDE.md muito longo para ser lido rapidamente para de funcionar porque as regras importantes ficam enterradas. Seis linhas certas são melhores do que sessenta linhas de preenchimento.
Escalando para mais de 300 linhas: divida em arquivos de tópico com inclusões @filename:
# CLAUDE.md (raiz)
@rules/stack.md
@rules/security.md
@rules/db-migrations.mdCada arquivo de tópico permanece focado; a raiz permanece curta.
Commit CLAUDE.md para controle de versão. As regras se tornam revisáveis em PRs, e um novo colega de equipe clona o repositório com Claude já configurado. Adicione cada regra "Não Faça Isso" no mesmo commit que a correção de bug que a ensinou. Uma ressalva: generalize caminhos específicos da máquina antes de fazer o commit.
O que pertence ao CLAUDE.md vs um prompt? Raio de explosão. Se uma regra evita uma classe de erro que custa uma hora ou mais para corrigir, ela vai para o CLAUDE.md. Instruções específicas da sessão permanecem nos prompts.
Crie seu primeiro CLAUDE.md em dez minutos. Dê a Claude este prompt:
"Estou configurando o Claude Code para um projeto com esta stack: [stack]. Convenções chave que alguém novo não saberia: [convenções]. Regras de segurança que nunca devem ser violadas: [regras]. Coisas que causaram bugs antes: [armadilhas]. Rascunhe um CLAUDE.md com cinco seções: Stack, Rotas, Convenções, Regras de Segurança, Não Faça Isso."
O primeiro rascunho lhe dá 80 por cento. Refine-o com o que Claude perdeu; os 20 por cento restantes são o que é específico para sua experiência real com o projeto.
CLAUDE.md na raiz do projeto carrega sua stack, rotas, convenções, regras de segurança e armadilhas em cada sessão. Arquivo global para padrões entre projetos, arquivo de projeto para sobrescritas. Restrições, não aspirações. Seis linhas certas são melhores do que sessenta. Atualize-o sempre que Claude cometer um erro que uma regra escrita teria evitado.