Del Vibe Coding al Spec Kit

Resumen

El auge de los agentes autónomos de codificación (GitHub Copilot, Claude Code, Gemini CLI, Kimi) ha popularizado el vibe-coding: generar código a partir de instrucciones informales y ambiguas. Si bien es útil para prototipado rápido, este enfoque falla sistemáticamente en proyectos de misión crítica, produciendo código no conforme a la intención real, violaciones de arquitectura y deuda técnica. Este artículo analiza Spec Kit, el toolkit open source de GitHub (Delimarsky, 2025) que propone el paradigma de Spec-Driven Development (SDD): un flujo de cuatro fases (/specify, /plan, /tasks, /implement) donde la especificación es un artefacto vivo y ejecutable que gobierna al agente de IA. Presentamos el marco teórico del SDD, comparándolo con TDD y BDD, y validamos su aplicación mediante un caso de estudio completo una API de suscripciones y pagos documentando los artefactos reales (spec.md, plan.md, tasks.md), el código resultante y las decisiones tomadas en cada checkpoint humano. Los resultados cualitativos indican que el SDD no elimina la ambigüedad, sino que la reubica hacia fases tempranas y de bajo costo de corrección, reduciendo así la necesidad de reescritura tardía.

1. Introducción

Los agentes autónomos de codificación han evolucionado en tres generaciones: (i) autocompletado estadístico local, sin capacidad de decisión; (ii) asistentes conversacionales de alcance limitado a un archivo o función; y (iii) agentes autónomos capaces de operar sobre un repositorio completo leer múltiples archivos, ejecutar comandos, correr pruebas y proponer cambios multi-archivo. Este último salto expone con claridad un problema que antes pasaba desapercibido: la capacidad del agente ya no es el cuello de botella; lo es la calidad del contexto que el humano le entrega.

El vibe-coding instruir al agente con prompts breves y ambiguos (“hazme un login”, “agrega compartir fotos”) delega en el modelo la inferencia de miles de requisitos no verbalizados. Es adecuado para prototipos desechables, pero en software de misión crítica produce fallas recurrentes: código que no compila, cumplimiento parcial de la intención, violaciones de arquitectura y acumulación de deuda técnica. La causa no es una limitación de “inteligencia” del modelo, sino un desajuste de expectativas: los modelos de lenguaje son excelentes completando patrones, pero no tienen acceso a información no verbalizada.

Frente a esto, GitHub propone Spec-Driven Development, materializado en el toolkit Spec Kit: la especificación deja de ser un documento estático olvidado en una wiki y se convierte en la fuente única de verdad, tanto para el desarrollador como para el agente.

Hipótesis de trabajo (H1): La especificación tratada como artefacto ejecutable, mediante el flujo estructurado de Spec Kit, incrementa la precisión de la primera implementación generada por el agente y reduce los ciclos de reescritura, frente a la generación de código a partir de prompts no estructurados.

Este trabajo aborda H1 de forma cualitativa mediante un caso de estudio end-to-end, dado que una validación estadística rigurosa con múltiples equipos y repeticiones controladas excede su alcance y se propone como trabajo futuro (§6).

2. Marco Teórico

2.1 Filosofía del Spec-Driven Development

El SDD invierte la relación tradicional entre código y documentación. En el desarrollo convencional el código es la fuente de verdad y la documentación es un derivado secundario que tiende a desactualizarse. El SDD invierte esto: la especificación es la fuente de verdad y el código es su proyección, compilada por el agente de IA. Esto solo es viable en la era de los agentes porque, por primera vez, una especificación en lenguaje natural estructurado puede convertirse automáticamente en artefactos técnicos sin transcripción manual.

2.2 SDD frente a TDD y BDD

El SDD no reemplaza a TDD/BDD, los contiene: las tareas atómicas de /tasks incluyen criterios de aceptación testeables, y /implement puede aplicar TDD dentro de cada tarea. El SDD opera en una capa superior, gobernando el “qué” y el “por qué” antes de la primera línea de código.

2.3 Arquitectura de Spec Kit

Spec Kit opera en tres capas: (1) CLI de inicialización (specify, distribuido vía uvx, sin instalación permanente), que instala en el repositorio los comandos slash del agente elegido; (2) comandos slash (/specify, /plan, /tasks), plantillas de prompt estructurado con reglas de negociación de ambigüedad; (3) artefactos Markdown versionables (spec.md, plan.md, tasks.md), que permiten revisión tipo pull request, trazabilidad histórica y portabilidad entre agentes (Copilot, Claude Code, Gemini CLI).

2.4 Ciclo de Cuatro Fases y Checkpoints

El flujo de Spec Kit es secuencial, con un checkpoint humano obligatorio entre cada fase:

1. Inicialización: specify init instala en el repositorio la estructura base y los comandos slash del agente.
2. /specify (qué y por qué) → el agente genera spec.md → Checkpoint 1 (validación humana).
3. /plan (stack, arquitectura, restricciones) → el agente genera plan.md y diagramas → Checkpoint 2.
4. /tasks → el agente genera tasks.md → Checkpoint 3.
5. Implementación (por cada tarea atómica): el agente genera código + pruebas → Checkpoint 4.N (aprobar o corregir).
6. Merge a la rama principal.

El elemento distintivo no es la generación en sí, sino el checkpoint humano obligatorio entre fases: el desarrollador no avanza sin validar que cada artefacto captura correctamente la intención y las restricciones reales. El rol del desarrollador migra de escritor de sintaxis a auditor técnico y de producto.

3. Metodología

3.1 Diseño del caso de estudio

Se seleccionó una API de gestión de suscripciones y pagos, en modalidad greenfield, por tres razones: (i) contiene reglas de negocio no triviales (ciclos de facturación, reintentos, estados) que exponen bien las ventajas de una especificación explícita; (ii) requiere decisiones de arquitectura ineludibles (idempotencia, webhooks) que deben fijarse antes de programar; (iii) es acotada, permitiendo documentar el ciclo completo con detalle real.

3.2 Entorno técnico

3.3 Criterios de evaluación

Cobertura de requisitos (trazabilidad spec → tarea → test), calidad de código (adherencia a plan.md), mantenibilidad, ciclos de iteración por fase hasta checkpoint aprobado, y cobertura de pruebas automatizadas.

4. Caso de Estudio: Ejecución del Flujo Spec Kit

4.1 Inicialización

uvx --from git+https://github.com/github/spec-kit.git specify init subs-payments-api
cd subs-payments-api

subs-payments-api/
├── .specify/{commands,templates}/
├── specs/001-subscription-payments/{spec.md,plan.md,tasks.md}
├── memory/constitution.md
├── src/
└── tests/

4.2 Fase Specify

Prompt entregado: “Servicio de suscripciones B2B con planes Free/Pro/Enterprise, cobro recurrente automático, reintentos ante fallo, suspensión tras el tercer fallo y auditoría completa del historial.”

Extracto de spec.md generado:

## HU-04: Cobro recurrente y reintentos
Como sistema de facturación, quiero cobrar automáticamente cada
ciclo y reintentar de forma controlada ante fallos.

**Criterios de aceptación:**
- El cobro se intenta en la fecha de próximo cobro.
- Si falla, se reintenta a las 24h, 72h y 7 días.
- Tras el tercer reintento fallido, la suscripción pasa a
  `suspended` y se notifica al cliente en cada intento fallido.
- Un pago exitoso en cualquier reintento restaura el estado
  `active` y reprograma el ciclo.

Checkpoint 1: se detecta una omisión qué ocurre si el cliente cambia de plan durante un reintento pendiente y se corrige explícitamente: un cambio de plan cancela cualquier reintento pendiente y genera un nuevo ciclo de cobro. Este tipo de ambigüedad es precisamente la que el vibe-coding dejaría sin resolver hasta manifestarse como bug en producción.

4.3 Fase Plan

La arquitectura definida en plan.md se organiza en cuatro capas:

• Capa API (FastAPI): POST /subscriptions, PATCH /subscriptions/:id/plan, POST /webhooks/payment-gateway.
• Capa de Aplicación: CreateSubscription, ProcessBillingCycle, HandlePaymentWebhook.
• Capa de Dominio: Subscription, PaymentAttempt.
• Infraestructura: PostgreSQL, cliente de la pasarela de pagos y el planificador APScheduler.

Flujo principal: R1 → U1 → E1 → DB; R2 → U1; R4 → U5 → E3 → DB; SCHED → U4 → GW; U4 → DB.

Restricción clave fijada en plan.md: cada intento de cobro se asocia a una idempotency_key determinística (subscription_id + billing_cycle_id), con restricción UNIQUE en base de datos, para evitar cargos duplicados ante reintentos de red.

Checkpoint 2: se agrega rate-limiting a los endpoints públicos, ausente en la primera versión del plan.

4.4 Fase Tasks

## T-04: Job de ciclo de facturación con idempotencia
**Criterio de aceptación:** ejecutar el job dos veces sobre el
mismo ciclo no genera doble cobro.
**Depende de:** T-01.

## T-05: Webhook de pasarela con verificación HMAC
**Criterio de aceptación:** firma inválida → 401; evento duplicado
(mismo `event_id`) se ignora; evento válido actualiza el intento
y dispara notificación en fallo.
**Depende de:** T-01, T-04.

Checkpoint 3: se prioriza implementar T-01, T-04 y T-05 primero por concentrar el mayor riesgo técnico (idempotencia y seguridad).

4.5 Fase Implement

async def process_billing_cycle(
    subscription, billing_cycle_id, payment_repo, payment_gateway,
):
    idempotency_key = f"{subscription.id}:{billing_cycle_id}"
    existing = await payment_repo.find_by_idempotency_key(idempotency_key)
    if existing is not None:
        return existing.status  # ya procesado: no se recobra

    try:
        result = await payment_gateway.charge(
            customer_id=subscription.customer_id,
            idempotency_key=idempotency_key,
        )
    except Exception as exc:
        await payment_repo.record_attempt(
            idempotency_key, status="failed", error=str(exc)
        )
        raise

    await payment_repo.record_attempt(idempotency_key, status="success")
    return "success"

@pytest.mark.asyncio
async def test_billing_cycle_is_idempotent(dummy_subscription):
    repo, gateway = FakePaymentRepo(), FakeGateway()
    await process_billing_cycle(dummy_subscription, "cycle_2026_09", repo, gateway)
    await process_billing_cycle(dummy_subscription, "cycle_2026_09", repo, gateway)
    assert gateway.charge_calls == 1  # criterio de aceptación T-04

Checkpoint 4: la primera versión generada no capturaba la excepción del gateway antes de registrar el fallo, dejando el intento sin trazar ante errores de red. Se exige explícitamente al agente mover record_attempt(status="failed") dentro del bloque except, como se refleja en el código final. Este ajuste ilustra por qué el checkpoint humano no la generación automática por sí sola es el mecanismo que produce calidad.

5. Resultados y Discusión

5.1 Comparación cualitativa frente a vibe-coding

El hallazgo central: el SDD no elimina la ambigüedad ni el error; los reubica hacia fases tempranas y baratas de corregir (texto) en lugar de fases tardías y costosas (código en producción).

5.2 Escenarios de aplicabilidad

• Greenfield: mayor beneficio evitando decisiones de arquitectura implícitas desde el primer commit.
• Feature work en sistemas existentes: el escenario de mayor impacto según GitHub, al forzar declarar explícitamente la integración con el sistema vigente; requiere context engineering adicional para que el agente conozca el código existente.
• Modernización de legacy: el spec captura la lógica de negocio real, independiente de la implementación técnica antigua, permitiendo diseñar arquitectura nueva sin deuda heredada.

5.3 Limitaciones

1. Curva de aprendizaje: redactar especificaciones verificables es una habilidad distinta de programar.
2. Sobre-especificación: riesgo de reintroducir la rigidez del waterfall si spec.md se vuelve excesivamente detallado.
3. Contexto en repositorios masivos: sin indexación semántica adicional, /plan puede seguir siendo genérico en bases de código grandes.
4. Gobernanza documental: mantener los artefactos sincronizados con el sistema real requiere disciplina; de lo contrario reaparece el problema de la documentación desactualizada.

6. Conclusiones y Trabajo Futuro

El caso de estudio respalda cualitativamente H1: al forzar la resolución explícita de ambigüedades antes de generar código, Spec Kit desplazó la corrección de defectos desde depuración post-implementación hacia checkpoints de revisión textual, de menor costo. Esta validación es cualitativa y basada en un único caso, por lo que no constituye evidencia estadística generalizable.

Recomendaciones: adopción incremental sobre features de riesgo medio-alto; revisión por pares de spec.md/plan.md con el mismo rigor que el código; definición explícita de una “constitución” de proyecto; checkpoints sustantivos, no formales; e inversión en context engineering para proyectos sobre sistemas existentes.

Trabajo futuro: diseño de un experimento controlado multi-equipo que compare cuantitativamente ciclos de reescritura, cobertura de pruebas y tiempo de entrega entre vibe-coding y SDD; estudio de la integración de Spec Kit con context engineering a escala; evaluación de integraciones nativas en IDEs; y mecanismos de gobernanza automatizada para evitar la desactualización de artefactos.

Referencias

Delimarsky, D. (2025, septiembre 2). Spec-driven development with AI: Get started with a new open source toolkit. The GitHub Blog. https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/

GitHub. (2025). spec-kit [Repositorio de software]. GitHub. https://github.com/github/spec-kit

Nota metodológica: los artefactos (spec.md, plan.md, tasks.md) y el código presentados en §4 son ilustrativos, elaborados para este trabajo siguiendo la estructura real que produce Spec Kit; constituyen un caso de estudio construido con fines académicos, no un proyecto de producción auditado.

Palabras clave: Spec-Driven Development, Spec Kit, agentes de IA, GitHub Copilot, Claude Code, ingeniería de prompts, arquitectura de software.