Caçador de Bugs

Caçe e corrija bugs sistematicamente usando técnicas de depuração comprovadas. Sem adivinhações — siga as evidências.

Quando Usar Esta Habilidade

• O usuário relata um bug ou erro
• Algo não está funcionando como esperado
• O usuário diz "corrija o bug" ou "depure isso"
• Falhas intermitentes ou comportamento estranho
• Problemas de produção precisam de investigação

O Processo de Depuração

1. Reproduzir o Bug

Primeiro, faça com que ele aconteça consistentemente:

1. Get exact steps to reproduce
2. Try to reproduce locally
3. Note what triggers it
4. Document the error message/behavior
5. Check if it happens every time or randomly

Se você não conseguir reproduzir, colete mais informações:

• Qual ambiente? (dev, staging, prod)
• Qual navegador/dispositivo?
• Quais ações do usuário o precederam?
• Existem logs de erro?

2. Coletar Evidências

Reúna todas as informações disponíveis:

Verificar logs:

# Application logs
tail -f logs/app.log

# System logs
journalctl -u myapp -f

# Browser console
# Open DevTools → Console tab

Verificar mensagens de erro:

• Rastreamento de pilha completo (stack trace)
• Tipo e mensagem de erro
• Números de linha
• Carimbo de data/hora

Verificar estado:

• Quais dados estavam sendo processados?
• O que o usuário estava tentando fazer?
• O que há no banco de dados?
• O que há no armazenamento local/cookies?

3. Formular uma Hipótese

Com base nas evidências, adivinhe o que está errado:

"The login times out because the session cookie 
expires before the auth check completes"

"The form fails because email validation regex 
doesn't handle plus signs"

"The API returns 500 because the database query 
has a syntax error with special characters"

4. Testar a Hipótese

Prove ou desprove sua suposição:

Adicionar logs:

console.log('Before API call:', userData);
const response = await api.login(userData);
console.log('After API call:', response);

Usar depurador (debugger):

debugger; // Execution pauses here
const result = processData(input);

Isolar o problema:

// Comment out code to narrow down
// const result = complexFunction();
const result = { mock: 'data' }; // Use mock data

5. Encontrar a Causa Raiz

Rastreie até o problema real:

Causas raiz comuns:

• Valores nulos/indefinidos (null/undefined)
• Tipos de dados incorretos
• Condições de corrida (race conditions)
• Falta de tratamento de erros
• Lógica incorreta
• Erros de "um a mais" (off-by-one errors)
• Problemas com async/await
• Falta de validação

Exemplo de rastreamento:

Symptom: "Cannot read property 'name' of undefined"
↓
Where: user.profile.name
↓
Why: user.profile is undefined
↓
Why: API didn't return profile
↓
Why: User ID was null
↓
Root cause: Login didn't set user ID in session

6. Implementar Correção

Corrija a causa raiz, não o sintoma:

Correção ruim (sintoma):

// Just hide the error
const name = user?.profile?.name || 'Unknown';

Boa correção (causa raiz):

// Ensure user ID is set on login
const login = async (credentials) => {
  const user = await authenticate(credentials);
  if (user) {
    session.userId = user.id; // Fix: Set user ID
    return user;
  }
  throw new Error('Invalid credentials');
};

7. Testar a Correção

Verifique se realmente funciona:

1. Reproduce the original bug
2. Apply the fix
3. Try to reproduce again (should fail)
4. Test edge cases
5. Test related functionality
6. Run existing tests

8. Prevenir Regressão

Adicione um teste para que ele não volte:

test('login sets user ID in session', async () => {
  const user = await login({ email: 'test@example.com', password: 'pass' });
  
  expect(session.userId).toBe(user.id);
  expect(session.userId).not.toBeNull();
});

Técnicas de Depuração

Busca Binária

Corte o espaço do problema pela metade repetidamente:

// Does the bug happen before or after this line?
console.log('CHECKPOINT 1');
// ... code ...
console.log('CHECKPOINT 2');
// ... code ...
console.log('CHECKPOINT 3');

Depuração com Pato de Borracha (Rubber Duck Debugging)

Explique o código linha por linha em voz alta. Frequentemente, você identificará o problema enquanto explica.

Depuração por Impressão (Print Debugging)

console.logs estratégicos:

console.log('Input:', input);
console.log('After transform:', transformed);
console.log('Before save:', data);
console.log('Result:', result);

Depuração por Diferença (Diff Debugging)

Compare o que funciona com o que está quebrado:

• O que mudou recentemente?
• O que é diferente entre os ambientes?
• O que é diferente nos dados?

Depuração com Viagem no Tempo (Time Travel Debugging)

Use o git para descobrir quando quebrou:

git bisect start
git bisect bad  # Commit atual está quebrado
git bisect good abc123  # Este commit antigo funcionava

…