CLAUDE.md — o manual do seu projeto

CLAUDE.md é o README que você escreve pro Claude, não pro humano. Toda sessão ele lê esse arquivo e ajusta o comportamento a partir dele.

Onde fica

Três lugares, em ordem de prioridade:

1. ~/.claude/CLAUDE.md — global, vale pra tudo que você faz
2. <projeto>/CLAUDE.md — específico do repo, commitado junto com o código
3. <subpasta>/CLAUDE.md — contexto local (ex: backend/CLAUDE.md com convenções só do backend)

O do projeto é o que mais importa. Commita no git — o time inteiro se beneficia.

O que incluir

Coisas que o Claude não adivinha só olhando o código:

• Comandos: como rodar testes, build, lint, migrations
• Convenções: “sempre usa pnpm, nunca npm”, “testes ficam ao lado do arquivo, não em __tests__”
• Arquitetura mínima: onde fica o que, o que é legado, o que tá sendo migrado
• Decisões já tomadas: “não usamos ORM, SQL cru mesmo”
• O que NÃO mexer: “não edita generated/, é gerado por codegen”

O que NÃO incluir

• Documentação longa de features (isso é README)
• Lista exaustiva de todos os arquivos (ele descobre sozinho)
• Repetir o que já tá claro no código
• Linhas sobre “seja cuidadoso”, “pense antes de agir” — não ajuda
• Histórico, changelog, roadmap

Cada linha de CLAUDE.md vira token em toda sessão. Enxuto é melhor que completo.

Exemplo ruim

# Sobre o projeto

Este é um projeto muito importante da empresa, desenvolvido
com muito carinho. Por favor, seja cuidadoso ao editar.

Temos muitos arquivos no src/, incluindo components/, utils/,
services/, hooks/, types/, e também temos testes em __tests__/.

Seja organizado. Escreva código limpo. Pense antes de agir.

Não diz nada acionável. Vai pro lixo.

Exemplo bom

# Stack
- Next.js 15 (App Router), TypeScript strict, pnpm
- Drizzle ORM + Postgres, Vitest pra testes

# Comandos
- `pnpm dev` — dev server
- `pnpm test` — roda testes (sempre rodar antes de commit)
- `pnpm db:push` — aplica schema no DB local

# Convenções
- Server components por padrão. `"use client"` só quando precisar.
- Testes ao lado do arquivo: `foo.ts` → `foo.test.ts`
- Nada de `any`. Se precisar, comenta o porquê.

# Não mexer
- `src/generated/` — gerado por `drizzle-kit`
- `legacy/` — em processo de migração, vai ser deletado

Direto, acionável, sem enrolação.

Gotcha

Revisa o CLAUDE.md a cada 2-3 meses. Convenção que caiu, stack que mudou, comando que virou outro — tudo isso polui o contexto e confunde o modelo. Arquivo vivo, não monumento.