Claude Craft

Português

English
Français
Español
Deutsch

Português

English
Français
Español
Deutsch

Appearance

Guia de Correção de Bugs ​

Este guia cobre a abordagem sistemática para corrigir bugs usando o Claude-Craft, desde o diagnóstico até a validação.

Índice ​

  1. Fluxo de Correção de Bugs
  2. Fase 1: Reproduzir
  3. Fase 2: Diagnosticar
  4. Fase 3: Escrever Teste de Regressão
  5. Fase 4: Corrigir
  6. Fase 5: Validar
  7. Fase 6: Documentar
  8. Procedimentos de Hotfix
  9. Exemplo Completo

Fluxo de Correção de Bugs ​

A abordagem sistemática para corrigir bugs:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ 1. Reproduzir│ --> │2. Diagnosticar│ --> │  3. Teste   │
└─────────────┘     └─────────────┘     └─────────────┘
                                              │
                                              v
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ 6. Documentar│ <-- │  5. Validar │ <-- │ 4. Corrigir │
└─────────────┘     └─────────────┘     └─────────────┘

Por Que Esta Abordagem? ​

  1. Reproduzir primeiro: Não é possível corrigir o que não se consegue ver
  2. Testar antes de corrigir: Prova que o bug existe e foi corrigido
  3. Validar completamente: Garante que não há regressão
  4. Documentar: Ajuda a prevenir bugs semelhantes no futuro

Fase 1: Reproduzir ​

Antes de corrigir, reproduza o bug de forma consistente.

Coletar Informações ​

Obtenha do relatório de bug:

  • Passos para reproduzir
  • Comportamento esperado
  • Comportamento real
  • Ambiente (versão, SO, etc.)
  • Mensagens de erro/logs
  • Capturas de tela, se aplicável

Criar Ambiente de Reprodução ​

bash
# Fazer checkout da versão problemática
git checkout <commit-ou-tag>

# Configurar ambiente idêntico
make docker-up

# Reproduzir com os passos exatos

Verificar a Reprodução ​

Você consegue acionar o bug de forma consistente?

  • [ ] Bug ocorre com os passos relatados
  • [ ] Bug ocorre no mesmo ambiente
  • [ ] Bug é determinístico (não aleatório)

Se Você Não Conseguir Reproduzir ​

markdown
@research-assistant Ajude-me a entender por que este bug pode ser específico do ambiente

Relatório de bug:
- Usuário vê erro X ao fazer Y
- Não consigo reproduzir localmente
- Usuário está no ambiente Z

Possíveis causas?

Fase 2: Diagnosticar ​

Encontre a causa raiz do bug.

Usando o Comando de Análise ​

bash
/common:analyze-bug "Os usuários não conseguem fazer login com credenciais corretas após redefinição de senha"

Este comando irá:

  1. Sugerir áreas para investigar
  2. Identificar causas potenciais
  3. Recomendar passos de depuração
  4. Listar áreas de código relacionadas

Usando o TDD Coach para Diagnóstico ​

markdown
@tdd-coach Ajude-me a diagnosticar este bug de autenticação

Sintomas:
- O usuário redefine a senha com sucesso
- A nova senha é salva (confirmado no banco de dados)
- O login falha com "credenciais inválidas"
- A senha antiga também não funciona

O que devo investigar?

Técnicas de Depuração ​

Adicionar Logging ​

php
// Log de depuração temporário
$this->logger->debug('Password verification', [
    'user_id' => $user->getId(),
    'stored_hash' => substr($user->getPasswordHash(), 0, 20) . '...',
    'verification_result' => $result,
]);

Inspecionar o Estado do Banco de Dados ​

sql
-- Verificar estado do usuário após redefinição de senha
SELECT id, email, password_hash, updated_at
FROM users
WHERE email = 'user@example.com';

Rastrear o Caminho de Execução ​

php
// Adicionar stack trace em pontos suspeitos
debug_print_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS);

Identificar a Causa Raiz ​

Categorias comuns:

  • Erro de lógica: Condição ou cálculo incorreto
  • Erro de estado: Estado de dados incorreto
  • Condição de corrida: Comportamento dependente de temporização
  • Erro de integração: Problema com serviço externo
  • Erro de configuração: Configurações erradas

Checklist de Diagnóstico ​

  • [ ] Bug reproduzido de forma consistente
  • [ ] Localização do erro identificada
  • [ ] Causa raiz compreendida
  • [ ] Áreas de código relacionadas identificadas
  • [ ] Abordagem de correção determinada

Fase 3: Escrever Teste de Regressão ​

Escreva um teste que FALHE ANTES da correção e PASSE DEPOIS.

Por Que Testar Primeiro? ​

  1. Prova que o bug existe: O teste falha com o código atual
  2. Prova que a correção funciona: O teste passa após a correção
  3. Previne regressão: O teste detecta quebras futuras
  4. Documenta o comportamento: O teste descreve o comportamento esperado

Usando o TDD Coach ​

markdown
@tdd-coach Ajude-me a escrever um teste de regressão para este bug

Bug: A redefinição de senha não atualiza o hash de senha corretamente

Comportamento esperado:
- O usuário solicita a redefinição de senha
- O usuário define uma nova senha
- O usuário consegue fazer login com a nova senha

Comportamento real:
- O login falha após a redefinição de senha

Exemplo de Teste de Regressão ​

php
/**
 * @test
 * @see https://github.com/company/project/issues/123
 *
 * Bug: Os usuários não conseguiam fazer login após a redefinição de senha
 * Causa raiz: O hash de senha não era persistido corretamente
 */
public function test_user_can_login_after_password_reset(): void
{
    // Arrange: Criar usuário com senha conhecida
    $user = $this->createUser('user@example.com', 'old-password');

    // Act: Redefinir senha
    $this->passwordResetService->resetPassword($user, 'new-password');

    // Assert: Consegue fazer login com a nova senha
    $result = $this->authService->authenticate('user@example.com', 'new-password');

    $this->assertTrue($result->isSuccess());
    $this->assertNotNull($result->getToken());
}

/**
 * @test
 * Relacionado: Garantir que a senha antiga não funciona mais
 */
public function test_old_password_fails_after_reset(): void
{
    $user = $this->createUser('user@example.com', 'old-password');

    $this->passwordResetService->resetPassword($user, 'new-password');

    $result = $this->authService->authenticate('user@example.com', 'old-password');

    $this->assertFalse($result->isSuccess());
}

Checklist de Escrita de Testes ​

  • [ ] O teste reproduz o bug (falha antes da correção)
  • [ ] O teste tem nome descritivo
  • [ ] O teste referencia o número do issue
  • [ ] O teste documenta a causa raiz no comentário
  • [ ] Casos extremos relacionados testados

Fase 4: Corrigir ​

Implemente a correção mínima para o bug.

Diretrizes de Correção ​

  1. Mudança mínima: Corrija apenas o bug, não refatore
  2. Intenção clara: O código deve mostrar o que estava errado
  3. Sem efeitos colaterais: Não altere comportamento não relacionado
  4. Manter estilo: Corresponder aos padrões do código existente

Exemplo de Correção ​

php
// ANTES (com bug)
public function resetPassword(User $user, string $newPassword): void
{
    $hash = $this->hasher->hash($newPassword);
    $user->setPasswordHash($hash);
    // Bug: Falta persist/flush!
}

// DEPOIS (corrigido)
public function resetPassword(User $user, string $newPassword): void
{
    $hash = $this->hasher->hash($newPassword);
    $user->setPasswordHash($hash);
    $this->entityManager->persist($user);  // <-- Correção
    $this->entityManager->flush();          // <-- Correção
}

Executar o Teste de Regressão ​

bash
# O teste deve passar agora
make test-unit TEST=tests/Unit/PasswordResetTest.php

# Ou executar teste específico
./vendor/bin/phpunit --filter test_user_can_login_after_password_reset

Checklist de Correção ​

  • [ ] O teste de regressão agora passa
  • [ ] A correção é mínima e focada
  • [ ] Nenhuma alteração não relacionada incluída
  • [ ] Estilo do código mantido

Fase 5: Validar ​

Certifique-se de que a correção não quebre nada mais.

Executar a Suite Completa de Testes ​

bash
# Todos os testes unitários
make test-unit

# Todos os testes de integração
make test-integration

# Suite completa de testes
make test

Verificações de Qualidade ​

bash
# Qualidade do código (por tecnologia)
/symfony:check-code-quality
/flutter:check-code-quality
/python:check-code-quality

# Segurança (se a correção toca código sensível)
/common:security-audit

# Conformidade completa
/symfony:check-compliance

Testes Manuais ​

Mesmo com testes automatizados, verifique manualmente:

  1. Seguir os passos originais de reprodução do bug
  2. Verificar que o bug não ocorre mais
  3. Testar funcionalidades relacionadas
  4. Verificar casos extremos

Usando o Agente Revisor ​

markdown
@symfony-reviewer Revise minha correção para o issue #123

Bug: Os usuários não conseguiam fazer login após a redefinição de senha
Correção: Adicionados persist/flush ausentes em resetPassword()

Arquivos alterados:
- src/Application/Service/PasswordResetService.php
- tests/Unit/PasswordResetTest.php

Por favor, verifique:
1. A correção está correta e completa
2. Ausência de efeitos colaterais
3. Cobertura de teste adequada

Checklist de Validação ​

  • [ ] O teste de regressão passa
  • [ ] Todos os testes existentes passam
  • [ ] A análise estática passa
  • [ ] Os testes manuais confirmam a correção
  • [ ] Revisão de código concluída

Fase 6: Documentar ​

Documente a correção para referência futura.

Formato da Mensagem de Commit ​

fix(auth): resolver falha de login após redefinição de senha

Bug: Os usuários não conseguiam fazer login após redefinir a senha
Causa raiz: A alteração do hash de senha não era persistida no banco de dados
Correção: Adicionadas chamadas a persist() e flush() em PasswordResetService

Closes #123

Test: test_user_can_login_after_password_reset

Atualizar o Rastreador de Issues ​

markdown
## Resolução

**Causa Raiz:**
O método `resetPassword()` em `PasswordResetService` estava atualizando o hash
de senha do usuário na memória, mas não persistia a alteração no banco de dados.

**Correção:**
Adicionadas chamadas a `persist()` e `flush()` após definir o novo hash de senha.

**Testes:**
- Teste de regressão adicionado: `test_user_can_login_after_password_reset`
- Teste de caso extremo adicionado: `test_old_password_fails_after_reset`

**Prevenção:**
Considere adicionar um item de verificação na lista de revisão de código para operações de persistência.

Entrada na Base de Conhecimento (se for um padrão recorrente) ​

markdown
# Bug Comum: Alterações de Entidade Não Persistidas

## Sintomas
- As alterações de dados parecem funcionar (sem erros)
- As alterações não aparecem no banco de dados
- As alterações são perdidas após atualização da página

## Causa Raiz
Chamadas a `persist()` e/ou `flush()` ausentes no Doctrine.

## Padrão de Correção
```php
$entity->setSomething($value);
$this->entityManager->persist($entity); // Não esqueça!
$this->entityManager->flush();

Prevenção ​

  • Adicionar verificação de persistência ao checklist de revisão de código
  • Considerar auto-flush na classe base do serviço

### Checklist de Documentação

- [ ] A mensagem de commit descreve o bug e a correção
- [ ] O rastreador de issues atualizado com a resolução
- [ ] Documentação relacionada atualizada
- [ ] Entrada na base de conhecimento se for um padrão

---

## Procedimentos de Hotfix

Para bugs críticos em produção.

### Fluxo de Hotfix
  1. Criar branch de hotfix a partir de produção
  2. Aplicar correção mínima
  3. Testar completamente
  4. Implantar em produção
  5. Mesclar de volta em main

### Passo a Passo

```bash
# 1. Criar branch de hotfix
git checkout production
git checkout -b hotfix/issue-123-login-failure

# 2. Aplicar correção
# ... fazer as alterações ...

# 3. Escrever teste de regressão
# ... adicionar teste ...

# 4. Verificar
make test
/symfony:check-compliance

# 5. Commitar com mensagem clara
git commit -m "fix(auth): resolver falha crítica de login após redefinição de senha

HOTFIX para issue de produção.
Causa raiz: Hash de senha não persistido após redefinição.

Closes #123"

# 6. Criar PR para revisão
gh pr create --base production --title "HOTFIX: Falha de login após redefinição de senha"

# 7. Após merge, implantar
# ... processo de implantação ...

# 8. Mesclar de volta em main
git checkout main
git merge hotfix/issue-123-login-failure
git push origin main

Checklist de Hotfix ​

  • [ ] Branch de hotfix criada a partir de produção
  • [ ] Correção mínima e focada apenas
  • [ ] Teste de regressão adicionado
  • [ ] Todos os testes passando
  • [ ] PR revisado e aprovado
  • [ ] Implantado em produção
  • [ ] Verificado em produção
  • [ ] Mesclado de volta em main

Exemplo Completo ​

Vamos percorrer a correção de um bug real.

Relatório de Bug ​

Issue #456: Total do pedido calculado incorretamente

Passos para reproduzir:
1. Adicionar item com preço $10.00, quantidade 3
2. Adicionar item com preço $5.50, quantidade 2
3. Visualizar o carrinho

Esperado: Total = $41.00 (30 + 11)
Real: Total = $36.00

Ambiente: Produção v2.3.1
Reportado por: Suporte ao cliente
Prioridade: Alta

Passo 1: Reproduzir ​

php
// Teste local rápido
$order = new Order();
$order->addItem(new Item('A', 10.00), 3);  // $30
$order->addItem(new Item('B', 5.50), 2);   // $11
echo $order->getTotal(); // Mostra 36.00 - confirmado!

Passo 2: Diagnosticar ​

markdown
@tdd-coach Ajude-me a encontrar o bug no cálculo do total do pedido

O total deveria ser 41.00, mas mostra 36.00
A diferença é 5.00, que é exatamente o preço de um item B

Hipótese: a quantidade do segundo item não está sendo contada?

A investigação revela:

php
// Bug encontrado em Order::calculateTotal()
public function calculateTotal(): Money
{
    $total = Money::zero();
    foreach ($this->items as $item) {
        // BUG: Usando 1 em vez da quantidade do item!
        $total = $total->add($item->getPrice()->multiply(1));
    }
    return $total;
}

Passo 3: Escrever Teste de Regressão ​

php
/**
 * @test
 * @see https://github.com/company/shop/issues/456
 *
 * Bug: O total do pedido ignorava as quantidades dos itens
 */
public function test_order_total_includes_all_quantities(): void
{
    $order = new Order();
    $order->addItem($this->createItem(10.00), 3);  // $30
    $order->addItem($this->createItem(5.50), 2);   // $11

    $total = $order->calculateTotal();

    $this->assertEquals(41.00, $total->getAmount());
}

/**
 * @test
 * Caso extremo: item único com quantidade > 1
 */
public function test_single_item_quantity_multiplied(): void
{
    $order = new Order();
    $order->addItem($this->createItem(10.00), 5);

    $this->assertEquals(50.00, $order->calculateTotal()->getAmount());
}

Executar o teste — confirma que falha.

Passo 4: Corrigir ​

php
public function calculateTotal(): Money
{
    $total = Money::zero();
    foreach ($this->items as $item) {
        // Corrigido: Usar a quantidade real do item do pedido
        $total = $total->add(
            $item->getPrice()->multiply($item->getQuantity())
        );
    }
    return $total;
}

Passo 5: Validar ​

bash
# Teste de regressão passa
./vendor/bin/phpunit --filter test_order_total

# Todos os testes passam
make test

# Verificação de qualidade
/symfony:check-compliance
# Pontuação: 94/100 ✓

Passo 6: Documentar ​

bash
git commit -m "fix(order): corrigir cálculo do total para incluir as quantidades

Bug: O total do pedido ignorava as quantidades dos itens, sempre usando 1
Causa raiz: multiply(1) codificado em vez de multiply(quantity)
Correção: Usar getQuantity() do item do pedido no cálculo

Closes #456

Testes de regressão adicionados:
- test_order_total_includes_all_quantities
- test_single_item_quantity_multiplied"

Dicas de Prevenção de Bugs ​

  1. Escreva os testes primeiro: TDD previne muitos bugs
  2. Revisão de código: Outros olhos detectam problemas
  3. Análise estática: Ferramentas encontram erros comuns
  4. Testes de integração: Capturam bugs de interação
  5. Monitorar produção: Detectar problemas mais cedo
  6. Use /loop: Configure verificações de qualidade recorrentes (ex.: /loop 5m /common:pre-commit-check)
  7. Salve aprendizados: Use /memory para persistir padrões de bugs entre sessões

← Desenvolvimento de Features | Referência de Ferramentas →