Spec-driven development

El spec-driven development puede no tener la visibilidad de un término como vibe coding, pero aun así es una de las prácticas más importantes que han surgido en 2025. También pone en evidencia cuán rápidamente ha evolucionado la ingeniería de software en los últimos meses, a medida que se ha adaptado a nuevas herramientas de IA y ha encontrado nuevas formas de aprovecharlas.

Sin embargo, como ocurre con cualquier término o práctica nueva, entender exactamente qué es resulta complejo. También surgen dudas sobre cuán efectiva es realmente una técnica en la que todo parece definirse desde el inicio: ¿podemos considerarla verdaderamente ágil? En este blog profundizo en mi visión sobre qué es y cómo se está aplicando.

Definición de spec-driven development y las interpretaciones que compiten entre sí

Mi comprensión del spec-driven development (SDD) es que se trata de un paradigma de desarrollo que utiliza especificaciones de requisitos de software bien elaboradas como prompts, apoyadas por agentes de codificación con IA, para generar código ejecutable.

Cabe destacar que existen distintas opiniones dentro de la industria sobre qué es una especificación y cuál es su rol dentro del SDD. En el extremo más radical, se sostiene que ahora podemos descartar el código y tratar las especificaciones como la única fuente de verdad que requiere mantenimiento. Desde esta perspectiva, el código es un subproducto, un producto intermedio entre los requisitos y los binarios compilados. En contraste, personas tecnólogas con una visión más tradicional, como yo, creemos que las especificaciones son simplemente elementos que impulsan la generación de código, como sucede en el test-driven development. El código ejecutable sigue siendo la fuente de verdad que debe mantenerse.

Parte de este desacuerdo se debe a cómo han evolucionado los enfoques en los últimos dos años desde que la industria comenzó a utilizar IA generativa para producir código. Cuando empezamos a explorar programación más avanzada con ChatGPT, descubrimos que el código generado a partir de especificaciones técnicas definidas previamente, como el stack tecnológico, el estilo arquitectónico y el estilo de codificación, utilizando chain-of-thought y few-shot prompting, tenía una calidad significativamente superior al generado a partir de requisitos en texto plano. Más recientemente, a medida que las herramientas de codificación con IA han mejorado, se ha vuelto más sencillo incorporar también los requisitos funcionales.

Si bien esto tiene beneficios claros, no podemos depender únicamente de los requisitos funcionales. Es necesario prestar atención a los detalles técnicos.

El contexto en el que surge el spec-driven development

Manipular computadoras mediante lenguaje natural que represente el negocio siempre ha sido el santo grial del desarrollo de software y de la teoría de lenguajes de programación. De hecho, los intentos de generación de código basada en especificaciones son anteriores a la era de los LLM, aunque nunca llegaron a consolidarse como desarrollo real.

Las especificaciones se han utilizado de distintas maneras en la ingeniería de software. En la computación distribuida y la comunicación RPC, por ejemplo, funcionan como contratos de comunicación entre sistemas heterogéneos. Esto suele implicar un trabajo transversal tedioso, que incluye validación de tipos de datos entre lenguajes, enrutamiento, interceptores y observabilidad.

En behavior-driven development (BDD), en cambio, las especificaciones se utilizan como un medio para facilitar la colaboración con personas del negocio. Normalmente se escriben como escenarios y ejemplos, y se tratan como documentos vivos del comportamiento del sistema. Esto se apoya en mecanismos de pruebas automatizadas e integración continua.

Independientemente de cómo se utilicen, en última instancia son instrucciones basadas en texto. Dada la capacidad de los LLM para manipular texto, no resulta sorprendente que las especificaciones encajen tan bien con el crecimiento de la IA en la ingeniería de software.

Los primeros asistentes de codificación, como GitHub Copilot, se enfocaban únicamente en generar fragmentos de código. Solo cuando las ventanas de contexto de los modelos fundacionales comenzaron a crecer, se volvió más viable escribir código y construir software directamente a partir de requisitos en lenguaje natural.

Para facilitar esto, los agentes de codificación con IA más recientes suelen separar, de alguna forma, las fases de planificación e implementación del proceso de desarrollo. La fase de planificación se centra en comprender los requisitos, diseñar restricciones y curar mejor los prompts para las etapas posteriores. Este proceso es, en esencia, la creación de la especificación, que constituye la base del spec-driven development.

¿Qué es una especificación?

Una especificación es mucho más que un documento de requisitos de producto (PRD). Incluso aplicar un prompt más estructurado y restricciones técnicas más explícitas puede producir mejor código que un PRD en texto plano.

Desde un punto de vista técnico, una especificación debería definir explícitamente el comportamiento externo del software objetivo, incluyendo aspectos como mapeos de entrada y salida, precondiciones y postcondiciones, invariantes, restricciones, tipos de interfaz, contratos de integración y lógica secuencial o máquinas de estado.

En el pasado, las especificaciones solían escribirse en formatos altamente formalizados y legibles por máquina. Hoy, con la ayuda de los LLM, podemos describirlas usando lenguaje natural. En esencia, una especificación sigue definiendo el comportamiento del software objetivo y no se limita a describir requisitos de negocio.

¿Qué hace que una especificación sea buena?

Nuestras experiencias con behavior-driven development siguen siendo válidas. Esta nueva tecnología no debería cambiar demasiado las cosas en esta área.

Por ejemplo, las especificaciones deberían seguir utilizando lenguaje ubicuo orientado al dominio para describir la intención del negocio, en lugar de implementaciones específicas ligadas a la tecnología. También deberían tener una estructura clara, con un estilo común para definir escenarios usando Given/When/Then, y buscar un equilibrio entre completitud y concisión, cubriendo el camino crítico sin enumerar todos los casos posibles. Esto tiene un beneficio adicional en el desarrollo de software asistido por IA, ya que ayuda a ahorrar tokens.

También es importante que las especificaciones apunten a la claridad y al determinismo. Si bien los LLM no generan código determinista como la generación de código tradicional, la compilación o la ejecución automatizada de pruebas, las especificaciones claras pueden ayudar a reducir las alucinaciones del modelo y producir código más robusto.

Aunque los LLM se destacan principalmente en el manejo del lenguaje natural, no debemos subestimar el rol de las entradas y salidas estructuradas. La experiencia demuestra que proporcionar al modelo prompts de entrada semi estructurados o forzar salidas estructuradas puede mejorar significativamente el rendimiento del razonamiento y reducir alucinaciones. Por ello, las especificaciones legibles por máquina siguen siendo esenciales en la era de los LLM.

Finalmente, en cuanto a la organización de los archivos de especificaciones, muchas personas enfatizan la separación entre especificaciones de requisitos de negocio y especificaciones técnicas. Sin embargo, en la práctica, definir el límite entre ambas suele ser poco claro.

Spec-driven development en la práctica

Los flujos de trabajo de SDD pueden variar significativamente según las herramientas que se utilicen. Herramientas como Amazon Kiro y GitHub Spec-Kit ofrecen flujos de trabajo predefinidos. Si se utiliza una herramienta de codificación con IA más neutral desde el punto de vista metodológico, como Cursor o Claude Code, será necesario encontrar un flujo de trabajo que se adapte a las necesidades del equipo.

El núcleo del SDD va más allá del vibe coding, ya que separa las fases de diseño e implementación. En la fase de planificación, los requisitos se analizan primero utilizando un agente de codificación con IA, que genera planes de diseño e implementación. Normalmente, estas especificaciones de requisitos se formalizan en distintos archivos Markdown (.md). La revisión y validación de estas especificaciones suele ser un proceso iterativo que requiere participación humana.

Una vez finalizadas las especificaciones, se entregan al agente de codificación para generar el código del producto, basándose en los requisitos técnicos, como el estilo arquitectónico y las restricciones, definidos en reglas de Cursor o en AGENTS.md.

Existen distintas opiniones sobre si las especificaciones son solo intermediarios descartables del proceso o la verdad última sobre el comportamiento del software. Estas perspectivas divergentes también conducen a diferentes flujos de trabajo para curar y mantener las especificaciones y generar el código.

Spec-driven development y context engineering

A menudo digo que el prompt engineering optimiza la interacción humano-LLM, mientras que el context engineering optimiza la interacción agente-LLM. Esto se debe a que los agentes de IA suelen requerir más información y ventanas de contexto más amplias para completar tareas, lo que supone un desafío significativo para las capacidades de procesamiento de los LLM.

Dado que las tareas de codificación requieren una gran cantidad de información contextual, es necesario curar cuidadosamente ese contexto. Las herramientas de agentes de codificación, junto con archivo AGENTS.md predefinidos, suelen proporcionar un buen system prompt.

El spec-by-example que usamos habitualmente en BDD es, en esencia, la técnica de few-shot prompt technique. Separar el análisis de requisitos y la planificación de la fase de implementación del código comprime el contexto en especificaciones. Servidores MCP como Context7 también pueden proporcionar información de documentación en tiempo real.

Nuestra herramienta CodeConcise extrae la estructura del código y las dependencias de bases de código heredadas, construye un grafo de conocimiento en bases de datos vectoriales y de grafos, y puede integrarse con servidores MCP como JIRA y Confluence para respaldar la generación posterior de código. Muchas prácticas de context engineering pueden aplicarse en SDD.

¿Es el spec-driven development solo un regreso a waterfall?

He escuchado a algunas personas afirmar que esto representa un regreso a waterfall, y no es una crítica injustificada, pero creo que esta vez es diferente.

El problema del desarrollo waterfall tradicional es la excesiva duración de sus ciclos de feedback. Existe una desconexión entre el diseño y la implementación del software, lo que genera arquitecturas paralelas y una enorme ineficiencia debido a la necesidad de mantener código, documentación y pruebas continuas a medida que cambian los requisitos.

Los problemas que enfrentamos actualmente con la codificación asistida por IA son distintos. Provienen del hecho de que el vibe coding es demasiado rápido, espontáneo y desordenado. Como es tan fácil para la IA generar prototipos demostrables, muchas personas pasan por alto la importancia de las buenas prácticas de ingeniería, lo que da como resultado demasiado código no mantenible, defectuoso y de un solo uso.

Por eso es fundamental incorporar un análisis serio de requisitos, un diseño de software prudente, las restricciones arquitectónicas necesarias y una gobernanza con participación humana. Argumentaría que eso es precisamente lo que el spec-driven development nos ayuda a hacer. No crea ciclos de feedback largos como waterfall, sino que proporciona un mecanismo para ciclos más cortos y efectivos que los que serían posibles con vibe coding puro.

Los desafíos y riesgos del spec-driven development

Como se mencionó anteriormente, no existe un consenso sobre cuál es el flujo de trabajo “correcto” de spec-driven development ni sobre cómo debería verse una buena especificación en el contexto de la codificación asistida por IA. Si bien tengo mi propia visión sobre qué hace que una especificación sea buena, esta se basa en mi experiencia, y todavía no existe una forma sistemática de evaluar especificaciones como ocurre, por ejemplo, con los evals.

La generación de código a partir de especificaciones mediante LLM no es determinista, lo que plantea desafíos en actualizaciones y mantenimiento. La deriva de especificaciones y las alucinaciones son difíciles de evitar, por lo que seguimos necesitando prácticas de CI/CD altamente deterministas para garantizar la calidad del software y proteger nuestras arquitecturas.

Finalmente, la pregunta sobre si la especificación o el código es el artefacto final del desarrollo de software sigue abierta. Ambas posturas conducen a flujos de trabajo y prácticas de desarrollo completamente distintos. Personas programadoras con experiencia pueden encontrar que especificaciones excesivamente formalizadas generan fricción innecesaria y ralentizan los ciclos de cambio y feedback, tal como ocurrió en las primeras etapas del desarrollo waterfall.

El spec-driven development sigue siendo una práctica emergente a medida que 2025 llega a su fin, y es probable que veamos aún más cambios en 2026. Mantenerse al día con el pensamiento de la industria y los experimentos en curso es fundamental. En Thoughtworks continuaremos experimentando y, por supuesto, compartiendo nuestros aprendizajes e ideas con el resto de la comunidad de software.