Error Resolver

Error Resolver

Uma abordagem de primeiros princípios para diagnosticar e resolver erros em todas as linguagens e frameworks.

Filosofia Central

O Processo de Resolução de Erros em 5 Passos:

1. CLASSIFICAR  ->  2. ANALISAR  ->  3. CORRESPONDER  ->  4. INVESTIGAR  ->  5. RESOLVER
     |                  |                |                    |                |
  Que tipo?         Extrair chaves    Padrão             Causa raiz      Corrigir +
                    informações       conhecido?         análise         Prevenir

Início Rápido

Quando encontrar um erro:

1. Cole o erro completo (incluindo stack trace, se disponível)
2. Forneça contexto (o que você estava tentando fazer?)
3. Compartilhe código relevante (arquivo/função envolvida)

Framework de Classificação de Erros

Categorias Primárias

Atributos Secundários

• Severidade: Fatal / Erro / Aviso / Informação
• Escopo: Tempo de compilação / Execução / Tempo de teste
• Origem: Código do usuário / Framework / Third-party / Sistema

Workflow de Análise

Passo 1: Classificar

Identifique a categoria do erro examinando:

• Nome/código do erro (ex: ENOENT, TypeError)
• Palavras-chave da mensagem de erro
• Onde ocorreu (compilação, execução, teste)

Passo 2: Analisar

Extraia informações-chave:

- Código do erro: [código específico, se houver]
- Caminho do arquivo: [onde o erro originou]
- Número da linha: [linha exata, se disponível]
- Função/método: [contexto do erro]
- Variável/valor: [o que estava envolvido]
- Profundidade da stack trace: [quão profunda é a pilha de chamadas]

Passo 3: Corresponder Padrões

Verifique contra padrões de erro conhecidos:

• Veja o diretório patterns/ para padrões específicos de linguagem
• Corresponda assinaturas de erro a soluções conhecidas
• Verifique o histórico de replay para soluções anteriores

Passo 4: Análise de Causa Raiz

Aplique a técnica dos 5 Porquês:

Erro: Cannot read property 'name' of undefined
  Por que 1? -> objeto user está undefined
  Por que 2? -> chamada de API retornou null
  Por que 3? -> ID do usuário não existe no banco de dados
  Por que 4? -> ID veio de cache desatualizado
  Por que 5? -> invalidação de cache não foi implementada

Causa Raiz: Lógica de invalidação de cache ausente

Passo 5: Resolver

Gere solução acionável:

1. Correção imediata - Fazer funcionar agora
2. Correção apropriada - A forma correta de resolver
3. Prevenção - Como evitar no futuro

Formato de Output

Ao resolver um erro, forneça:

## Diagnóstico do Erro

**Classificação**: [Categoria] / [Severidade] / [Escopo]

**Assinatura do Erro**:
- Código: [código do erro]
- Tipo: [tipo do erro]
- Localização: [arquivo:linha]

## Causa Raiz

[Explicação de por que esse erro ocorreu]

**Fatores Contribuintes**:
1. [Fator 1]
2. [Fator 2]

## Solução

### Correção Imediata
[Passos rápidos para resolver]

### Mudança de Código
[Código específico a adicionar/modificar]

### Verificação
[Como verificar se a correção funciona]

## Prevenção

[Como prevenir esse erro no futuro]

## Tag de Replay

[Identificador único para essa solução - para referência futura]

Sistema de Replay

O sistema de replay registra soluções bem-sucedidas para referência futura.

Registrando uma Solução

Após resolver um erro, registre-o:

# Crie diretório de registro de solução no projeto
mkdir -p .claude/error-solutions

# Formato do arquivo de solução: [error-type]-[hash].yaml

Formato de Registro de Solução

# .claude/error-solutions/[error-signature].yaml
id: "nodejs-module-not-found-express"
created: "2024-01-15T10:30:00Z"
updated: "2024-01-20T14:22:00Z"

error:
  type: "dependency"
  category: "ModuleNotFound"
  language: "nodejs"
  pattern: "Cannot find module 'express'"
  context: "npm project, missing dependency"

diagnosis:
  root_cause: "Package not installed or node_modules corrupted"
  factors:
    - "Missing npm install after git clone"
    - "Corrupted node_modules directory"
    - "Package not in package.json"

solution:
  immediate:
    - "Run: npm install express"
  proper:
    - "Check package.json has express listed"
    - "Run: rm -rf node_modules && npm install"
  code_change: null

verification:
  - "Run the application again"
  - "Check express is in node_modules"

prevention:
  - "Add npm install to project setup docs"
  - "Use npm ci in CI/CD pipelines"

metadata:
  occurrences: 5
  last_resolved: "2024-01-20T14:22:00Z"
  success_rate: 1.0
  tags: ["nodejs", "npm", "dependency"]

Busca de Replay

Ao encontrar um erro:

1. Gere assinatura de erro a partir da mensagem de erro
2. Pesquise .claude/error-solutions/ para padrões correspondentes
3. Se encontrado, aplique a solução registrada
4. Se novo, prossiga com análise completa e registre a solução

Geração de Assinatura de Erro

signature = hash(
  error_type +
  error_code +
  normalized_message +  # remova valores específicos
  language +
  framework
)

Exemplos de transformações:

• Cannot find module 'express' -> Cannot find module '{module}'
• TypeError: Cannot read property 'name' of undefined -> TypeError: Cannot read property '{prop}' of undefined

Comandos de Debug

Comandos úteis durante depuração:

Node.js

# Output de erro verboso
NODE_DEBUG=* node app.js

# Debug de memória
node --inspect app.js

# Verificar pacotes instalados
npm ls [package-name]

# Verificar package.json
npm ls --depth=0

Python

# Modo debug
python -m pdb script.py

# Verificar pacotes instalados
pip show [package-name]
pip list

Geral

# Verificar permissões de arquivo
ls -la [file]

# Verificar uso de porta
lsof -i :[port]
netstat -an | grep [port]

# Verificar variáveis de ambiente
env | grep [VAR_NAME]
printenv [VAR_NAME]

# Verificar espaço em disco
df -h

# Verificar memória
free -m  # Linux
vm_stat  # macOS

Padrões Comuns de Depuração

Padrão 1: Busca Binária

Quando a localização do erro é incerta:

1. Comente metade do código
2. Se o erro persistir, está na metade restante
3. Repita até encontrar a linha exata

Padrão 2: Reprodução Mínima

Crie o menor código que reproduz o erro:

1. Comece com arquivo vazio
2. Adicione código peça por peça
3. Interrompa quando o erro aparecer
4. Esse é seu caso de reprodução mínimo

Padrão 3: Rubber Duck Debugging

Explique o problema em voz alta (ou para Claude):

1. O que deveria acontecer?
2. O que realmente acontece?
3. O que mudou recentemente?
4. Quais pressupostos estou fazendo?

Padrão 4: Git Bisect

Encontre qual commit introduziu o bug:

git bisect start
git bisect bad  # commit atual é ruim
git bisect good [last-known-good-commit]
# Git fará checkout de commits para você testar
git bisect good/bad  # marque cada um como bom ou ruim
git bisect reset  # quando concluído

Arquivos de Referência

• patterns/ - Padrões de erro específicos de linguagem

  • nodejs.md - Erros comuns de Node.js
  • python.md - Erros comuns de Python
  • react.md - Erros de React/Next.js
  • database.md - Erros de banco de dados
  • docker.md - Erros de Docker/container
  • git.md - Erros de Git
  • network.md - Erros de rede/API

• analysis/ - Metodologias de análise

  • stack-trace.md - Guia de análise de stack trace
  • root-cause.md - Técnicas de análise de causa raiz

• replay/ - Sistema de replay

  • solution-template.yaml - Template para registrar soluções