TipsFeb 20, 2026·Code Velocity Academy

Boas Práticas de CLAUDE.md: Configure o Claude Code para Qualquer Projeto

CLAUDE.md é a configuração de maior impacto do Claude Code. Um bem escrito transforma assistência genérica de IA em expertise específica do projeto.

CLAUDE.md é um arquivo markdown na raiz do seu projeto. O Claude Code o lê no início de cada sessão, antes de você digitar qualquer coisa. Um bom CLAUDE.md transforma IA genérica em uma ferramenta que entende as convenções, stack técnica e limites do seu projeto.

O que incluir no CLAUDE.md?

Foque em informações que um desenvolvedor inteligente entrando no time precisaria no primeiro dia. Mantenha prático: stack técnica, comandos, convenções e coisas a evitar.

Template mínimo de CLAUDE.md

markdown

# Contexto do Projeto

App Next.js 14 com TypeScript, Tailwind CSS e Prisma.
Banco: PostgreSQL. Auth: NextAuth.js.

## Comandos
- `npm run dev` — iniciar servidor de dev (porta 3000)
- `npm run test` — rodar testes Jest
- `npm run lint` — rodar ESLint
- `npm run db:migrate` — rodar migrações Prisma

## Arquitetura
- Server components por padrão, client components em /components/client/
- Rotas API em /app/api/ com validação Zod
- Queries de banco em /lib/db/ (nunca em componentes)

## Convenções
- TypeScript strict mode, nunca use `any`
- Tailwind para estilização, sem CSS modules
- Conventional commits: feat:, fix:, chore:

## NÃO faça
- Modificar arquivos em /legacy/ ou /vendor/
- Alterar configuração de auth sem aprovação explícita
- Adicionar novas dependências sem perguntar primeiro

Quais são os erros mais comuns no CLAUDE.md?

Erro	Por que prejudica	Correção
Muito longo (500+ linhas)	Desperdiça janela de contexto em cada sessão	Mantenha abaixo de 200 linhas, link para docs para detalhes
Muito vago ("escreva código limpo")	Não dá orientação acionável	Seja específico: "Use server components por padrão"
Comandos faltando	Claude adivinha como rodar/testar/buildar	Liste todo script npm relevante
Sem restrições	Claude pode modificar arquivos sensíveis	Adicione uma seção clara "NÃO faça"
Duplicata do README	README é para humanos, CLAUDE.md é para IA	Foque em convenções e regras, não descrição do projeto

Como estruturar o CLAUDE.md para projetos grandes?

Para codebases grandes, use a sintaxe @import para dividir configuração entre diretórios. O Claude Code segue os imports e constrói o quadro completo.

markdown

# CLAUDE.md raiz

## Convenções globais
- TypeScript strict, sem `any`
- Todas as rotas API validam input com Zod

@import packages/api/CLAUDE.md
@import packages/web/CLAUDE.md
@import packages/shared/CLAUDE.md

Cada sub-CLAUDE.md contém regras específicas daquele pacote. Isso mantém o arquivo raiz curto enquanto dá ao Claude Code contexto profundo sobre cada área da codebase.

Como gerar o CLAUDE.md automaticamente?

O Claude Code pode gerar um CLAUDE.md inicial analisando seu projeto:

bash

# Auto-gerar CLAUDE.md
claude /init

# Isso cria um CLAUDE.md baseado em:
# - Scripts do package.json
# - Estrutura do projeto
# - Arquivos de config existentes
# - Padrões do histórico git

DICA

Comece com /init, depois refine manualmente. O arquivo auto-gerado é um bom ponto de partida, mas não vai saber as convenções não escritas do seu time. Adicione essas você mesmo.

E a hierarquia de memória do CLAUDE.md?

O Claude Code lê arquivos CLAUDE.md de múltiplos locais, em ordem de prioridade:

+CLAUDE.md na raiz do projeto (todos no time compartilham)
+Arquivos CLAUDE.md em subdiretórios (via @import)
+~/.claude/CLAUDE.md (suas preferências pessoais globais)
+Auto Memory (MEMORY.md, gerenciado pelo comando /memory)

Configurações de projeto sobrescrevem as pessoais. Isso significa que convenções do time sempre ganham de preferências individuais.

Perguntas frequentes

Devo commitar o CLAUDE.md no git?+

Sim. CLAUDE.md é um recurso do time, como .editorconfig ou .eslintrc. Commitá-lo garante que todo desenvolvedor no time tenha o mesmo comportamento da IA. Se você tem preferências pessoais, coloque em ~/.claude/CLAUDE.md.

Com que frequência devo atualizar o CLAUDE.md?+

Atualize sempre que as convenções do projeto mudarem. Adicione novos comandos, atualize notas de arquitetura e refine restrições conforme aprende onde o Claude Code precisa de orientação. Uma revisão trimestral é uma boa cadência mínima.

O CLAUDE.md funciona com outras ferramentas de IA?+

CLAUDE.md é específico do Claude Code. O Cursor usa .cursorrules para propósito similar. Os conceitos são transferíveis, mas o formato do arquivo não. Alguns times mantêm ambos os arquivos a partir de uma fonte única de verdade.

Qual a diferença entre CLAUDE.md e Skills?+

CLAUDE.md fornece contexto e regras do projeto que se aplicam a toda sessão. Skills são templates de comandos reutilizáveis para tarefas específicas (ex: "deploy para staging"). Pense no CLAUDE.md como o documento de briefing e Skills como o playbook de ações.