CLAUDE.md — o cérebro do seu projeto

Use um único arquivo markdown para dar contexto permanente ao Claude

⏱ Estim. ~4 min

01 · Ler

Toda vez que você abre uma nova sessão do Claude Code, o Claude começa do zero. Ele não lembra da sua última conversa, do seu estilo de código, das convenções do seu projeto, nem mesmo qual framework você usa. Você precisa explicar tudo de novo a cada vez.

O CLAUDE.md resolve isso. É um arquivo markdown que o Claude lê no início de cada sessão — o manual de instruções permanente do seu projeto.

💡 Imagine assimPense no CLAUDE.md como o documento de onboarding de um novo membro do time. Em vez de explicar as convenções todas as manhãs, você escreve uma vez. O CLAUDE.md é esse documento — o Claude lê toda vez que "começa a trabalhar".

Pontos-chave

Cada sessão do Claude Code começa do zero — não lembra conversas anteriores
O CLAUDE.md é carregado automaticamente no início de cada sessão
Ele informa ao Claude as regras, convenções e contexto importante do seu projeto
É só um arquivo markdown — você edita como qualquer outro arquivo

02 · Ler

O CLAUDE.md pode ficar em três lugares, cada um com um escopo diferente.

Nível de projeto — coloque CLAUDE.md na raiz do repo (ou em .claude/CLAUDE.md). Compartilhado com o time via git. Use para convenções do projeto, comandos de build, padrões de arquitetura.

Nível de usuário — coloque em ~/.claude/CLAUDE.md. É pessoal e vale para todos os projetos. Use para suas preferências individuais.

Subdiretórios — arquivos CLAUDE.md em subdiretórios são carregados sob demanda quando o Claude lê arquivos daquele diretório. Bom para instruções específicas de um módulo.

Pontos-chave

Nível de projeto (./CLAUDE.md): compartilhado com o time, commitado no git
Nível de usuário (~/.claude/CLAUDE.md): pessoal, vale para todos os seus projetos
CLAUDE.md de subdiretório: carregamento sob demanda para módulos específicos
Em caso de conflito, as regras do projeto sobrescrevem as do usuário

03 · Exemplo de código

Um bom CLAUDE.md inclui comandos de build, estilo de código, arquitetura e convenções específicas do projeto. Abaixo, um exemplo real.

Exemplo de CLAUDE.md

# Build & Test
- `npm run dev` — start frontend dev server
- `npm run build` — TypeScript check + production build
- `npm test` — run tests (Vitest)

# Code Style
- TypeScript strict mode, ES modules (import/export)
- 2-space indentation, single quotes
- Functional React components, no class components

# Architecture
- API routes in `server/src/routes/`
- Database schema in `server/src/db/schema.ts`
- Frontend components in `src/components/`

# Important
- The `--color-purple` CSS variable is actually orange (#FF6B35)
- Auth cookies use sameSite: 'none' for cross-origin

Repare no que ele inclui: coisas que o Claude não descobriria só lendo o código. Comandos de build, convenções de nomeação incomuns, peculiaridades entre fontes. Não inclua o que o Claude pode descobrir explorando — foque no que não é óbvio.

04 · Exemplo de código

Quando seu CLAUDE.md crescer, você pode usar imports e um diretório de rules para dividi-lo em arquivos focados.

CLAUDE.md com @import

# Project Overview
See @README.md for project description
See @specs/ARCHITECTURE.md for system design

# Code Style
@docs/code-style.md

Estrutura do diretório rules

.claude/
├── CLAUDE.md          (main instructions)
└── rules/
    ├── api-design.md  (API conventions)
    ├── testing.md     (test patterns)
    └── security.md    (security rules)

O prefixo @ importa o conteúdo de outro arquivo para o CLAUDE.md. O diretório .claude/rules/ guarda regras específicas por tema, carregadas automaticamente pelo Claude. Mantém o CLAUDE.md principal enxuto e dá ao Claude acesso a conhecimento detalhado por domínio.

05 · Quiz

Você tem convenções de projeto que todo dev do time deve seguir. Onde colocar o CLAUDE.md para compartilhar com o time?

No seu diretório do usuário (~/.claude/CLAUDE.md)
Na raiz do repo (./CLAUDE.md), commitado no git
Um Google Doc linkado no README
Uma mensagem fixada no canal do Slack

06 · Preencher

Para importar outro arquivo no CLAUDE.md, coloque _____ antes do caminho

Outras lições deste capítulo

⚠ A experiência interativa completa precisa de JavaScript. Ative-o e recarregue a página.

※ Este é um projeto educacional independente — não é um produto oficial da Anthropic. Claude™ é uma marca registrada da Anthropic, PBC.