Spec-driven development: del vibe coding a la memoria del equipo

El «vibe coding» nació como un tuit improvisado y acabó siendo palabra del año. Andrej Karpathy acuñó el término el 2 de febrero de 2025^[1]: entrégate a las vibras y olvídate de que el código existe. Doce meses después él mismo lo describió como «a shower of thoughts throwaway tweet», un pensamiento suelto lanzado sin más^[2]. Por el camino, Collins Dictionary lo coronó palabra del año 2025^[3] mientras GitHub Spec Kit, que empuja justo lo contrario, pasaba de rareza a 117.000 estrellas en GitHub^[4].

Diecisiete meses de hype y resaca que han decantado en algo parecido a una práctica. Nadie lo planificó. Si tu equipo produce código con agentes más rápido que nunca pero cada sesión empieza de cero y nadie se fía del resultado, este es tu tema. El spec-driven development propone una idea incómoda para quien disfruta improvisando: piensa primero, teclea después. Aquí defiendo por qué esa incomodidad es justo lo que te faltaba.

¿Por qué el vibe coding se derrumba en cuanto hay que mantener?

El vibe coding se derrumba porque el contexto que lo sostiene no se escribe en ningún sitio: vive en la cabeza del que promptea y en la sesión del agente, y se evapora al cerrar la pestaña.

Que quede claro, porque no quiero montar un espantapájaros: para un prototipo funciona, y muy bien. En el 25% de la cohorte Winter 2025 de Y Combinator, el 95% de las líneas de código las generaba un LLM^[5]. Garry Tan lo celebraba en marzo de 2025: «the age of vibe coding is here», la era del vibe coding ha llegado.

El problema aparece después, cuando ese prototipo hay que mantenerlo. Una nota de investigación de la Cloud Security Alliance de abril de 2026 agrega datos del sector y el retrato es duro: los desarrolladores asistidos por IA hacen commits a un ritmo tres o cuatro veces mayor, pero introducen hallazgos de seguridad a un ritmo diez veces mayor. El 45% de las muestras de código generado por IA arrastran vulnerabilidades del OWASP Top 10, y ya hay 74 CVE atribuidos a herramientas de IA^[6].

El vibe coding funciona para lo suyo; se vuelve no-mantenible sin un artefacto de control. La misma cohorte que Tan celebraba es el contexto de esa resaca: velocidad sin memoria.

¿Y si el «vibe» te está mintiendo sobre tu velocidad?

La sensación de ir rápido no es evidencia de ir rápido. En el ensayo controlado de METR, publicado en julio de 2025, dieciséis desarrolladores open source experimentados resolvieron 246 tareas en repos maduros. Con IA permitida tardaron un 19% más. Lo demoledor es la brecha de percepción: esperaban ir un 24% más rápido y, al terminar, seguían creyendo que habían ido un 20% más rápido^[7].

El propio METR avisa de que el resultado no generaliza a cualquier desarrollador ni a cualquier dominio: eran repos enormes, con más de un millón de líneas y años de contexto acumulado. Aun con ese matiz, el patrón incomoda. El «vibe» te dice una cosa y el cronómetro otra.

El informe DORA 2025 de Google llega al mismo sitio por otro camino. La adopción de IA alcanzó el 90%, más del 80% percibe una mejora de productividad, pero el 30% confía «poco» o «nada» en el código que genera^[8]. DORA describe la IA como espejo y multiplicador: si tu proceso ya es ordenado, lo amplifica; si es un caos, amplifica el caos.

La respuesta a este autoengaño es medir, no confiar en la sensación. Si quieres cambiar impresión por evidencia, el trabajo está en cómo evaluar agentes de IA en producción y en tratar cada mejora como un experimento con telemetría, como cuento en esta metodología para que los agentes se mejoren solos. Una spec con criterios de validación explícitos es la versión mínima de esa idea.

¿Qué es exactamente el spec-driven development?

El spec-driven development invierte el orden del vibe coding: en vez de saltar a la implementación, haces primero el trabajo duro de pensar y lo documentas en una especificación versionada en el repo que los agentes leen como contrato.

Mariya Mansurova lo definió con precisión en Towards Data Science: hacer primero el trabajo duro de pensar (las decisiones de arquitectura y los no-negociables) y documentarlo en una spec en markdown guardada en el repositorio y actualizada junto al proyecto^[9]. La idea detrás del título de este post es la suya: la spec preserva el contexto «entre sesiones e incluso entre distintos agentes de IA». Esa es la idea fuerza. La spec es la memoria persistente del equipo.

GitHub Spec Kit lleva esto al extremo operativo. Su README lo resume sin rodeos: «specifications become executable, directly generating working implementations rather than just guiding them»^[4], las especificaciones se vuelven ejecutables y generan la implementación en lugar de solo guiarla. Es un flujo de slash-commands, ya en producción, que soporta más de 30 agentes de código, de Claude Code a Cursor.

# Flujo de GitHub Spec Kit: de los principios al código
/speckit.constitution   # fija los principios y no-negociables del proyecto
/speckit.specify        # define QUÉ se construye y por qué
/speckit.plan           # traza el plan técnico de implementación
/speckit.tasks          # descompone el plan en tareas accionables
/speckit.implement      # el agente ejecuta contra la spec

Puesto uno al lado del otro, el reparto de fuerzas se ve claro:

	Vibe coding	Spec-driven development
Dónde vive el contexto	En la cabeza y en la sesión del agente	En el repo, versionado en git
Velocidad inicial	Máxima, arrancas al instante	Menor: pagas el coste de pensar primero
Entre sesiones y agentes	Se evapora al cerrar la pestaña	Persiste; cualquier agente lo relee
Qué puedes delegar	Poco, y con supervisión constante	Franjas acotadas con contrato verificable
Cuándo compensa	Prototipo, spike, algo de usar y tirar	Lo que hay que mantener o toca a más de una persona

¿Es esto waterfall reencarnado?

No, y la diferencia está en la longitud del bucle de feedback. Es la objeción número uno de cualquier senior que sufrió el waterfall, y es legítima. Liu Shangqi, de Thoughtworks, distingue dos sabores de spec-driven development^[10]. En el radical, la spec es la única fuente de verdad y el código es desechable: regeneras la implementación cada vez que cambia la spec. En el conservador, la spec guía la generación pero el código sigue mandando y CI/CD arbitra.

Mi postura es que hoy solo el conservador sobrevive al contacto con producción. Liu lo defiende bien: el spec-driven development no crea bucles de feedback enormes como el waterfall, sino que ofrece un mecanismo para bucles más cortos y efectivos de lo que permitiría el vibe coding puro. La spec no congela el diseño durante seis meses. Se actualiza en el mismo PR que el cambio que la invalida.

El riesgo simétrico también existe: una spec sobre-formalizada frena el cambio en vez de habilitarlo. Y aparece un fallo nuevo, el «spec drift»: la spec deja de reflejar el sistema y los agentes generan contra un contrato falso. Es el doc-rot de toda la vida, y se combate igual que el código: revisándola en cada PR y dejando que la CI falle cuando la spec y la implementación divergen.

Diagrama de flujo que compara el sabor radical y el conservador del spec-driven development: cuando la spec cambia, el sabor radical regenera toda la implementación y trata el código como desechable, mientras que el sabor conservador genera o edita el código contra la spec y un gate de CI/CD comprueba si código y spec coinciden, devolviendo un bucle corto de corrección si divergen o haciendo merge si el contrato queda verificado — La diferencia entre los dos sabores de spec-driven development es práctica: qué manda cuando código y spec divergen, y qué tan corto es el bucle hasta detectarlo.

¿Qué contiene una spec útil (y qué no)?

Una spec útil describe el comportamiento externo del software y deja el cómo al agente. Thoughtworks lo concreta: mapeos de entrada/salida, precondiciones y postcondiciones, invariantes, restricciones y contratos de integración^[10]. Mansurova añade la capa de intención: los no-negociables y las decisiones de arquitectura, unos documentos «constitucionales» que cambian poco (misión, stack técnico, roadmap y principios de diseño) y, por feature, una spec con sus requisitos y sus criterios de validación^[9]. Y WeBuild-AI insiste en dos secciones que casi nadie escribe y todos echan de menos: las implementaciones existentes con las que la feature se relaciona y los estándares de seguridad que le aplican^[11], incluidos los de la cadena de suministro de skills y servidores MCP que tu agente ejecuta al implementarla.

Junto, tiene esta pinta. Este es el esqueleto que uso yo para un worker de reintento de webhooks, el clásico servicio que nadie quiere volver a tocar a ciegas:

# Spec: worker de reintento de webhooks

## Objetivo
Reentregar los webhooks fallidos sin duplicar entregas ya confirmadas.

## Comportamiento externo (I/O)
- Entrada: evento en la cola `webhooks.dead` con su payload y nº de intentos.
- Salida: POST al endpoint del cliente; marca el evento `delivered` o `exhausted`.

## Invariantes y no-negociables
- Nunca reenviar un evento ya confirmado (idempotencia por `event_id`).
- Máximo 5 reintentos, con backoff exponencial.
- Cero secretos ni PII en los logs.
- Un evento agotado no vuelve a la cola activa.

## Contratos de integración
- Lee de `webhooks.dead` (formato v2). Escribe métricas en `delivery_stats`.

## Criterios de validación
- Un evento confirmado no se reenvía aunque reaparezca en la cola.
- Al 6º fallo el evento queda `exhausted`, nunca en bucle.

## Fuera de alcance
- Alta de nuevos endpoints de cliente (eso lo cubre otra feature).

Dónde vive: en el repo, junto al código, versionada en git como un fichero más. Cómo evoluciona: se actualiza en el mismo PR que el cambio que la deja obsoleta, jamás «cuando haya tiempo». Fíjate en la sección de criterios de validación, porque ahí es donde la spec engancha con los tests. Esos criterios son el contrato que tu estrategia de tests para código generado por IA ejecuta de verdad. Y los no-negociables que van arriba del todo son los mismos que ya trabajas al diseñar un agente: si aún no los tienes claros, empieza por las decisiones que definen la arquitectura de un agente empresarial.

Lo que una spec no contiene es el detalle de implementación. Si le dictas al agente el cómo línea a línea, has vuelto al prompt gigante y has perdido la spec. Y para un cambio pequeño, escribir una spec completa es, en palabras de Mansurova, «probably overkill»^[9].

Spec-driven y context engineering: dos mitades de lo mismo

La spec y la gestión de contexto no compiten: son dos mitades de la misma solución. Ben Saunders lo plantea sin ambigüedad en WeBuild-AI: «neither can succeed without the other», ninguna de las dos triunfa sin la otra^[11]. Spec-driven development sin gestión de contexto produce specs que el agente no consigue ejecutar bien, porque no le llega la información correcta en el momento correcto. Y la gestión de contexto sin una spec es, según él, infraestructura sofisticada sin un destino claro: sabes servir contexto, pero no hacia qué objetivo.

Mi reencuadre es más simple. La spec es context engineering estable. Es contexto que no se reconstruye cada sesión: persiste y está versionado. Cuando escribes una spec, estás decidiendo qué información merece sobrevivir al cierre de la pestaña.

Diagrama del ciclo cerrado entre la spec, el ensamblado de contexto y la validación: la spec aporta el contrato y los criterios, el ensamblado de contexto selecciona la porción relevante para el agente, el agente produce un diff de código, un rombo de decisión comprueba si cumple los criterios de validación. Si no, vuelve al agente con el test fallido; si sí, hace merge y actualiza la spec si el contrato cambió, cerrando el ciclo — La spec y la gestión de contexto no son piezas separadas: forman un ciclo cerrado donde la validación decide si el código vuelve al agente o actualiza el contrato.

¿Qué cambia en tu rol si adoptas spec-driven development?

Adoptar spec-driven development mueve tu trabajo de escribir la implementación a definir y verificar el contrato. El «2026 Agentic Coding Trends Report» de Anthropic pone número a la tensión: los desarrolladores ya usan IA en torno al 60% de su trabajo, pero solo pueden delegar por completo entre el 0 y el 20% de las tareas^[12]. Esa brecha entre «lo uso para casi todo» y «casi nada lo suelto del todo», la brecha de delegación que ya analicé a fondo, es donde vive el spec-driven development. Anthropic describe el rol humano primario como orquestar los agentes de IA que escriben código, evaluar su salida, dar dirección estratégica y asegurar que el sistema resuelve el problema correcto. La spec es el artefacto que ensancha la franja delegable: convierte la supervisión activa constante en un contrato verificable más una revisión.

En The Pragmatic Engineer, una encuesta con más de 900 ingenieros recoge cómo se ve esto en el día a día. Un ingeniero lo cuenta así: pega los criterios de aceptación y la descripción del issue en el plan mode, deja que el modelo lo resuelva y luego pasa a Composer o Sonnet para que el agente tome el relevo^[13]. Los criterios de aceptación son, otra vez, la spec en miniatura.

Mansurova lo resume: el rol del ingeniero se desplaza «de escribir código directamente a centrarse más en las decisiones de arquitectura, la revisión y el diseño de sistema»^[9]. La spec es lo que define el contrato que cierra el bucle del agente, la pieza que convierte un bucle agéntico en algo con un criterio de parada verificable en vez de una barra de progreso emocional.

Ese trabajo tiene nombre: dirigir agentes con criterio. Saber qué pedir y cómo verificar la salida es una habilidad, no un don, y es exactamente lo que entrena el curso «Patrones de Diseño para Agentes de IA». La spec la exige; el curso la enseña.

Errores comunes que convierten la spec en teatro

Spec-teatro: escribirla después del código

Escribir la spec cuando la feature ya está mergeada, solo para cumplir el ritual, es el error más común y el más inútil. Una spec que documenta lo que ya existe no es memoria ni contrato: es un acta de una reunión que ya pasó. Su valor está en escribirla antes, cuando todavía obliga a decidir algo.

Spec drift: el contrato que miente

La spec deja de reflejar el sistema y los agentes empiezan a generar contra un contrato falso. Lo he visto en mi propio repo: subes el límite de reintentos en el código y la spec se queda diciendo cinco, así que el siguiente agente que la lee genera contra un número que ya no existe. Thoughtworks avisa de que el spec drift y las alucinaciones son inherentemente difíciles de evitar^[10], y por eso insiste en CI/CD determinista. El antídoto es mecánico: la spec se toca en el mismo PR que el código que la invalida, o la CI lo rechaza.

# En el MISMO PR que sube el límite de reintentos
## Invariantes y no-negociables
- - Máximo 5 reintentos, con backoff exponencial.
+ - Máximo 8 reintentos, con backoff exponencial.

Sobre-formalización

Escribir specs exhaustivas para todo frena el cambio en vez de habilitarlo, el riesgo simétrico que señala Thoughtworks. Para una mejora menor, la spec sobra.

Una spec sin criterios de validación

Describe el qué pero no cómo comprobarlo, y el «vibe» vuelve por la puerta de atrás. Sin verificación, tu percepción de velocidad no vale nada, que es exactamente lo que mostró METR. Si la sección de validación está vacía, has escrito una intención y la has llamado contrato.

Dictar el cómo, no el qué

Cuando la spec baja al nivel de «usa un for en vez de un map», deja de ser un contrato de comportamiento y se convierte en micromanagement del agente. Fija el comportamiento externo y los invariantes; el cómo es problema del modelo. Y si no te fías del cómo, ahí entran los tests, no más líneas de spec. Afinar instrucciones puntuales es otra disciplina: eso son patrones de prompt engineering, y operan un nivel por debajo del contrato.

Checklist: ¿tu spec sirve como memoria del equipo?

La spec vive en el repo y se versiona en git como el código.
Fija el comportamiento externo y los invariantes, no el detalle de implementación.
Incluye criterios de validación que un test puede ejecutar.
Se actualiza en el mismo PR que el cambio que la deja obsoleta.
Documenta los no-negociables y las decisiones de arquitectura antes de escribir código.
Para un cambio pequeño de una sola sesión, has decidido conscientemente no escribirla.

Fuentes

«Vibe coding» — Andrej Karpathy (X) — tuit original que acuña el término (2 feb 2025).
Retrospectiva de Karpathy (X) — «a shower of thoughts throwaway tweet», un año después.
Word of the Year 2025 — Collins Dictionary — «vibe coding», palabra del año 2025 (cobertura en CNN).
GitHub Spec Kit — 117k estrellas (julio de 2026), flujo de slash-commands y la cita «specifications become executable».
A quarter of startups in YC’s current cohort… — TechCrunch — 25% de la cohorte W25 con ~95% de código generado por LLM (tuit de Garry Tan).
AI-Generated Code Vulnerability Surge — Cloud Security Alliance — commits 3-4x, hallazgos 10x, 45% OWASP Top 10, 74 CVE (4 abr 2026).
Measuring the Impact of Early-2025 AI on Experienced OS Developers — METR — ralentización del 19% frente a una percepción de +20% (paper).
State of AI-assisted Software Development — Google DORA 2025 — 90% de adopción, 30% confía poco o nada, IA como «espejo y multiplicador».
From Vibe Coding to Spec-Driven Development — Mariya Mansurova, Towards Data Science — definición de SDD, contenido de la spec y cambio de rol (12 may 2026).
Spec-driven development: unpacking 2025’s new engineering practices — Liu Shangqi, Thoughtworks — dos sabores de SDD, anti-waterfall, spec drift y qué define una spec.
Aligning Spec-Driven Development and Context Engineering for 2026 — Ben Saunders, WeBuild-AI — «neither can succeed without the other» y las secciones de una spec.
2026 Agentic Coding Trends Report — Anthropic — IA en ~60% del trabajo, 0-20% totalmente delegable, rol de orquestación (PDF).
The impact of AI on software engineers in 2026 — The Pragmatic Engineer — encuesta a 900+ ingenieros; flujo criterios de aceptación → plan mode → agente.

Preguntas Frecuentes

¿El spec-driven development es lo mismo que waterfall?

No. El waterfall crea un único bucle de feedback gigante entre especificar y entregar; el spec-driven development hace lo contrario, con bucles cortos y frecuentes, como argumenta Thoughtworks. La spec no se congela al principio del proyecto: se actualiza en el mismo PR que el código que la cambia.

¿Necesito GitHub Spec Kit para hacer spec-driven development?

No, aunque ayuda. Una spec es markdown versionado en el repo: eso lo montas sin instalar nada. Spec Kit añade un flujo de slash-commands y convenciones cómodas, y sigue muy activo en julio de 2026, con más de 117.000 estrellas. Es una comodidad, no un requisito.

¿Merece la pena escribir una spec para un cambio pequeño?

Casi nunca. Para una mejora menor, escribir una spec completa es, como dice Mansurova, «probably overkill»^[9]. El umbral práctico es sencillo: si el trabajo hay que mantenerlo y lo va a tocar más de una sesión o más de un agente, la spec compensa.

¿En qué se diferencia una spec de un AGENTS.md o un CLAUDE.md?

El archivo de contexto describe el proyecto entero y sus convenciones de forma estable: cómo se construye y qué convenciones sigue. La spec fija el contrato de una feature concreta: su comportamiento externo, sus invariantes, sus contratos de integración y los criterios con los que se valida. Se complementan, y si aún no controlas el fichero de contexto, empieza por cómo un AGENTS.md puede arruinar o salvar tu agente.

¿La fuente de verdad es el código o la spec?

El código, hoy por hoy. Mi postura es el sabor conservador: la spec guía la generación, pero el código sigue mandando y la CI arbitra cuando divergen. El sabor radical, donde la spec es la única verdad y el código es desechable, todavía no sobrevive al contacto con un pipeline de producción real.