Boas Práticas & Padrões

# O que INCLUIR no CLAUDE.md

✓ Stack técnico específico (ex: "Next.js 14 App Router + Prisma + PostgreSQL")
✓ Comandos do projeto (npm run dev, npm test, npm run build)
✓ Convenções de código (ex: "usamos kebab-case para arquivos, PascalCase para componentes")
✓ Arquivos críticos com propósito (ex: "src/lib/db.ts — cliente Prisma singleton")
✓ Exemplos de padrões usados (ex: "Server Actions em src/actions/")
✓ Restrições importantes (ex: "nunca modificar migrations existentes")

# O que EVITAR no CLAUDE.md

✗ Secrets e API keys (use .env)
✗ Informações genéricas que Claude já sabe (ex: "JavaScript é case-sensitive")
✗ Instruções longas demais — Claude lê tudo, contexto tem custo
✗ Regras contraditorias ou desatualizadas

# Projeto: [Nome]

## Stack
- Runtime: Node.js 20 + TypeScript 5
- Framework: Next.js 14 (App Router)
- DB: PostgreSQL via Prisma ORM
- Testes: Vitest + Testing Library

## Comandos
- `npm run dev` — servidor de desenvolvimento (porta 3000)
- `npm test` — roda testes com Vitest
- `npm run db:push` — sincroniza schema Prisma
- `npm run lint` — ESLint + Prettier

## Convenções
- Componentes: PascalCase em src/components/
- Arquivos: kebab-case
- Server Actions: src/actions/*.ts
- Tipos compartilhados: src/types/index.ts

## Arquivos Críticos
- src/lib/db.ts — cliente Prisma (singleton, não reinstanciar)
- src/lib/auth.ts — NextAuth config
- src/middleware.ts — proteção de rotas

## Padrões
- Sempre usar Server Components por padrão
- Client Components apenas quando necessário (useState, useEffect, eventos)
- Erros: usar Result type de src/lib/result.ts

# Prompts ruins vs. bons

✗ "Melhore meu código"
✓ "Refatore src/auth.ts para usar async/await em vez de .then()/.catch()
    e adicione tratamento de erros com Result type de src/lib/result.ts"

✗ "Faça testes"
✓ "Crie testes unitários para todas as funções exportadas em src/utils/format.ts
    usando Vitest. Mock dependências externas. Cobertura mínima: 80%."

✗ "Isso está errado"
✓ "Este código tem N+1 query problem na linha 45 de src/api/users.ts.
    Corrija usando include do Prisma para eager loading de posts."

✗ "Adicione autenticação"
✓ "Adicione autenticação JWT em src/api/middleware.ts. Use o padrão já
    existente em src/api/auth.ts. Tokens expiram em 24h. Retorne 401 para
    tokens inválidos com { error: 'Unauthorized' }."

# Rotina recomendada

Manhã — iniciar sessão limpa
  claude "o que foi modificado ontem? resume o estado atual do projeto"
  claude "qual é a tarefa prioritária de hoje?"

Durante o trabalho — sessões focadas
  Uma sessão por tarefa/feature quando possível
  /compact ao contexto crescer demais (~70% da janela)
  /status para monitorar tokens consumidos

Antes de parar
  claude "faça commit das mudanças com mensagem semântica"
  claude "resume o que foi feito para retomar amanhã" > HANDOFF.md

Revisão de PR
  claude "revise este diff e aponte: bugs, edge cases, melhorias de performance"
  git diff main..feature/branch | claude --stdin "revise este diff"

# Monitorando a sessão
/status                    # tokens usados, modelo, custo estimado

# Quando compactar
/compact                   # resume a sessão mantendo contexto essencial
# Use quando: tarefa longa, mudança de assunto, contexto > 70% da janela

# Quando reiniciar
# Use nova sessão quando: comportamento estranho, tarefa completamente diferente,
# bugs de raciocínio circulares

# Passando contexto entre sessões
claude "leia HANDOFF.md e retome de onde paramos"

# Referenciando arquivos em vez de colar conteúdo
# RUIM: colar 500 linhas de código no prompt
# BOM:  "analise src/components/UserCard.tsx e sugira melhorias"

# Regras essenciais de segurança

✗ Nunca cole API keys, tokens ou senhas no prompt
✗ Não peça ao Claude para fazer push diretamente em main sem review
✗ Cuidado com --dangerously-skip-permissions em máquinas de produção
✗ Não aprovem ações destrutivas sem ler o diff (rm -rf, DROP TABLE, etc.)

✓ Use allow/deny lists em settings.json para restringir ferramentas
✓ Revise cada ação destrutiva antes de aprovar
✓ Use plan mode antes de mudanças grandes ou arriscadas
✓ Configure .claudeignore para excluir arquivos sensíveis
✓ Em CI/CD: use ANTHROPIC_API_KEY como secret do sistema, nunca hardcoded
✓ Prefira sessões com auto-accept DESLIGADO em produção

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Bash(git *)",
      "Bash(npm run *)",
      "Bash(npx *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(sudo *)",
      "WebFetch"
    ]
  }
}

# Diagnóstico de sessão

# 1. Verifique o status da sessão
/status

# 2. Ative verbose para ver todas as chamadas de ferramentas
claude --verbose

# 3. Se o contexto estiver muito pesado
/compact

# 4. Se o comportamento for circular ou errado
# Inicie nova sessão — não tente "corrigir" uma sessão com reasoning falho

# 5. Se uma ferramenta específica não funcionar
# Verifique settings.json e permissões
cat ~/.claude/settings.json

# 6. Se resultados forem inconsistentes entre sessões
# Revise e atualize seu CLAUDE.md — pode estar desatualizado

# Flags úteis para debug
claude --verbose          # mostra cada chamada de tool
claude --output-format json  # saída estruturada para scripts
claude --no-auto-accept   # review manual de cada ação

# Review de um PR completo
git diff main..HEAD | claude --stdin \
  "Revise este diff. Foque em:
   1. Bugs e edge cases não tratados
   2. Problemas de segurança (SQL injection, XSS, auth bypass)
   3. Performance (N+1 queries, loops desnecessários)
   4. Conformidade com padrões do projeto (ver CLAUDE.md)
   Formato: lista de issues por categoria, severidade (alta/média/baixa)"

# Review de arquivo específico
claude "revise src/api/payments.ts focando em segurança e tratamento de erros"

# Review antes de cada commit (via hook)
# Ver módulo 15 para integração com pre-commit hooks

# Boas práticas para times

CLAUDE.md compartilhado no repositório
  - Versionado junto ao código
  - Revisado em PRs como qualquer outro arquivo
  - Atualizado quando padrões mudam

Separar configurações pessoais das do projeto
  ~/.claude/settings.json  — configurações pessoais (não versionar)
  .claude/settings.json    — configurações do projeto (versionar)

Documentar decisões de arquitetura
  "claude, por que foi escolhido X em vez de Y?" → save em ADR.md

Compartilhar prompts que funcionam bem
  Criar src/prompts/ com prompts reutilizáveis para tarefas comuns
  Ex: prompts/review-security.md, prompts/generate-tests.md