Seu assistente de codificação IA abre seu repositório pela primeira vez. Ele escaneia a estrutura de arquivos, dependências, talvez um README. Então sugere uma configuração de roteador que quebra seu sistema de layout existente, importa um pacote que você descontinuou há três sprints, e escreve testes em um estilo que sua equipe abandonou no ano passado. O assistente não é burro — está cego. Claude Code, Cursor, Copilot, Cody — todo par-programador IA bate na mesma parede: não consegue ler o contexto da sua equipe apenas pelo histórico de commits. Um único arquivo CLAUDE.md na raiz do seu projeto muda isso. É a diferença entre um assistente que combate suas convenções e um que as estende como um desenvolvedor sênior que tem feito deploy com você há meses. Mas a maioria das equipes escreve arquivos CLAUDE.md que a IA na verdade não consegue usar.

Se você vem jogando prompts no Claude Code e recebendo resultados genéricos, errados 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 enviamos na Social Animal.

Sumário

O que é CLAUDE.md e Por Que Importa

CLAUDE.md é um arquivo markdown que você coloca na raiz do seu repositório e que Claude Code lê automaticamente sempre que inicia uma sessão. Pense nele como documentação de onboarding para seu par-programador IA. Quando um novo desenvolvedor entra em sua equipe, você não apenas entrega um laptop e diz "descubra". Você o guia pela arquitetura, explica as partes estranhas, aponta as armadilhas. CLAUDE.md faz a mesma coisa para Claude.

Sem ele, Claude Code tem que inferir tudo a partir da estrutura de arquivos, package.json e de quaisquer arquivos que acontece ler. É como pedir a um novo funcionário que entenda todo seu sistema lendo arquivos de código aleatórios. Ele acertará algumas coisas, mas também fará suposições que desperdiçam o tempo de todos.

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

Como Claude Code Lê o Contexto do Seu Projeto

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

A Ordem de Carregamento de Contexto

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

O CLAUDE.md de nível de projeto é onde você gastará a maioria do tempo. O arquivo global é bom para preferências pessoais ("prefiro componentes funcionais" ou "sempre use TypeScript strict mode"), mas o valor real 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 de janela de contexto. Se seu CLAUDE.md tem 5.000 palavras de documentação divagando, você está queimando tokens que poderiam ser usados para raciocínio de código real. Seja conciso. Seja específico. Cada linha deve ganhar seu lugar.

A Anatomia de um Ótimo Arquivo CLAUDE.md

Depois de escrever e refinar arquivos CLAUDE.md em dezenas de projetos — aplicativos 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.

## Stack Tecnológico
Versões exatas e frameworks.

## Arquitetura
Como as peças se encaixam.

## Convenções Principais
Padrões de codificação, padrões de nomeação, regras de organização de arquivos.

## Comandos Comuns
Comandos de build, test, deploy e dev.

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

## Problemas Conhecidos / Armadilhas
Armadilhas a evitar.

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

Vamos detalhar cada seção.

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

Visão Geral

Mantenha isso em 2-3 frases no máximo. Claude não precisa do seu roadmap de produtos — ele precisa entender o domínio para fazer decisões contextualmente apropriadas.

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

Stack Tecnológico

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

## Stack Tecnológico
- **Framework**: Next.js 15.1 (App Router, RSC por padrão)
- **Linguagem**: TypeScript 5.7 (strict mode)
- **Estilo**: Tailwind CSS v4 com configuração CSS-first
- **CMS**: Sanity v3 com preview ao vivo
- **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 no cliente)

Arquitetura

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

## Arquitetura
- `app/` — Páginas e layouts do Next.js App Router
- `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, consultas (GROQ) e geração de tipo
- `content/` — Arquivos MDX para posts de blog (colocalizados com frontmatter)
- `public/` — Ativos estáticos (prefira next/image para todas as imagens)

Fluxo de dados: Sanity CMS → consultas GROQ em lib/sanity/queries.ts → Server Components → Client Components (apenas quando interatividade é necessária)

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

Convenções Principais

Esta seção economiza o máximo de 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 PascalCase, um componente por arquivo
- Use named exports, nunca default exports (exceto pages/layouts)
- Toda busca de dados acontece em Server Components — nunca use useEffect para busca de dados
- Tipos de resposta de API vivem em lib/types/ e são auto-gerados do schema Sanity
- Use utilitário `cn()` (lib/utils.ts) para merge de classe condicional, não template literals
- Error boundaries envolvem cada seção de página principal, não a página inteira
- Todo tratamento de formulário usa react-hook-form + schemas de validação zod
- Mensagens de commit seguem Conventional Commits (feat:, fix:, chore:)

Comandos Comuns

Isso parece básico, mas Claude Code na verdade executa esses comandos. Se não souber os certos, vai chutar, e frequentemente erra.

## 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 de schema
- `pnpm db:migrate` — Executa migrações Drizzle ORM

Contexto Importante

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

## Contexto Importante
- Usamos ISR (revalidate: 3600) para todas as páginas de CMS. Nunca use `force-dynamic` a menos que absolutamente necessário.
- O webhook Sanity em /api/revalidate maneja 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 de CMS.
- Auth é tratado 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

Cada projeto tem coisas estranhas. Coloque aqui para que Claude não tropeça nelas.

## Armadilhas Conhecidas
- O renderizador de portable text Sanity tem um bug com listas aninhadas em 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
- Os rewrites vercel.json para /docs/* fazem proxy para nosso site de docs Mintlify. Não modifique isso sem verificar com a equipe.
- Variáveis de ambiente prefixadas com NEXT_PUBLIC_ são as únicas disponíveis no lado do cliente. Nunca exponha secrets de API dessa forma.

A Seção "NÃO FAZER"

Arguavelmente é a seção mais importante. Instruções negativas são incrivelmente eficazes com modelos de IA.

## NÃO FAZER
- Não instale novas dependências sem perguntar antes
- Não use tipo `any` — encontre ou crie tipos apropriados
- Não crie novas rotas de API para coisas que podem ser feitas em Server Components
- Não modifique arquivos de 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 event handlers
- Não escreva arquivos CSS — tudo é classes utilitárias Tailwind
- Não hardcode strings que deveriam vir do CMS

Exemplos de CLAUDE.md Reais

Exemplo: Site Next.js de Marketing

Esta é uma versão reduzida de um CLAUDE.md que usamos em projetos de clientes, 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 de Sanity CMS. Objetivo: LCP sub-2s em todas as páginas.

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

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

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

## Convenções
- Named exports apenas (exceto page.tsx/layout.tsx)
- Componentes: PascalCase, um por arquivo
- cn() para merge 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 FAZER
- Adicione "use client" sem justificativa
- Instale pacotes sem perguntar
- Use default exports para componentes
- Modifique arquivos 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 desenvolvedores com 500+ artigos. Static-first, zero JS por padrão. MDX para conteúdo com componentes customizados.

## Stack Tecnológico
Astro 5.x | MDX | Tailwind v4 | Deploy 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 Astro com width/height apropriados
- Feed RSS auto-gera da content collection — não construa lógica de feed manual

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

Erros Comuns Que Destroem Seu Contexto IA

Revisei muitos arquivos CLAUDE.md até agora. 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 importante se perde Mantenha abaixo de 800 palavras. Link para docs externas para aprofundamentos.
Muito vago ("usamos React") Claude preenche 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 FAZER"
Copy-paste do README.md READMEs são para humanos, não para contexto IA Escreva CLAUDE.md do zero com framing específico para IA
Inclui dados sensíveis Chaves de API, secrets no arquivo de contexto Nunca coloque secrets em CLAUDE.md. Referencie .env.example em vez disso
Nunca atualiza Projeto evolui, arquivo de contexto não Revise CLAUDE.md a cada sprint ou refatoração maior
Instruções contraditórias "Use server components" + exemplos com useEffect fetching Uma pessoa seja dona do arquivo, revise para consistência

CLAUDE.md vs Outros Arquivos de Contexto IA

Claude Code não é a única ferramenta IA que lê arquivos de contexto de projeto. Aqui está como o cenário se vê em 2026:

Arquivo Ferramenta Auto-Lê Escopo
CLAUDE.md Claude Code Sim, no início da sessão Em todo o projeto
.cursorrules Cursor Sim, na abertura de arquivo Em todo o projeto
.github/copilot-instructions.md GitHub Copilot Sim, no Copilot Chat Em todo o repositório
.windsurfrules Windsurf (Codeium) Sim Em todo o projeto
AGENTS.md OpenAI Codex CLI Sim Em todo o projeto
.ai/context.md Convenção customizada Não (referência manual) Varia

A boa notícia: a maioria do conteúdo é transferível. Se escrever um CLAUDE.md sólido, convertê-lo para .cursorrules ou copilot-instructions.md leva uns 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 IA (e muitas usam em 2026), 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 codebases 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 da app web
│   └── api/
│       └── CLAUDE.md      # Contexto específico da API
├── packages/
│   └── ui/
│       └── CLAUDE.md      # Contexto do design system

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

Contexto Dinâmico com /compact

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

  1. Comece com CLAUDE.md carregado automaticamente
  2. Trabalhe em um feature
  3. Execute /compact quando o contexto ficar pesado
  4. Continue — Claude retém o contexto CLAUDE.md mais um resumo comprimido

Contexto Compartilhado vs Pessoal da Equipe

Mantemos CLAUDE.md no controle de versão (deve 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 da equipe limpo e focado em fatos do 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:

  • Acurácia de primeira tentativa: Com que frequência a primeira resposta de Claude precisa de zero correções? Um bom CLAUDE.md fica acima de 80%.
  • Violações de convenção: Conte quantas vezes Claude quebra seus padrões de codificação. Deveria tender a 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 de Claude. Menor é melhor.

Uma equipe em uma startup de médio porte relatou cortar seu tempo médio de tarefa assistida por IA de 12 minutos para 4 minutos depois de investir uma hora em seu CLAUDE.md. Essa é uma melhoria de 3x a partir de um único arquivo.

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

Perguntas Frequentes

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

Qual deve ser o tamanho de um arquivo CLAUDE.md? Mire em 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 melhor usado para raciocínio de código real. Seja conciso e específico. Cada frase deve ganhar seu lugar. Se precisar de mais profundidade, linke para documentação externa em vez de embutir.

Devo commitar CLAUDE.md no controle de versão? Absolutamente. CLAUDE.md deve ser tratado como qualquer outra documentação de projeto — versionado, revisado e mantido atualizado. Toda sua equipe se beneficia de comportamento 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 fornecem contexto de projeto a uma ferramenta de codificação IA. A diferença é qual ferramenta lê eles. CLAUDE.md é para Claude Code (ferramenta CLI do Anthropic), enquanto .cursorrules é para Cursor IDE. Se usa ambas as ferramentas, mantenha uma fonte de verdade única e copie para ambos os 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 FAZER". Instruções negativas são desproporcionalmente eficazes com modelos IA. Dizer a 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 que não são código? Sim. CLAUDE.md funciona para qualquer projeto onde você interage com Claude Code. Vi ones eficazes para repositórios de documentação, projetos de infraestrutura-como-código, e até pipelines de análise de dados. O princípio é o mesmo: dê a Claude o contexto que ela precisa para tomar boas decisões sobre seu projeto específico.

Com que frequência devo atualizar meu CLAUDE.md? Revise em cada refatoração maior e pelo menos uma vez por sprint. Se atualizar uma versão de framework, mudar uma dependência principal ou adotar uma nova convenção, atualize o arquivo imediatamente. Contexto desatualizado é pior que nenhum contexto porque ativa engana a IA. Algumas equipes adicionam revisão de CLAUDE.md ao 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 codificação baseada em CLI. Se usar 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.