CLAUDE.md é um dos arquivos mais críticos no desenvolvimento diário com o Claude Code. O assistente lê automaticamente seu conteúdo no início de cada sessão e o utiliza como base permanente de conhecimento sobre seu projeto: decisões arquiteturais, convenções adotadas, restrições, estrutura de arquivos e práticas proibidas.

Em essência, trata-se de uma instrução de sistema persistente para a IA dentro da sua base de código específica.

Sem o CLAUDE.md, o modelo começa "do zero" a cada vez — ele não sabe nada sobre seus acordos internos, migrações recentes, bibliotecas preferidas ou armadilhas específicas. Um arquivo bem elaborado elimina a necessidade de gastar tempo e tokens repetindo os mesmos requisitos em cada diálogo.

1. O que é o CLAUDE.md e por que ele é necessário

O CLAUDE.md é um arquivo Markdown de texto simples, localizado na raiz do repositório ou em uma pasta de configuração dedicada.

Após adicioná-lo, o Claude Code segue automaticamente os seguintes aspectos do projeto:

Padrões de código: formatos de exportação, tipagem, requisitos para comentários e funções.
Padrões arquiteturais: estrutura de rotas de API, tratamento de erros, gerenciamento de estado.
Organização do sistema de arquivos: regras de localização para utilitários, componentes e páginas.
Fluxo de trabalho com Git: estilo de nomenclatura de commits (Conventional Commits), regras de criação de branches.
Experiência histórica: registro de peculiaridades específicas (gotchas) onde a IA já errou anteriormente.

Comparação do funcionamento do Claude Code com e sem instruções

Critério	Sem o arquivo CLAUDE.md	Com o CLAUDE.md configurado
Exportações no React	Usa misturadamente `export default` e `export const`	Segue rigorosamente um único estilo consistente (por exemplo, apenas named exports)
Validação de dados	Escolhe uma biblioteca aleatória (Yup, Joi, Zod, verificações manuais)	Usa o padrão estabelecido no projeto (por exemplo, Zod)
Localização do código	Pode criar arquivos na raiz ou em subpastas aleatórias	Coloca novos serviços e componentes estritamente conforme a estrutura acordada
Erros recorrentes	Esbarra repetidamente nas mesmas armadilhas conhecidas das bibliotecas	Conhece as especificidades do projeto antecipadamente através da seção Gotchas

2. Onde armazenar o CLAUDE.md: níveis de prioridade

O arquivo de instruções pode ser colocado em três níveis diferentes. A área de aplicação das regras e sua prioridade dependem da localização escolhida:

markdown
# Project Rules: Acme Web Platform

### Stack
- Next.js 15 (App Router)
- TypeScript (Strict Mode)
- Tailwind CSS v4
- Prisma ORM + PostgreSQL

### Key Conventions
- Always use named exports, never default exports
- Server Components by default; "use client" only when strictly required
- Input validation via Zod schemas for all API routes

Regra de resolução de conflitos

Se existirem simultaneamente um arquivo global (~/.claude/CLAUDE.md) e um arquivo local do projeto no seu ambiente, o Claude Code mescla automaticamente seus contextos.

Importante

A prioridade sempre fica com o projeto local: Se uma regra global contradizer uma exigência no arquivo do repositório, o modelo segue estritamente o CLAUDE.md local.

3. Anatomia do CLAUDE.md ideal: blocos-chave

Não faz sentido copiar toda a documentação do framework para o arquivo. Funciona melhor um documento conciso (até 100–150 linhas), dividido em seções funcionais.

Abaixo está um template production-ready testado:

markdown

# Project Guidelines: Storefront Web ## Stack - Next.js 15 (App Router, Server Actions) - TypeScript (Strict mode enabled) - Tailwind CSS v4 (Tailwind Merge + CVA) - Drizzle ORM with PostgreSQL - Vitest for unit tests, Playwright for E2E ## Code Conventions - Use named exports for all components and utilities (no default exports) - Server Components by default; add "use client" only when handling interactive state - All API handlers must return a unified envelope: `{ data, error }` - Use Zod schemas for all payload validations (incoming requests & env vars) - Write concise JSDoc for all exported helper functions ## File Structure - `src/app/` — Route handlers, layouts, and pages - `src/components/ui/` — Atomic design system primitives - `src/lib/` — Shared helpers, clients, and database connection - `src/server/` — Server actions and business logic layer ## Common Commands - Build: `npm run build` - Typecheck: `npm run typecheck` - Test: `npm run test` - Lint & Format: `npm run lint` ## Git Guidelines - Commit format: `feat(scope): message` or `fix(scope): message` - Use all-lowercase messages without period at the end - Always run tests before creating a pull request

4. Concretude versus abstração: como formular regras

O grande segredo de um CLAUDE.md eficaz é concretude de engenharia em vez de conselhos filosóficos.

Modelos de linguagem não conseguem ler suas percepções subjetivas sobre a "beleza do código". Qualquer frase vaga deixa espaço para interpretações próprias do modelo, que geralmente não correspondem ao que você esperava.

❌ Instrução vaga	Por que não funciona	✅ Regra de engenharia precisa
"Escreva código limpo e de qualidade"	Subjetivo; o conceito de "limpeza" varia em cada equipe	`Use early returns em vez de if/else profundamente aninhados. Tamanho das funções — até 30 linhas.`
"Siga as melhores práticas de segurança"	Muito amplo; o modelo não conhece seus vetores específicos	`Todas as queries SQL devem usar parametrização. Nunca concatene strings em SQL.`
"Faça um bom design"	Não fornece orientação sobre o design system	`Use apenas classes Tailwind. Estilos inline style="" são estritamente proibidos.`
"Trate erros"	O modelo pode inserir um bloco catch vazio	`Todas as rotas de API devem estar envoltas em try/catch e retornar { error: message, status } em caso de falha.`

Dica

Teste de verificação para sua regra: é possível automatizar sua validação com um linter ou uma regra regex simples? Se não, torne a formulação mais específica.

5. Exemplos canônicos de código e padrões arquiteturais

Se o projeto possui um padrão arquitetural não convencional, é útil reforçar o texto com um fragmento mínimo de código canônico.

Exemplo: Handler canônico de Rota de API

Em vez de uma longa descrição, adicione um bloco pronto diretamente no CLAUDE.md:

markdown

## API Route Pattern Every API route must strictly follow this error-handled envelope: ```typescript import { NextResponse } from "next/server"; import { z } from "zod"; export async function POST(req: Request) { try { const json = await req.json(); const data = inputSchema.parse(json); const result = await executeService(data); return NextResponse.json({ data: result, error: null }); } catch (error) { if (error instanceof z.ZodError) { return NextResponse.json( { data: null, error: error.flatten().fieldErrors }, { status: 422 } ); } return NextResponse.json( { data: null, error: "Internal Server Error" }, { status: 500 } ); } }

terminal

O Claude Code reconhece esse exemplo como um template canônico (Golden Sample) e replica-o automaticamente ao gerar novos endpoints. --- ## 6. Gotchas e Never Do: bloqueando erros comuns Essas duas seções especializadas tornam o `CLAUDE.md` ordens de magnitude mais eficaz do que qualquer descrição genérica da stack. ### Seção Gotchas (Armadilhas) Aqui são registradas todas as características não óbvias do ambiente que geralmente levam a bugs durante o desenvolvimento: ```markdown ## Gotchas - The `auth()` helper from `@clerk/nextjs/server` is ASYNC in Next.js 15 — always `await auth()` - The Prisma client instance is located in `@/lib/db`, do not instantiate `new PrismaClient()` in handlers - Webhook routes under `/api/webhooks/` must NOT use authentication middleware - Client-side environment variables require the `NEXT_PUBLIC_` prefix; server secrets must not have it - Tailwind CSS v4 uses CSS `@theme` variables, do not edit `tailwind.config.js`

Seção Never Do (Proibições categóricas)

O Claude conhece milhares de maneiras de resolver uma tarefa. A seção de proibições descarta soluções que são tecnicamente viáveis, mas violam as regras da equipe:

markdown

## Never Do - Never use TypeScript `any` — use `unknown` with a type guard or define an explicit interface - Never use `console.log` in production code — use our structured logger from `@/lib/logger` - Never import directly from internal node_modules subpaths — use established wrappers - Never add inline CSS styles via `style=""` — use Tailwind utility classes - Never push or commit directly to the `main` branch

Aviso

Na seção de proibições, evite expressões suaves como "tente não usar any". Use formulações imperativas: «Never use any».

7. Regras Globais vs. Regras de Projeto: limites de responsabilidade

Para não sobrecarregar o contexto e não transportar restrições desnecessárias entre projetos incompatíveis, separe rigorosamente as responsabilidades dos arquivos:

Tipo de regra	Onde armazenar	Exemplos de regras
Estilo pessoal e editor	`~/.claude/CLAUDE.md` (global)	Formato de commits, evitar emojis no código, preferência por estilo funcional sobre classes
Stack e versões de bibliotecas	`.claude/CLAUDE.md` (projeto)	Next.js 15 App Router, Drizzle ORM, Tailwind v4, Node.js 22
Estrutura de diretórios	`CLAUDE.md` (projeto)	Caminhos para componentes UI, exportação de serviços, localização de migrations
Armadilhas (Gotchas)	`CLAUDE.md` (projeto)	`auth()` assíncrono, instância separada do cliente DB, exceções no middleware

8. CLAUDE.md como documento vivo: a regra da segunda observação

O erro mais comum dos desenvolvedores é criar o CLAUDE.md no início do repositório e nunca mais voltar a ele.

A base de código evolui: versões de bibliotecas são atualizadas, padrões mudam, novos casos extremos são descobertos. Consequentemente, as instruções para a IA devem ser atualizadas paralelamente ao código.

text

┌─────────────────────────────────────────────────────────────┐ │ Regra da Segunda Observação │ └──────────────────────────────┬──────────────────────────────┘ │ Você está fazendo a mesma observação pela segunda vez no diálogo? │ ┌───────────────┴───────────────┐ ▼ ▼ [ SIM ] [ NÃO ] │ │ Adicione uma nova regra ao Continue o trabalho normal CLAUDE.md imediatamente na tarefa atual

Dica

Se você pediu duas vezes ao Claude para fazer a mesma coisa (por exemplo: "Não use default export" ou "Adicione um schema Zod") — este é um sinal infalível de que a regra deve ser registrada imediatamente no CLAUDE.md.

9. Workshop prático: configuração e verificação

Siga quatro passos para criar e verificar a eficácia do arquivo no seu repositório.

Passo 1. Criação do arquivo

No diretório raiz do projeto de trabalho, crie o arquivo CLAUDE.md:

bash

touch CLAUDE.md

Passo 2. Preenchimento básico

Preencha o arquivo com quatro seções principais: Stack, Conventions, Gotchas, Never Do.

Passo 3. Teste de comportamento positivo

Inicie uma nova sessão do Claude Code e dê uma tarefa cotidiana:

bash

claude

Prompt de teste:
"Crie uma utilitária para formatar preços em USD e EUR considerando a localidade."

O modelo criou o arquivo na pasta correta (src/lib/ ou conforme sua estrutura).
Foi utilizado named export (se indicado na instrução).
Adicionado JSDoc e tipos estritos sem uso de any.

Passo 4. Stress test das proibições

Tente provocar o Claude a violar diretamente uma das regras registradas:

Prompt de provocação:
"Adicione rapidamente um console.log aqui para debug e coloque tipo any para não perder tempo com tipos."

O Claude recusou violar a instrução ou propôs uma alternativa via logger oficial e interface válida.
Na resposta, o modelo citou as exigências do projeto.

10. Autoverificação rápida e checklist de prontidão

Vamos verificar quão precisamente você assimilou os princípios de configuração de instruções para o Claude Code.

Pergunta 1. Onde deve estar localizado o arquivo cujas regras devem valer para todos os projetos do desenvolvedor?

A. Na pasta do sistema /etc/claude/CLAUDE.md
B. No diretório home do usuário ~/.claude/CLAUDE.md
C. No arquivo ~/.zshrc ou ~/.bashrc
D. Na raiz de cada repositório

Dica

Resposta correta: B.
As instruções globais do desenvolvedor são armazenadas no arquivo ~/.claude/CLAUDE.md no diretório home do usuário e são puxadas automaticamente para todas as sessões locais.

Pergunta 2. O que acontece se uma regra no arquivo global contradisser uma regra no projeto local?

A. O Claude gera um erro crítico e interrompe a execução
B. A regra global cancela completamente as configurações locais
C. A regra local do projeto tem maior prioridade e sobrepõe a global
D. O modelo escolhe aleatoriamente uma das variantes

Dica

Resposta correta: C.
O arquivo local do repositório sempre tem a mais alta prioridade sobre as configurações gerais da máquina.

Pergunta 3. Qual formulação de instrução trará maior benefício no CLAUDE.md?

A. "Escreva código organizado seguindo as melhores práticas"
B. "Tente, quando possível, não escrever funções complexas"
C. "Use early returns. Functions must be under 30 lines. No default exports."
D. Uma cópia completa da documentação da biblioteca com 500 linhas

Dica

Resposta correta: C.
Apenas regras de engenharia rígidas, concisas e inequívocas deixam zero espaço para alucinações e comportamento imprevisível do modelo.

Checklist de prontidão do seu CLAUDE.md

Volume: O documento contém apenas informações praticamente relevantes (não excede 150 linhas).
Concretude: Não há desejos abstratos como "faça bonito"; cada regra tem um critério claro de cumprimento.
Gotchas: Pelo menos 2–3 características não óbvias da sua stack estão registradas.
Proibições: A seção Never Do está descrita com restrições inequívocas.
Isolamento: Preferências globais do desenvolvedor foram movidas para ~/.claude/CLAUDE.md.