Desarrollo guiado por especificaciones vs. programación por ambiente: ¿Cascada?

¿Especificaciones como fuente de verdad o ceremonia lenta?

Índice

El Desarrollo Guiado por Especificaciones (SDD) entró en 2026 como la respuesta seria de los desarrolladores al desvío hacia la “codificación por ambiente” (vibe coding).

El argumento es simple: los agentes de IA producen resultados mejores y más consistentes cuando implementan contra una especificación revisada en lugar de contra un prompt improvisado. Teóricamente, es difícil discutirlo.

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

Ambos bandos tienen razón.

Desarrollo Guiado por Especificaciones versus Codificación por Ambiente

El caso a favor del SDD en un mundo de codificación por ambiente

La codificación por ambiente – la práctica de escribir un prompt amplio e iterar sobre lo que el agente de IA produzca – funciona de manera notable para trabajos pequeños, exploratorios y desechables. Durante los primeros seis meses de 2025, fue el patrón de codificación con IA dominante. Los desarrolladores entregaron scripts, prototipos y herramientas simples más rápido que nunca.

Luego, los proyectos crecieron. Las características que involucraban múltiples archivos comenzaron a desviarse. Las restricciones establecidas en la sesión uno fueron olvidadas para la sesión tres. Se descartaron suposiciones de seguridad. Las decisiones arquitectónicas cambiaron a mitad de la característica porque el agente no tenía una memoria duradera de la intención.

El Desarrollo Guiado por Especificaciones (SDD) apareció como la respuesta disciplinada. La afirmación central: hacer que la especificación sea el artefacto central, no el prompt. Escriba primero los requisitos, el diseño y un plan de tareas. Permita que el agente implemente contra esos artefactos, un trozo a la vez. Mantenga la especificación versionada y actualizada.

GitHub Spec Kit, Kiro, los flujos de trabajo de SDD de Claude Code y BMAD, junto con otros andamios comunitarios, 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 buena la codificación por ambiente

Antes de descartar la codificación por ambiente, vale la pena ser preciso sobre en qué es buena.

Prototipos exploratorios. Cuando no está seguro de lo que desea 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 sabe, 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. La codificación por ambiente le permite ver opciones rápidamente, descartar la mayoría y converger en algo que realmente se siente correcto. Un documento de requisitos no le ayuda aquí.

Automatización desechable. Scripts de uso único, trabajos de extracción de datos, asistentes de migración – estos rara vez necesitan un documento de diseño. El costo de equivocarse ligeramente es bajo. El costo de un proceso lento y ceremonial es real.

Retroalimentación rápida. Cuando necesita aprender algo rápidamente – ¿funciona esta API como creo que funciona? – la codificación por ambiente reduce el ciclo de aprendizaje a minutos. El SDD ralentizaría eso sin ningún beneficio.

El error es tomar los patrones de éxito de estos contextos y aplicarlos a características de producción con restricciones reales, usuarios reales y consecuencias reales por equivocarse.

Dónde falla la codificación por ambiente

La codificación por ambiente se degrada de manera predecible a medida que aumentan el alcance y las apuestas.

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

Desvío arquitectónico. 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 codificación por ambiente, es algo que mencionó una vez en la sesión uno y el agente no recuerda en la sesión cuatro cuando escribe el nuevo 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 pasan por alto cuando el agente está optimizando para un código funcional plausible en lugar de un código correcto y restringido.

Entrega al equipo. Si lo construyó mediante prompts iterativos, el artefacto que registra qué se decidió y por qué es… el registro de git (git log). Buena suerte con eso.

Qué cambia el Desarrollo Guiado por Especificaciones

El SDD no afirma eliminar la iteración. Las buenas versiones del 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 métodos formales – vea ¿Qué es el Desarrollo Guiado por Especificaciones?

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

El SDD atraviesa cinco fases – especificar, planificar, tareas, implementar, validar – con una puerta de revisión humana en cada paso. Vea Flujo de Trabajo de Desarrollo Guiado por Especificaciones: De Requisitos a 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 la codificación por ambiente.

Por qué los desarrolladores lo llaman Waterfall

La crítica del Waterfall no es incorrecta. Simplemente está dirigida hacia un mal SDD, no hacia el SDD en sí.

El modo de fallo específico es la planificación extensa inicial. La característica definitoria del Waterfall es un ciclo 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 el momento en que descubre que la suposición de diseño era incorrecta, ya ha 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 nada, 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 CLI y encontró que era “demasiado lento, demasiados ajustes antes de ver el código”. Esa es la mala versión. Ese usuario tenía razón en rechazarla para esa tarea.

La crítica útil no es “las especificaciones son malas”. Es “la planificación extensa inicial antes de la retroalimentación es mala”. Esas 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 característica debería caber en una pantalla. Si la especificación tiene diez páginas, es либо un diseño de plataforma либо necesita dividirse en características más pequeñas. Las especificaciones demasiado grandes tardan demasiado en revisarse y se vuelven obsoletas rápidamente.

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

Implementación temprana. Especifique la primera tarea, impleméntela, valídela y luego pase a la siguiente tarea. No especifique todo antes de implementar nada. La primera implementación revelará cosas que su especificación obtuvo incorrectamente. Actualice la especificación antes de continuar.

Especificación viva. Cuando la realidad difiere del diseño – y lo hará – actualice 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 al menos a una prueba. El conjunto de pruebas es la versión legible por máquina de la especificación. Si la especificación dice “solo los 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 codificación por ambiente y no es Waterfall. Es iteración controlada con artefactos duraderos.

Cuando el SDD supera a la codificación por ambiente

Use el SDD – incluso un SDD ligero – cuando el costo de equivocarse sea real.

Lógica de negocio arriesgada. Facturación, permisos, migraciones de datos, idempotencia – cualquier lógica donde el comportamiento incorrecto sea costoso o difícil de revertir. La codificación por ambiente deja estos tipos de requisitos implícitos. El SDD los hace explícitos y revisables antes de la implementación.

Cambios en API de producción. Cualquier cambio en un contrato de API pública o interna debe tener un documento de diseño. El documento de diseño es lo que revisa antes de que el agente escriba código que rompa a los llamadores.

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

Entrega al equipo. Si otro desarrollador u otro agente continuará con este trabajo, la especificación es el artefacto de entrega. 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 pensaba que se preservaron.

Cuando la codificación por ambiente sigue siendo mejor

El SDD es 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. Escriba el prompt, verifique la salida, lánzelo.

Experimentos. Si está aprendiendo si un enfoque es factible – explorando una API, probando una biblioteca, validando una hipótesis – necesita velocidad, no estructura. Experimente primero, especifique si el experimento tiene éxito.

Bocetos de UI. El diseño de interacción se beneficia de ver en lugar de especificar. Construya varias variaciones rudimentarias rápidamente, reaccione a lo que ve y solo especifique lo que realmente va a lanzar.

Automatización desechable. Scripts de uso único, importaciones de datos, asistentes de migración – el costo de un resultado ligeramente incorrecto suele ser bajo, y el artefacto se eliminará después del uso de todos modos.

Prototipos individuales. Si es la única persona que verá este código y el objetivo es el aprendizaje en lugar de la producción, la codificación por ambiente es más rápida y las desventajas están contenidas.

Un marco de decisión simple

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

Use la codificación por ambiente cuando:

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

Use el 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á con el trabajo
  • Necesita escribir pruebas que mapeen a los requisitos

Use el SDD completo cuando:

  • La característica toca una interfaz pública o un contrato de datos
  • Participan múltiples agentes o miembros del equipo
  • La organización requiere una revisión de diseño antes de la implementación
  • Se requieren cumplimiento o registros de auditoría

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 elija, la especificación solo permanece útil si algo la verifica constantemente contra el código; Mantener Especificaciones, Pruebas y Código Sincronizados en el Desarrollo con IA cubre las verificaciones de trazabilidad que capturan cuando una especificación se vuelve obsoleta silenciosamente.

El mal SDD es Waterfall con markdown. El buen SDD es iteración controlada con artefactos duraderos. La codificación por ambiente es la herramienta correcta para las tareas correctas – y la herramienta incorrecta para las incorrectas. Conocer la diferencia es la habilidad.

Enlaces útiles

Suscribirse

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