🧠 CLAUDE.md — O Cerebro do Projeto

O CLAUDE.md e um arquivo Markdown que o Claude Code le automaticamente no inicio de cada sessão. Ele funciona como um system prompt persistente: tudo que voce escrever ali vai influenciar como o Claude se comporta dentro do seu projeto.

Sem CLAUDE.md, o Claude Code e genérico. Ele nao sabe que seu projeto usa TypeScript, que voce prefere tabs em vez de spaces, que ha uma convenção de nomes especifica. Com CLAUDE.md, ele vira um especialista no seu projeto desde a primeira mensagem. A diferença e dramatica.

O Claude Code le CLAUDE.md de tres locais, nesta ordem: ~/.claude/CLAUDE.md (global, vale pra todos os projetos), ./CLAUDE.md (na raiz do projeto) e subdir/CLAUDE.md (em qualquer subpasta onde voce esta trabalhando).

A cascata funciona por adição: o conteúdo de cada nivel se soma ao anterior. O global define preferências pessoais ("nunca use em dashes", "prefira TypeScript"). O de projeto define stack e convenções. O de pasta define regras especificas daquela area do código. Os tres juntos formam o contexto completo.

~/.claude/CLAUDE.md          ← global (todas as sessões)
./CLAUDE.md                  ← projeto (raiz do repo)
./src/CLAUDE.md              ← pasta (regras do /src)
./src/api/CLAUDE.md          ← subpasta (regras do /api)

# Todos são lidos e somados. Mais específico refina o geral.

O formato e Markdown puro. Use headings (## Stack, ## Convenções), listas com bullets, e blocos de codigo para exemplos. O tom ideal e imperativo e concreto: "Sempre use async/await" funciona melhor que "seria bom considerar usar async/await quando possivel".

Algumas convenções que funcionam bem: agrupar por seção (Stack, Convenções, Proibições), usar negrito para destaques, incluir exemplos de codigo quando a regra for tecnica, e manter o arquivo entre 50 e 200 linhas. Mais que isso, o retorno diminui e voce gasta contexto desnecessariamente.

Os tipos de instrução que mais impactam sao: stack e tecnologias ("este projeto usa Next.js 14 com App Router"), convenções de codigo ("nomes de arquivo em kebab-case"), proibições explicitas ("NUNCA delete arquivos sem confirmar"), e padrões do projeto ("use o pattern de service layer em src/services/").

Proibições em caixa alta (NUNCA, SEMPRE) sao respeitadas com mais consistência. Isso nao e superstição: o modelo da mais peso a tokens enfaticos. Use com moderação para nao virar ruido.

## Stack
- Next.js 14 (App Router)
- TypeScript strict
- Tailwind CSS
- Prisma ORM + PostgreSQL

## Convenções
- Arquivos: kebab-case (user-profile.ts)
- Componentes: PascalCase (UserProfile.tsx)
- NUNCA usar any. Sempre tipar explicitamente.
- Testes: colocar em __tests__/ ao lado do arquivo.

## Padrões
- API routes usam o pattern em src/app/api/[resource]/route.ts
- Validação com Zod em todo input de API

Bons exemplos de CLAUDE.md compartilham algumas caracteristicas: sao curtos (raramente passam de 150 linhas), focam no que e diferente naquele projeto (nao repetem conhecimento genérico), e incluem pelo menos uma seção de proibições explicitas.

Um anti-pattern comum e o CLAUDE.md que tenta ensinar programação ao modelo ("use boas praticas de codigo"). O Claude ja sabe boas praticas. O que ele precisa saber e quais sao as suas praticas especificas.

O CLAUDE.md deve ir no git, junto com o codigo. Isso garante que qualquer pessoa (ou agente) que clonar o repo receba o contexto automaticamente. Trate como um arquivo de configuração: versionado, revisado, e atualizado junto com o projeto.

Uma rotina saudavel: revise o CLAUDE.md uma vez por mês ou quando mudar algo significativo no projeto (nova lib, novo padrão). Entre revisões, use /memory para adicionar notas rápidas que persistem sem editar o arquivo diretamente.

CLAUDE.md desatualizado e pior que nenhum, porque o agente vai seguir instruções erradas com confiança. Se removeu uma lib do projeto mas o CLAUDE.md ainda diz "use lib X", o Claude vai tentar usar e falhar.