# CLAUDE.md: como configurar instruções para o Claude Code > Como configurar corretamente o arquivo CLAUDE.md para o Claude Code: níveis de configuração, padrões de código, seções Gotchas e Never Do, exemplos de referência e a regra da segunda observação. **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: :::tabs === Raiz do Projeto (CLAUDE.md) ```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 ``` === Pasta do Projeto (.claude/CLAUDE.md) ```markdown # Scoped Project Rules - Location: .claude/CLAUDE.md - Applies to all contributors of this repository - Versioned in Git alongside codebase - Overrides any user-level global preferences ``` === Arquivo Global (~/.claude/CLAUDE.md) ```markdown # Global User Preferences ### Coding Style - Prefer functional patterns over OOP classes - Always write explicit error handling with typed errors - Keep functions short (under 30 lines where possible) ### Git - Use lowercase commit messages - Conventional commits: feat:, fix:, chore:, docs:, refactor: - Never push directly to main/master branch ``` ::: ### 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. > [!IMPORTANT] > **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.` | > [!TIP] > 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 } ); } } ``` ``` 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 ``` > [!WARNING] > 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 ``` > [!TIP] > 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 > [!TIP] > **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 > [!TIP] > **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 > [!TIP] > **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 - [x] **Volume:** O documento contém apenas informações praticamente relevantes (não excede 150 linhas). - [x] **Concretude:** Não há desejos abstratos como "faça bonito"; cada regra tem um critério claro de cumprimento. - [x] **Gotchas:** Pelo menos 2–3 características não óbvias da sua stack estão registradas. - [x] **Proibições:** A seção `Never Do` está descrita com restrições inequívocas. - [x] **Isolamento:** Preferências globais do desenvolvedor foram movidas para `~/.claude/CLAUDE.md`.