O que é o CLAUDE.md e como escrever um que realmente funcione

Você instalou o Claude Code. Rodou alguns prompts. Os resultados foram... ok. Talvez ele tenha sugerido instalar um pacote que você já tem. Talvez tenha usado CommonJS quando seu projeto inteiro é ESM. Talvez tenha escrito testes em Mocha quando você usa Vitest.

O problema não é o Claude Code. O problema é que o Claude Code não sabe nada sobre o seu projeto até você contar.

É para isso que serve o CLAUDE.md. É um arquivo markdown simples que fica na raiz do seu repositório e dá ao Claude Code o contexto de que ele precisa para trabalhar de forma eficaz no seu código específico. Pense nele como uma documentação de onboarding -- não para um novo contratado, mas para uma IA que consegue ler todo o seu código em segundos, mas ainda precisa conhecer as regras não escritas.

Este guia cobre tudo: o que é o CLAUDE.md, como estruturar um que realmente funcione, exemplos reais para diferentes tipos de projeto, erros a evitar e como aprimorá-lo ao longo do tempo.

Índice

• O que é o CLAUDE.md?
• Por que o CLAUDE.md importa mais do que você imagina
• Anatomia de um bom CLAUDE.md
• Exemplos reais por tipo de projeto
• Antipadrões: o que não fazer
• Como aprimorar seu CLAUDE.md
• Como o SuperBuilder ajuda
• Perguntas frequentes

O que é o CLAUDE.md?

O CLAUDE.md é um arquivo de configuração para o Claude Code -- o agente de código com IA da Anthropic que roda no seu terminal. Quando o Claude Code inicia uma sessão em um diretório, ele lê automaticamente o arquivo CLAUDE.md na raiz do projeto para entender as convenções, a arquitetura e as preferências do seu código.

Não é um formato de configuração rígido. Não há schema, nem campos obrigatórios, nem validação. É markdown simples. Você escreve qualquer contexto que ajude um agente inteligente a trabalhar de forma mais eficaz no seu projeto.

Aqui está um exemplo mínimo:

# Project: Invoice API

Node.js REST API using Express + TypeScript + Prisma.

## Commands
- `npm run dev` -- start dev server on port 3001
- `npm test` -- run Vitest tests
- `npm run lint` -- ESLint + Prettier check

## Conventions
- All API routes go in `src/routes/`
- Business logic goes in `src/services/`, not in route handlers
- Use Zod for request validation
- Tests live next to source files (`*.test.ts`)

São 12 linhas. Leva dois minutos para escrever. E evita dezenas de suposições erradas.

Onde os arquivos CLAUDE.md ficam

O Claude Code lê arquivos CLAUDE.md de vários locais, combinados em ordem de precedência:

1. ~/.claude/CLAUDE.md -- Preferências globais que se aplicam a todos os projetos (seu estilo de código pessoal, ferramentas preferidas)
2. CLAUDE.md na raiz do projeto -- Convenções de nível de projeto compartilhadas pela equipe
3. CLAUDE.md em subdiretórios -- Instruções com escopo para partes específicas de um monorepo ou base de código

Essa abordagem em camadas significa que você pode definir padrões globais e sobrescrevê-los por projeto ou por diretório.

Por que o CLAUDE.md importa mais do que você imagina

O Claude Code é poderoso. Ele consegue ler arquivos, executar comandos, editar código e executar planos de múltiplas etapas. Mas poder sem contexto leva a código de aparência plausível que erra o alvo.

Sem um CLAUDE.md, o Claude Code vai:

• Adivinhar sua stack. Ele pode sugerir jest quando você usa vitest, ou axios quando você usa a API nativa fetch.
• Ignorar convenções do projeto. Sua equipe coloca todas as consultas de banco de dados em uma pasta repositories/? O Claude não sabe disso.
• Usar padrões errados. Seu app React usa server components exclusivamente? O Claude pode usar "use client" por padrão em tudo.
• Pular etapas de build. Se seu projeto precisa de npm run codegen antes de os testes passarem, o Claude não vai saber a menos que você diga.

Com um CLAUDE.md bem escrito, o Claude Code se torna um membro da equipe que de fato leu a documentação de onboarding. Ele segue seus padrões, usa suas bibliotecas preferidas e entende a arquitetura.

A diferença é dramática. Equipes que mantêm um bom CLAUDE.md relatam que o Claude Code acerta de primeira de 2 a 3 vezes mais do que ao escrever prompts sem ele.

Anatomia de um bom CLAUDE.md

Depois de analisar centenas de arquivos CLAUDE.md de projetos open-source e de nossos próprios usuários, uma estrutura clara emerge. Os melhores arquivos compartilham estas seções:

1. Visão geral do projeto (2-3 linhas)

Diga o que é o projeto e a stack tecnológica principal. Seja específico sobre versões quando isso importar.

# SuperWidget

React 19 + TypeScript dashboard app. Vite 6 for builds, Tailwind CSS v4 for styling. 
Deployed on Vercel. Monorepo managed with Turborepo.

2. Comandos principais

Liste os comandos que um desenvolvedor (ou IA) precisa para fazer build, testar, lintar e rodar o projeto. Esta é a seção de maior valor, porque evita que o Claude Code fique adivinhando.

## Commands
- `pnpm dev` -- start dev server
- `pnpm test` -- run all Vitest tests
- `pnpm test:e2e` -- Playwright end-to-end tests
- `pnpm lint` -- ESLint check
- `pnpm typecheck` -- TypeScript strict check
- `pnpm db:migrate` -- run Drizzle migrations
- `pnpm db:generate` -- regenerate Drizzle schema types

3. Arquitetura e organização de arquivos

Descreva onde as coisas ficam. Isso evita que o Claude Code precise varrer toda a sua árvore de arquivos para entender a estrutura.

## Architecture
- `src/app/` -- Next.js App Router pages and layouts
- `src/components/` -- Shared React components
- `src/lib/` -- Utility functions and shared logic
- `src/server/` -- Server-only code (API routes, DB queries)
- `src/server/routers/` -- tRPC router definitions
- `prisma/schema.prisma` -- Database schema (PostgreSQL)

4. Convenções de código

É aqui que você codifica as regras não escritas. As coisas que um novo membro da equipe aprende na primeira semana.

## Conventions
- Use named exports, not default exports
- Prefer `interface` over `type` for object shapes
- Error handling: wrap async route handlers in `tryCatch()` from `src/lib/utils`
- All database access goes through `src/server/db/` -- never import Prisma client directly in components
- CSS: use Tailwind utility classes, no custom CSS files except `globals.css`
- Imports: use `@/` path alias (maps to `src/`)

5. Restrições importantes

Coisas que o Claude Code nunca deve fazer, ou sempre deve fazer.

## Important
- NEVER modify `src/generated/` -- these files are auto-generated by `pnpm db:generate`
- NEVER use `any` type -- use `unknown` and narrow with type guards
- Always add Zod validation for new API endpoints
- Run `pnpm typecheck` after making changes to verify no type errors
- This project uses strict TypeScript -- no implicit any, no unused variables

6. Padrões de teste

Se sua configuração de testes tem convenções específicas, deixe-as explícitas.

## Testing
- Unit tests use Vitest with `@testing-library/react`
- Test files: `__tests__/ComponentName.test.tsx` (co-located)
- Mock API calls with MSW (Mock Service Worker), not jest.mock
- E2E tests in `tests/e2e/` using Playwright
- Run single test: `pnpm test -- --run src/path/to/test.test.ts`

Exemplos reais por tipo de projeto

A teoria é boa, mas você precisa de algo que possa copiar e adaptar. Aqui estão cinco arquivos CLAUDE.md para tipos de projeto comuns, baseados em padrões de projetos do mundo real.

Exemplo 1: App React + TypeScript

# TaskFlow

React 19 + TypeScript task management app. Vite 6 for bundling, Zustand for state, 
React Query v5 for server state. Deployed on Vercel.

## Commands
- `npm run dev` -- start dev server (port 5173)
- `npm test` -- Vitest in watch mode
- `npm run test:run` -- single Vitest run (CI)
- `npm run build` -- production build
- `npm run lint` -- ESLint + Prettier

## Architecture
- `src/components/` -- UI components, grouped by feature
- `src/hooks/` -- custom React hooks
- `src/stores/` -- Zustand stores (one per domain: tasks, auth, ui)
- `src/api/` -- React Query hooks wrapping API calls
- `src/lib/` -- pure utility functions
- `src/types/` -- shared TypeScript interfaces

## Conventions
- Components: function declarations, not arrow functions
- State: Zustand for client state, React Query for server state. Never use useState for data from the API.
- Styling: Tailwind CSS utility classes. No CSS modules, no styled-components.
- Routing: React Router v7 with lazy-loaded routes in `src/routes.tsx`
- All API calls go through `src/api/client.ts` (configured Axios instance with auth interceptor)

## Important
- NEVER put business logic in components -- extract to hooks or stores
- All new components must have a corresponding `.test.tsx` file
- Use `cn()` utility from `src/lib/utils.ts` for conditional class merging

Exemplo 2: API Python (FastAPI)

# Nexus API

FastAPI backend for the Nexus platform. Python 3.12, async-first. 
PostgreSQL + SQLAlchemy 2.0 (async). Redis for caching.

## Commands
- `uv run fastapi dev` -- start dev server with hot reload
- `uv run pytest` -- run all tests
- `uv run pytest -x -k "test_name"` -- run single test, stop on failure
- `uv run ruff check .` -- lint
- `uv run ruff format .` -- format
- `uv run alembic upgrade head` -- run migrations
- `uv run alembic revision --autogenerate -m "description"` -- create migration

## Architecture
- `app/api/routes/` -- FastAPI routers (one file per resource)
- `app/models/` -- SQLAlchemy ORM models
- `app/schemas/` -- Pydantic request/response schemas
- `app/services/` -- business logic layer
- `app/repositories/` -- database query layer (no raw SQL in services)
- `app/core/` -- config, security, dependencies
- `tests/` -- mirrors `app/` structure, uses pytest-asyncio

## Conventions
- All endpoints return Pydantic models, never raw dicts
- Use dependency injection for DB sessions: `db: AsyncSession = Depends(get_db)`
- Repository pattern: services call repositories, never use `db.execute()` directly
- Error handling: raise `HTTPException` in routes only, use custom exceptions in services
- Naming: snake_case everywhere, plural resource names in URLs (`/api/v1/users`)

## Important
- NEVER use synchronous database calls -- everything is async
- NEVER commit `.env` -- use `.env.example` for documentation
- Run `ruff check` and `ruff format` before considering any change complete
- All new endpoints need tests in `tests/api/`

Exemplo 3: Monorepo (Turborepo)

# CloudStack

Turborepo monorepo. pnpm workspaces.

## Packages
- `apps/web` -- Next.js 15 marketing site
- `apps/dashboard` -- Next.js 15 app (App Router, RSC-first)
- `apps/api` -- Hono.js API server on Cloudflare Workers
- `packages/ui` -- shared component library (React + Tailwind)
- `packages/db` -- Drizzle ORM schema + migrations (shared)
- `packages/auth` -- authentication utilities (shared)
- `packages/config-eslint` -- ESLint config
- `packages/config-ts` -- shared tsconfig bases

## Commands (from root)
- `pnpm dev` -- start all apps in parallel
- `pnpm build` -- build all packages and apps
- `pnpm lint` -- lint all packages
- `pnpm test` -- test all packages
- `pnpm dev --filter=dashboard` -- start only dashboard

## Conventions
- Import shared packages with `@cloudstack/ui`, `@cloudstack/db`, etc.
- New shared code goes in `packages/`, not duplicated across apps
- Each package has its own `tsconfig.json` extending `packages/config-ts`
- Database changes: modify `packages/db/schema.ts`, then `pnpm db:generate`

## Important
- NEVER install dependencies in the root -- always in the specific package
- NEVER import between apps directly -- extract shared code to a package
- When modifying `packages/ui`, verify both `apps/web` and `apps/dashboard` still build
- The `apps/api` package uses Hono, NOT Express or Fastify

Exemplo 4: Ferramenta CLI (Go)

# bolt CLI

Command-line tool for managing cloud deployments. Go 1.23, Cobra for commands, 
Bubble Tea for TUI components. Distributed as single binary.

## Commands
- `go build -o bolt ./cmd/bolt` -- build binary
- `go test ./...` -- run all tests
- `go test -v ./internal/deploy/...` -- test specific package
- `golangci-lint run` -- lint
- `goreleaser release --snapshot` -- test release build

## Architecture
- `cmd/bolt/` -- entrypoint, Cobra root command
- `cmd/bolt/commands/` -- one file per CLI command (deploy, logs, config, etc.)
- `internal/` -- core logic, not exported
- `internal/deploy/` -- deployment orchestration
- `internal/config/` -- YAML config file parsing
- `internal/api/` -- HTTP client for cloud API
- `pkg/` -- reusable packages safe for external import

## Conventions
- Errors: wrap with `fmt.Errorf("action: %w", err)` for context chains
- CLI output: use `internal/ui` package (wraps lipgloss styles), never raw fmt.Println for user-facing output
- Config: Viper for config file + env vars, Cobra for flags
- HTTP: standard library `net/http`, no third-party HTTP clients
- Tests: table-driven tests, use `testify/assert` for assertions

## Important
- NEVER use `os.Exit()` outside of `cmd/bolt/main.go`
- All user-facing strings must go through the `ui` package for consistent formatting
- Support both `--json` flag (machine output) and human-readable output for all commands
- Minimum Go version is 1.23 -- use range-over-func and other 1.23 features freely

Exemplo 5: App mobile (React Native)

# FitTrack

React Native 0.76 fitness tracking app. Expo SDK 52, TypeScript.
iOS and Android. Expo Router for navigation.

## Commands
- `npx expo start` -- start Expo dev server
- `npx expo run:ios` -- run on iOS simulator
- `npx expo run:android` -- run on Android emulator
- `npm test` -- Jest + React Native Testing Library
- `npm run lint` -- ESLint
- `npm run typecheck` -- tsc --noEmit
- `eas build --profile preview` -- create preview build

## Architecture
- `app/` -- Expo Router file-based routes
- `app/(tabs)/` -- bottom tab navigator screens
- `app/(auth)/` -- authentication flow screens
- `components/` -- shared components
- `hooks/` -- custom hooks
- `stores/` -- Zustand stores
- `services/` -- API layer (wrapping fetch, auth headers)
- `constants/` -- theme colors, sizes, config values

## Conventions
- Navigation: Expo Router file-based routing. Never use React Navigation directly.
- Styling: StyleSheet.create, organized by component. No NativeWind in this project.
- Platform checks: use `Platform.select()` not `Platform.OS === 'ios'`
- Animations: Reanimated 3 for performance-critical, LayoutAnimation for simple cases
- Storage: MMKV for key-value, SQLite (expo-sqlite) for structured data

## Important
- NEVER use `AsyncStorage` -- we use MMKV for all local storage
- Test on BOTH iOS and Android before marking changes complete
- All health data access goes through `services/health.ts` (wraps HealthKit/Health Connect)
- Expo Config Plugin modifications go in `plugins/` directory

Antipadrões: o que não fazer

Um CLAUDE.md ruim pode ser pior do que nenhum CLAUDE.md, porque dá ao Claude Code um contexto confiante, mas errado. Aqui estão os erros mais comuns.

1. O romance (longo demais)

Se o seu CLAUDE.md tem mais de 500 linhas, está longo demais. O Claude Code processa o arquivo inteiro no início de cada sessão, e um arquivo excessivamente longo dilui as informações importantes com ruído.

Ruim:

## Complete API Reference
### GET /users
Returns a list of users. Supports pagination via `page` and `limit` query params...
[400 more lines of API documentation]

Melhor: Crie um link para a documentação.

## API
- API docs: `docs/api.md`
- OpenAPI spec: `api/openapi.yaml`
- All endpoints follow REST conventions documented in `docs/api-conventions.md`

2. O aceno vago (genérico demais)

Instruções que poderiam se aplicar a qualquer projeto são espaço desperdiçado.

Ruim:

- Write clean code
- Follow best practices
- Add comments where needed
- Make sure tests pass

Melhor: Seja específico para o seu projeto.

- Functions over 30 lines should be broken up
- No abbreviations in variable names (use `transaction`, not `txn`)
- JSDoc on all exported functions
- Tests must cover error paths, not just happy paths

3. A contradição

Quando o seu CLAUDE.md diz uma coisa, mas o seu código faz outra, o Claude Code fica confuso.

Ruim:

## Conventions
- Use Tailwind CSS for all styling

...mas metade do código usa CSS Modules.

Melhor: Reconheça a realidade.

## Conventions
- New components: use Tailwind CSS for styling
- Legacy components in `src/components/v1/` use CSS Modules -- migrate when touching these files

4. O artefato desatualizado

Um CLAUDE.md escrito há seis meses que referencia pacotes já removidos, comandos de build que mudaram ou uma arquitetura que foi reestruturada.

Solução: Trate o CLAUDE.md como documentação viva. Atualize-o quando mudar sua stack ou suas convenções.

5. A injeção de prompt

Alguns desenvolvedores tentam usar o CLAUDE.md como um playground de engenharia de prompt, enchendo-o de instruções elaboradas no estilo system prompt.

Ruim:

You are an expert senior principal staff engineer with 25 years of experience.
Always think step by step. Take a deep breath before coding. 
Rate your confidence from 1-10 before every answer.

Melhor: O CLAUDE.md é para contexto do projeto, não para instruções de personalidade. Foque em fatos sobre o seu código.

Como aprimorar seu CLAUDE.md

Seu primeiro CLAUDE.md não vai ser perfeito. E tudo bem. Aqui está um processo prático para melhorá-lo ao longo do tempo.

Comece pequeno

Comece com apenas três seções: visão geral do projeto, comandos principais e convenções. Isso cobre 80% do valor. Você sempre pode adicionar mais depois.

Fique atento a correções repetidas

Toda vez que você se pegar corrigindo o Claude Code com o mesmo feedback -- "não, usamos pnpm, não npm" ou "coloque isso na camada de services" -- adicione ao seu CLAUDE.md. Essas correções são a sua melhor fonte do que incluir.

Revise mensalmente

Crie um lembrete no calendário. Leia o seu CLAUDE.md uma vez por mês. Remova qualquer coisa desatualizada. Adicione qualquer coisa que você venha repetindo ao Claude Code nos prompts.

Peça ajuda ao Claude Code

Você pode literalmente pedir ao Claude Code que sugira melhorias para o seu CLAUDE.md:

Look at this codebase and suggest additions to CLAUDE.md based on 
patterns you observe in the code.

O Claude Code vai varrer o seu projeto e sugerir convenções que percebe -- padrões de import, nomenclatura de arquivos, estruturas de teste e mais. Essa é uma ótima maneira de capturar convenções implícitas que você talvez não pensasse em documentar.

Use CLAUDE.md por diretório para projetos grandes

Se o seu projeto tem seções distintas com convenções diferentes (um frontend e um backend no mesmo repositório, por exemplo), use arquivos CLAUDE.md aninhados:

project/
  CLAUDE.md              # Global: monorepo structure, shared commands
  frontend/
    CLAUDE.md            # Frontend-specific: React patterns, styling rules
  backend/
    CLAUDE.md            # Backend-specific: API patterns, DB conventions
  infrastructure/
    CLAUDE.md            # Infra-specific: Terraform conventions, naming

Como o SuperBuilder ajuda

O SuperBuilder é um aplicativo desktop construído sobre o Claude Code que torna mais fácil gerenciar seu fluxo de trabalho de código com IA -- incluindo o seu CLAUDE.md.

Editor visual de CLAUDE.md

Em vez de editar manualmente um arquivo markdown, o SuperBuilder oferece um editor estruturado que organiza o seu CLAUDE.md em seções. Adicione comandos, convenções e notas de arquitetura por meio de uma interface limpa, e o SuperBuilder gera o markdown devidamente formatado.

Sugestões de modelos

Quando você abre um novo projeto no SuperBuilder, ele varre seu package.json, pyproject.toml, go.mod ou outros arquivos de manifesto e sugere um modelo de CLAUDE.md adaptado à sua stack. Um projeto React + Vite + Vitest recebe sugestões diferentes de um projeto Django + PostgreSQL.

Sistema de memória

O SuperBuilder mantém uma memória persistente entre sessões que funciona em conjunto com o CLAUDE.md. À medida que você trabalha com o Claude Code pelo SuperBuilder, ele lembra correções e preferências, acumulando contexto que complementa seu arquivo CLAUDE.md estático. Pense no CLAUDE.md como a documentação da equipe e na memória do SuperBuilder como suas anotações pessoais.

Integração com o modo de depuração

Quando o Claude Code está depurando um problema, o SuperBuilder registra hipóteses, resultados de testes e descobertas. Esse contexto de depuração funciona junto com o seu CLAUDE.md -- a arquitetura e as convenções que você documenta ajudam o Claude Code a formar hipóteses melhores sobre onde os bugs podem estar.

Juntando tudo

Aqui está um checklist para escrever o seu CLAUDE.md hoje:

1. Declare sua stack em 2-3 linhas no topo (framework, linguagem, bibliotecas principais)
2. Liste todos os comandos que um desenvolvedor precisa (dev, test, lint, build, migrate)
3. Mapeie sua estrutura de arquivos -- onde ficam os components, services, testes e configs?
4. Anote suas convenções -- as regras não escritas que sua equipe segue
5. Adicione restrições -- coisas que o Claude Code nunca deve fazer no seu projeto
6. Mantenha-o com menos de 200 linhas para a maioria dos projetos (500 no máximo para monorepos grandes)
7. Faça o commit no controle de versão para que toda a equipe se beneficie
8. Revise-o mensalmente e atualize quando sua stack ou seus padrões mudarem

Os melhores arquivos CLAUDE.md não são obras de arte. São práticos, específicos e atuais. Levam 15 minutos para escrever e poupam horas corrigindo código gerado por IA que não combina com o seu projeto.

Se você está usando o Claude Code sem um CLAUDE.md, está usando-o a uma fração do seu potencial. Escreva um hoje. Comece pequeno, aprimore e veja a qualidade do código gerado por IA no seu projeto disparar dramaticamente.

Perguntas frequentes

Qual deve ser o tamanho de um CLAUDE.md?

Para a maioria dos projetos, de 50 a 200 linhas é o ideal. Monorepos podem chegar a 300-500 linhas. Se você está acima de 500 linhas, provavelmente está incluindo informações que pertencem a arquivos de documentação separados.

Devo fazer o commit do CLAUDE.md no controle de versão?

Sim. O CLAUDE.md de nível de projeto deve estar no seu repositório para que todos os membros da equipe e ambientes de CI se beneficiem dele. Seu ~/.claude/CLAUDE.md pessoal permanece local.

O CLAUDE.md funciona com outras ferramentas de IA?

O CLAUDE.md é específico do Claude Code (e de ferramentas construídas sobre ele, como o SuperBuilder). No entanto, convenções semelhantes existem para outras ferramentas -- o Cursor usa .cursorrules, o GitHub Copilot usa .github/copilot-instructions.md. O conteúdo costuma ser transferível mesmo que o formato do arquivo seja diferente.

Posso ter vários arquivos CLAUDE.md?

Sim. O Claude Code lê arquivos CLAUDE.md do seu diretório home, da raiz do projeto e de qualquer subdiretório em que você esteja trabalhando. Eles são combinados, com os arquivos mais específicos tendo precedência.

E se o meu CLAUDE.md contradizer o código?

O Claude Code geralmente segue as instruções do seu CLAUDE.md, mas também lê o seu código real. Se houver uma contradição, ele pode ficar confuso ou pedir esclarecimentos. A solução é manter o seu CLAUDE.md em sincronia com a realidade -- documente o que existe e anote as mudanças planejadas separadamente.

Devo incluir chaves de API ou segredos no CLAUDE.md?

Nunca. O CLAUDE.md é versionado e não deve conter segredos. Use nomes de variáveis de ambiente: "Defina DATABASE_URL no .env para desenvolvimento local."

Como o CLAUDE.md é diferente de um README?

Um README é para desenvolvedores humanos e geralmente cobre setup, uso e diretrizes de contribuição. O CLAUDE.md é otimizado para consumo por IA -- ele foca em convenções, restrições e padrões que um agente de IA precisa para gerar código correto. Há alguma sobreposição, mas o público e os objetivos diferem.

Quer extrair mais do Claude Code? O SuperBuilder dá a você uma interface visual para gerenciar o CLAUDE.md, memória persistente entre sessões e ferramentas poderosas de depuração. Baixe gratuitamente em superbuilder.sh.