Como escrever um CLAUDE.md que realmente funciona
Dato clave
Um CLAUDE.md bem escrito pode reduzir em 70% o número de instruções que você precisa dar ao Claude por sessão. É o arquivo mais importante do seu projeto.
O CLAUDE.md é o arquivo que faz o Claude parar de ser um estranho e começar a operar como parte da sua equipe. Aqui está a estrutura exata, com template para copiar.
Passo 1: entenda onde o arquivo vive
O CLAUDE.md fica na raiz do projeto (ou em ~/.claude/CLAUDE.md para configuração global). Claude Code lê esse arquivo automaticamente ao iniciar cada sessão dentro da pasta. Você pode ter dois: um global (para informações sobre você) e um por projeto (para contexto específico daquele trabalho).
Passo 2: defina quem você é e o que você faz
Comece com o bloco de identidade. Não escreva um currículo. Escreva o que o Claude precisa saber para tomar decisões melhores.
# Contexto Sou gestor de tráfego e co-fundador do DR.TRAFEGO. Gerencio 12 contas Meta Ads. Stack principal: Next.js, Drizzle, Neon, Claude Code. Foco em automação de operação de agência, não em desenvolvimento de produto.
Passo 3: defina as regras que nunca mudam
Este é o bloco mais valioso. Tudo que você sempre precisaria dizer antes de qualquer tarefa vai aqui.
## Regras gerais - NUNCA use travessões nem hifens decorativos. Use vírgula, ponto ou dois-pontos. - Responda sempre em português BR - Prefira ações diretas, não faça perguntas desnecessárias - Quando não souber um valor, pergunte. Não chute. - Confirme ações destrutivas antes de executar
Passo 4: documente o stack e os projetos ativos
Diga ao Claude com o que você trabalha. Isso reduz drasticamente o número de perguntas que ele precisa fazer antes de começar.
## Stack padrão - Next.js 15 (App Router, Server Components) - TypeScript strict - Drizzle ORM + Neon PostgreSQL - Tailwind CSS v4 + shadcn/ui - pnpm como package manager - Deploy no Vercel ## Projetos ativos - lp_trafego: LP principal casaldotrafego.com - mvp_crm: CRM leads Meta Ads - agent_campanhas_meta: scripts e agentes Meta Ads
Passo 5: adicione os agentes disponíveis
Se você usa slash commands ou subagentes, liste aqui. O Claude passa a sugerir o agente certo na hora certa.
## Agentes disponíveis /copy → Cleo: copywriting, anúncios, conteúdo social /analista → Alex: métricas, relatórios, diagnósticos /gestor → Gage: campanhas Meta Ads via MCP /designer → Dani: direção criativa, briefings
Passo 6: teste e itere
Abra uma sessão nova e olhe como o Claude responde às primeiras perguntas. Se ele ainda pede informações que deveriam estar no CLAUDE.md, adicione. O arquivo cresce com o uso.
Template completo para copiar e colar
# [Seu nome] — Contexto Permanente ## Quem sou [Profissão e contexto de trabalho em 2 ou 3 linhas] [Stack principal ou ferramentas que você usa] [Foco do trabalho (o que você está construindo ou gerenciando)] ## Regras gerais - Responda sempre em português BR - NUNCA use travessões nem hifens decorativos - Prefira ações diretas. Não faça perguntas desnecessárias. - Quando não souber um valor, pergunte. Não chute. - Confirme ações destrutivas antes de executar - Nunca adicione features além do pedido - Nunca crie arquivos desnecessários ## Stack padrão - [Framework principal] - [Banco de dados] - [Ferramentas de trabalho] - [Package manager] - [Onde você faz deploy] ## Projetos ativos - [pasta]: [descrição curta] - [pasta]: [descrição curta] ## Contas e credenciais de contexto - [Conta ou sistema]: [identificador, sem senha] ## Agentes disponíveis (se aplicável) /[comando] → [Nome]: [função]
Pro tips
- 01
Global vs projeto: use o CLAUDE.md global (~/.claude/CLAUDE.md) para quem você é e as regras que nunca mudam. Use o CLAUDE.md do projeto para contexto específico daquele trabalho.
- 02
Não escreva um manual. O arquivo não precisa cobrir tudo. Cobre o que você sempre precisaria repetir. Se algo aparece só uma vez, não vai pro CLAUDE.md.
- 03
Regras negativas funcionam melhor: NUNCA use travessão é mais efetivo que use boa pontuação. Seja específico sobre o que você não quer.
- 04
Documente erros que se repetem. Se o Claude errou duas vezes no mesmo padrão, adicione uma regra no CLAUDE.md para prevenir a terceira.
- 05
Versione o arquivo. Trate o CLAUDE.md como código. Commita junto com o projeto. Quando algo parar de funcionar, você pode ver o histórico.
- 06
Menos é mais no início. Comece com 10 linhas. É melhor um arquivo curto e lido do que um manual de 200 linhas ignorado.
- 07
Atualize após cada sessão produtiva. Se você deu uma instrução ao Claude que funcionou muito bem, anote no CLAUDE.md antes de fechar.
Continue lendo
Instalando Claude Code no terminal (Mac, Windows e Linux)
Passo a passo completo de instalação do Claude Code para os três sistemas operacionais, com os erros mais comuns documentados e os primeiros comandos pra rodar.
Template de equipe de tráfego para Claude Code
6 agentes especializados (analista, gestor, copywriter, social, designer, closer) prontos para ativar com slash commands. Template CLAUDE.md completo.
Como conectar o Claude ao Meta Ads via MCP
MCP é o protocolo que deixa o Claude falar com ferramentas externas. Passo a passo para conectar Claude Code à API do Meta Ads e operar campanhas pelo terminal.
Perguntas frequentes
O CLAUDE.md é obrigatório?
Não é obrigatório, mas sem ele você repete contexto toda sessão. Em qualquer projeto que você abra mais de duas vezes, vale ter um. É o investimento de 10 minutos que economiza horas depois.
Posso ter CLAUDE.md global e por projeto ao mesmo tempo?
Sim. O Claude lê os dois. Use o global (~/.claude/CLAUDE.md) para regras universais (idioma, tom, padrões de código) e o do projeto para contexto específico daquele trabalho (stack, schema, agentes).
Qual tamanho ideal pro arquivo?
Entre 50 e 200 linhas no início. Cresce conforme o uso. Se passar de 400 linhas você está provavelmente colocando coisas que deveriam estar em outros lugares (documentação técnica, README, etc).
Posso colocar credenciais no CLAUDE.md?
Não. Coloque só identificadores (IDs de conta, nomes de tabela, URLs públicas). Tokens, senhas e chaves de API vão em .env e o CLAUDE.md menciona apenas que existem.
O Claude segue todas as regras do arquivo?
Na grande maioria das vezes sim, principalmente as primeiras 20 a 30 linhas. Regras muito específicas no final do arquivo podem ser ignoradas se o contexto da tarefa for muito grande. Coloque o crítico no topo.
Quer implementar isso?
Me chama no WhatsApp. Ajudo você a configurar ou implemento pra você.
Quero ajuda no WhatsAppGastão Matos
@gastaomatos