CLAUDE.md - Manual de Sobrevivência

Sabe quando alguém novo entra no projeto e você tem que explicar tudo do zero? Tipo: "esse botão aqui chama isso, que faz aquilo, que depende disso aqui…".

Agora imagina se a pessoa já soubesse tudo antes mesmo de te perguntar. É isso que o CLAUDE.md faz com o Claude.

É tipo deixar um bilhete super bem escrito pro seu futuro você — ou pro Claude — não fazer besteira quando estiver ajudando com o código.

Por que isso muda o jogo

Imagina esses dois cenários:

🔄 Você tem que explicar o projeto do zero toda vez que conversa com a IA

✨ Você conversa com alguém que já é quase um dev sênior do seu time, que já conhece tudo

O CLAUDE.md transforma o Claude de "um estagiário curioso" em um "parceiro de código com memória e contexto".

Estrutura Básica do CLAUDE.md

É tipo um manual de instruções + bastidores do projeto, dividido em seções essenciais que criam um contexto completo para a IA.

Regra de Ouro

Quando estiver em dúvida sobre como fazer algo, pergunta pro dev. Não inventa, não adivinha regra de negócio.

É como cozinhar na casa de alguém: se não sabe onde tá o sal, pergunta. Não pega açúcar achando que é igual.

Contexto do Projeto

Diz claramente:

• O que o projeto faz

• Pra quem ele serve

• Por que ele existe

Tipo explicar pra sua mãe o que você faz: "É um sistema que ajuda pessoas a montarem agentes de IA com memória e tarefas específicas, tipo assistentes virtuais inteligentes."

Decisões Arquiteturais Importantes

Em vez de dizer só "a gente usa PostgreSQL", explica o porquê.

Exemplos:

• A gente usa PostgreSQL + pgvector porque precisa de buscas por vetores e transações confiáveis (tipo: memória da IA com consistência).

• A gente usa Temporal porque o fluxo de trabalho dura dias, não segundos.

É como escolher entre uma Kombi e um caminhão baú. Depende do tipo de carga e do tempo de viagem.

Estilo de Código e Padrões

Explica como escrever o código aqui dentro:

• Usa o formatador Black com limite de 96 caracteres

• Organiza os imports com isort

• Usa tipagem completa (pra IA entender melhor e evitar erro humano)

É tipo deixar a cozinha arrumada do mesmo jeito sempre: o sal tá sempre na prateleira de cima.

Dicionário do Projeto

Algumas palavras têm significados muito específicos dentro do projeto. Se Claude entender errado, ferrou.

Exemplos:

Agent é um robô inteligente com memória e ferramentas — não é um agente secreto.

Task é o fluxo de tarefas da IA — e não uma task do Celery.

Session é o papo com memória, não só uma aba do navegador.

É tipo trabalhar num restaurante e saber que "ponto da carne" ali não significa localização geográfica.

Comentários Âncora (Anchor Comments)

É uma forma de colocar bilhetinhos estratégicos no código. Tipo grudar post-its inteligentes pros devs e pro Claude entenderem o que não pode ser ignorado.

AIDEV-NOTE

Algo que é muito importante e não pode ser mexido na inocência.

# AIDEV-NOTE: esse trecho é ultra performático. Não adicione mais nada aqui.

Tipo: "não mexe na fiação da casa sem desligar o disjuntor".

AIDEV-TODO

Coisa que ainda falta fazer, mas com contexto. Não é só um # TODO genérico.

# AIDEV-TODO: implementar paginação baseada em cursor (ticket FEED-123)

Tipo: "terminar de pintar a parede, mas só depois de secar o fundo".

AIDEV-QUESTION

É quando você deixa uma dúvida ou uma decisão não óbvia registrada.

                    # AIDEV-QUESTION: por que a filtragem de itens privados é feita aqui e não no cache?
                

Tipo: "coloquei o detergente na geladeira — estranho, mas tem motivo, depois te explico".

🛠 Exemplos de uso avançado

1. Performance

                    # AIDEV-NOTE: esse código roda 100 mil vezes por segundo. NÃO adicione consultas ao banco aqui.
                

2. Regras de negócio caras

                    # AIDEV-NOTE: cliente que paga R$10k/mês exige rastreabilidade. Não simplifique esse código.
                

3. Contratos de API

                    # AIDEV-NOTE: essa função serve apps mobile desde a versão 3.2. Mudança aqui exige migração.
                

Quando atualizar o CLAUDE.md?

Sempre que rolar:

1. Uma nova tecnologia → diz por que ela entrou no time.

2. Um padrão de código novo → escreve exemplo claro.

3. Um erro que se repete → ensina como evitar.

4. Uma mudança arquitetural → registra com detalhes.

Buscar Comentários Importantes

Comandos pra você encontrar bilhetes no código:

                    grep -r "AIDEV-NOTE" ./src
grep -r "AIDEV-TODO" ./src
grep -r "AIDEV-QUESTION" ./src
                

Tipo procurar todos os post-its vermelhos na parede de avisos.

O que você ganha com isso

2 horas pra escrever

Dezenas de horas economizadas por semana

Onboarding muito mais rápido

Código consistente e fácil de entender

Modelo Básico pra Começar

                            CLAUDE.md
                        

# CLAUDE.md - Nome do Projeto

## 📋 Contexto
1 parágrafo dizendo o que o projeto faz, pra quem e por quê.

## 🏗️ Decisões de Arquitetura
- Tecnologia X: usada porque Y
- Framework Z: escolhido por W

## 📝 Convenções
- Estilo de código: ferramentas e regras
- Padrões bons e ruins: exemplos claros

## 📚 Vocabulário do Projeto
- Palavra A: significado exato
- Palavra B: cuidado com confusão

## ⚡ Regras de Performance
- O que é proibido: nunca faça X
- O que é sagrado: sempre mantenha Y
                        

Copie este template e adapte para seu projeto

A mágica disso tudo?

Cada bug vira aprendizado.
Cada escolha vira documentação.
Cada padrão vira referência.

No fim, você treina a IA como se fosse um dev do seu time — e treina o time também.