Vibe-Code Cleanup — Refatoração de Produção

Um fluxo de trabalho seguro e incremental para limpeza de aplicativos fullstack gerados por IA / com "vibe-code". O objetivo é tornar a base de código pronta para produção sem quebrar nada que já funcione.

Quando Usar

• Use quando um aplicativo construído rapidamente funciona, mas tem imports quebrados, lógica duplicada, código morto, variáveis de ambiente pouco claras ou higiene de lançamento frágil.
• Use antes do lançamento ou da entrega para converter código exploratório em uma linha de base de produção mantenível.
• Use quando a limpeza deve preservar o comportamento existente e evitar grandes reescritas de rotas, APIs, autenticação, modelos de dados ou integrações.

Filosofia Principal

Cirurgia, não demolição. Remova apenas o que é comprovadamente inativo. Preserve todo o resto.

Nunca:

• Reescreva sistemas que funcionam por motivos estéticos
• Renomeie rotas, slugs ou endpoints de API que podem ser indexados ou cacheados
• Altere entradas/saídas de ferramentas, contratos de API, esquema de banco de dados ou fluxo de autenticação
• Exclua arquivos que você não verificou se estão em uso
• Faça grandes alterações em um único commit

Sempre:

• Faça alterações pequenas, direcionadas e reversíveis
• Valide após cada lote significativo de alterações
• Prefira helpers compartilhados em vez de blocos copiados e colados
• Mantenha a compatibilidade retroativa

Passo 1 — Reconhecimento (leia antes de tocar)

Antes de alterar qualquer coisa, mapeie a base de código:

# List all pages/routes
find . -type f \( -name 'page.js' -o -name 'page.jsx' -o -name 'page.ts' -o -name 'page.tsx' \)
find pages -type f \( -name '*.js' -o -name '*.jsx' -o -name '*.ts' -o -name '*.tsx' \) | rg -v '/_' | sort

# Find broken imports (TS projects)
npx tsc --noEmit 2>&1 | head -80

# Find unused exports (optional, for larger projects)
npx ts-prune 2>/dev/null | head -40

# Check for console.log / debug leftovers
grep -r "console\.log\|debugger\|TODO\|FIXME\|HACK" --include="*.{js,ts,jsx,tsx}" -l

Documente o que você encontrar. NÃO altere ainda.

Passo 2 — Corrija Imports Quebrados Primeiro

Imports quebrados causam falhas na compilação e devem ser corrigidos antes de qualquer outra coisa.

# TypeScript: list all errors
npx tsc --noEmit 2>&1

# Common patterns to fix:
# - Missing file (file was deleted or renamed)
# - Wrong relative path (../lib vs ../../lib)
# - Named export that doesn't exist

Regra de correção: Corrija a referência do import. NÃO exclua o arquivo referenciado a menos que você tenha confirmado que ele não é usado em nenhum lugar.

Passo 3 — Identifique Código Morto (verifique antes de remover)

Um arquivo/exportação é seguro para remover apenas se:

1. Nenhum outro arquivo o importa (confirmado por grep)
2. Ele não é referenciado em configurações, sitemap ou manifesto de rotas
3. Não é um URL público (page.js, route.js)

# Check if a file is imported anywhere
grep -r "from.*my-file\|require.*my-file" --include="*.{js,ts,jsx,tsx}" .

# Check if a component is used anywhere  
grep -r "MyComponent" --include="*.{js,ts,jsx,tsx}" .

Passo 4 — Consolide Lógica Repetida em Helpers

Procure por padrões repetidos (blocos de metadados, wrappers de busca de API, manipuladores de erro) que aparecem em 3+ locais.

Bons alvos de consolidação:

• Metadados de SEO em nível de página (Open Graph, Twitter cards, canônico)
• Wrappers de busca com tratamento de erros
• Funções utilitárias repetidas (slugify, formatDate, truncate)

Maus alvos de consolidação (deixe como está):

• Lógica de negócios única
• Manipuladores de rota com contratos diferentes
• Qualquer coisa que toque no esquema do banco de dados ou na autenticação

Padrão para helper de metadados compartilhados (Next.js):

// lib/socialMetadata.js
export function buildPageMetadata({ title, description, path, image }) {
  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || 'https://yourdomain.com';
  const imageUrl = image?.startsWith('http') ? image : `${baseUrl}${image}`;
  
  return {
    title,
    description,
    openGraph: {
      title,
      description,
      url: `${baseUrl}${path}`,
      images: [{ url: imageUrl, width: 1200, height: 630, alt: title }],
    },
    twitter: {
      card: 'summary_large_image',
      title,
      description,
      images: [imageUrl],
    },
    alternates: {
      canonical: `${baseUrl}${path}`,
    },
  };
}

Passo 5 — Auditoria de Variáveis de Ambiente

# List all env vars used in code
grep -r "process\.env\." --include="*.{js,ts,jsx,tsx}" . | grep -oP 'process\.env\.\w+' | sort -u

# Compare against .env.example or .env.local
cat .env.example 2>/dev/null || cat .env.local 2>/dev/null

Marque quaisquer variáveis de ambiente usadas no código, mas ausentes em .env.example. Nunca adicione segredos ao controle de versão.

…