Hay una diferencia enorme entre pedirle algo a la IA y dirigirla.
La mayoría de devs que trabajan con Claude Code, Cursor o cualquier agente de turno están haciendo lo primero: “Hazme un endpoint de login”, “Crea un componente de tabla con paginación”, “Añade validación al formulario”. Prompt por prompt, función por función. Y luego se preguntan por qué el código generado no encaja, por qué hay que refactorizar tanto, por qué la IA “no entiende el proyecto”.
El problema no es la IA. El problema es el flujo.
El fallo del Prompt Driven Development
Cuando le pides a la IA una cosa técnica directamente, le estás pidiendo que adivine la lógica. Le das una instrucción de implementación sin contexto de comportamiento. La IA es muy buena generando código que parece correcto. El problema es que está optimizada para ser verosímil, no para ser fiel a tu intención.
El resultado: código que compila, tests que pasan, y una funcionalidad que no hace lo que querías.
Spec Driven Development resuelve esto desde la raíz.
Qué es Spec Driven Development
SDD es un flujo de trabajo en el que tú no empiezas por funciones, endpoints ni tablas. Empiezas por reglas, flujos y resultados esperados.
La idea es simple: antes de que la IA escriba una sola línea de código, tiene que entender qué tiene que construir, cómo se tiene que comportar, para qué existe, cuándo hacerlo y dónde dejar cada cosa.
Es la diferencia entre decirle a un contratista “ponme una puerta aquí” versus darle los planos del edificio y decirle “la entrada principal tiene que cumplir estas condiciones de accesibilidad, seguridad y flujo de usuarios”. El resultado final puede parecer similar a primera vista, pero uno tiene criterio y el otro está improvisando.
Cómo se construye una spec
La estructura básica
Una especificación SDD parte de una historia de usuario y la expande con condiciones concretas. No es documentación técnica al uso, es una descripción del comportamiento que esperas.
Ejemplo real de una spec de login:
Como usuario quiero poder iniciar sesión dentro del sistema
para acceder a contenido personalizado
- Inicio sesión con correo y contraseña
- El usuario existe en la base de datos
- El usuario está activo
- El formulario valida formato de correo
- La contraseña debe tener más de 8 caracteres
- El formulario tiene 2 campos y 2 botones (enviar y limpiar)
- Existe un link "Olvidé mi contraseña" — no se implementa en este cicloLuego añades los caminos de ejecución:
Happy path: el usuario introduce credenciales válidas, presiona enviar, el botón se deshabilita y muestra “enviando…”, y aterriza en el home.
Sad path: credenciales inválidas, mismo flujo visual, aparece un texto en rojo debajo del formulario con “credenciales inválidas”, el botón se reactiva.
Esto último es BDD (Behaviour Driven Development) integrado en la spec. No es teoría de libro — es la diferencia entre una IA que genera un formulario genérico y una que genera tu formulario.
El flujo con agente: dejar que la IA llene los huecos
La forma más efectiva que he encontrado para crear specs no es escribirlas de cero. Es darle a la IA la historia de usuario y pedirle que asuma, para luego corregirla. El prompt que uso:
Vamos a definir una spec. Yo te daré una historia de usuario y tú
tendrás que rellenar los espacios en blanco. Todas las cosas que
asumiste, no técnicas o funcionales, me las mostrarás en un listado.
Luego yo te diré los números de las asunciones que no me gustaron y
me harás preguntas una a una. En cada pregunta nueva me mostrarás
una barra de progreso con la cantidad de preguntas que llevo y las
que faltan. Además me mostrarás 4 opciones de asunción y una quinta
que dirá "otra". Al finalizar me dirás que ya estás listo para crear
la especificación.El resultado es un proceso iterativo donde tú validas la intención y la IA construye la especificación. No al revés.
Cuando el resultado te convence, un Agrega BDD a la especificación cierra el ciclo, y luego Crea la spec en /specs/login.md la persiste en el repositorio.
Por qué funciona: el repositorio como sistema
Hay un principio de Harness Engineering que está detrás de todo esto y que merece su propio artículo: el repositorio es el sistema.
La IA no tiene memoria entre sesiones. Su ventana de contexto se degrada a partir del 20-40% de capacidad. Si trabajas sin estructura, cada sesión con el agente empieza desde cero y termina con resultados inconsistentes.
Las specs en /specs/ no son solo documentación. Son el arnés que rodea al modelo: el contexto persistente que le dice qué existe, cómo se comporta y qué ya está implementado. El modelo puede cambiar (y cambiará, cada pocos meses hay uno mejor), pero el sistema —tus specs, tus reglas, tu lógica de negocio— sobrevive al swap.
Es como tener una empresa donde los empleados rotan pero los procesos están escritos. No dependes del conocimiento tácito de nadie.
Lo que SDD no es
SDD no es escribir documentación extensa antes de codificar. No es waterfall con pasos extra. No es un proceso burocrático que ralentiza el desarrollo.
Es precisamente lo contrario: es la forma de ir más rápido porque la IA ejecuta con menos ambigüedad. Cada ciclo de corrección que te ahorras en código generado mal son horas recuperadas.
También hay algo que me parece importante señalar: SDD no elimina tu criterio técnico, lo centraliza. Tú sigues siendo el que decide el comportamiento. La IA implementa. Eso es exactamente la división de trabajo correcta con las herramientas actuales.
Para quién tiene sentido
Si trabajas solo en proyectos con algo de complejidad de negocio, SDD cambia completamente la calidad del output que obtienes de cualquier agente. No necesitas escribir specs perfectas desde el día uno, necesitas el hábito de especificar comportamiento antes de pedir código.
Si estás en equipo, las specs se convierten en contrato compartido. Menos “yo entendí que…” y más “aquí está lo que acordamos”.
Si eres indie hacker o construyes productos propios, las specs son la memoria externa de tu producto. En seis meses, cuando vuelvas a un módulo, sabrás exactamente qué hace y por qué.
El siguiente nivel: agentes especializados en specs
El flujo que describí antes se puede convertir en un agente reutilizable. Creas un agente en Claude Code con la skill de generación de specs, le das permisos de lectura, bash y websearch, y lo configuras para funcionar como agente y como subagente (así puede ser invocado por otros agentes del sistema).
El resultado: cualquier historia de usuario que entres al sistema pasa por el mismo proceso de refinamiento antes de que se genere una sola línea de código.
Eso ya no es “usar IA para programar”. Eso es tener un sistema de desarrollo que usa IA.
Conclusión
La IA no va a entender tu proyecto si no le das contexto estructurado. Prompt Driven Development es eficiente a corto plazo y costoso a medida que el proyecto crece. Spec Driven Development invierte ese ciclo: un poco más de trabajo al inicio, mucho menos ruido durante la implementación.
El cambio de mentalidad es simple: deja de pedirle código a la IA y empieza a darle intención.
Todo lo demás se construye sobre eso.
Si te interesa el tema de harness engineering y cómo construir sistemas de desarrollo con agentes, tengo más en pipeline. Sígueme en LinkedIn o vuelve por aquí.