Estou usando Claude Code diariamente desde o início de 2025, e posso te dizer que o fator mais importante para obter resultados úteis não é engenharia de prompts ou truques inteligentes. É contexto. Especificamente, é um arquivo CLAUDE.md bem escrito na raiz do seu projeto. Este único arquivo faz a diferença entre um assistente de IA que luta com sua base de código e um que se sente como um dev sênior que está na sua equipe há meses.

Se você tem jogado prompts para Claude Code e recebido resultados genéricos, incorretos ou frustrantes, este guia é para você. Vou detalhar exatamente como estruturar seu CLAUDE.md, o que incluir, o que deixar de fora, e compartilhar exemplos reais de projetos em produção que lançamos na Social Animal.

Índice

O que é CLAUDE.md e Por Que Importa

CLAUDE.md é um arquivo markdown que você coloca na raiz do seu repositório que Claude Code lê automaticamente toda vez que inicia uma sessão. Pense nele como documentação de onboarding para seu pair programmer de IA. Quando um novo dev entra na sua equipe, você não apenas entrega um laptop e diz "descobre aí". Você o guia pela arquitetura, explica as partes estranhas, aponta as armadilhas. CLAUDE.md faz o mesmo para Claude.

Sem ele, Claude Code tem que inferir tudo da sua estrutura de arquivos, package.json, e qualquer arquivo que aconteça de ler. É como pedir a um novo contratado entender todo o sistema lendo arquivos fonte aleatórios. Ele vai acertar algumas coisas, mas também vai fazer suposições que desperdiçam o tempo de todos.

Com um CLAUDE.md sólido, já vi a precisão de conclusão de tarefas saltar de aproximadamente 60% para mais de 90% nas primeiras tentativas. Isso não é uma melhoria pequena — é a diferença entre desenvolvimento assistido por IA ser um multiplicador de produtividade e ser um sumidouro de tempo frustrante.

Como Claude Code Lê o Contexto do Seu Projeto

Claude Code tem uma hierarquia específica para carregar contexto. Entender isto importa porque afeta como você organiza a memória do seu projeto.

A Ordem de Carregamento de Contexto

  1. ~/.claude/CLAUDE.md — Suas preferências globais (aplicadas a todos os projetos)
  2. ./CLAUDE.md — O arquivo no nível do projeto na raiz do seu repo
  3. ./subdirectory/CLAUDE.md — Sobrescrita específica do diretório
  4. .claude/settings.json — Permissões de ferramentas específicas do projeto e configurações
  5. Contexto de sessão — O que você diz ao Claude na conversa atual

O CLAUDE.md no nível do projeto é onde você gastará a maioria do seu tempo. O arquivo global é bom para preferências pessoais ("prefiro componentes funcionais" ou "sempre use TypeScript strict mode"), mas o verdadeiro valor está no contexto por projeto.

Aqui está o que é crucial: Claude Code lê o CLAUDE.md no início de cada sessão, mas também tem espaço limitado na janela de contexto. Se seu CLAUDE.md tem 5.000 palavras de documentação divagante, você está queimando tokens que poderiam ser usados para raciocínio real de código. Seja conciso. Seja específico. Cada linha deve merecer seu lugar.

A Anatomia de um Ótimo Arquivo CLAUDE.md

Depois de escrever e refinar arquivos CLAUDE.md em dezenas de projetos — apps Next.js, sites Astro, integrações de CMS headless, serviços de API — cheguei a uma estrutura consistente que funciona.

A Estrutura Ideal

# Nome do Projeto

## Visão Geral
Um parágrafo explicando o que este projeto faz e para quem.

## Tech Stack
Versões exatas e frameworks.

## Arquitetura
Como as peças se encaixam.

## Convenções Principais
Padrões de código, nomes de padrões, regras de organização de arquivos.

## Comandos Comuns
Build, test, deploy, e comandos dev.

## Contexto Importante
Coisas que não são óbvias do código.

## Problemas Conhecidos / Armadilhas
Armadilhas para evitar.

## NÃO Faça
Coisas explícitas que a IA nunca deve fazer.

Vamos aprofundar em cada seção.

Análise Seção por Seção

Visão Geral

Mantenha isto em 2-3 frases no máximo. Claude não precisa do seu roadmap de produto — precisa entender o domínio para poder tomar decisões contextualmente apropriadas.

## Visão Geral
Este é o site de marketing da Acme Corp, uma plataforma SaaS B2B para gerenciamento de cadeia de suprimentos. O site é gerado estaticamente com rotas de API dinâmicas para manipulação de formulários e captura de leads. O conteúdo é gerenciado através do Sanity CMS pela equipe de marketing.

Tech Stack

Seja exato. Não apenas diga "React" — especifique a versão, o framework, a estratégia de renderização. Isto previne Claude de sugerir padrões que funcionam em React 18 mas quebram em React 19, ou recomendar Pages Router quando você está em App Router.

## Tech Stack
- **Framework**: Next.js 15.1 (App Router, RSC por padrão)
- **Linguagem**: TypeScript 5.7 (modo strict)
- **Estilo**: Tailwind CSS v4 com configuração CSS-first
- **CMS**: Sanity v3 com live preview
- **Deploy**: Vercel (ambientes Production + Preview)
- **Gerenciador de Pacotes**: pnpm 9.x
- **Node**: v22 LTS
- **Testes**: Vitest + Playwright
- **Gerenciamento de Estado**: Zustand (mínimo, apenas para estado de UI do lado do cliente)

Arquitetura

Este é o lugar onde a maioria das pessoas escreve muito pouco ou muito. Você não está escrevendo um doc de design de sistema. Você está dando ao Claude um modelo mental.

## Arquitetura
- `app/` — Páginas e layouts do App Router do Next.js
- `app/api/` — Rotas de API (envios de formulário, webhooks)
- `components/` — Componentes de UI compartilhados (design atômico: atoms/, molecules/, organisms/)
- `lib/` — Funções utilitárias, clientes de API, definições de tipo
- `lib/sanity/` — Cliente Sanity, queries (GROQ), e geração de tipo
- `content/` — Arquivos MDX para posts de blog (co-localizados com frontmatter)
- `public/` — Ativos estáticos (prefira next/image para todas as imagens)

Fluxo de dados: Sanity CMS → Queries GROQ em lib/sanity/queries.ts → Componentes do Servidor → Componentes do Cliente (apenas quando interatividade é necessária)

Todas as páginas são geradas estaticamente no tempo de build exceto /blog/[slug]/preview que usa modo draft.

Convenções Principais

Esta seção economiza mais tempo. Sem ela, Claude seguirá as melhores práticas gerais que podem conflitar com as escolhas da sua equipe.

## Convenções Principais
- Componentes são nomeados em PascalCase, um componente por arquivo
- Use named exports, nunca default exports (exceto pages/layouts)
- Toda busca de dados acontece em Componentes do Servidor — nunca use useEffect para buscar dados
- Tipos de resposta de API vivem em lib/types/ e são auto-gerados do schema Sanity
- Use utilidade `cn()` (lib/utils.ts) para mesclagem de classes condicional, não template literals
- Error boundaries envolvem cada seção de página principal, não a página inteira
- Todo formulário usa react-hook-form + schemas de validação zod
- Mensagens de commit seguem Conventional Commits (feat:, fix:, chore:)

Comandos Comuns

Isto parece básico, mas Claude Code realmente executa esses comandos. Se não souber os corretos, vai adivinhar, e frequentemente vai adivinhar errado.

## Comandos Comuns
- `pnpm dev` — Inicia servidor de desenvolvimento (porta 3000)
- `pnpm build` — Build de produção
- `pnpm lint` — Verificação ESLint + Prettier
- `pnpm test` — Executa testes unitários Vitest
- `pnpm test:e2e` — Executa testes E2E Playwright
- `pnpm sanity:typegen` — Regenera tipos Sanity após mudanças no schema
- `pnpm db:migrate` — Executa migrações Drizzle ORM

Contexto Importante

Isto é para coisas que Claude não pode descobrir lendo seu código. Lógica de negócio, restrições externas, coisas que levariam um revisor humano 30 minutos para explicar.

## Contexto Importante
- Usamos ISR (revalidate: 3600) para todas as páginas do CMS. Nunca use `force-dynamic` a menos que absolutamente necessário.
- O webhook Sanity em /api/revalidate manipula revalidação sob demanda — não adicione lógica de revalidação manual.
- Otimização de imagem passa pela CDN Sanity (cdn.sanity.io), não next/image para conteúdo do CMS.
- Auth é manipulado por Clerk — nunca construa fluxos de auth customizados.
- O endpoint /api/leads tem rate limiting via Upstash Redis. Não remova o middleware de rate limit.

Armadilhas Conhecidas

Todo projeto tem coisas estranhas. Coloque aqui para que Claude não tropece nelas.

## Armadilhas Conhecidas
- O renderizador portable text do Sanity tem um bug com listas aninhadas na v3.2. Usamos um serializador customizado em components/portable-text/list-fix.tsx
- Tailwind v4 não suporta a diretiva `@apply` em arquivos CSS de módulo — use classes inline em vez disso
- O vercel.json rewrite para /docs/* faz proxy para nosso site de docs Mintlify. Não modifique estes sem verificar com o time.
- Variáveis de ambiente prefixadas com NEXT_PUBLIC_ são as únicas disponíveis no lado do cliente. Nunca exponha segredos de API desta forma.

A Seção "NÃO Faça"

Esta é argumentavelmente a seção mais importante. Instruções negativas são incrivelmente efetivas com modelos de IA.

## NÃO Faça
- Não instale novas dependências sem perguntar primeiro
- Não use tipo `any` — encontre ou crie tipos próprios
- Não crie novas rotas de API para coisas que podem ser feitas em Componentes do Servidor
- Não modifique os arquivos schema Sanity sem confirmar o plano de migração
- Não use `"use client"` a menos que o componente genuinamente precise de APIs do navegador ou manipuladores de evento
- Não escreva arquivos CSS — tudo é classes utilitárias Tailwind
- Não hardcode strings que deveriam vir do CMS

Exemplos Reais de CLAUDE.md

Exemplo: Site de Marketing Next.js

Esta é uma versão reduzida de um CLAUDE.md que usamos em projetos de cliente, particularmente ao construir sites Next.js com backends de CMS headless.

# Site de Marketing Acme

## Visão Geral
Site de marketing para Acme (acme.com). Construído com Next.js 15, estilizado com Tailwind v4, conteúdo do Sanity CMS. Objetivo: LCP sub-2s em todas as páginas.

## Tech Stack
Next.js 15.1 | TypeScript 5.7 strict | Tailwind v4 | Sanity v3 | Vercel | pnpm

## Arquitetura
App Router com RSC. Toda busca de dados em componentes server via queries GROQ em lib/sanity/queries.ts. Componentes client apenas para elementos interativos (modais, formulários, carrosséis).

Páginas: / (home), /about, /pricing, /blog, /blog/[slug], /contact

## Convenções
- Apenas named exports (exceto page.tsx/layout.tsx)
- Componentes: PascalCase, um por arquivo
- cn() para mesclagem de classe
- Schemas Zod para toda validação de formulário
- Sem useEffect para busca de dados. Nunca.

## Comandos
pnpm dev | pnpm build | pnpm lint | pnpm test

## NÃO Faça
- Adicione "use client" sem justificação
- Instale pacotes sem perguntar
- Use default exports para componentes
- Modifique sanity/schema/ sem confirmar migração
- Use tipo any

Exemplo: Site de Conteúdo Astro

Para projetos Astro, o CLAUDE.md parece um pouco diferente porque o paradigma de arquitetura é diferente.

# Tech Blog — Astro

## Visão Geral
Blog de developer com 500+ artigos. Estático-primeiro, zero JS por padrão. MDX para conteúdo com componentes customizados.

## Tech Stack
Astro 5.x | MDX | Tailwind v4 | Deployado em Cloudflare Pages | Content Collections v2

## Arquitetura
src/content/ — Artigos MDX com frontmatter validado por Zod
src/components/ — Componentes Astro (zero JS) e ilhas React (interativas)
src/layouts/ — Layouts base
src/pages/ — Roteamento baseado em arquivo

## Regras Principais
- Padrão para componentes Astro (.astro). Use React apenas para ilhas que precisam de interatividade.
- client:visible para componentes interativos abaixo da dobra
- client:idle para componentes interativos não-críticos
- Nunca use client:load a menos que absolutamente necessário
- Todas as imagens usam componente Image do Astro com width/height apropriados
- Feed RSS auto-gera da content collection — não construa lógica de feed manual

## NÃO Faça
- Adicione componentes React quando um componente Astro funcionaria
- Use diretiva client:load
- Pule dimensões de imagem (causa CLS)
- Modifique o schema de content collection sem atualizar frontmatter existente

Erros Comuns Que Destroem Seu Contexto de IA

Já revisei muitos arquivos CLAUDE.md neste ponto. Aqui estão os padrões que consistentemente levam a resultados ruins.

Erro Por Que Prejudica Solução
Muito longo (2000+ palavras) Queima tokens da janela de contexto, info-chave se perde Mantenha sob 800 palavras. Linke para docs externos para aprofundamentos.
Muito vago ("usamos React") Claude preenche as lacunas com suposições Seja específico: versões, padrões, ferramentas exatas
Sem instruções negativas Claude faz coisas "razoáveis" que quebram suas convenções Sempre inclua uma seção "NÃO Faça"
Copiar-colar README.md READMEs são para humanos, não contexto de IA Escreva CLAUDE.md do zero com enquadramento específico de IA
Incluindo dados sensíveis Chaves de API, segredos em arquivos de contexto Nunca coloque segredos em CLAUDE.md. Referencie .env.example em vez disso
Nunca atualizar Projeto evolui, arquivo de contexto não Revise CLAUDE.md a cada sprint ou refator maior
Instruções contraditórias "Use componentes server" + exemplos com fetching useEffect Tenha uma pessoa responsável pelo arquivo, revise por consistência

CLAUDE.md vs Outros Arquivos de Contexto para IA

Claude Code não é a única ferramenta de IA que lê arquivos de contexto do projeto. Aqui está como o panorama se parece em 2025:

Arquivo Ferramenta Auto-Lê Escopo
CLAUDE.md Claude Code Sim, no início da sessão Projeto-inteiro
.cursorrules Cursor Sim, ao abrir arquivo Projeto-inteiro
.github/copilot-instructions.md GitHub Copilot Sim, em Copilot Chat Repo-inteiro
.windsurfrules Windsurf (Codeium) Sim Projeto-inteiro
AGENTS.md OpenAI Codex CLI Sim Projeto-inteiro
.ai/context.md Convenção customizada Não (referência manual) Varia

A boa notícia: a maioria do conteúdo é transferível. Se você escrever um CLAUDE.md sólido, convertê-lo para .cursorrules ou copilot-instructions.md leva cerca de 5 minutos. A estrutura e informação são as mesmas — apenas o nome do arquivo e formatação menor diferem.

Se sua equipe usa múltiplas ferramentas de IA (e muitas fazem em 2025), considere manter uma única fonte de verdade e gerar os arquivos específicos da ferramenta a partir dela. Um simples script de build pode copiar seu arquivo de contexto master para todos os locais certos.

Padrões Avançados para Projetos Grandes

Arquivos CLAUDE.md Aninhados

Para monorepos ou bases de código grandes, você pode colocar arquivos CLAUDE.md em subdiretórios. Claude Code lerá o mais específico para o diretório em que você está trabalhando.

project/
├── CLAUDE.md              # Contexto global do projeto
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Contexto específico app web
│   └── api/
│       └── CLAUDE.md      # Contexto específico API
├── packages/
│   └── ui/
│       └── CLAUDE.md      # Contexto sistema de design

O CLAUDE.md raiz cobre arquitetura e convenções compartilhadas. Cada arquivo aninhado adiciona especificidades para aquele pacote.

Contexto Dinâmico com /compact

O comando /compact do Claude Code sumariza a conversa atual e libera espaço de contexto. Para sessões longas, encontrei um padrão que funciona bem:

  1. Inicie com CLAUDE.md carregado automaticamente
  2. Trabalhe em uma feature
  3. Execute /compact quando contexto ficar pesado
  4. Continue — Claude retém o contexto CLAUDE.md plus um sumário comprimido

Contexto Compartilhado por Equipe vs Pessoal

Mantemos CLAUDE.md em controle de versão (deveria ser commitado). Mas desenvolvedores individuais também usam ~/.claude/CLAUDE.md para preferências pessoais:

# Preferências Pessoais
- Prefiro nomes de variáveis verbosos sobre abreviações
- Mostre-me o raciocínio antes de escrever código
- Ao sugerir mudanças, mostre o diff completo do arquivo
- Uso VS Code com keybindings Vim (não sugira atalhos específicos de IDE)

Esta separação mantém o arquivo do time limpo e focado em fatos de projeto enquanto permite que indivíduos customizem sua experiência.

Medindo o Impacto

Como você sabe que seu CLAUDE.md está funcionando? Aqui estão métricas que rastreamos internamente:

  • Precisão na primeira tentativa: Com que frequência a primeira resposta do Claude precisa de zero correções? Um bom CLAUDE.md consegue isto acima de 80%.
  • Violações de convenção: Conte quantas vezes Claude quebra seus padrões de código. Deveria tender para zero.
  • Perguntas de contexto: Se Claude continua perguntando "qual framework é este?" ou "devo usar o App Router?", seu CLAUDE.md está faltando informação.
  • Frequência de desfazer: Com que frequência você tem que rejeitar ou reverter mudanças do Claude. Menos é melhor.

Um time em uma startup de médio porte relatou reduzir seu tempo médio de tarefa assistida por IA de 12 minutos para 4 minutos após investir uma hora no seu CLAUDE.md. Isso é uma melhoria de 3x de um único arquivo.

Se você está construindo um projeto conosco através de nossos serviços de desenvolvimento de CMS headless, incluímos um CLAUDE.md tailorizado como parte de cada handoff de projeto. É tão importante para velocidade de desenvolvimento contínua.

FAQ

O que é CLAUDE.md e onde ele vai? CLAUDE.md é um arquivo markdown colocado na raiz do seu repositório de projeto. Claude Code o lê automaticamente no início de cada sessão para entender a arquitetura, convenções, tech stack e restrições do seu projeto. Pense nele como um documento de onboarding escrito especificamente para seu assistente de IA para código.

Qual deve ser o tamanho de um arquivo CLAUDE.md? Vise 300-800 palavras. Arquivos mais curtos perdem contexto crítico, mas qualquer coisa acima de 1.000 palavras começa a comer sua janela de contexto — espaço que é melhor usado para raciocínio real de código. Seja conciso e específico. Cada frase deveria merecer seu lugar. Se precisar de mais profundidade, linke para documentação externa em vez de embarcá-la.

Devo commitar CLAUDE.md no controle de versão? Absolutamente. CLAUDE.md deveria ser tratado como qualquer outra documentação do projeto — versionado, revisado, e mantido atualizado. Seu time inteiro se beneficia de comportamento de IA consistente. Preferências pessoais vão em ~/.claude/CLAUDE.md em vez disso, que fica local na máquina de cada desenvolvedor.

Como CLAUDE.md é diferente de .cursorrules? O conteúdo é quase idêntico — ambos providenciam contexto do projeto para uma ferramenta de IA. A diferença é qual ferramenta o lê. CLAUDE.md é para Claude Code (ferramenta CLI de Anthropic), enquanto .cursorrules é para Cursor IDE. Se você usa ambas ferramentas, mantenha uma única fonte de verdade e copie para ambos arquivos, ajustando para qualquer formatação específica da ferramenta.

Qual é a seção mais importante de um CLAUDE.md? A seção "NÃO Faça". Instruções negativas são desproporcionalmente efetivas com modelos de IA. Dizer ao Claude o que evitar — não use tipos any, não adicione "use client" desnecessariamente, não instale novos pacotes sem perguntar — previne os erros mais comuns e frustrantes. Uma boa lista de proibições economiza mais tempo que páginas de instruções positivas.

Posso usar CLAUDE.md para projetos não-código? Sim. CLAUDE.md funciona para qualquer projeto onde você interage com Claude Code. Já vi arquivos efetivos para repos de documentação, projetos infrastructure-as-code, e até mesmo pipelines de análise de dados. O princípio é o mesmo: dê ao Claude o contexto que ele precisa para tomar boas decisões sobre seu projeto específico.

Com que frequência devo atualizar meu CLAUDE.md? Revise a cada refator maior e pelo menos uma vez por sprint. Se você atualizar a versão de um framework, mudar uma dependência-chave, ou adotar uma nova convenção, atualize o arquivo imediatamente. Contexto obsoleto é pior que sem contexto porque ativamente engana a IA. Alguns times adicionam uma revisão de CLAUDE.md no seu checklist de PR para mudanças de infraestrutura.

CLAUDE.md funciona com Claude na web (claude.ai)? Não. CLAUDE.md é especificamente lido por Claude Code, a ferramenta de código baseada em CLI. Se você está usando Claude através da interface web ou API, você precisaria colar o contexto manualmente ou usar o recurso Projects para anexá-lo como um arquivo de conhecimento. O carregamento automático de Claude Code é o que torna o arquivo tão poderoso — zero fricção, cada sessão.