Contexto
Este artículo es la continuación de De un script monolítico a una arquitectura de software, donde conté cómo transformé un script monolítico en un proyecto con arquitectura hexagonal, TDD y Extreme Programming — todo asistido por IA. Si no lo has leído, empieza por ahí.
Aquel proyecto era una web de personajes de Monster High para que mi hija practique a leer. Sigue siéndolo. Solo que ahora, en lugar de marcar favoritos, puede crear grupos de amigas y asignar personajes a cada grupo. Una evolución pequeña para ella, un refactor completo para mí.
Lo que cambió no fue qué construí, sino cómo lo planifiqué.
Lo que funcionó (pero no escaló)
En el primer ciclo de desarrollo escribí una especificación técnica completa antes de empezar: stack, requisitos funcionales, decisiones de diseño, estructura de carpetas, tema visual. Todo en un solo archivo de más de 500 líneas. Junto a él, un tablero de progreso manual y un registro de consultas técnicas. Así se veía el proyecto en ese momento.
Funcionó. El agente tenía contexto, seguía las reglas, y el resultado fue bueno. Pero esos documentos eran una foto fija del inicio del proyecto. A medida que el desarrollo avanzaba y tomaba decisiones que se alejaban del plan original, las specs dejaron de reflejar la realidad. Nadie las actualizó — no había un mecanismo para hacerlo — y lo que empezó como una guía se convirtió en ruido. Llegó un punto en que tuve que eliminarlas del proyecto porque generaban más confusión que valor.
El problema no era de método. El TDD seguía funcionando, las reglas estaban claras. El problema era que las especificaciones eran artefactos estáticos en un proceso que no paraba de moverse. Y cuando llegó el momento de hacer un cambio grande no tenía un sistema para planificarlo, solo la experiencia del desarrollo inicial del frontend en el proyecto.
La primera vez que quise retomar el proyecto para añadir una nueva funcionalidad — evolucionar el sistema de favoritos a grupos de amigas — me di cuenta de que no podía reproducir el proceso que me había llevado a aquellas specs originales. Las había construido de forma artesanal, iterando con la IA hasta dar con algo que me pudiera servir como apoyo para guiar el desarrollo y hacer seguimiento, pero sin registrar cómo. No recordaba los prompts, las decisiones intermedias, ni los descartados. Funcionó una vez, pero no era un proceso, era un resultado irrepetible.
Spec-Driven Development
La respuesta fue Spec-Driven Development: usar especificaciones estructuradas como el artefacto central del proceso de desarrollo.
La idea no es nueva. Los equipos de software llevan décadas escribiendo specs. Lo que cambia cuando trabajas con IA es que las specs dejan de ser documentación para humanos y se convierten en la interfaz entre tú y el agente. Son el contrato. Lo que está en la spec se ejecuta; lo que no está, no existe.
En la práctica, esto significó reemplazar mi archivo de specs monolítico por un framework que estructura cada cambio en tres artefactos:
- Proposal — el porqué. Qué problema resuelve, qué cambia, qué no cambia.
- Design — el cómo. Decisiones técnicas, alternativas descartadas, riesgos.
- Tasks — el qué. Tareas concretas, ordenadas, con referencia a las reglas que aplican.
Cada cambio vive en su propio directorio. Cada artefacto se construye sobre el anterior. El agente lee solo lo que necesita para la sesión actual, no 500 líneas de contexto acumulado.
Yo usé OpenSpec para esto, pero el concepto es lo que importa. Hay otros frameworks que aplican la misma idea. Lo relevante es que el proceso de especificación deje de ser un paso previo que se hace una vez y se olvida, y pase a ser el eje sobre el que gira todo el desarrollo.
Primero diagnosticar, después planificar
Antes de escribir una sola spec, hice algo que resultó ser clave: una sesión de exploración.
Tenía definidos los patrones de arquitectura que quería aplicar: reglas concretas sobre dónde vive cada tipo de archivo, cómo se conectan las capas, qué puede importar qué. Estas reglas venían de una skill del programa de mentoría de Software Crafters al que estoy inscrito, que es lo que me ha guiado en estas prácticas deliberadas.
Le pedí al agente que comparara el código actual con esas reglas. El resultado fue un diagnóstico: qué cumplía, qué violaba, qué faltaba. No escribió una línea de código. Solo mapeó la distancia entre lo que tenía y lo que debería tener.
De ese diagnóstico salió el plan. No al revés.
Esto es lo que hace potente al SDD más allá de la planificación pura: las specs no solo definen lo que vas a construir, también definen el estado objetivo contra el que puedes auditar lo que ya tienes.
Dividir para no saturar
Trabajar con un agente de IA tiene una limitación que no existe en el pair programming entre personas: la ventana de contexto. Es la cantidad de información que el modelo puede manejar en una conversación. Cuando se satura, el agente empieza a cometer errores — referencias a archivos que ya moviste, imports de código que ya no existe, soluciones que contradicen decisiones anteriores. Es lo que se llama alucinación. No es un bug. Es una restricción técnica que hay que diseñar alrededor.
El diagnóstico previo reveló que la migración era demasiado grande para una sola sesión. Así que la dividí en cinco cambios independientes, cada uno con su propio ciclo de proposal → design → tasks.
La clave fue diseñar las dependencias entre cambios de forma que cada uno pudiera ejecutarse en una sesión limpia — sin arrastrar contexto de sesiones anteriores. Cada sesión arrancaba leyendo únicamente los artefactos de su cambio. Nada más.
¿El resultado? Cinco sesiones limpias. Sin alucinaciones. Sin pérdida de contexto. Cada una terminaba con los tests pasando, un commit, y la certeza de que la siguiente sesión podía empezar desde cero.
Lo que me llevé
En el primer post cerré con: "método + planificación explícita + IA, en ese orden."
Ahora añadiría un matiz: la planificación explícita no es solo tener un plan. Es tener un sistema para crear, estructurar y ejecutar planes. Ese sistema es lo que aporta el Spec-Driven Development.
Mi hija ahora puede organizar sus personajes de Monster High en grupos de amigas que ella misma crea y administra. Yo confirmé que cuando el marco metodológico se queda corto, la respuesta no es más instrucciones — es mejor estructura.
La combinación que funciona: método + especificaciones estructuradas + gestión de la ventana de contexto + IA. En ese orden.
Explora el código
El proceso completo está documentado en el repositorio. Puedes comparar el estado del proyecto antes y después de adoptar SDD.
Ver Repositorio en GitHub →