Desarrollo guiado por especificaciones vs. codificación por ambiente: ¿cascada?

¿Especificaciones como fuente de verdad o ceremonia lenta?

Índice

El desarrollo basado en 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 sencillo: los agentes de IA producen un resultado mejor y más consistente cuando implementan contra una especificación revisada, en lugar de hacerlo contra un prompt ad hoc. En teoría, es difícil discutir esto.

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

Ambos bandos tienen razón.

Desarrollo basado en 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 vago 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 dominante en la programación con IA. 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 primera sesión se olvidaron en la tercera. Los supuestos de seguridad se descartaron. 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 basado en especificaciones (SDD) apareció como la respuesta disciplinada. La afirmación central: hacer de la especificación el artefacto central, no del prompt. Escribir primero los requisitos, un diseño y un plan de tareas. Permitir que el agente implemente contra esos artefactos, una porción a la vez. Mantener la especificación versionada y actualizada.

Las herramientas de codificación con IA – GitHub Spec Kit, Kiro, BMAD y un conjunto creciente de flujos de trabajo personalizados de Claude Code – son todas implementaciones de esta idea. Las herramientas son reales. El interés es real. El rechazo 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ás seguro de qué 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. El diseño visual y la sensación de interacción son difíciles de especificar con anticipación. La codificación por ambiente te permite ver opciones rápidamente, descartar la mayoría y converger en algo que realmente se siente correcto. Un documento de requisitos no te ayuda aquí.

Automatización desechable. Scripts de un solo uso, trabajos de extracción de datos, ayudantes 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 necesitas 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 beneficio alguno.

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 se rompe 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 rastro de los invariantes. Sin un documento de diseño, cada prompt tiene que restablecer el contexto que se estableció y olvidó en una sesión anterior.

Desvío arquitectónico. Sin no-objetivos explícitos, los agentes implementan cosas. El agente agrega una capa de caché porque parece razonable. Tres sesiones después, el supuesto de caché está integrado en el modelo de datos y eliminarlo es costoso.

Restricciones olvidadas. “Solo los usuarios autenticados pueden desencadenar esto” es una frase en un documento de requisitos. En una sesión de codificación por ambiente, es algo que mencionaste una vez en la primera sesión y el agente no recuerda en la cuarta cuando escribe el nuevo endpoint.

Supuestos de seguridad ocultos. 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 optimiza para un código funcional plausible en lugar de un código correcto y restringido.

Transición en equipo. Si lo construiste a través de prompts iterativos, el artefacto que registra qué se decidió y por qué es… el registro de git. Buena suerte con eso.

Qué cambia el desarrollo basado en especificaciones

El SDD no pretende eliminar la iteración. Las versiones buenas 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 – ver ¿Qué es el desarrollo basado en especificaciones?

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

Un flujo de trabajo típico de SDD atraviesa cinco fases:

Especificar. Enunciado del problema, usuarios, objetivos, no-objetivos, criterios de aceptación, preguntas abiertas.

Planificar. Decisiones arquitectónicas, módulos afectados, modelo de datos, contratos de API, preocupaciones de seguridad, estrategia de pruebas.

Desglose de tareas. Porciones pequeñas de implementación con criterios de validación explícitos y puntos de control de revisión humana.

Implementar. Una tarea a la vez, con reinicio de contexto entre tareas, aplicando restricciones de la especificación y actualizando el plan cuando la realidad difiere del diseño.

Validar. Pruebas, lint, comprobaciones de tipos, criterios de aceptación, diff de especificación a código.

El agente participa en la mayoría de las fases – redactando la especificación, generando el diseño, proponiendo tareas – 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 cascada

La crítica del modelo en cascada no es incorrecta. Simplemente está dirigida a un mal SDD, no al SDD en sí.

El modo de fallo específico es la planificación prolongada inicial. La característica definitoria del modelo en cascada 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 descubres que el supuesto de diseño era incorrecto, ya has construido sobre él 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 modelo en cascada. Es modelo en cascada 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 versión mala. Ese usuario tenía razón en 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”. Esas son afirmaciones diferentes.

El punto medio útil

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

Especificaciones pequeñas. Un documento de requisitos para una sola característica debe caber en una pantalla. Si la especificación tiene diez páginas, es o bien un diseño de plataforma o necesita dividirse en características 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 del 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. Especifica la primera tarea, implementa, valida, y luego pasa a la siguiente tarea. No especifiques todo antes de implementar nada. La primera implementación revelará cosas que tu especificación tuvo incorrectas. 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 los usuarios autenticados pueden desencadenar esto”, debería 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 modelo en cascada. Es iteración controlada con artefactos duraderos.

Cuando el SDD supera a la codificación por ambiente

Usa el SDD – incluso el SDD ligero – cuando el costo de equivocarse es 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 revisas antes de que el agente escriba código que rompe 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.

Transición en equipo. Si otro desarrollador u otro agente continuará con este trabajo, la especificación es el artefacto de transición. 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 qué debe permanecer igual (comportamiento) y qué está permitido cambiar (estructura). Sin eso, el agente puede romper contratos que pensaste que se conservaban.

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. Escribe el prompt, verifica la salida, y lánzalo.

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

Bocetos de interfaz de usuario. 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 desechable. Scripts de un solo uso, importaciones de datos, ayudantes 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 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?”

Usa la codificación por ambiente cuando:

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

Usa 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
  • Necesitas escribir pruebas que mapeen a los requisitos

Usa el SDD completo cuando:

  • La característica 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 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 aplicar ninguna especificación en absoluto a tareas que necesitan al menos una ligera.

El SDD malo es modelo en cascada con markdown. El SDD bueno 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.