🧠 CLAUDE.md — O Cerebro do Projeto

O CLAUDE.md e um arquivo Markdown que o Claude Code le automaticamente no inicio de cada sessao. Ele funciona como um system prompt persistente: tudo que voce escrever ali vai influenciar como o Claude se comporta dentro do seu projeto. Nao e uma sugestao, e uma instrucao. O modelo trata o conteudo do CLAUDE.md como diretriz de alta prioridade.

Sem CLAUDE.md, o Claude Code e generico. Ele nao sabe que seu projeto usa TypeScript, que voce prefere tabs em vez de spaces, que ha uma convencao de nomes especifica. Com CLAUDE.md, ele vira um especialista no seu projeto desde a primeira mensagem. A diferenca e dramatica: em vez de perguntar "qual framework voce usa?", ele ja sabe e age de acordo.

O mecanismo e simples: quando voce inicia uma sessao com claude, o agente procura arquivos CLAUDE.md no seu ambiente, le o conteudo e injeta como parte do system prompt. Isso acontece antes de voce digitar qualquer coisa. E como um briefing automatico que o agente recebe toda manhã antes de comecar a trabalhar.

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). Os tres sao lidos e concatenados para formar o contexto completo.

A cascata funciona por adicao: o conteudo de cada nivel se soma ao anterior. O global define preferencias pessoais ("nunca use em dashes", "prefira TypeScript"). O de projeto define stack e convencoes. O de pasta define regras especificas daquela area do codigo. Os tres juntos formam o contexto completo que o agente recebe.

Essa hierarquia e poderosa porque permite separacao de responsabilidades. Voce define suas preferencias pessoais uma vez (global) e nunca mais precisa repetir em cada projeto. Cada projeto define suas proprias regras sem interferir nos outros. E subpastas especiais (como src/api/) podem ter regras adicionais sem poluir o CLAUDE.md principal.

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

# Todos sao lidos e somados. Mais especifico refina o geral.

O formato e Markdown puro. Use headings (## Stack, ## Convencoes), 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". O modelo obedece instrucoes diretas com muito mais consistencia do que sugestoes vagas.

Algumas convencoes que funcionam bem: agrupar por secao (Stack, Convencoes, Proibicoes), 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. Cada linha do CLAUDE.md consome tokens da janela de contexto.

Evite redundancia com o que o modelo ja sabe. Nao precisa dizer "escreva codigo legivel" ou "use boas praticas". O Claude ja faz isso por padrao. O CLAUDE.md deve conter o que e diferente neste projeto ou na sua forma de trabalhar. Se o padrao funciona, nao gaste linhas com ele.

# Projeto XYZ

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

## Convencoes
- Arquivos: kebab-case (user-profile.ts)
- Componentes: PascalCase (UserProfile.tsx)
- NUNCA usar `any`. Sempre tipar explicitamente.

## Proibicoes
- NUNCA deletar arquivos sem confirmar
- NUNCA commitar .env ou secrets
- NUNCA usar console.log em producao

Os tipos de instrucao que mais impactam sao: stack e tecnologias ("este projeto usa Next.js 14 com App Router"), convencoes de codigo ("nomes de arquivo em kebab-case"), proibicoes explicitas ("NUNCA delete arquivos sem confirmar"), e padroes do projeto ("use o pattern de service layer em src/services/").

Proibicoes em caixa alta (NUNCA, SEMPRE) sao respeitadas com mais consistencia. Isso nao e supersticao: o modelo da mais peso a tokens enfaticos. Use com moderacao para nao virar ruido, mas nao hesite em usar quando a regra for critica. Um "NUNCA use sudo" bem posicionado pode prevenir acidentes serios.

Outra categoria poderosa: instrucoes de workflow. "Sempre rode testes antes de commitar", "peca confirmacao antes de deletar", "use git commit com mensagens em portugues". Essas instrucoes moldam como o agente trabalha, nao apenas o que ele produz. Elas transformam o Claude de ferramenta passiva em colega de trabalho com disciplina.

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

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

## Padroes
- API routes usam o pattern em src/app/api/[resource]/route.ts
- Validacao com Zod em todo input de API

## Workflow
- Sempre rode npm test antes de commitar
- Commit messages em portugues, imperativo

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 generico), e incluem pelo menos uma secao de proibicoes explicitas. Estudar exemplos reais e o atalho mais rapido para escrever um CLAUDE.md eficaz.

Um anti-pattern comum e o CLAUDE.md que tenta ensinar programacao 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. Outro anti-pattern: copiar a documentacao inteira do framework. O modelo ja conhece React, Next.js, etc. Diga qual versao usa e como usa, nao o que e.

Um exemplo excelente e o CLAUDE.md do proprio repositorio do Claude Code da Anthropic. Ele e conciso, foca em convencoes internas (como rodar testes, como commitar, quais padroes de arquitetura seguir), e tem proibicoes claras. Outro bom exemplo: projetos open source populares que adotaram a pratica e publicam seus CLAUDE.md no GitHub.

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 configuracao: versionado, revisado, e atualizado junto com o projeto. Pull requests que mudam a stack ou convencoes devem incluir a atualizacao correspondente no CLAUDE.md.

Uma rotina saudavel: revise o CLAUDE.md uma vez por mes ou quando mudar algo significativo no projeto (nova lib, novo padrao, novo membro no time). Entre revisoes, use /memory para adicionar notas rapidas que persistem sem editar o arquivo diretamente. O /memory e o atalho; o CLAUDE.md e a fonte canonica.

CLAUDE.md desatualizado e pior que nenhum, porque o agente vai seguir instrucoes erradas com confianca. Se removeu uma lib do projeto mas o CLAUDE.md ainda diz "use lib X", o Claude vai tentar usar e falhar. Se mudou de ORM, atualize o CLAUDE.md. Se mudou convencoes de naming, atualize. A regra e simples: se mudou no codigo, mude no CLAUDE.md.

Manutencao do CLAUDE.md:
[ ] Commitar no git junto com o codigo
[ ] Revisar mensalmente ou ao mudar stack
[ ] Remover instrucoes obsoletas imediatamente
[ ] Usar /memory pra notas rapidas entre revisoes
[ ] Incluir atualizacao em PRs que mudam convencoes
[ ] Manter entre 50-200 linhas (nao deixar inchar)