CLAUDE.md — Como o Claude lembra do seu projeto

O que é o CLAUDE.md

Um arquivo de instruções que o Claude lê automaticamente

Toda vez que você abre o Claude Code numa pasta, ele procura por um arquivo chamado CLAUDE.md naquele diretório. Se encontrar, lê o conteúdo antes de responder qualquer coisa.

É onde você explica o projeto, define regras, descreve o stack, lista convenções de código e qualquer contexto que o Claude precisaria saber pra trabalhar bem.

Sem CLAUDE.md, o Claude começa do zero toda sessão

Ele não tem memória entre conversas. Sem o arquivo, você vai repetir o mesmo contexto toda vez: "esse é um projeto React", "usamos TypeScript", "não mexe no arquivo X". Com o CLAUDE.md, você escreve uma vez e nunca mais precisa repetir.

Onde criar o arquivo

Na raiz do projeto — lido sempre que você abre o Claude Code nessa pasta

meu-projeto/CLAUDE.md

Dentro de subpastas — lido quando o Claude acessa arquivos naquele diretório

src/components/CLAUDE.md

Gerar automaticamente com o comando /init — o Claude analisa o projeto e cria o arquivo

/init

Estrutura básica

Exemplo de CLAUDE.md para um projeto real

# Meu Projeto

## Stack
- Next.js 14 com App Router
- TypeScript estrito
- Tailwind CSS
- Supabase como banco

## Regras de código
- Sempre usar Server Components por padrão
- Nunca usar `any` em TypeScript
- Funções assíncronas sempre com tratamento de erro

## O que não mexer
- `src/lib/supabase.ts` — configuração crítica
- `middleware.ts` — não alterar sem revisar antes

## Como rodar
npm run dev   # desenvolvimento
npm run build # build de produção

O que vale colocar no CLAUDE.md

Descrição do projeto — o que faz, pra quem, qual o objetivo

# Meu Projeto
SaaS de agendamento pra clínicas.
Stack: Next.js + Supabase + Stripe.
Público: clínicas pequenas, sem time técnico.

Comandos do projeto — como rodar, testar, buildar

## Comandos
npm run dev     # inicia em localhost:3000
npm run test    # roda todos os testes
npm run lint    # checa o código antes de commitar

Convenções de código — padrões que o time usa

## Convenções
- Componentes: PascalCase
- Arquivos de util: camelCase
- Nomes de branch: feat/, fix/, chore/
- Commits em inglês no imperativo

Arquivos intocáveis — o que não pode ser mexido sem aviso

## Não alterar sem perguntar
- `prisma/schema.prisma` — mudanças geram migrations
- `next.config.js` — configuração de infra
- `.env.example` — atualizar quando adicionar var

Diferença na prática

Sem CLAUDE.md

Você escreve: "cria um botão de login".

O Claude cria em JavaScript puro, sem Tailwind, sem TypeScript, no estilo errado.

Com CLAUDE.md

Você escreve: "cria um botão de login".

O Claude já sabe que é TypeScript, usa Tailwind, segue o padrão de componentes do projeto.

Dicas rápidas

Menos é mais — o CLAUDE.md vai pro contexto. Arquivo enorme = menos espaço pro código.

Atualize quando o projeto mudar — se trocou de biblioteca, mudou o stack, acrescentou uma regra, coloca no arquivo.

Use subpastas — um CLAUDE.md em src/api/ pode ter regras específicas pra API sem poluir o principal.

Versione no git — o CLAUDE.md faz parte do projeto. Commita junto com o código, o time inteiro se beneficia.

Atalho: rode /init dentro do Claude Code e ele lê o projeto, entende o stack e gera um CLAUDE.md com o que encontrou. Edite depois pra adicionar regras específicas.