📁 CLAUDE.md no Root do Projeto
O local mais comum e importante para o CLAUDE.md e a raiz do repositorio. Quando voce coloca um CLAUDE.md no root, ele se aplica a todo o projeto, independentemente de qual subdiretorio voce esta trabalhando.
🎯 Conceito Principal
- •Escopo global do projeto: Tudo que esta no CLAUDE.md da raiz se aplica a qualquer arquivo ou diretorio do projeto
- •Ponto de entrada padrao: E o primeiro lugar que o Claude Code procura ao iniciar uma sessao
- •Versionado com o projeto: Vai para o git, pode ser revisado em PRs, evolui com o time
- •Unico obrigatorio: Se voce so vai ter um CLAUDE.md, coloque na raiz
💡 Dica Pratica
Comece sempre pela raiz. Mesmo que depois voce adicione CLAUDE.md em subdiretorios, o da raiz e o fundamento. Ele contem as regras universais do projeto: stack, comandos, convencoes gerais.
📂 CLAUDE.md em Subdiretorios
Voce pode colocar um CLAUDE.md em qualquer subdiretorio do projeto. Quando o Claude trabalha em arquivos daquele diretorio, ele le tanto o CLAUDE.md da raiz quanto o do subdiretorio, combinando as instrucoes.
🎯 Conceito Principal
- •Escopo local: Instrucoes especificas para aquele diretorio e seus filhos
- •Complementa o root: Nao substitui o CLAUDE.md da raiz, adiciona instrucoes extras
- •Ideal para monorepos: Cada package/app pode ter suas proprias regras
- •Exemplo classico: src/frontend/CLAUDE.md com regras de React, src/backend/CLAUDE.md com regras de API
💡 Dica Pratica
Use CLAUDE.md em subdiretorios quando partes do projeto tem convencoes muito diferentes. Em um monorepo com frontend React e backend Python, cada um merece seu proprio CLAUDE.md com regras especificas.
🌐 CLAUDE.md Global ~/.claude/
O CLAUDE.md global fica em ~/.claude/CLAUDE.md e se aplica a todos os projetos que voce abrir no Claude Code. E perfeito para preferencias pessoais que transcendem qualquer projeto.
🎯 Conceito Principal
- •Escopo universal: Aplicado em qualquer projeto, em qualquer diretorio
- •Preferencias pessoais: Seu estilo de comunicacao, idioma preferido, padroes que voce sempre segue
- •Nao vai para o git: Fica na sua maquina local, nao afeta outros membros do time
- •Exemplo: Responda sempre em portugues. Use arrow functions. Prefira composicao sobre heranca.
💡 Dica Pratica
O CLAUDE.md global e ideal para coisas como: 'Sempre responda em portugues', 'Prefira TypeScript sobre JavaScript', 'Use single quotes'. Coisas que sao suas preferencias pessoais, nao do projeto.
🔄 Como Claude Resolve Conflitos entre Escopos
Quando existem multiplos CLAUDE.md, o Claude combina todos, mas com uma hierarquia clara de prioridade. Entender essa hierarquia evita surpresas.
🎯 Conceito Principal
- •Prioridade: Subdiretorio > Root > Global. O mais especifico vence
- •Combinacao, nao substituicao: Claude le todos os CLAUDE.md relevantes e combina as instrucoes
- •Conflitos: Se o global diz 'use classes' e o root diz 'use funcoes', o root vence
- •Transparente: Voce pode perguntar ao Claude quais instrucoes ele carregou para verificar
💡 Dica Pratica
Pense na hierarquia como CSS: o seletor mais especifico vence. Se o global diz algo e o subdiretorio diz o oposto, o subdiretorio ganha. Use isso a seu favor: regras gerais no global, overrides especificos nos subdiretorios.
📚 Estrategia de Camadas
A estrategia de camadas e a forma mais eficiente de organizar seus CLAUDE.md. Cada camada adiciona contexto mais especifico, como camadas de uma cebola.
🎯 Conceito Principal
- •Camada 1 - Global: Preferencias pessoais, idioma, estilo de comunicacao
- •Camada 2 - Root do projeto: Stack, comandos, convencoes do projeto
- •Camada 3 - Subdiretorios: Regras especificas para frontend, backend, testes, etc
- •Principio DRY: Nao repita informacoes. Se algo esta no root, nao precisa repetir no subdiretorio
💡 Dica Pratica
Antes de adicionar uma regra ao CLAUDE.md de um subdiretorio, pergunte: 'Isso se aplica a todo o projeto?'. Se sim, coloque no root. A regra e: o mais alto possivel na hierarquia, o mais baixo necessario.
🎯 Quando Usar Cada Escopo
Com tres escopos disponiveis, a decisao de onde colocar cada instrucao se torna importante. Aqui esta um framework de decisao pratico.
🎯 Conceito Principal
- •Use Global para: Idioma, preferencias de estilo pessoal, padroes que voce segue em TODO projeto
- •Use Root para: Stack do projeto, comandos, convencoes de codigo, things to avoid
- •Use Subdiretorio para: Regras de frontend vs backend, padroes de teste, convencoes de API
- •Nao exagere: A maioria dos projetos precisa apenas do Root. Subdiretorios sao para casos especificos
💡 Dica Pratica
Se voce esta comecando, use so o root. Adicione um CLAUDE.md global quando perceber que repete as mesmas instrucoes em todo projeto. Adicione subdiretorios quando partes do projeto tem regras conflitantes.
Exercicio Pratico
Exercicio: Criar CLAUDE.md Global + Projeto + Subdiretorio
Tempo estimado: 15-20 minutos
Criar CLAUDE.md global
Crie ~/.claude/CLAUDE.md com suas preferencias pessoais: idioma, estilo de codigo preferido, padroes universais.
Criar CLAUDE.md no root de um projeto
No root do seu projeto, crie CLAUDE.md com stack, comandos e convencoes especificas.
Criar CLAUDE.md em um subdiretorio
Escolha um subdiretorio (ex: src/api/) e crie um CLAUDE.md com regras especificas para aquela area.
Verificar hierarquia
Abra Claude Code no subdiretorio e pergunte: 'Quais instrucoes voce carregou? De quais arquivos?'. Verifique se a combinacao esta correta.
📋 Resumo do Modulo
Proximo Modulo:
2.4 - Regras Modulares (.claude/rules/)