CLAUDE.md: como dar memória, contexto e personalidade ao agente

# Claude Code procura CLAUDE.md em três locais, nesta ordem:

# 1. ~/.claude/CLAUDE.md — preferências globais
#    Ativo em TODOS os projetos. Use para preferências pessoais universais.

# 2. CLAUDE.md em diretórios pai
#    Ex: ~/projetos/empresa/CLAUDE.md — ativo para todos os repos da empresa.
#    Útil para monorepos ou times com convenções compartilhadas.

# 3. CLAUDE.md na raiz do projeto
#    Contexto específico do projeto. Commite no repositório para que
#    todos no time tenham o mesmo comportamento de Claude Code.

# Todos são concatenados e injetados como contexto de sistema.
# Exemplo de hierarquia real:

~/.claude/CLAUDE.md:
# Preferências pessoais
- Responda sempre em português brasileiro
- Prefira commits atômicos e descritivos
- Antes de criar um arquivo novo, verifique se já existe similar

~/projetos/empresa/CLAUDE.md:
# Convenções da empresa
- Seguimos Google Style Guide para Python
- Toda mudança em banco precisa de migration reversível
- PRs não podem ter mais de 400 linhas alteradas

~/projetos/empresa/api/CLAUDE.md (este projeto):
# Stack: FastAPI + PostgreSQL + Redis
# Testar: pytest src/tests/ -x
# Deploy: ./scripts/deploy.sh staging

# Exemplo de CLAUDE.md bem estruturado (projeto Next.js):

# CLAUDE.md

## Visão Geral
Plataforma de e-learning com gamificação. Stack: Next.js 16, TypeScript, Tailwind v4.
Sem backend — 100% localStorage. Deploy estático na Hostinger via export.

## Comandos essenciais
npm run dev      # dev server em localhost:3000
npm run build    # build estático em out/
npm run lint     # ESLint

## Gotcha: processos órfãos
Se npm run dev der erro: pkill -f "next-server" && rm -rf .next

## Arquitetura
- src/lib/curriculum.ts  → fonte única do currículo (modificar aqui para conteúdo)
- src/components/article/primitives.tsx → Section, Callout, CodeBlock, ComparisonTable
- src/app/aprenda/[slug]/page.tsx → um arquivo por artigo
- Nunca hardcode hex — sempre usar var(--ffv-*) para cores

## Convenções
- Commits em PT-BR, formato: "tipo: descrição curta"
- Artigos em português brasileiro, sem hype, sem clickbait
- Usar primitive Section/Callout/CodeBlock — nunca definir inline
- Não usar next/image (desabilitado no export)

# ~/.claude/CLAUDE.md — o arquivo que você cria uma vez e esqueça

# Preferências de idioma e tom
Responda sempre em português brasileiro, exceto se o código ou arquivo estiver em inglês.
Mantenha respostas concisas — evite explicar o óbvio.

# Segurança e revisão
Antes de deletar arquivos ou pastas, confirme listando o que será deletado.
Ao criar arquivos novos, verifique se já existe algo similar no projeto.

# Git
Prefira commits atômicos (uma mudança lógica por commit).
Mensagens de commit seguem Conventional Commits: feat/fix/refactor/docs/test/chore.
Nunca faça git push sem confirmação explícita.

# Código
Não adicione comentários desnecessários — código legível não precisa de comentário óbvio.
Não adicione features não pedidas — faça exatamente o que foi solicitado.
Quando encontrar um bug adjacente ao que estava corrigindo, mencione mas não corrija sem pedir.

# Ambiente
Sistema operacional: macOS. Shell: zsh.
Node.js: 20.x. Python: 3.12.
Editor principal: VS Code.

# CLAUDE.md é contexto e instruções de comportamento.
# Não é um substituto para:

# 1. Hooks — para automação de eventos
# CLAUDE.md: "sempre rode os testes depois de editar" → isso é uma instrução
# Hooks (.claude/hooks/): script que EFETIVAMENTE roda os testes automaticamente
# A diferença: instrução depende de Claude seguir; hook é determinístico

# 2. Skills / slash commands — para workflows repetitivos
# CLAUDE.md: "para fazer deploy, siga estes passos: ..."
# Skill (.claude/commands/deploy.md): /deploy → executa o workflow automaticamente

# 3. Variáveis de ambiente — para segredos
# CLAUDE.md: ❌ NUNCA coloque API keys, senhas, tokens
# Use: .env + .gitignore, ou variáveis de ambiente do sistema

# 4. Documentação de referência — para specs e ADRs
# CLAUDE.md é lido A CADA SESSÃO → deve ser conciso (< 2.000 tokens idealmente)
# Para especificações longas, use docs/ separados e instrua Claude a ler quando precisar:
# "Para decisões de arquitetura, leia docs/ADR/"
# Claude lerá o arquivo específico sob demanda, não antecipadamente

# 5. Histórico de contexto da conversa — para tarefas com múltiplas sessões
# CLAUDE.md persiste entre sessões; histórico de conversa não
# Para retomar uma tarefa longa: claude --continue (retoma a última sessão)
# Ou resuma o estado ao final de cada sessão em um arquivo de "work in progress"

# CLAUDE.md deve ser commitado no repositório — não é arquivo pessoal de dev

# Benefícios:
# - Todo desenvolvedor do time tem o mesmo comportamento do Claude Code
# - Onboarding: novo dev instala Claude Code, clona o repo, já tem contexto
# - Review: mudanças no CLAUDE.md ficam no histórico git — auditável

# Ciclo de manutenção:
# 1. Algo quebra frequentemente? → adicione ao CLAUDE.md como gotcha
# 2. Um comando novo virou essencial? → documente em "Comandos"
# 3. CLAUDE.md está crescendo demais? → mova detalhes para docs/ e referencie

# Dica: revise o CLAUDE.md a cada sprint
# Perguntas para a revisão:
# - Tem algo aqui que Claude nunca usa?
# - Tem algo que repetiram nas últimas sessões e deveria estar aqui?
# - Há algum gotcha novo que vale documentar?

# Tamanho ideal: 200-800 linhas (suficiente para contexto, conciso o bastante
# para não desperdiçar tokens a cada sessão)

# Para verificar o tamanho em tokens (aproximação):
wc -c CLAUDE.md   # bytes
# 1 token ≈ 4 bytes → 4000 bytes = ~1000 tokens