Claude Code
Comente PERFIL no Instagram @gastaomatos

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.

prompt
# 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.

prompt
## 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.

prompt
## 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.

prompt
## 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

prompt
# [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

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 06

    Menos é mais no início. Comece com 10 linhas. É melhor um arquivo curto e lido do que um manual de 200 linhas ignorado.

  7. 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.

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 WhatsApp
DT

Gastão Matos

@gastaomatos