🎯 O que é CLAUDE.md
Toda vez que você abre o Claude Code em um projeto, ele procura um arquivo chamado CLAUDE.md e o lê automaticamente, antes de qualquer coisa. Esse arquivo é seu documento central de identidade — define quem o agente é naquele contexto, quais regras seguir, o que nunca fazer e qual o estado atual do projeto. Sem ele, cada sessão começa do zero. Com ele, o agente sabe exatamente onde está e como operar.
📌 O que o CLAUDE.md carrega
- •Identidade do agente — nome, função, persona, tom de voz.
- •Contexto do negócio — o que é o projeto, quem são os usuários, qual o objetivo.
- •Regras inegociáveis — o que nunca fazer, o que sempre fazer.
- •Decisões já tomadas — para não revisitar o que já foi resolvido.
- •Padrões técnicos — stack, convenções de código, estrutura de pastas.
👤 Marco, e-commerce de moda
"Antes do CLAUDE.md eu passava 10 minutos no início de cada sessão explicando o projeto. Depois, o agente já sabia tudo — stack, tom, o que era produto, o que era variante. Ganho imediato."
🏗️ Estrutura de um CLAUDE.md útil
Um CLAUDE.md sem estrutura vira diário de bordo — cresce sem critério e perde sinal no ruído. Um CLAUDE.md com estrutura clara é um manual operacional: qualquer agente que o lê sabe exatamente como operar. A estrutura não precisa ser rígida, mas precisa ser intencional.
Seções recomendadas
- # Identidade — quem sou, função, tom de voz, língua padrão.
- # Contexto do Projeto — o que é, stack, estrutura de pastas chave.
- # Regras Inegociáveis — NUNCA / SEMPRE. Máximo 10 itens, objetivos.
- # Decisões Tomadas — escolhas arquiteturais já resolvidas + motivo.
- # Estado Atual — o que está em progresso, o que está bloqueado.
- # Personas — usuário-alvo, stakeholders chave (opcional).
✓ Bom CLAUDE.md
- ✓Seções claras com headers
- ✓Regras curtas e acionáveis
- ✓Exemplos concretos
- ✓Menos de 500 tokens
- ✓Atualizado após cada erro recorrente
✗ CLAUDE.md problemático
- ✗Parágrafo longo sem estrutura
- ✗Duplica o README inteiro
- ✗Changelog de commits
- ✗Mais de 2000 tokens
- ✗Regras vagas ("seja cuidadoso")
🌳 Hierarquia: global → projeto → local
O Claude Code suporta três níveis de CLAUDE.md que se combinam em cascade. O global fica em ~/.claude/CLAUDE.md e define regras que valem em todos os projetos. O projeto fica na raiz do repositório e define contexto específico. O local fica em subpastas e sobrescreve apenas naquele escopo.
🌳 Cascade de CLAUDE.md
- ~/.claude/CLAUDE.md — regras globais: língua, estilo, proibições universais.
- projeto/CLAUDE.md — contexto do projeto: stack, regras de negócio, personas.
- projeto/subpasta/CLAUDE.md — override local: regras específicas para aquela área.
Regra mais específica vence. Local sobrescreve projeto; projeto sobrescreve global.
💡 Dica prática — Sally, escritório jurídico
Sally tem no global: "sempre responder em inglês formal". No projeto do cliente X tem: "responder em português". O agente no projeto X usa português — sem conflito, sem confusão. Cascade funciona como CSS: específico ganha.
📐 Tom, estilo e regras inegociáveis
As regras inegociáveis são o DNA do agente — o que ele faz em todas as situações, sem depender do prompt. São guardas-rails que protegem contra erros recorrentes, desvios de qualidade e comportamentos que você já aprendeu a custo que precisam ser bloqueados. Escreva-as como comandos diretos: NUNCA, SEMPRE, OBRIGATÓRIO.
Exemplos de regras eficazes
- Tom: "Sempre responda em português. Nunca use linguagem informal com clientes."
- Código: "Nunca faça commit diretamente em main. Sempre crie branch feature/."
- Dados: "Nunca leia /secrets/. Nunca escreva fora de /src/ sem aprovação."
- Qualidade: "Sempre rodar testes antes de propor PR. Nunca silenciar erros com try/catch vazio."
- Formato: "Sempre usar 2 espaços de indentação. TypeScript strict mode obrigatório."
📊 Regra dos 10
Mantenha no máximo 10 regras inegociáveis por CLAUDE.md. Mais que isso, o sinal se dilui. Se você tem 20 regras, provavelmente metade é redundante ou deveria ser uma convenção de código — não uma regra do agente.
🚫 O que NÃO colocar
O CLAUDE.md é lido em todas as sessões, inteiro, antes de qualquer trabalho. Cada token que você coloca tem custo real em tempo e dinheiro. Um CLAUDE.md inflado com conteúdo de baixo valor é literalmente dinheiro queimado em overhead, toda sessão. A disciplina de manter o documento enxuto é tão importante quanto mantê-lo atualizado.
✗ Não pertence ao CLAUDE.md
- ✗Changelog / histórico de decisões antigas
- ✗Credenciais, tokens, senhas (NUNCA)
- ✗Documentação técnica extensa
- ✗Duplicata do README ou docs/
- ✗Listas de todos os arquivos do projeto
- ✗Instruções para uma única tarefa pontual
✓ Pertence ao CLAUDE.md
- ✓Identidade e função do agente
- ✓Regras que se aplicam em toda sessão
- ✓Decisões arquiteturais + motivo
- ✓Stack e convenções mínimas
- ✓O que está em progresso agora
- ✓Links para Silver Platters relevantes
⚠️ Alerta crítico
Jamais coloque credenciais, API keys ou senhas em CLAUDE.md. O arquivo normalmente vai para o git. Use variáveis de ambiente ou cofre de secrets. Um vazamento acidental custa muito mais que qualquer conveniência.
🔄 Evolução do CLAUDE.md
O CLAUDE.md não é um documento que você escreve uma vez e esquece — é um organismo vivo. Cada vez que o agente comete um erro recorrente, você adiciona uma regra. Cada vez que uma decisão arquitetural é tomada, você registra. Cada vez que o projeto muda de direção, você atualiza o contexto. A maturidade do CLAUDE.md reflete diretamente a maturidade do seu sistema agêntico.
Ciclo de evolução
- 1. Erro recorrente detectado → adiciona regra inegociável no CLAUDE.md.
- 2. Decisão tomada → registra em "Decisões Tomadas" com motivo.
- 3. CLAUDE.md cresce demais → faz limpeza: remove o que não é universal, move para Silver Platters.
- 4. Projeto muda de fase → atualiza "Estado Atual" e "Contexto".
- 5. Novo agente entra no projeto → lê o CLAUDE.md e está operacional em minutos.
💡 CLAUDE.md em controle de versão
Versionar o CLAUDE.md no git é obrigatório. Mudanças no documento de identidade do agente precisam passar por review — da mesma forma que mudanças em código crítico. Um PR que altera as regras inegociáveis do agente merece a mesma atenção que um PR que altera a autenticação.
📋 Resumo do Módulo
Próximo Módulo:
2.2 — AGENTS.md como padrão multi-vendor