Desarrollo Basado en Especificaciones (SDD)

1. Visión general del concepto y problema sistémico

El error más común de los desarrolladores principiantes en vibecoding es el enfoque "Prompt-and-Pray" (escribir un prompt difuso en el chat y esperar que el modelo adivine la arquitectura). Cuando el prompt dice "Haz la facturación a través de Stripe para suscriptores", el modelo elige aleatoriamente esquemas de bases de datos, utiliza bibliotecas obsoletas, ignora webhooks, olvida la idempotencia y no considera los casos límite de cancelación de pagos. Cuando el ingeniero pide arreglar un bug, el modelo comienza a parchear frenéticamente, convirtiendo la base de código en spaghetti code (AI Slop).

Desarrollo Basado en Especificaciones (SDD) es una disciplina de ingeniería que separa la etapa de diseño del sistema de la etapa de generación de código. Antes de tocar la base de código, se crea un documento formalizado de especificación (spec.md o RFC.md). Este documento se convierte en la única fuente de verdad (Single Source of Truth) y contrato contra el cual el agente ejecuta y verifica cada paso subsiguiente.

2. Taxonomía arquitectónica y modelo mental

El marco arquitectónico de SDD se construye sobre una jerarquía clara de artefactos de diseño:

┌─────────────────────────────────────────────────────────────┐
│             ESQUEMA DE ARTEFACTOS DEL DESARROLLO BASADO EN ESPECIFICACIONES      │
├─────────────────────────────────────────────────────────────┤
│ 1. Contexto del Producto: Problema del usuario y objetivo comercial     │
├─────────────────────────────────────────────────────────────┤
│ 2. Contratos Técnicos:                                     │
│    • Esquemas de datos (Drizzle / Prisma schemas, SQL DDL)        │
│    • Contratos API (Zod Schemas, OpenAPI, tipos de TypeScript) │
│    • Invariantes y Reglas de Seguridad (Idempotencia, RBAC, Auth)  │
├─────────────────────────────────────────────────────────────┤
│ 3. Lista de Verificación de Tareas Atómicas (DAG):                             │
│    • Paso 1 ➔ Paso 2 ➔ Paso 3 (Orden estricto de dependencias) │
├─────────────────────────────────────────────────────────────┤
│ 4. Predicados de Verificación: Criterios de aceptación verificables por máquina     │
└─────────────────────────────────────────────────────────────┘

1. Contratos Técnicos (Interface-First):
   • Describen la interacción del sistema antes de implementar la lógica interna. Se definen las estructuras de solicitudes/respuestas, esquemas de validación y estados de error.
2. Grafo de Tareas Atómicas (Task Decomposition DAG):
   • La tarea se descompone en una secuencia de subtareas pequeñas y verificables de manera independiente. Cada subtarea debe modificar no más de 1-3 archivos.
3. Criterios de Aceptación Verificables por Máquina (Acceptance Predicates):
   • En lugar de un "verifica que todo funcione" subjetivo, la especificación contiene comandos de verificación concretos: "pnpm test auth.test.ts pasa exitosamente, cobertura de ramas > 90%."
4. Rastreador de Estado del Ciclo de Vida (Lifecycle Tracker):
   • La especificación contiene casillas de verificación interactivas ([ ] ➔ [x]), que el agente actualiza después de completar y verificar cada paso.

3. Pipeline técnico y mecánica interna

El ciclo de vida del desarrollo bajo la metodología SDD:

1. Entrevistas y síntesis de la especificación (Interview Phase): El ingeniero formula la tarea. El modelo hace preguntas aclaratorias sobre detalles no triviales: ¿qué comportamiento se espera al romper la red?, ¿cómo manejar duplicados?, ¿cuáles son los límites de rate limiting?
2. Fijación de la especificación en el repositorio: Se crea un artefacto (por ejemplo, .specs/004-billing-integration.md), que se añade al sistema de control de versiones Git.
3. Auditoría humana y aprobación (Spec Approval): El ingeniero revisa los esquemas de datos y contratos propuestos. Si la solución arquitectónica tiene defectos, se corrigen a nivel de texto de la especificación en 2 minutos, evitando horas de reescritura de código.
4. Delegación paso a paso al agente (Step-by-Step Execution): El agente se invoca para implementar un paso específico de la especificación:
   • El agente lee el contexto de la especificación.
   • Escribe pruebas de acuerdo con los contratos (TDD).
   • Implementa la funcionalidad.
   • Ejecuta las pruebas y registra la ejecución de la subtarea.
5. Verificación final y archivo: Cuando todos los puntos de la especificación están marcados como completados, se realiza una auditoría integral, y la especificación se mantiene en el repositorio como documentación viva de la característica.

4. Escenarios prácticos de ingeniería en producción

01. Desarrollo de un módulo de pago crítico con idempotencia

Antes de escribir el código de integración del gateway de pago, el ingeniero crea una especificación:

• Fija la estructura de la tabla idempotency_keys con los campos key, response_payload, status, expires_at.
• Describe el algoritmo exacto de comportamiento al recibir un webhook repetido con un transaction_id similar.
• El agente implementa el módulo estrictamente según la especificación; ningún caso límite se pierde.

02. Trabajo paralelo de agentes de backend y frontend

El equipo crea un nuevo dashboard de analítica:

• Primero, en la especificación se describen los esquemas Zod y las interfaces de TypeScript para todos los gráficos y métricas.
• El agente de frontend utiliza estos esquemas para maquetar componentes con datos simulados.
• El agente de backend implementa simultáneamente las consultas SQL reales y las rutas API bajo el mismo contrato.
• La integración se realiza sin ningún conflicto de incompatibilidad de tipos.

03. Migración segura y escalable de un módulo legado

Reemplazo de la antigua autorización personalizada por Better Auth:

• La especificación describe la conservación de la compatibilidad hacia atrás de las sesiones en Redis y un plan paso a paso para migrar los hashes de contraseñas de bcrypt a Argon2id.
• El agente descompone la migración en 7 etapas aisladas, cada una de las cuales se prueba por separado.

5. Errores comunes, trampas y seguridad

• Parálisis por sobreingeniería (Over-Engineering Paralysis): Escribir una especificación de 20 páginas para un pequeño ajuste de sangrías o cambio de color de botón es una pérdida de tiempo absurda. Aplique SDD para tareas que afecten más de 2 módulos o contengan lógica comercial crítica.
• Desincronización de código y especificaciones (Spec Rot): Si durante el desarrollo surge la necesidad de cambiar un esquema, los ingenieros a menudo corrigen el código directamente, olvidando actualizar spec.md. Esto confunde a los siguientes agentes que volverán a leer una especificación obsoleta.
• Uso de formulaciones difusas: Frases como "el sistema debe funcionar rápido" o "garantizar fiabilidad" son catastróficas para la IA. La especificación debe operar con valores concretos: "tiempo de respuesta p99 < 150ms", "devolver HTTP 429 al superar 100 rpm."
• Ignorar el versionado de especificaciones: Los archivos de especificaciones deben ser parte del repositorio Git junto con el código, lo que permite rastrear la evolución de las decisiones arquitectónicas a través del historial de commits.