Desarrollo basado en especificaciones frente a codificación por intuición: ¿cascada?

¿Las especificaciones como fuente de verdad o una ceremonia lenta?

Índice

El Desarrollo Basado en Especificaciones (Spec-Driven Development) llegó al 2026 como la respuesta seria de los desarrolladores al “deriva” del vibe coding.

El argumento es simple: los agentes de IA producen una salida de mejor calidad y más consistente cuando implementan contra una especificación revisada, en lugar de contra un prompt improvisado. Es difícil discutir esto en teoría.

En la práctica, Hacker News lo llamó “El Retorno del Waterfall”.

Ambos lados tienen un punto.

Desarrollo Basado en Especificaciones versus Vibe Coding

El caso a favor del SDD en un mundo de Vibe Coding

Vibe coding – la práctica de escribir un prompt suelto e iterar sobre lo que el agente de IA produce – funciona sorprendentemente bien para trabajos pequeños, exploratorios y descartables. Durante los primeros seis meses de 2025, fue el patrón dominante de codificación con IA. Los desarrolladores lanzaron scripts, prototipos y herramientas simples más rápido que nunca.

Luego, los proyectos crecieron. Las funciones de múltiples archivos comenzaron a desviarse. Las restricciones establecidas en la sesión uno fueron olvidadas en la sesión tres. Las suposiciones de seguridad se perdieron. Las decisiones arquitectónicas cambiaron a mitad de la función porque el agente no tenía una memoria duradera de la intención.

El Desarrollo Basado en Especificaciones (SDD) apareció como la respuesta disciplinada. La afirmación central: hacer que la especificación sea el artefacto central, no el prompt. Primero se escriben los requisitos, un diseño y un plan de tareas. Se deja que el agente implemente contra esos artefactos, una porción a la vez. Se mantiene la especificación versionada y actualizada.

GitHub Spec Kit, Kiro, flujos de trabajo SDD de Claude Code y BMAD, así como otros andamiajes de la comunidad como Superpowers, son todas implementaciones de esta idea. Las herramientas son reales. El interés es real. La reacción en contra también es real.

En qué es bueno el Vibe Coding

Antes de descartar el vibe coding, vale la pena ser preciso sobre lo que hace bien.

Prototipos exploratorios. Cuando no estás seguro de lo que quieres construir, el camino más rápido es construir algo rudimentario y reaccionar a ello. El SDD requiere saber qué especificar. Si aún no lo sabes, las especificaciones son prematuras.

Experimentos de interfaz de usuario (UI). El diseño visual y la sensación de interacción son difíciles de especificar con antelación. El vibe coding te permite ver opciones rápidamente, descartar la mayoría de ellas y converger hacia algo que realmente se siente correcto. Un documento de requisitos no te ayuda aquí.

Automatización descartable. Scripts de un solo uso, trabajos de extracción de datos, asistentes de migración – estos raramente necesitan un documento de diseño. El costo de hacerlo un poco mal es bajo. El costo de un proceso lento y ceremonial es real.

Retroalimentación rápida. Cuando necesitas aprender algo rápidamente – ¿funciona esta API de la manera en que creo que funciona? – el vibe coding reduce el ciclo de aprendizaje a minutos. El SDD lo ralentizaría sin beneficio alguno.

El error es tomar los patrones de éxito de estos contextos y aplicarlos a funciones de producción con restricciones reales, usuarios reales y consecuencias reales por hacerlo mal.

Dónde falla el Vibe Coding

El vibe coding se degrada de manera predecible a medida que aumentan el alcance y las apuestas.

Cambios en múltiples archivos. Una vez que una función toca cinco o más archivos, la ventana de contexto del agente empieza a perder el rastro de los invariantes. Sin un documento de diseño, cada prompt debe reestablecer el contexto que se estableció y se olvidó en una sesión anterior.

Deriva arquitectónica. Sin objetivos no explícitos (non-goals), los agentes implementan cosas. El agente añade una capa de caché porque parece razonable. Tres sesiones después, la suposición de caché está integrada en el modelo de datos y eliminarla es costoso.

Restricciones olvidadas. “Solo los usuarios autenticados pueden activar esto” es una frase en un documento de requisitos. En una sesión de vibe coding, es algo que mencionaste una vez en la sesión uno y el agente no lo recuerda en la sesión cuatro cuando escribe el nuevo punto de conexión (endpoint).

Suposiciones de seguridad ocultas. Reglas de autorización, límites de validación de entrada, manejo de secretos: estos son exactamente el tipo de requisitos implícitos que se pierden cuando el agente optimiza para código funcional plausible en lugar de código correcto y restringido.

Traspaso de equipo (Team handoff). Si lo construiste mediante prompting iterativo, el artefacto que registra lo que se decidió y por qué es… el registro de git. Buena suerte con eso.

Qué cambia el Desarrollo Basado en Especificaciones

El SDD no afirma eliminar la iteración. Las buenas versiones de SDD son explícitamente iterativas. Lo que cambian es dónde ocurre la iteración. Para la definición completa – incluyendo cómo el SDD difiere de TDD, BDD y los métodos formales – ver ¿Qué es el Desarrollo Basado en Especificaciones?

En lugar de iterar sobre el código e inferir la intención desde las diferencias (diffs), se itera sobre la especificación y luego se implementa. La especificación se convierte en el artefacto que registra qué se decidió, por qué y qué está fuera de alcance – sirviendo a una función similar a la de los Registros de Decisiones Arquitectónicas pero orientada a la intención de la función en lugar de a las decisiones a nivel de sistema. El código implementa esa intención.

El SDD pasa por cinco fases – especificar, planificar, tareas, implementar, validar – con una puerta de revisión humana en cada paso. Ver Flujo de Trabajo de Desarrollo Basado en Especificaciones: De los Requisitos al Código para el proceso completo, plantillas y puntos de control. El agente participa en la mayoría de las fases, pero los humanos revisan los artefactos antes de que comience la implementación. Ese paso de revisión es la diferencia central entre el SDD y el vibe coding.

Por qué los desarrolladores lo llaman Waterfall

La crítica del waterfall no es incorrecta. Simplemente está dirigida al SDD malo, no al SDD en sí mismo.

El modo de fallo específico es la planificación inicial prolongada. La característica definitoria del waterfall es un bucle de retroalimentación que se extiende a semanas o meses: fase de requisitos, fase de diseño, fase de construcción, fase de prueba, lanzamiento. La retroalimentación llega tarde. Para cuando descubres que la suposición de diseño estaba equivocada, has construido sobre ella durante semanas.

Cuando un desarrollador usa Spec Kit y genera una lista de tareas de 200 líneas antes de escribir una sola línea de código, y luego pasa dos días puliendo el documento de requisitos antes de que el agente toque algo, eso es waterfall. Es waterfall con Markdown en lugar de UML, pero el modo de fallo es idéntico.

Un comentarista de HN describió el uso de Spec Kit para una pequeña herramienta de CLI y encontró que era “demasiado lento, demasiado ajuste antes de ver el código”. Esa es la mala versión. Ese usuario tenía razón al rechazarlo para esa tarea.

La crítica útil no es “las especificaciones son malas”. Es “la planificación inicial prolongada antes de la retroalimentación es mala”. Son afirmaciones diferentes.

El punto medio útil

El buen SDD evita la trampa del waterfall manteniendo la especificación pequeña y comenzando la implementación temprano.

Especificaciones pequeñas. Un documento de requisitos para una sola función debe caber en una pantalla. Si la especificación tiene diez páginas, o es un diseño de plataforma o necesita dividirse en funciones más pequeñas. Las especificaciones demasiado grandes tardan demasiado en revisarse y se vuelven obsoletas rápidamente.

Porciones de tareas cortas. Cada tarea debe ser implementable en una sola sesión de agente, revisable como una diferencia (diff) pequeña y probable de forma aislada. Si las tareas son demasiado grandes, el bucle de implementación se extiende y el mapeo de especificación a código se vuelve difícil de verificar.

Implementación temprana. Especifica la primera tarea, implementsla, valídala y luego pasa a la siguiente tarea. No especifiques todo antes de implementar algo. La primera implementación revelará cosas que tu especificación tuvo mal. Actualiza la especificación antes de continuar.

Especificación viva. Cuando la realidad difiere del diseño – y lo hará – actualiza la especificación, no solo el código. La especificación solo es útil si refleja lo que realmente se construyó.

Pruebas como retroalimentación ejecutable. Cada criterio de aceptación debe mapearse a al menos una prueba. El conjunto de pruebas es la versión legible por máquina de la especificación. Si la especificación dice “solo usuarios autenticados pueden activar esto”, debe haber una prueba que verifique que las solicitudes no autenticadas sean rechazadas.

Este híbrido – especificaciones pequeñas, tareas cortas, implementación temprana, documentos vivos – es lo que realmente funciona. No es vibe coding y no es waterfall. Es iteración controlada con artefactos duraderos.

Cuando el SDD supera al Vibe Coding

Usa el SDD – incluso el SDD ligero – cuando el costo de hacerlo mal es real.

Lógica de negocio de alto riesgo. Facturación, permisos, migraciones de datos, idempotencia: cualquier lógica donde el comportamiento incorrecto sea costoso o difícil de revertir. El vibe coding deja estos tipos de requisitos implícitos. El SDD los hace explícitos y revisables antes de la implementación.

Cambios en APIs de producción. Cualquier cambio en un contrato de API público o interno debe tener un documento de diseño. El documento de diseño es lo que se revisa antes de que el agente escriba código que rompa a los llamadores (callers).

Flujos de trabajo multiagente. Cuando múltiples agentes están implementando diferentes partes de una función, la especificación es la fuente de verdad compartida. Sin ella, cada agente optimiza localmente y las piezas pueden no encajar.

Traspaso de equipo (Team handoff). Si otro desarrollador o otro agente continuará este trabajo, la especificación es el artefacto de traspaso. Un registro de git y un README no son suficientes.

Refactorizaciones significativas. Las refactorizaciones que tocan abstracciones centrales necesitan una declaración explícita de lo que debe permanecer igual (comportamiento) y lo que se permite cambiar (estructura). Sin eso, el agente puede romper contratos que creías preservados.

Cuando el Vibe Coding sigue siendo mejor

El SDD es una sobrecarga. A veces la sobrecarga no vale la pena.

Scripts rápidos. Un script de 50 líneas para renombrar archivos o transformar JSON no necesita un documento de requisitos. Escribe el prompt, revisa la salida, lánzalo.

Experimentos. Si estás aprendiendo si un enfoque es factible – explorando una API, probando una librería, validando una hipótesis – necesitas velocidad, no estructura. Experimenta primero, especifica si el experimento tiene éxito.

Bocetos de interfaz de usuario (UI). El diseño de interacción se beneficia de ver en lugar de especificar. Construye varias variaciones rudimentarias rápidamente, reacciona a lo que ves y solo especifica lo que realmente vas a lanzar.

Automatización descartable. Scripts de un solo uso, importaciones de datos, asistentes de migración: el costo de un resultado ligeramente incorrecto suele ser bajo, y el artefacto se eliminará después de su uso de todos modos.

Prototipos solitarios. Si eres la única persona que verá este código y el objetivo es aprender en lugar de producción, el vibe coding es más rápido y las desventajas están contenidas.

Un marco de decisión simple

La pregunta práctica no es “¿SDD o vibe coding?”. Es “¿cuánta especificación necesito para esta tarea específica?”.

Usa vibe coding cuando:

  • La tarea toma menos de un día
  • Estás explorando o aprendiendo
  • El artefacto es descartable o de bajo riesgo
  • Eres la única persona que tocará esto
  • La velocidad de retroalimentación importa más que la corrección

Usa SDD ligero cuando:

  • La tarea toma dos o más días
  • Se ven afectados múltiples archivos
  • Hay requisitos explícitos de seguridad o corrección
  • Otra persona o agente continuará el trabajo
  • Necesitas escribir pruebas que se mapeen a los requisitos

Usa SDD completo cuando:

  • La función toca una interfaz pública o un contrato de datos
  • Están involucrados múltiples agentes o miembros del equipo
  • La organización requiere una revisión de diseño antes de la implementación
  • Se requieren trazas de auditoría o cumplimiento

El error más común es aplicar el SDD completo a tareas que solo necesitan SDD ligero, y no aplicar ninguna especificación a tareas que necesitan al menos una ligera. Cualquiera sea el nivel que elijas, la especificación solo se mantiene útil si algo la verifica constantemente contra el código; Mantener Especificaciones, Pruebas y Código en Sincronía en el Desarrollo con IA cubre las verificaciones de trazabilidad que detectan una especificación que se vuelve obsoleta en silencio.

El SDD malo es waterfall con Markdown. El buen SDD es iteración controlada con artefactos duraderos. El vibe coding es la herramienta correcta para las tareas correctas – y la herramienta incorrecta para las incorrectas. Saber la diferencia es la habilidad.

Enlaces Útiles

Suscribirse

Recibe nuevas publicaciones sobre sistemas, infraestructura e ingeniería de IA.