📄 O que é CLAUDE.md
CLAUDE.md é um arquivo Markdown que o Claude Code lê automaticamente ao iniciar uma sessão. Ele funciona como a "memória de longo prazo" do CC — instruções permanentes que ficam disponíveis em toda sessão sem você precisar repetir.
🧠 Como o CC usa o CLAUDE.md
Ao iniciar, o CC procura e carrega automaticamente os arquivos CLAUDE.md encontrados na hierarquia de diretórios. O conteúdo é injetado no contexto inicial da sessão — antes de qualquer mensagem sua.
- • Carregamento automático: sem precisar mencionar o arquivo em cada sessão
- • Persiste entre sessões: o arquivo fica no disco, o contexto sempre disponível
- • Sobrevive ao /compact: mesmo após compactação, o CLAUDE.md é recarregado
✗ Sem CLAUDE.md
Sessão 1: "Estamos usando FastAPI, Python 3.11, pytest para testes..."
Sessão 2: "Lembra que usamos FastAPI? Sim, e o padrão é type hints em tudo..."
Sessão 3: "Nosso comando para rodar é make run, não npm start..."
Repetindo contexto toda sessão = tempo desperdiçado
✓ Com CLAUDE.md
Sessão 1: CC já sabe o stack, convenções e comandos.
Sessão 2: CC ainda sabe tudo — arquivo não mudou.
Sessão 3: Você começa direto com a tarefa.
Zero repetição = foco total na tarefa
🗂️ Global vs Projeto
Existem dois níveis de CLAUDE.md: global (suas preferências pessoais, aplicado em todos os projetos) e local (específico para o repositório, commit junto com o código). Ambos são carregados juntos — o local complementa o global.
Global: ~/.claude/CLAUDE.md
Suas preferências pessoais, aplicadas em todo projeto que você trabalha.
- • Idioma preferido para respostas (português)
- • Estilo de código pessoal (type hints, docstrings)
- • Ferramentas que você sempre usa (ripgrep, fd)
- • Instruções de comportamento geral do CC
Projeto: .claude/CLAUDE.md
Contexto específico do repositório. Vai no git e é compartilhado com o time.
- • Stack tecnológico e versões
- • Comandos do projeto (make run, npm test)
- • Convenções do time
- • Restrições e decisões arquiteturais
💡 Quando fazer commit do CLAUDE.md
Faça commit do CLAUDE.md do projeto junto com o código. Assim todo membro do time que usar CC terá o contexto correto automaticamente — sem onboarding manual de preferências.
✍️ O que Colocar
O conteúdo ideal de um CLAUDE.md é direto e acionável. CC lê como instruções, não como documentação — então seja conciso e específico. Evite texto explicativo longo; prefira listas e exemplos.
✓ Coloque no CLAUDE.md
- ✓ Linguagem, versão e frameworks principais
- ✓ Comandos para rodar, testar e buildar
- ✓ Convenções de nomenclatura e estilo
- ✓ Coisas para NUNCA fazer (print() para debug, commitar sem testes)
- ✓ Decisões arquiteturais importantes já tomadas
✗ Não coloque no CLAUDE.md
- ✗ Documentação detalhada de APIs (use arquivos separados)
- ✗ Histórico de mudanças (use git log)
- ✗ Segredos ou credenciais (nunca em texto plano)
- ✗ Informações que mudam frequentemente (use comentários no código)
- ✗ Textos longos explicativos — CC prefere listas diretas
📋 Exemplo Prático
Um CLAUDE.md real e completo para um projeto Python com FastAPI. Use este como template e adapte para sua stack — está equilibrado em tamanho e cobertura de contexto.
# Projeto: API REST em Python
## Stack
- Python 3.11+
- FastAPI
- PostgreSQL (via SQLAlchemy 2.0)
- Alembic para migrações
- pytest para testes
## Convenções
- Usar type hints em TODAS as funções
- Docstrings no formato Google Style
- Funções máximo 30 linhas — dividir se passar disso
- Testes para toda função pública
- Variáveis em snake_case, classes em PascalCase
## Comandos
- `make run` — inicia o servidor de desenvolvimento
- `make test` — roda os testes com coverage
- `make lint` — roda ruff + mypy
- `make migrate` — aplica migrações pendentes
- `make shell` — abre shell Python com contexto do app
## Estrutura
- `src/api/` — rotas FastAPI
- `src/models/` — modelos SQLAlchemy
- `src/services/` — lógica de negócio
- `src/schemas/` — schemas Pydantic
## Não fazer
- Não usar print() para debug — usar logging
- Não commitar sem testes passando (`make test`)
- Não colocar lógica de negócio nas rotas — usar services
- Não usar `*` em imports
- Não fazer queries SQL diretas — usar SQLAlchemy ORM💡 Como criar o seu
Peça ao próprio CC para criar o CLAUDE.md do seu projeto:
> Analise este projeto e crie um CLAUDE.md adequado com stack, convenções e comandos identificados
CC vai explorar os arquivos do projeto (package.json, requirements.txt, Makefile etc.) e gerar um CLAUDE.md relevante.
📁 Sub-CLAUDE.md em Subpastas
Em projetos grandes, você pode criar CLAUDE.md em subpastas. Quando o CC trabalha em um arquivo dentro de uma pasta, ele também carrega o CLAUDE.md daquela pasta — fornecendo contexto específico do módulo.
Exemplo de hierarquia
meu-projeto/
├── .claude/
│ └── CLAUDE.md ← contexto do projeto inteiro
├── src/
│ ├── api/
│ │ └── CLAUDE.md ← rotas FastAPI, padrões de endpoint
│ ├── models/
│ │ └── CLAUDE.md ← convenções SQLAlchemy, relações
│ └── services/
│ └── CLAUDE.md ← padrões de service, validações
└── tests/
└── CLAUDE.md ← fixtures disponíveis, factories💡 Quando usar sub-CLAUDE.md
- Monorepos: frontend e backend com stacks completamente diferentes
- Módulos complexos: quando uma pasta tem padrões únicos que não se aplicam ao resto
- Times diferentes: cada time mantém o CLAUDE.md da sua área
- Contexto de testes: listar fixtures, factories e helpers disponíveis para testes
📏 Boas Práticas de Tamanho
CLAUDE.md consome tokens da janela de contexto em cada sessão. Um arquivo muito longo desperdiça espaço com informações raramente usadas — espaço que poderia ser aproveitado pelo código real.
📊 Guia de tamanho ideal
500–1500 tokens (~400–1200 palavras) — cobre o essencial sem desperdiçar contexto
1500–2500 tokens — projetos grandes com muitas convenções, revise se pode dividir
Acima de 3000 tokens — prefira sub-CLAUDE.md por módulo ou use referências a arquivos separados
💡 Regra de ouro do CLAUDE.md
Se você não usa uma informação pelo menos uma vez por semana de trabalho no projeto, não coloque no CLAUDE.md. Informações raramente usadas consomem contexto sem benefício — coloque em arquivos de documentação separados e referencie quando necessário.
✅ Resumo do Módulo 5.2
Próximo Módulo:
5.3 — 🔨 Projetos Práticos: criando scripts, debugando e gerando testes com Claude Code