Receita: Correção de Bug com SDD

Esta receita mostra como usar o SpecForge para documentar, delimitar e resolver um bug de forma que crie uma spec duradoura — para que o mesmo tipo de bug nunca seja lançado novamente.

Por que Documentar Bugs como Specs?

A maioria dos bugs recorre porque o comportamento correto nunca foi formalmente especificado. Corrigir um bug sem uma spec significa:

• A correção não tem critérios de aceitação (como você sabe que está corrigido?)
• O teste de regressão não tem rastreabilidade
• O mesmo padrão pode reaparecer em código relacionado

O SDD trata bugs como specs faltando ou incorretas. Corrigir o bug significa escrever a spec que deveria ter existido, depois implementar para correspondê-la.

---

Cenário

Usuários relatam que fazer dois pedidos simultaneamente às vezes resulta em cobranças duplicadas. Este é um bug de concorrência no fluxo de processamento de pedidos.

---

Etapa 1 — Esclarecer o Bug

Prompt:

Use o specforge para esclarecer requisitos para uma correção de bug:
cobranças duplicadas ao fazer pedidos simultâneos no projeto proj_abc123

O SpecForge perguntará:

• Onde a duplicação ocorre — camada de API, processador de pagamento ou banco de dados?
• Isso é reproduzível em condições específicas (carga, atraso de rede)?
• Qual é o comportamento esperado — exatamente uma cobrança por pedido, sempre?
• Existem testes que deveriam ter detectado isso?

---

Etapa 2 — Criar uma Spec de Correção de Bug

Prompt:

Crie uma spec para corrigir o bug de cobrança duplicada no processamento de pedidos para o projeto proj_abc123.
Causa raiz: condição de corrida em OrderService.placeOrder — sem chave de idempotência na chamada ao Stripe.
Esperado: exatamente uma cobrança por pedido independentemente de requisições concorrentes.

O que a spec conterá:

## Critérios de Aceitação

1. Fazer o mesmo pedido duas vezes concorrentemente resulta em exatamente uma cobrança no Stripe
2. A segunda requisição concorrente recebe uma resposta 409 Conflict com o ID do pedido
3. A chave de idempotência é derivada do orderId e armazenada na tabela orders
4. Pedidos existentes não podem ser modificados após o pagamento ser iniciado
5. Teste de integração cobre processamento concorrente de pedidos com 10 requisições simultâneas
6. Teste unitário cobre casos extremos de geração de chave de idempotência (UUID v4, resistência a colisão)

---

Etapa 3 — Testar o Design da Correção

Prompt:

Desafie a spec SPEC-BUG-001 do projeto proj_abc123

O SpecForge investigará:

• E se a geração da própria chave de idempotência tiver uma condição de corrida?
• E se a primeira requisição falhar no meio — a segunda terá sucesso?
• Qual é a política de expiração das chaves de idempotência?
• A correção lida com o caso em que o pagamento é bem-sucedido mas a escrita no banco de dados falha?

---

Etapa 4 — Verificação de Segurança

Prompt:

Execute uma verificação de segurança na spec SPEC-BUG-001 do projeto proj_abc123

Bugs de pagamento concorrente frequentemente têm implicações de segurança — garanta que a correção não introduza uma vulnerabilidade TOCTOU.

---

Etapa 5 — Fazer Engenharia Reversa do Código Existente

Documente o que o código atual (com bug) realmente faz:

Prompt:

Faça engenharia reversa do código em /Users/me/meu-app/src/orders/OrderService.ts para o projeto proj_abc123

Isso cria uma spec do comportamento atual — útil para entender exatamente onde a spec e a implementação divergiram.

---

Etapa 6 — Gerar Testes Primeiro (abordagem TDD)

Prompt:

Gere testes para a spec SPEC-BUG-001 no projeto proj_abc123

Escreva os testes de regressão antes de tocar na implementação. Isso garante:

• O bug é reproduzível com um teste (vermelho)
• A correção faz o teste passar (verde)
• O teste permanece na suite para sempre (proteção contra regressão)

---

Etapa 7 — Gerar Plano de Execução

Prompt:

Gere um plano de execução para a spec SPEC-BUG-001 no projeto proj_abc123

Para uma correção de bug, o plano normalmente fica assim:

## Fase 1: Reproduzir
- [ ] Escrever teste de integração com falha que aciona cobrança duplicada (RED)
- [ ] Confirmar que o teste falha contra a implementação atual

## Fase 2: Corrigir
- [ ] Adicionar coluna idempotency_key à tabela orders (migração)
- [ ] Gerar chave de idempotência no OrderService antes da chamada ao Stripe
- [ ] Armazenar a chave atomicamente com a criação do pedido (transação)
- [ ] Tratar 409 do endpoint de idempotência do Stripe

## Fase 3: Verificar
- [ ] Executar teste de integração (GREEN)
- [ ] Executar suite de testes completa
- [ ] Teste manual com modo de teste do Stripe em requisições concorrentes

---

Etapa 8 — Implementar e Validar

Após implementar a correção:

Prompt:

Valide a spec SPEC-BUG-001 contra o código em /Users/me/meu-app/src para o projeto proj_abc123

Garanta que todos os 6 critérios de aceitação estejam cobertos pela implementação e testes.

---

Etapa 9 — Detectar Drift da Spec Original

Se houver uma SPEC existente para o fluxo de processamento de pedidos, verifique se a correção introduziu drift:

Prompt:

Detecte drift na spec SPEC-002 (processamento de pedidos) do projeto proj_abc123

A correção pode precisar ser refletida na spec original como um novo critério: "O sistema deve usar chaves de idempotência para todas as chamadas à API Stripe."

---

Etapa 10 — Capturar o Aprendizado

Prompt:

Capture aprendizado: chamadas à API de provedores de pagamento devem sempre incluir chaves de idempotência derivadas do ID da entidade de negócio, nunca de UUIDs gerados pela requisição

Este padrão agora está armazenado e influenciará specs futuras que envolvam chamadas à API de pagamento.

---

Resultado desta Receita

Ao final:

• Uma spec de correção de bug (SPEC-BUG-001) com critérios de aceitação completos
• Testes de regressão com rastreabilidade para cada critério
• A spec original atualizada para refletir o comportamento correto
• Um aprendizado capturado que evita a recorrência do padrão
• Uma trilha de auditoria: quando o bug foi encontrado, qual foi a correção, por que foi a correção certa