Receta: Agregar una Nueva Feature

Esta receta recorre el workflow SDD completo para agregar una nueva feature a un proyecto existente. Usamos "agregar integración de pagos con Stripe" como ejemplo de hilo conductor.

Prerequisitos

• SpecForge instalado y configurado (Primeros Pasos)
• Proyecto inicializado (init_project ya ejecutado, tienes un projectId)

---

Paso 1 — Clarificar Requisitos

Antes de escribir cualquier cosa, saca a la superficie las ambigüedades.

Prompt:

Use specforge to clarify requirements for adding Stripe payment integration to project proj_abc123

O en español:

Usa specforge para clarificar los requisitos de agregar integración de pagos con Stripe al proyecto proj_abc123

Qué esperar: Una lista de 5–10 preguntas dirigidas como:

• ¿Debemos soportar pagos únicos, suscripciones o ambos?
• ¿Qué monedas necesitan soportarse?
• ¿Necesitamos generación de facturas?
• ¿Cómo deben manejarse los pagos fallidos — lógica de reintentos? ¿notificaciones?
• ¿Cuál es la política de reembolsos y quién puede iniciarlos?

Responde estas preguntas en la conversación. SpecForge incorporará las respuestas a la spec.

---

Paso 2 — Crear la Spec

Prompt:

Create a spec for Stripe payment integration in project proj_abc123.
Requirements: one-time payments only, USD and EUR, email receipt on success,
webhook for payment events, admin refund capability.

Qué esperar: Un HU.md completo guardado en el almacenamiento de specs de tu proyecto con:

• 8–15 criterios de aceptación que cubren el happy path, casos de error y casos borde
• Esquema de base de datos para tablas payments y payment_events
• Contrato de UI para el componente de formulario de checkout
• Hint de ADR sobre idempotency keys para llamadas a la API de Stripe
• PLAN.md con pasos de implementación

SpecForge asigna a esta spec un ID como SPEC-004. Anótalo.

---

Paso 3 — Revisar y Ajustar

Lee la spec generada y refina si es necesario.

Prompt:

Summarize spec SPEC-004 for project proj_abc123

Si algo falta o está incorrecto:

Prompt:

Add a criterion to SPEC-004 for project proj_abc123:
"The system must validate card details client-side before sending to Stripe to minimize failed charges"

---

Paso 4 — Hacer Stress-Test de la Spec

Prompt:

Challenge spec SPEC-004 for project proj_abc123

Qué esperar: SpecForge indagará en:

• ¿Qué pasa si el webhook de Stripe llega antes de la respuesta de la API?
• ¿Qué pasa si el usuario recarga durante el pago? (idempotencia)
• ¿Qué pasa si el servicio de conversión de EUR no está disponible?
• Concurrencia: dos pestañas completando el pago simultáneamente

Aborda cualquier brecha encontrada antes de continuar.

---

Paso 5 — Verificar Preparación

Prompt:

Check if spec SPEC-004 is ready for implementation in project proj_abc123

Esto valida:

• Todos los criterios son testeables e inequívocos
• Sin dependencias bloqueantes (p.ej., la autenticación SPEC-001 debe estar lista primero)
• Cumplimiento de la Constitución

Si pasa, verás DoR: PASSED. Si no, corrige lo que se señale.

---

Paso 6 — Estimar Esfuerzo

Prompt:

Estimate spec SPEC-004 for project proj_abc123

Qué esperar:

Effort: 8–13 story points
Time: 2–4 days (solo dev) / 1–2 days (pair)
Cost: $640–$1,040 at $80/hr
AI token estimate: ~45k tokens
Risk factors: Stripe webhook reliability, idempotency complexity

---

Paso 7 — Verificación de Seguridad

Dado que esta spec involucra pagos:

Prompt:

Run a security check on spec SPEC-004 for project proj_abc123

Qué revisar: Mapeo OWASP Top 10, superficie PCI DSS, validación de firma de webhook, manejo de API keys de Stripe.

---

Paso 8 — Generar el Plan de Ejecución

Prompt:

Generate an execution plan for spec SPEC-004 in project proj_abc123

Esto genera un PLAN.md con pasos RED/GREEN/VERIFY:

## Fase 1: Fundación (se pueden paralelizar 1a, 1b, 1c)
- [ ] 1a: Migración de BD — crear tablas payments + payment_events
- [ ] 1b: Definir interfaces TypeScript para payloads de Stripe
- [ ] 1c: Escribir tests fallando para PaymentService (RED)

## Fase 2: Implementación Core
- [ ] 2a: Implementar PaymentService.createCheckoutSession
- [ ] 2b: Implementar webhook handler con validación de firma
- [ ] 2c: Implementar AdminRefundService

## Fase 3: Frontend
- [ ] 3a: Construir componente CheckoutForm con Stripe Elements
- [ ] 3b: Implementar polling de estado de pago / SSE de webhook

## Fase 4: Verificar
- [ ] 4a: Ejecutar suite completa de tests (GREEN + VERIFY)
- [ ] 4b: Probar con tarjetas de test de Stripe
- [ ] 4c: Actualizar estado de spec SPEC-004 a review

---

Paso 9 — Generar Tests

Prompt:

Generate tests for spec SPEC-004 in project proj_abc123

Esto produce stubs de tests mapeados a cada criterio de aceptación — listos para completar o usar como punto de partida para TDD.

---

Paso 10 — Actualizar Estado a En Progreso

Prompt:

Update status of spec SPEC-004 to in_progress in project proj_abc123

---

Paso 11 — Implementar

Usa el PLAN.md como guía de implementación. Tu agente de IA seguirá el ciclo RED/GREEN/VERIFY. La spec actúa como el contrato — cada criterio de aceptación debe cumplirse.

---

Paso 12 — Validar la Implementación

Prompt:

Validate spec SPEC-004 against the code at /Users/me/my-app/src for project proj_abc123

Qué esperar:

Criterion 1: Payment creation ✅ covered
Criterion 2: Webhook handling ✅ covered
Criterion 3: Refund flow ✅ covered
Criterion 4: Email receipt ⚠️ partially covered — tests missing for failure case
Criterion 5: Currency validation ✅ covered

Coverage: 90% (1 criterion needs attention)

Cierra la brecha, luego vuelve a validar.

---

Paso 13 — Marcar como Completado

Prompt:

Mark spec SPEC-004 as done in project proj_abc123

SpecForge valida el checklist DoD antes de aceptar la transición. Una vez completada, la spec es parte del registro permanente del proyecto.

---

Resumen de Tiempos

Paso	Tiempo típico
Clarificar + Crear	5–15 min
Challenge + Verificación de preparación	5 min
Estimación + Seguridad	3 min
Generar plan + tests	5 min
Implementación	Varía por spec
Validar + Marcar completado	5 min

El overhead del SDD es de 20–30 minutos. La recompensa es una spec lista para producción, un diseño verificado en seguridad y validación de que la implementación coincide con lo acordado.