# Busca e correção de bugs com Claude Code: guia prático

> Guia prático completo para depuração de código via Claude Code: análise de stack traces, interpretação de logs do servidor, correção de erros TypeScript, ajuste de testes e eliminação de gargalos de desempenho.

## 1. Por que a depuração com Claude Code é mais eficiente do que o debugging tradicional

O processo clássico de busca por erros frequentemente se transforma em uma rotina exaustiva: o desenvolvedor passa horas navegando por stack traces confusos no terminal, inserindo manualmente dezenas de `console.log` ou pontos de interrupção do debugger e tentando correlacionar dados de vários módulos.

O agente de terminal Claude Code altera fundamentalmente essa abordagem: tendo acesso direto ao sistema de arquivos, ele pode percorrer instantaneamente a cadeia de execução desde a interface do usuário (UI) do cliente, passando pelos controladores do backend, até as consultas ao banco de dados.

```mermaid
flowchart TD
    A["Симптом: Помилка або аварійний лог"] --> B["Claude Code CLI"]
    B --> C["Аналіз Stack Trace & Виділення файлів"]
    C --> D["Read & Grep по кодовій базі"]
    D --> E["Локалізація джерела збою"]
    E --> F["Генерація гіпотези та виправлення"]
    F --> G["Автоматичний прогін тестів / збірки"]
    G -->|Успіх| H["Коміт виправлення"]
    G -->|Помилка| E
```

### Comparação entre debugging manual e depuração com Claude Code

| Critério | Depuração manual tradicional | Depuração com Claude Code |
| :--- | :--- | :--- |
| **Localização do erro** | Navegação manual pelas linhas da pilha na IDE | Correspondência automática do erro com o contexto do projeto |
| **Trabalho com logs** | Busca visual por anomalias em milhares de linhas | Análise autônoma de logs estruturados via pipelines CLI |
| **Relações complexas** | Necessidade de manter mentalmente o grafo de chamadas de 5-10 arquivos | Rastreamento semântico passo a passo dos fluxos de dados |
| **Erros TypeScript** | Tentativas de resolver rapidamente usando `as any` | Correção adequada da narrowing de tipos sem violar o sistema |
| **Verificação da correção** | Reinício manual da aplicação ou testes no console | Reinício automático e cíclico dos testes até o sucesso total |

> [!NOTE]
> O Claude Code não substitui a compreensão do código pelo desenvolvedor, mas reduz o tempo entre a ocorrência do incidente e a localização da causa raiz em 3 a 5 vezes.

---

## 2. Anatomia de um bug report ideal para assistentes de IA

A qualidade e a velocidade da resolução dependem diretamente da completude da descrição do bug na solicitação inicial.

### Solicitação vaga versus descrição estruturada

> [!WARNING]
> **Solicitação ineficiente:**
> *«A aplicação quebrou, o formulário de registro não funciona, veja o que há de errado.»*
> 
> Com base nessa descrição, o agente é forçado a vasculhar dezenas de arquivos aleatoriamente, desperdiçando os limites da janela de contexto com suposições.

> [!TIP]
> **Descrição profissional de engenharia:**
> *«Ao enviar o formulário para `/register`, o usuário recebe um status 500. No console do navegador aparece o erro: `TypeError: Cannot read properties of undefined (reading 'email')`. A requisição envia JSON com os campos `username` e `mailAddress`. Verifique o esquema de validação em `src/api/auth.ts` e alinhe os nomes dos campos.»*

### Quatro regras para uma descrição exaustiva do defeito

1. **Comportamento Esperado (Expected Behavior):** o que deveria acontecer exatamente em um cenário de sucesso.
2. **Comportamento Real (Actual Behavior):** o texto exato do erro, código de status ou resultado inesperado do cálculo.
3. **Passos para Reprodução (Reproduction Steps):** quais botões foram clicados, quais parâmetros foram passados na URL ou qual corpo de requisição foi enviado.
4. **Contexto de Localização (Context & File Paths):** em qual página, componente ou endpoint específico a execução falha.

---

## 3. Análise de Stack Traces e decomposição de mensagens de erro

Mensagens de erro e stacks de chamadas podem ser fornecidos ao agente em sua forma bruta. O Claude filtrará automaticamente o ruído das bibliotecas do sistema (`node_modules`) e focará no código do seu projeto.

### Fornecendo o stack trace bruto do erro

```text
I am getting this runtime error when rendering the user table:

TypeError: Cannot read properties of undefined (reading 'map')
    at UserTable (src/components/UserTable.tsx:34:22)
    at renderWithHooks (node_modules/react-dom/cjs/react-dom.development.js:15486:18)
    at mountIndeterminateComponent (node_modules/react-dom/cjs/react-dom.development.js:20103:13)

What is causing this, and how should we properly handle loading and empty states?
```

### Como o Claude analisa incidentes semelhantes

1. **Leitura direcionada:** abre `src/components/UserTable.tsx` na linha 34 usando a ferramenta `Read`.
2. **Análise da fonte de dados:** verifica props e hooks de estado (`useState`, `useQuery`) para determinar por que o array de usuários está `undefined` no momento da renderização.
3. **Correção segura:** adiciona verificação de existência de dados (Optional Chaining `users?.map(...)`), estado de carregamento (Skeleton/Spinner) ou valores padrão (`users = []`).

---

## 4. Trabalho com logs de servidor e análise via pipeline CLI

Para investigar falhas no servidor ou erros em ambientes de staging, o Claude Code pode ser conectado diretamente aos fluxos padrão de entrada/saída do Unix.

### Análise de logs via pipeline de console

```bash
# Передати останні 100 рядків серверного логу в Claude для швидкої діагностики
tail -n 100 /var/log/nginx/error.log | claude -p "Find critical errors and explain their root cause. Provide actionable fix instructions."

# Пошук помилок із конкретного сервісу Docker
docker logs --tail 200 api-service 2>&1 | claude -p "Analyze database connection failures and timeout exceptions."
```

### Investigação interativa de arquivos de log

Em uma sessão interativa, você pode direcionar o agente para logs salvos:

```text
Read logs/production-error.log and focus on entries with status 500 from the last two hours. Group related exceptions and trace which external service call failed.
```

O Claude identificará padrões recorrentes de falhas, detectará problemas de autenticação em APIs externas ou esgotamento do pool de conexões com o banco de dados.

---

## 5. Instrumentação estratégica: logging pontual e tracing

Os bugs mais complexos são os chamados "Silent Bugs" (defeitos silenciosos), quando a aplicação não lança exceções, mas retorna resultados incorretos (por exemplo, o valor total do pedido calculado como `$0.00` em vez de `$42.50`).

Nesses casos, utiliza-se o método de instrumentação estratégica.

### Algoritmo passo a passo de investigação

1. **Defina a tarefa de inserção de logs:**
   ```text
   The order total calculation is returning 0 for items with promo codes. Add targeted diagnostic logging to calculateOrderTotal and its call sites to log input arguments, discount factors, and return values.
   ```
2. **Reproduza o bug na aplicação:** execute um pedido com cupom de desconto no ambiente de teste.
3. **Retorne os logs diagnósticos obtidos ao agente:**
   ```text
   Here is the diagnostic log from the checkout attempt:
   [DEBUG] Item subtotal: 42.50
   [DEBUG] Promo code applied: 'SPRING20' -> parsed discount: '0.2' (string)
   [DEBUG] Applying formula: 42.50 * (1 - '0.2') -> NaN -> coerced to 0

   What went wrong?
   ```
4. **Correção e limpeza:**
   O Claude indicará imediatamente o problema de incompatibilidade de tipos (string em vez de número), corrigirá a função de parsing e **removerá automaticamente todos os logs temporários de depuração**.

---

## 6. Correção de erros complexos de tipo em TypeScript

Erros do compilador TypeScript podem ser intrincados, especialmente ao trabalhar com generics, unions de tipos ou objetos aninhados.

### Por que é perigoso "silenciar" o compilador

Muitos desenvolvedores, na pressa, utilizam coerção explícita de tipos (`as unknown as TargetType`), o que oculta o problema na etapa de build, mas leva a falhas em runtime.

:::tabs
@tab Abordagem perigosa (Type Casting)
```typescript
// Погано: примусове ігнорування проблеми типів
const userEmail = (response.data as any).user.email;
// Якщо user виявиться null, додаток впаде в продакшені!
```
@tab Narrowing de tipos correto (Type Narrowing)
```typescript
// Добре: безпечне звуження типів через захисники
if (!response.data || typeof response.data !== 'object' || !('user' in response.data)) {
  throw new Error('Invalid API response structure');
}
const userEmail = response.data.user?.email ?? 'anonymous';
```
:::

### Instrução para o Claude sobre uma solução limpa

```text
I am encountering this TypeScript compiler error in src/services/payment.ts:48:

Type 'string | undefined' is not assignable to type 'string'.
Type 'undefined' is not assignable to type 'string'.

Fix this issue properly using strict type narrowing or safe fallback values. Do NOT use type assertions ('as') or 'any'.
```

O Claude verificará todo o ciclo de vida da variável e adicionará uma verificação correta para ausência de valor.

---

## 7. Reparo automatizado de builds e testes em loop

Uma das capacidades mais poderosas do Claude Code é o trabalho autônomo no ciclo "Executar → Analisar → Corrigir → Verificar".

```mermaid
flowchart TD
    A["Команда: 'Fix all failing tests'"] --> B["Запуск npm test через Bash"]
    B --> C{"Всі тести пройдено?"}
    C -->|Так| D["Звіт про успішне завершення"]
    C -->|Ні| E["Аналіз помилок у звіті тестувальника"]
    E --> F{"Де баг: у коді чи в тесті?"}
    F -->|У коді| G["Виправлення бізнес-логіки"]
    F -->|У тесті| H["Оновлення застарілих очікувань тесту"]
    G & H --> B
```

### Templates prontos de comandos para eliminação de defeitos

:::tabs
@tab Reparo de testes unitários (Jest / Vitest)
```text
Run the test suite with npm test. For each failing test:
1. Determine if the failure is caused by a real bug or an outdated test expectation.
2. Fix the underlying issue cleanly.
3. Re-run tests until all test suites pass.
```
@tab Correção de erros de compilação do build
```text
Run npm run build. Inspect the compiler and bundler error output. Fix all type and syntax errors, then verify with a clean build.
```
@tab Eliminação de erros de linting (ESLint)
```text
Run npx eslint src/ --max-warnings=0. Fix all reportable style and syntax errors without disabling ESLint rules.
```
:::

---

## 8. Identificação de gargalos de performance e vazamentos de recursos

Erros não são apenas crashes. Páginas lentas, sobrecarga excessiva do banco de dados e travamentos da interface são defeitos críticos de performance.

### Solicitação de auditoria de desempenho

```text
The /dashboard page takes over 6 seconds to load. Analyze the server-side data fetching and client components:
1. Check for N+1 query patterns in our Prisma calls.
2. Identify missing database indices on frequently queried foreign keys.
3. Look for unnecessary client component re-renders caused by unstable object references.
```

### O que o Claude procura durante a análise de performance

- **Consultas N+1:** substituição de consultas em loop por uma única consulta com operador `IN` ou relação `include`.
- **Memoização no React:** identificação de cálculos pesados sem `useMemo` ou handlers de eventos instáveis sem `useCallback`.
- **Payloads excessivos:** adição de paginação (`limit`/`offset`) ou projeção seletiva de campos (`select: { id: true, name: true }`) em vez de carregar toda a tabela.

---

## 9. Workshop prático: investigação passo a passo de um bug real

Vamos analisar um cenário prático: usuários reclamam que, ao aplicar um cupom de desconto de 15% em um carrinho com três itens, o valor total é descontado incorretamente.

### Passo 1. Localização do código de cálculo

Abra o Claude Code e encontre o módulo necessário:

```text
Find where the cart discount calculation is implemented and inspect the file.
```

O Claude usará o `Grep` pela palavra `discount` e abrirá o arquivo `src/domain/cart.ts`.

### Passo 2. Análise do código defeituoso

```typescript
// Знайдений фрагмент у src/domain/cart.ts:
export function applyCoupon(total: number, discountPercent: number): number {
  return total - total * (discountPercent / 100);
}
```

À primeira vista, a fórmula parece correta. Mas, em JavaScript, operações com ponto flutuante frequentemente causam problemas de arredondamento: `100 - 100 * (15 / 100)` resulta em `85.00000000000001`, o que quebra o gateway de pagamento Stripe, que espera centavos inteiros.

### Passo 3. Formulação da tarefa de correção e testes

```text
In src/domain/cart.ts, the applyCoupon function causes floating-point precision issues that fail payment validation. Refactor it to calculate prices in integer cents, add rounding via Math.round, and create a comprehensive unit test in src/domain/cart.test.ts covering edge cases.
```

### Passo 4. Verificação do resultado

O agente corrige a função:

```typescript
export function applyCouponInCents(totalCents: number, discountPercent: number): number {
  const discountAmount = Math.round(totalCents * (discountPercent / 100));
  return Math.max(0, totalCents - discountAmount);
}
```

Em seguida, o Claude executa automaticamente `npm test src/domain/cart.test.ts` e confirma que todos os testes passaram.

---

## 10. Autoverificação rápida e checklist final de debugging

Teste suas habilidades de depuração com o Claude Code.

### Perguntas-chave

> **1. Qual é a maneira mais eficaz de investigar uma falha no servidor ocorrida em um ambiente de staging?**
>
> > [!TIP]
> > **Resposta:** Passar as últimas linhas do log diretamente para o modo autônomo do Claude Code via pipeline de console: `tail -n 150 /var/log/app.log | claude -p "Find errors and diagnose causes"`.

> **2. Por que, ao corrigir erros de tipo TypeScript, deve-se proibir o assistente de usar o operador `as`?**
>
> > [!TIP]
> > **Resposta:** A coerção de tipos via `as` apenas mascara o problema para o compilador, mas não protege a aplicação de crashes em runtime quando os dados esperados estão ausentes. Deve-se exigir narrowing de tipos correto (Type Narrowing) ou valores padrão.

> **3. Como organizar corretamente a correção de dezenas de testes que falharam após um refactoring?**
>
> > [!TIP]
> > **Resposta:** Executar o Claude Code em modo de loop com instruções claras: rodar os testes, analisar os erros, distinguir expectativas obsoletas dos testes de defeitos reais na lógica de negócio e repetir a execução até atingir 100% de sucesso.

### Checklist de caça sistemática a bugs

- [ ] Forneça ao agente os 4 elementos obrigatórios: Comportamento Esperado, Comportamento Real, Passos de Reprodução e Caminhos dos Arquivos.
- [ ] Envie stack traces completos sem abreviações — o Claude encontrará as linhas de código relevantes sozinho.
- [ ] Use pipes do Unix (`tail | claude -p`) para diagnóstico rápido de logs do servidor.
- [ ] Exija que o assistente evite soluções superficiais; foque na causa raiz e na robustez do código.