O Guia Completo para Escrever CLAUDE.md: Boas Práticas de Configuração de Projeto

O Que É CLAUDE.md?

CLAUDE.md é um arquivo de contexto que ajuda o Claude Code a entender seu projeto. Coloque-o na raiz do seu projeto, e o Claude Code o lê automaticamente no início de cada sessão. Um CLAUDE.md bem escrito pode melhorar drasticamente a qualidade das respostas do Claude Code.

Locais dos Arquivos e Prioridade

Você pode colocar arquivos CLAUDE.md em múltiplos locais, e todos são carregados:

~/.claude/CLAUDE.md          # Configurações globais (compartilhadas entre projetos)
./CLAUDE.md                   # Raiz do projeto (compartilhada com a equipe)
./CLAUDE.local.md             # Configurações locais (adicione ao .gitignore)
./src/CLAUDE.md               # Configurações de subdiretório

• Global: Suas preferências pessoais de estilo de código
• Raiz do projeto: Regras e tech stack compartilhados pela equipe
• Local: Configurações pessoais que não vão para o Git
• Subdiretório: Contexto adicional para módulos específicos

Template Inicial

Aqui está um template prático de CLAUDE.md:

# Visão Geral do Projeto

API backend de e-commerce. Gerencia pedidos, inventário e autenticação de usuários.

## Tech Stack

- Linguagem: TypeScript 5.x
- Runtime: Node.js 22
- Framework: Fastify
- DB: PostgreSQL 16 + Prisma ORM
- Testes: Vitest
- CI: GitHub Actions

## Estrutura de Diretórios

src/
  routes/       # Definições de endpoints da API
  services/     # Lógica de negócios
  repositories/ # Camada de acesso a dados
  middleware/   # Auth, logging, tratamento de erros
  utils/        # Funções utilitárias
  types/        # Definições de tipos

## Convenções de Código

- Usar arrow functions
- Sempre usar try-catch para tratamento de erros com classes de erro personalizadas
- Nomenclatura: camelCase (variáveis/funções), PascalCase (tipos/classes)
- Nomes de arquivo: kebab-case
- Usar alias de caminho `@/` em vez de imports relativos

## Comandos Comuns

- Executar testes: `npm test`
- Verificação de tipos: `npx tsc --noEmit`
- Lint: `npm run lint`
- Migração do DB: `npx prisma migrate dev`
- Servidor de dev: `npm run dev`

## Regras Importantes

- Sempre criar uma migration após alterar prisma/schema.prisma
- Todo endpoint de API deve ter um schema de validação Zod
- Registrar novas rotas em routes/index.ts

Dicas para Escrever CLAUDE.md Eficazes

1. Mantenha Conciso

O CLAUDE.md consome tokens da janela de contexto. Evite explicações verbosas e prefira tópicos.

# Exemplo ruim
Este projeto usa TypeScript. TypeScript é uma linguagem desenvolvida
pela Microsoft que adiciona tipos ao JavaScript...

# Exemplo bom
- Linguagem: TypeScript 5.x (modo strict)

2. Documente o Que Você Não Quer

Listar explicitamente anti-padrões é surpreendentemente eficaz.

## Proibido

- Nenhum tipo `any`
- Nenhum default export (apenas exports nomeados)
- Nenhum console.log para debug (use o logger)
- Nunca deletar ou pular testes existentes

3. Defina Workflows

Oriente o Claude Code sobre como as tarefas devem ser abordadas.

## Adicionando uma Nova Funcionalidade

1. Criar definições de tipo em `src/types/`
2. Implementar a camada de acesso a dados em `src/repositories/`
3. Implementar a lógica de negócios em `src/services/`
4. Definir endpoints em `src/routes/`
5. Escrever testes unitários para cada camada
6. Verificar que todos os testes passam com `npm test`

4. Capture o Conhecimento Tribal

Documente informações importantes que não estão escritas em nenhum outro lugar.

## Notas Específicas do Projeto

- `user_id` usa UUID v7 (para ordenação cronológica)
- Todos os cálculos de preço devem usar `Decimal.js` (para evitar erros de ponto flutuante)
- Variáveis de ambiente são centralizadas em `src/config.ts` — nunca acesse process.env diretamente

Uso em Equipe

Configuração do .gitignore

Mantenha configurações pessoais fora do controle de versão:

# .gitignore
CLAUDE.local.md

Inclua nas Revisões de Código

Trate o CLAUDE.md como um documento importante do projeto. Inclua-o nas revisões de PRs e mantenha-o atualizado como equipe.

Quando Atualizar o CLAUDE.md

• Ao adicionar uma nova biblioteca
• Ao mudar convenções de código
• Ao reestruturar diretórios
• Quando perceber que o Claude Code está cometendo o mesmo erro repetidamente

Conclusão

O CLAUDE.md transforma o Claude Code em um especialista no seu projeto específico. Comece gerando uma base com /init, depois refine conforme trabalha. Compartilhe com sua equipe para que todos se beneficiem de interações otimizadas com o Claude Code.