O que é CLAUDE.md e Por Que É Essencial

Imagine contratar um desenvolvedor talentoso que, toda manhã, esquece tudo sobre o projeto. Esquece a stack. Esquece as convenções. Esquece onde ficam os arquivos. Você precisa explicar tudo de novo. Toda. Vez.

É exatamente assim que o Claude Code funciona sem um CLAUDE.md.

CLAUDE.md é um arquivo Markdown que fica na raiz do seu projeto. O Claude Code lê esse arquivo automaticamente no início de cada sessão. Sem configuração especial, sem sintaxe proprietária. Apenas um arquivo de texto que dá contexto ao Claude sobre quem é seu projeto, como ele funciona e o que importa.

É a diferença entre um assistente genérico e um que conhece sua casa.

O Problema que CLAUDE.md Resolve

Sem CLAUDE.md, toda sessão começa do zero. O Claude Code é inteligente o suficiente para ler seus arquivos e inferir muita coisa. Mas inferência leva tempo e nem sempre acerta.

O Claude Code opera como um assistente agentic — ele lê arquivos, executa comandos, edita código. Porém, quando inicia uma nova sessão, não tem memória do que aconteceu antes. Não sabe quais decisões foram tomadas, quais padrões foram estabelecidos, quais erros já foram cometidos e corrigidos.

Situações comuns sem CLAUDE.md:

Você pede uma alteração e o Claude usa CSS puro. Seu projeto inteiro usa Tailwind.
Ele cria um componente com var em vez de const. Sua equipe padronizou const/let há anos.
Você pede para rodar os testes e ele tenta npm test. Seu projeto usa pnpm vitest run.
Ele coloca um arquivo novo em /utils/. Seu padrão é /lib/.
Cria um endpoint REST quando você decidiu usar Server Actions para tudo.
Sugere instalar uma biblioteca que você já descartou na semana passada.

Cada correção dessas leva 30 segundos. Multiplicado por 20 vezes ao dia, são 10 minutos perdidos. Em uma semana, mais de uma hora. Repetindo as mesmas instruções que nunca mudam.

O mais frustrante: essas não são informações que mudam. Sua stack é a mesma hoje e amanhã. Seus comandos são os mesmos. Suas convenções são as mesmas. Repetir isso é desperdício puro.

Com CLAUDE.md, essas informações estão documentadas uma vez. O Claude lê, aplica e segue em frente.

Como Funciona

A mecânica é simples:

Crie um arquivo chamado CLAUDE.md na raiz do seu projeto
Escreva as informações relevantes em Markdown
Inicie o Claude Code normalmente

Pronto. Não precisa instalar nada, configurar nada, ativar nada. O Claude Code detecta o arquivo automaticamente e o carrega como contexto antes de processar qualquer comando seu.

Pense no CLAUDE.md como a documentação de onboarding para um novo membro da equipe. A diferença é que esse membro lê o documento inteiro, com atenção, toda vez. Sem pular parágrafos, sem esquecer detalhes.

O formato é Markdown puro — o mesmo usado em README, documentação, e milhares de outros arquivos. Se você já escreveu uma lista com hífens ou usou # para títulos, já sabe o suficiente. Se nunca viu Markdown, aprende em 5 minutos.

O Que Colocar no Seu CLAUDE.md

Nem tudo precisa estar lá. O segredo é incluir o que o Claude não consegue descobrir sozinho — ou o que ele erraria sem orientação explícita.

Visão geral do projeto

O que o projeto faz, para quem, em poucas linhas. Isso ajuda o Claude a tomar decisões alinhadas com o propósito.

Stack e tecnologias

As tecnologias que você usa, com versões quando relevante. Isso evita sugestões incompatíveis.

Comandos essenciais

Como rodar o projeto, executar testes, fazer build, deploy. Claude usa essas informações quando precisa rodar algo.

Convenções de código

Padrões de nomenclatura, estrutura de pastas, patterns preferidos. Tudo que um dev novo precisaria saber para escrever código "da casa".

Decisões de arquitetura

Por que você escolheu X em vez de Y. Sem isso, o Claude pode sugerir alternativas que você já descartou.

Armadilhas conhecidas

Bugs recorrentes, limitações, coisas que parecem certas mas quebram. Documentar evita que o Claude tropece nos mesmos problemas.

Exemplo Mínimo

Para um projeto simples, 15 linhas bastam:

# Meu App

App de lista de tarefas com autenticação.

## Stack
- Next.js 16 + TypeScript
- Tailwind CSS + Shadcn UI
- PostgreSQL + Prisma

## Comandos
- `pnpm dev` — servidor de desenvolvimento
- `pnpm test` — testes com Vitest
- `pnpm build` — build de produção

## Convenções
- Arquivos em kebab-case, componentes em PascalCase
- Server Components como padrão, Client Components só quando necessário

Com essas poucas linhas, o Claude já sabe usar pnpm (e não npm), já sabe que você usa Tailwind (e não CSS puro), e já vai nomear arquivos corretamente.

Perceba: não há nada complicado. São informações que você já tem na cabeça. O CLAUDE.md apenas tira essas informações da sua cabeça e coloca num lugar onde o Claude pode acessar sem perguntar.

Exemplo Completo

Para projetos maiores, vale detalhar mais:

# Portal Acme Corp

Portal de e-commerce B2B com painel administrativo e API pública.

## Stack
- Next.js 16 + TypeScript 5.9 (strict mode)
- Tailwind CSS 4 + Shadcn UI
- PostgreSQL + Prisma 7 (ORM)
- TanStack Query v5 (cache client-side)
- pnpm como package manager

## Comandos
- `pnpm dev` — servidor local (porta 3000)
- `pnpm build` — build de produção (standalone)
- `pnpm test` — testes unitários com Vitest
- `pnpm test:e2e` — testes E2E com Playwright
- `pnpm lint` — ESLint + Prettier
- `pnpm db:migrate` — rodar migrations do Prisma
- `pnpm db:studio` — abrir Prisma Studio

## Estrutura de Diretórios
- `src/app/` — rotas (App Router)
- `src/components/ui/` — componentes Shadcn
- `src/components/` — componentes do projeto
- `src/lib/actions/` — Server Actions (mutações)
- `src/lib/queries/` — queries do banco
- `src/lib/validators/` — schemas Zod

## Convenções
- Arquivos em kebab-case, componentes em PascalCase
- Server Components como padrão
- Toda mutação via Server Actions (nunca fetch manual)
- Validação com Zod em formulários e payloads de API
- Imports de componentes Shadcn via barrel `@ui`

## Decisões de Arquitetura
- Prisma direto em Server Components (sem camada de abstração)
- Estado: local → Context → URL → Server → Zustand (escalar só se necessário)
- Auth via NextAuth com adapter Prisma

## Armadilhas
- Prisma 7+ não roda generate automaticamente após migrate
- Standalone do Next.js não inclui node_modules — usar multi-stage Docker build
- Alpine Linux resolve localhost como IPv6 — usar 0.0.0.0 em healthchecks

Esse nível de detalhe pode parecer muito. Mas cada linha evita uma pergunta, uma correção ou um erro. O investimento se paga na primeira sessão.

Note a seção "Armadilhas" no final. Essa é talvez a parte mais valiosa do CLAUDE.md. São aquelas coisas que você descobriu na marra — depois de horas debugando — e que quer garantir que nunca mais aconteçam. Quando o Claude sabe dessas armadilhas, ele as evita proativamente.

A Hierarquia de Arquivos CLAUDE.md

O Claude Code não lê apenas um CLAUDE.md. Ele suporta três níveis, cada um com um propósito diferente.

`~/.claude/CLAUDE.md` — Global

Suas preferências pessoais que valem para todos os projetos. Idioma preferido, estilo de comunicação, regras gerais de código.

# Preferências Globais

## Idioma
- Código em inglês (variáveis, funções, classes)
- Comunicação e documentação em português

## Padrões
- Sempre usar TypeScript strict
- Preferir const sobre let
- JSDoc em funções exportadas

`./CLAUDE.md` — Projeto (compartilhado)

Na raiz do projeto. Este é o principal. Vai para o git, é compartilhado com a equipe. Contém tudo específico do projeto: stack, comandos, convenções, arquitetura.

`./.claude/CLAUDE.md` — Projeto (pessoal)

Dentro da pasta .claude/ do projeto. Normalmente no .gitignore. Suas configurações pessoais para aquele projeto específico que não precisam ser compartilhadas.

# Notas Pessoais

- Estou trabalhando na feature de pagamentos (branch feat/payments)
- O endpoint /api/webhooks/stripe está incompleto — não testar em produção
- Usar o banco de dev local (porta 5433), não o compartilhado

Como se combinam

O Claude Code lê os três na seguinte ordem:

Global (~/.claude/CLAUDE.md)
Projeto compartilhado (./CLAUDE.md)
Projeto pessoal (./.claude/CLAUDE.md)

Todos são aplicados juntos. Quando há conflito, o mais específico prevalece. Se o global diz "use npm" mas o projeto diz "use pnpm", o Claude usa pnpm.

Antes e Depois: O Impacto Real

A melhor forma de entender o valor é comparar sessões com e sem CLAUDE.md.

Sem CLAUDE.md

Você: Crie um componente de card de produto

Claude: *cria com CSS modules e classes genéricas*

Você: Não, use Tailwind. E Shadcn UI.

Claude: *refaz com Tailwind mas sem Shadcn*

Você: Use o componente Card do Shadcn.

Claude: *importa de @/components/ui/card*

Você: Não, importe via @ui, é o nosso barrel.

Claude: *finalmente acerta*

Quatro mensagens desperdiçadas. Tempo perdido. Frustração acumulada.

Com CLAUDE.md

Você: Crie um componente de card de produto

Claude: *cria usando Tailwind + Shadcn Card importado via @ui,
        seguindo as convenções de nomenclatura do projeto*

Uma mensagem. Resultado correto na primeira tentativa.

Multiplique isso por cada tarefa do dia. A diferença é brutal.

E não é só sobre economizar tempo. É sobre fluxo. Quando você precisa corrigir o Claude a cada mensagem, perde o ritmo. Perde a concentração. Em vez de pensar no próximo feature, está pensando "ele vai lembrar de usar Tailwind dessa vez?". Com CLAUDE.md, você confia que o resultado vai sair certo. Isso muda completamente a experiência de usar Claude Code.

Dicas para Manter o CLAUDE.md

Comece pequeno

Não tente documentar tudo de uma vez. Comece com stack, comandos e 3-4 convenções. Isso já cobre 80% dos casos.

Evolua com a prática

Toda vez que você corrigir o Claude na mesma coisa duas vezes, adicione ao CLAUDE.md. Esse é o sinal de que a informação precisa estar documentada.

Mantenha conciso

O Claude lê o CLAUDE.md inteiro em toda sessão. Cada linha consome tokens do contexto. Seja direto. Se algo pode ser dito em uma linha, não use três.

Versione com git

CLAUDE.md é documentação do projeto. Vai para o repositório, recebe code review como qualquer outro arquivo. Quando a stack muda, o CLAUDE.md muda junto.

Revise periodicamente

A cada mês, releia seu CLAUDE.md. Remova o que ficou obsoleto. Atualize o que mudou. Um CLAUDE.md desatualizado é pior que nenhum — dá instruções erradas.

Use o próprio Claude para ajudar

Um truque poderoso: peça ao Claude Code para analisar seu projeto e sugerir o que deveria estar no CLAUDE.md. Ele conhece o código, sabe quais tecnologias estão no package.json, entende a estrutura de pastas. É um ótimo ponto de partida.

Não duplique o que é óbvio

Se algo já está explícito no código (como o nome do framework no package.json), não precisa repetir no CLAUDE.md. Foque no que é implícito — convenções, decisões, preferências que não estão escritas em lugar nenhum.

CLAUDE.md vs Outros Arquivos

Uma dúvida comum: "mas isso não é a mesma coisa que README.md?" Não. São complementares.

Arquivo	Para Quem	Propósito
CLAUDE.md	Claude Code (IA)	Contexto e regras para a IA seguir
README.md	Humanos (devs, usuários)	Documentação do projeto para pessoas
.editorconfig	Editores de código	Formatação (tabs, espaços, encoding)
.cursorrules	Cursor (IA)	Equivalente do CLAUDE.md para o Cursor

README.md explica como usar o projeto para humanos. CLAUDE.md diz como trabalhar no projeto para a IA. Pode haver sobreposição? Sim. Mas o foco é diferente.

.editorconfig cuida de formatação básica (indentação, fim de linha). CLAUDE.md cuida de comportamento, decisões e contexto — coisas que nenhum arquivo de configuração cobre.

.cursorrules é o equivalente do Cursor. Se você usa ambas as ferramentas, pode ter os dois arquivos. O conteúdo será parecido, mas cada formato tem suas particularidades.

Conclusão

CLAUDE.md é, sem exagero, o arquivo mais importante do seu projeto quando você trabalha com Claude Code. Ele transforma cada sessão de "explicar tudo do zero" para "continuar de onde parou".

Não precisa ser perfeito. Não precisa ser longo. Precisa existir.

Crie o seu agora. Comece com 10 linhas. Vá adicionando conforme sentir necessidade. Em uma semana, você não vai entender como trabalhava sem ele.

Se você é novo no Claude Code, comece pelo guia de primeiros passos. Se já está usando e quer ir além, o Claude Code Guide ensina a construir um CLAUDE.md avançado como parte do fluxo completo de desenvolvimento com IA.

Referências

How Claude remembers your project — Claude Code Docs — Documentação oficial sobre CLAUDE.md e memória persistente
Claude Code settings — Claude Code Docs — Configurações e escopos de arquivos CLAUDE.md
How Claude Code works — Claude Code Docs — Como o Claude Code funciona internamente

O que é CLAUDE.md e Por Que É Essencial no Claude Code