Receita: Adicionando uma Nova Funcionalidade

Esta receita percorre o fluxo de trabalho SDD completo para adicionar uma nova funcionalidade a um projeto existente. Usaremos "adicionar integração de pagamentos Stripe" como exemplo contínuo.

Pré-requisitos

• SpecForge instalado e configurado (Início Rápido)
• Projeto inicializado (init_project já executado, você tem um projectId)

---

Etapa 1 — Esclarecer Requisitos

Antes de escrever qualquer coisa, traga as ambiguidades à tona.

Prompt:

Use o specforge para esclarecer requisitos para adicionar integração de pagamentos Stripe ao projeto proj_abc123

O que esperar: Uma lista de 5–10 perguntas direcionadas como:

• Devemos suportar pagamentos únicos, assinaturas ou ambos?
• Quais moedas precisam ser suportadas?
• Precisamos de geração de faturas?
• Como pagamentos falhos devem ser tratados — lógica de retry? notificações?
• Qual é a política de reembolso e quem pode iniciar reembolsos?

Responda essas perguntas na conversa. O SpecForge incorporará as respostas na spec.

---

Etapa 2 — Criar a Spec

Prompt:

Crie uma spec para integração de pagamentos Stripe no projeto proj_abc123.
Requisitos: apenas pagamentos únicos, USD e EUR, recibo por e-mail em caso de sucesso,
webhook para eventos de pagamento, capacidade de reembolso do administrador.

O que esperar: Um HU.md completo salvo no armazenamento de specs do seu projeto com:

• 8–15 critérios de aceitação cobrindo o caminho feliz, casos de erro e casos extremos
• Schema de banco de dados para tabelas payments e payment_events
• Contrato de UI para o componente de formulário de checkout
• Dica de ADR sobre chaves de idempotência para chamadas à API Stripe
• PLAN.md com etapas de implementação

O SpecForge atribui a esta spec um ID como SPEC-004. Anote-o.

---

Etapa 3 — Revisar e Ajustar

Leia a spec gerada e refine se necessário.

Prompt:

Resuma a spec SPEC-004 do projeto proj_abc123

Se algo estiver faltando ou errado:

Prompt:

Adicione um critério à SPEC-004 do projeto proj_abc123:
"O sistema deve validar os dados do cartão no cliente antes de enviar ao Stripe para minimizar cobranças com falha"

---

Etapa 4 — Testar a Spec sob Pressão

Prompt:

Desafie a spec SPEC-004 do projeto proj_abc123

O que esperar: O SpecForge investigará:

• O que acontece se o webhook do Stripe chegar antes da resposta da API?
• O que se o usuário atualizar a página durante o pagamento? (idempotência)
• E se o serviço de conversão de taxa EUR estiver indisponível?
• Concorrência: duas abas completando o pagamento simultaneamente

Resolva quaisquer lacunas encontradas antes de prosseguir.

---

Etapa 5 — Verificar Prontidão

Prompt:

Verifique se a spec SPEC-004 está pronta para implementação no projeto proj_abc123

Isso valida:

• Todos os critérios são testáveis e sem ambiguidade
• Sem dependências bloqueantes (ex.: SPEC-001 de autenticação deve estar concluída primeiro)
• Conformidade com a Constituição

Se passar, você verá DoR: PASSED. Se não, corrija o que foi sinalizado.

---

Etapa 6 — Estimar Esforço

Prompt:

Estime a spec SPEC-004 do projeto proj_abc123

O que esperar:

Esforço: 8–13 story points
Tempo: 2–4 dias (dev solo) / 1–2 dias (em par)
Custo: $640–$1.040 a $80/h
Estimativa de tokens de IA: ~45k tokens
Fatores de risco: confiabilidade de webhook Stripe, complexidade de idempotência

---

Etapa 7 — Verificação de Segurança

Como esta spec envolve pagamentos:

Prompt:

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

O que verificar: Mapeamento do OWASP Top 10, superfície de PCI DSS, validação de assinatura de webhook, tratamento de chave de API Stripe.

---

Etapa 8 — Gerar o Plano de Execução

Prompt:

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

Isso gera um PLAN.md com etapas RED/GREEN/VERIFY:

## Fase 1: Fundação (pode paralelizar 1a, 1b, 1c)
- [ ] 1a: Migração de banco de dados — criar tabelas payments + payment_events
- [ ] 1b: Definir interfaces TypeScript para payloads do Stripe
- [ ] 1c: Escrever testes com falha para PaymentService (RED)

## Fase 2: Implementação Principal
- [ ] 2a: Implementar PaymentService.createCheckoutSession
- [ ] 2b: Implementar handler de webhook com validação de assinatura
- [ ] 2c: Implementar AdminRefundService

## Fase 3: Frontend
- [ ] 3a: Construir componente CheckoutForm com Stripe Elements
- [ ] 3b: Implementar polling de status de pagamento/webhook SSE

## Fase 4: Verificação
- [ ] 4a: Executar suite de testes completa (GREEN + VERIFY)
- [ ] 4b: Testar com cartões de teste do Stripe
- [ ] 4c: Atualizar status da spec SPEC-004 para review

---

Etapa 9 — Gerar Testes

Prompt:

Gere testes para a spec SPEC-004 no projeto proj_abc123

Isso produz stubs de testes mapeados para cada critério de aceitação — prontos para serem preenchidos ou usados como ponto de partida para TDD.

---

Etapa 10 — Atualizar Status para Em Andamento

Prompt:

Atualize o status da spec SPEC-004 para in_progress no projeto proj_abc123

---

Etapa 11 — Implementar

Use o PLAN.md como guia de implementação. Seu agente de IA seguirá o ciclo RED/GREEN/VERIFY. A spec funciona como o contrato — cada critério de aceitação deve ser atendido.

---

Etapa 12 — Validar a Implementação

Prompt:

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

O que esperar:

Critério 1: Criação de pagamento ✅ coberto
Critério 2: Tratamento de webhook ✅ coberto
Critério 3: Fluxo de reembolso ✅ coberto
Critério 4: Recibo por e-mail ⚠️ parcialmente coberto — testes faltando para caso de falha
Critério 5: Validação de moeda ✅ coberto

Cobertura: 90% (1 critério precisa de atenção)

Corrija a lacuna e revalide.

---

Etapa 13 — Marcar como Concluído

Prompt:

Marque a spec SPEC-004 como done no projeto proj_abc123

O SpecForge valida o checklist DoD antes de aceitar a transição. Uma vez concluída, a spec faz parte do registro permanente do projeto.

---

Resumo de Tempo

Etapa	Tempo típico
Esclarecer + Criar	5–15 min
Desafiar + Verificar prontidão	5 min
Estimar + Segurança	3 min
Gerar plano + testes	5 min
Implementação	Varia por spec
Validar + Marcar concluído	5 min

O overhead do SDD é de 20–30 minutos. O retorno é uma spec pronta para produção, um design verificado quanto à segurança e a validação de que a implementação corresponde ao que foi acordado.