📄 O que e CLAUDE.md
CLAUDE.md e um arquivo de memoria do projeto que vive na raiz do seu repositorio. Toda vez que voce inicia uma sessao do Claude Code, ele le esse arquivo primeiro, ganhando contexto instantaneo sobre o que e o projeto, como funciona e quais regras seguir. Pense nele como um briefing automatico para o seu assistente de codificacao.
🎯 Conceito Principal
CLAUDE.md e um arquivo Markdown simples que funciona como memoria persistente entre sessoes. Ele nao e codigo, nao e configuracao tecnica. E um documento em linguagem natural que diz ao Claude tudo que ele precisa saber sobre o seu projeto.
- • Formato: Arquivo Markdown (.md) na raiz do repositorio. Pode ter qualquer conteudo em texto, listas, tabelas, blocos de codigo
- • Leitura automatica: Claude Code le o CLAUDE.md automaticamente ao iniciar cada sessao. Voce nao precisa pedir para ele ler
- • Escopo: As instrucoes do CLAUDE.md se aplicam a toda sessao de trabalho naquele projeto. E como dar um briefing no inicio de cada dia de trabalho
- • Versionavel: Por ser um arquivo no repo, ele entra no git, pode ser revisado em PRs, e evolui com o projeto
💡 Dica Pratica
A analogia mais precisa para CLAUDE.md e o onboarding de um novo desenvolvedor. Quando alguem entra no time, voce explica a stack, as convencoes, os comandos importantes e as regras do projeto. CLAUDE.md faz exatamente isso, mas para o Claude Code. A diferenca e que o Claude "esquece tudo" entre sessoes, entao ele precisa desse onboarding toda vez.
Crie o CLAUDE.md agora mesmo, mesmo que minimo. Comece com 5 linhas: nome do projeto, stack principal, como rodar o dev server, como rodar testes e uma regra importante. Voce pode expandir depois.
🔄 Por que toda sessao comeca lendo CLAUDE.md
Cada sessao do Claude Code comeca do zero. O Claude nao lembra o que voce conversou ontem, quais decisoes tomaram ou qual o padrao de codigo do projeto. O CLAUDE.md resolve isso ao funcionar como uma carga de contexto instantanea que acontece automaticamente antes de qualquer interacao.
🎯 Conceito Principal
O mecanismo e simples: ao iniciar, o Claude Code procura o arquivo CLAUDE.md no diretorio atual e em diretorios pai. Se encontrar, injeta o conteudo como contexto de sistema antes de qualquer prompt do usuario. Isso significa que o Claude ja sabe sobre seu projeto antes mesmo de voce digitar a primeira palavra.
- • Context loading: O conteudo do CLAUDE.md e carregado como instrucoes de sistema, com prioridade alta na atencao do modelo
- • Zero esforco: Nao precisa copiar/colar nada, nao precisa dizer "leia o CLAUDE.md". E automatico
- • Consistencia: Toda sessao comeca com as mesmas instrucoes, garantindo comportamento previsivel e consistente
💡 Dica Pratica
Para verificar se o Claude esta lendo seu CLAUDE.md, inicie uma sessao e pergunte: "Quais instrucoes voce tem sobre este projeto?". Ele deve listar exatamente o que esta no seu CLAUDE.md. Se nao listar, o arquivo pode estar no diretorio errado ou com nome incorreto (case-sensitive: deve ser CLAUDE.md, nao claude.md).
📊 CLAUDE.md vs Documentacao Tradicional
Muita gente confunde CLAUDE.md com README.md ou com documentacao de projeto. Sao coisas fundamentalmente diferentes em proposito, audiencia e formato. Entender essa diferenca e crucial para criar um CLAUDE.md eficaz.
🎯 Conceito Principal
A diferenca fundamental: README.md e para humanos entenderem o projeto. CLAUDE.md e para o Claude entender como trabalhar no projeto. A audiencia muda tudo.
- • README.md: Explica o que o projeto faz, como instalar, como contribuir. Feito para humanos que estao conhecendo o projeto pela primeira vez
- • CLAUDE.md: Instrucoes operacionais para o Claude. Quais comandos rodar, quais padroes seguir, o que evitar. Feito para um agente de AI que vai escrever codigo
- • Docs tradicionais: Referencia detalhada de APIs, arquitetura, fluxos. Otima para consulta, mas excessiva para o Claude (tokens demais)
Comparacao Direta
| Aspecto | README.md | CLAUDE.md |
|---|---|---|
| Audiencia | Humanos | Claude Code (AI) |
| Proposito | Apresentar o projeto | Instruir como trabalhar |
| Tamanho ideal | Sem limite | < 200 linhas |
| Conteudo | Descricao, instalacao, uso | Stack, comandos, regras, padroes |
| Leitura | Manual, sob demanda | Automatica, toda sessao |
💡 Dica Pratica
Nao tente transformar seu README.md em CLAUDE.md ou vice-versa. Sao documentos complementares. O README explica "o que e isso?". O CLAUDE.md explica "como eu devo trabalhar nisso?". Mantenha ambos, cada um com seu foco.
📈 O Impacto na Qualidade das Respostas
A diferenca entre usar Claude Code com e sem CLAUDE.md e dramatica. Sem ele, o Claude precisa adivinhar suas convencoes, sua stack e suas preferencias. Com ele, o Claude ja comeca sabendo tudo isso e produz codigo que se encaixa perfeitamente no seu projeto.
🎯 Conceito Principal
O impacto do CLAUDE.md e mensuravel em tres dimensoes: precisao (codigo que segue suas convencoes), velocidade (menos correcoes manuais) e consistencia (mesmo padrao em toda sessao).
- • Sem CLAUDE.md: Claude usa convencoes genericas. Pode gerar codigo com default exports quando voce usa named exports, com classes quando voce usa funcoes, com npm quando voce usa pnpm
- • Com CLAUDE.md: Claude segue suas convencoes desde a primeira linha de codigo. Named exports, componentes funcionais, pnpm, Tailwind. Exatamente como voce quer
- • Reducao de retrabalho: Equipes reportam ate 60% menos correcoes manuais apos implementar CLAUDE.md bem escrito
Sem CLAUDE.md
export default function Button() {
return <button className="btn">
Click me
</button>
}
Com CLAUDE.md
export const Button = () => {
return <button className="px-4 py-2 bg-blue-500">
Click me
</button>
}
💡 Dica Pratica
Faca o teste: abra o Claude Code num projeto sem CLAUDE.md e peca para criar um componente. Depois crie um CLAUDE.md com suas convencoes e repita o mesmo pedido. A diferenca na qualidade do output vai ser obvia e imediata.
🤔 Quando Criar e Quando Nao Criar
CLAUDE.md nao e obrigatorio e nem sempre e necessario. Existem cenarios onde ele agrega muito valor e cenarios onde e desnecessario ou ate contraproducente. Vamos definir um framework de decisao claro.
🎯 Conceito Principal
A regra e simples: se voce vai usar Claude Code no projeto mais de uma vez, crie um CLAUDE.md. O investimento de 10 minutos se paga na segunda sessao.
- • Sempre criar: Projetos ativos onde voce usa Claude Code regularmente. Projetos de equipe. Projetos com convencoes especificas
- • Opcional: Scripts one-off, projetos de aprendizado, prototipos rapidos que serao descartados
- • Nao criar: Projetos onde voce nunca usa Claude Code. Repos de documentacao pura. Repos de assets/imagens
💡 Dica Pratica
Na duvida, crie. Um CLAUDE.md de 5 linhas ja e melhor que nenhum. Voce pode comecar com apenas: nome do projeto, linguagem principal e comando de build. Depois vai adicionando conforme percebe o que o Claude erra sem a instrucao.
🌍 Exemplos do Mundo Real
Os melhores CLAUDE.md vem de projetos reais. Vamos ver exemplos de projetos open source que usam CLAUDE.md para instruir o Claude Code de forma eficaz.
🎯 Conceito Principal
Projetos de referencia no GitHub ja adotaram CLAUDE.md como parte do workflow. Estudar como eles estruturam o arquivo e a melhor forma de aprender o que funciona na pratica.
# CLAUDE.md
## Project Overview
SaaSify - B2B subscription management platform.
Built with Next.js 14 (App Router), TypeScript, Supabase.
## Commands
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
## Code Conventions
- Server Components by default
- Named exports for all components
- Zod for all input validation
## Things To Avoid
- Never use "any" type
- Don't use Pages Router
- Never commit .env files
💡 Dica Pratica
Pesquise no GitHub por filename:CLAUDE.md para encontrar exemplos reais. Copie a estrutura que mais se parece com o seu projeto e adapte. Nao reinvente a roda.
Exercicio Pratico
Exercicio: Explorar CLAUDE.md de 3 Projetos Open Source
Tempo estimado: 15-20 minutos
Pesquisar no GitHub
Acesse o GitHub e pesquise por repositorios que contem CLAUDE.md:
Analisar 3 projetos diferentes
Escolha projetos com stacks diferentes (ex: um em TypeScript, um em Python, um em Go). Para cada um, anote: quais secoes tem, qual o tamanho, quais regras definem.
Comparar padroes
Identifique o que e comum entre todos os CLAUDE.md e o que e especifico de cada projeto. Isso te mostra o "esqueleto" universal que todo CLAUDE.md deve ter.
✅ Criterios de Sucesso
📋 Resumo do Modulo
Proximo Modulo:
2.2 - Anatomia do CLAUDE.md Perfeito