📁 Escopo de Projeto (Raiz)
O escopo mais comum e o CLAUDE.md na raiz do projeto. Este arquivo contem as instrucoes gerais que se aplicam a todo o repositorio. E o ponto de partida para qualquer configuracao do Claude Code.
💡 Conceito Principal
O CLAUDE.md na raiz e lido sempre que voce inicia o Claude Code em qualquer lugar dentro do projeto. Ele define o contexto base que se aplica a todos os arquivos e diretorios.
meu-projeto/
├── CLAUDE.md ← Escopo de Projeto
├── src/
├── tests/
├── package.json
└── ...
- •Sempre carregado, independente do subdiretorio atual
- •Ideal para convencoes gerais, tech stack e comandos
- •Deve ser versionado no Git junto com o projeto
⚡ Dica Pratica
Se voce so vai ter um CLAUDE.md, coloque na raiz. Ele cobre 90% dos casos de uso. So crie outros escopos quando tiver necessidades especificas por area do projeto.
📂 Escopo de Subdiretorio
Voce pode colocar arquivos CLAUDE.md em subdiretorios para adicionar instrucoes especificas para aquela area do projeto. Isso e util em monorepos ou projetos com partes muito distintas (ex: frontend vs backend).
💡 Conceito Principal
CLAUDE.md em subdiretorios sao carregados quando o Claude trabalha com arquivos naquele diretorio. Eles complementam (nao substituem) o CLAUDE.md da raiz.
meu-projeto/
├── CLAUDE.md ← Regras gerais
├── frontend/
│ ├── CLAUDE.md ← Regras do frontend
│ ├── src/
│ └── ...
├── backend/
│ ├── CLAUDE.md ← Regras do backend
│ ├── src/
│ └── ...
- •Complementa o CLAUDE.md da raiz (nao substitui)
- •Ideal para monorepos com frontend/backend separados
- •Pode ter convencoes de codigo especificas por area
⚡ Dica Pratica
Em um monorepo, o CLAUDE.md do frontend pode especificar "use React Server Components" enquanto o do backend diz "use FastAPI com Pydantic v2". Cada area tem suas regras.
🌍 Escopo Global
O CLAUDE.md global fica em ~/.claude/CLAUDE.md e se aplica a TODOS os projetos em que voce usa o Claude Code. E o lugar para preferencias pessoais que valem para qualquer projeto.
💡 Conceito Principal
O CLAUDE.md global e pessoal e nao e compartilhado com a equipe. Use para preferencias que sao suas, independente do projeto.
~/.claude/
└── CLAUDE.md ← Escopo Global
# Conteudo exemplo:
- Sempre responda em portugues brasileiro
- Use comentarios explicativos no codigo
- Prefira abordagens funcionais quando possivel
- Sempre inclua tratamento de erros
- •Localizado em
~/.claude/CLAUDE.md - •Aplicado a todos os projetos automaticamente
- •Nao e versionado no Git (e pessoal)
⚡ Dica Pratica
Coloque no CLAUDE.md global: seu idioma preferido para respostas, seu estilo de commit message, e preferencias de formatacao que voce quer em todos os projetos.
🏗️ Hierarquia e Combinacao
Quando existem multiplos arquivos CLAUDE.md, o Claude Code os combina hierarquicamente. O global e carregado primeiro, depois o da raiz do projeto, e por fim o do subdiretorio. Instrucoes mais especificas tem prioridade sobre as mais gerais.
💡 Conceito Principal
A ordem de carregamento e de prioridade segue a logica do mais geral para o mais especifico:
# Ordem de carregamento:
1. ~/.claude/CLAUDE.md (Global - menos especifico)
2. /projeto/CLAUDE.md (Projeto)
3. /projeto/src/CLAUDE.md (Subdiretorio - mais especifico)
# Se houver conflito, o mais especifico vence
- •Todos os niveis sao combinados, nao substituidos
- •Em caso de conflito, o mais especifico (subdiretorio) prevalece
- •O Claude recebe todas as instrucoes como um unico contexto
⚡ Dica Pratica
Evite contradizer no subdiretorio o que esta na raiz. Se o CLAUDE.md raiz diz "use Tailwind" e o do subdiretorio diz "use CSS Modules", isso pode confundir o Claude. Seja intencional com as excecoes.
📑 Trabalhando com Multiplos Arquivos
Em projetos grandes, voce pode ter varios CLAUDE.md espalhados pelo repositorio. A chave e manter cada um focado no seu escopo e evitar duplicacao de informacao entre eles.
💡 Conceito Principal
A regra de ouro e: informacao geral na raiz, informacao especifica nos subdiretorios. Nunca duplique conteudo.
monorepo/
├── CLAUDE.md # TypeScript, convencoes gerais
├── apps/
│ ├── web/
│ │ └── CLAUDE.md # Next.js, React, Tailwind
│ └── mobile/
│ └── CLAUDE.md # React Native, Expo
├── packages/
│ └── shared/
│ └── CLAUDE.md # Regras para codigo compartilhado
- •Cada CLAUDE.md deve ser autocontido no seu escopo
- •Evite duplicar informacoes entre niveis
- •Mantenha os arquivos curtos e objetivos
⚡ Dica Pratica
Lembre-se que cada CLAUDE.md consome tokens do contexto. Mantenha-os concisos. Se o total de todos os CLAUDE.md ficar muito grande, o Claude pode perder informacoes importantes que foram "empurradas" para fora da janela de contexto.
🎯 Quando Usar Cada Escopo
Saber quando usar cada escopo e fundamental para manter a organizacao. Cada nivel tem seu proposito e usar o escopo errado pode causar problemas de manutencao.
💡 Conceito Principal
Use este guia rapido para decidir onde colocar cada instrucao:
- •Global → Preferencias pessoais (idioma, estilo de resposta, formatacao)
- •Projeto (Raiz) → Tech stack, comandos, convencoes gerais, things to avoid
- •Subdiretorio → Regras especificas de uma area (frontend, API, testes)
⚡ Dica Pratica
Para a maioria dos projetos, um unico CLAUDE.md na raiz e suficiente. So adicione subdiretorios quando tiver areas com tecnologias ou convencoes realmente diferentes. Comece simples e expanda conforme necessario.
📋 Resumo do Modulo
Proximo Modulo:
2.4 - Exemplo Real: Next.js SaaS App