Spec-Driven Development
Antes de construir con IA, producir claridad.
Una forma de trabajar con agentes de programación sin depender de una conversación infinita.
El problema no es que la IA no pueda escribir código.
El problema aparece cuando le pedimos que construya sin estructura previa.
“La velocidad sin claridad se vuelve frágil.”
Vibe coding: pedir, probar, corregir, insistir.
Puede servir para explorar ideas pequeñas, pero se vuelve inestable cuando el proyecto crece.
Decisiones enterradas
Las ideas y el diseño quedan perdidos en el scroll infinito del chat.
Instrucciones contradictorias
Al no tener una base firme, el modelo olvida lo que ya hizo y se contradice.
Resultados difíciles de revisar
Sin especificación, solo podemos juzgar si "parece que funciona".
Pérdida del hilo
El proyecto entra en un espiral de parches y correcciones ciegas.
El contexto es la memoria de trabajo de la IA.
Cada vez que hablamos con un agente, trabaja con una ventana limitada que incluye instrucciones, archivos y la conversación previa.
Cuando el contexto se llena, el modelo se degrada.
La IA empieza a olvidar instrucciones iniciales, repite errores previos, confunde archivos o inventa decisiones para llenar los vacíos.
“No necesariamente el modelo se volvió peor. Le estamos pasando demasiado ruido.”
No necesitamos un chat más largo.
Necesitamos una memoria externa.
Spec-Driven Development convierte la intención del proyecto en documentos estructurados, legibles y ejecutables fuera del chat.
Spec-Driven Development
Una práctica donde antes de escribir una sola línea de código, se definen especificaciones claras.
“Primero entendemos qué construir. Después construimos.”
Cuatro documentos para ordenar el trabajo
La memoria externa se organiza en cuatro capas de abstracción decreciente:
proposal.md
La intención y el alcance estratégico del proyecto.
Ver más →functional_spec.md
La experiencia del usuario, flujos, pantallas y comportamientos.
Ver más →technical_spec.md
La arquitectura, tecnologías, archivos y restricciones del sistema.
Ver más →tasks.md
El plan paso a paso, dividido en tareas pequeñas y verificables.
Ver más →1. Proposal
Define la intención inicial, el problema, la audiencia a la que va dirigida la solución y los límites del proyecto.
# Proposal - Galería Generativa
## Propósito
Crear una web minimalista para presentar una obra interactiva de arte generativo.
## Audiencia
Visitantes de la exposición y coleccionistas digitales.
## Alcance
Una sola página local con:
- Portada de impacto
- Galería de capturas
- Texto sobre el proceso de creación
- Acceso interactivo a la obra2. Functional Spec
Describe pantallas, comportamientos ante interacciones, estados (cargando, error, vacío) y los recorridos visuales del usuario.
Clave: No decide todavía la tecnología (si es React, Vanilla o WebGL). Se enfoca en qué tiene que pasar, no en el cómo.
3. Technical Spec
Define la arquitectura de archivos, las librerías a importar, el esquema de datos, las variables globales y las restricciones técnicas del entorno.
Clave: Debe responder exactamente al alcance funcional. No añade complejidad técnica innecesaria ni sobreingeniería.
4. Tasks
Divide el desarrollo en una lista de tareas pequeñas, secuenciales y ordenadas. Cada tarea es un bloque atómico de trabajo.
Clave: Cada tarea debe terminar con un criterio de aceptación claro que el programador (o la IA) pueda probar inmediatamente.
Cada documento construye al siguiente
Al segmentar el conocimiento, el agente puede concentrarse en una sola tarea a la vez, reduciendo drásticamente la carga de contexto y evitando confusiones.
Una task por vez.
No intentes implementar todo de un solo golpe. La ambición confunde al modelo.
Trabajar de manera incremental permite comprobar que los cimientos del proyecto sean sólidos antes de seguir agregando lógica.
Implementá únicamente la Task 1.
Usá como fuente de verdad functional_spec.md y technical_spec.md.
No avances a la Task 2.
Al terminar, explicá cómo verificar el resultado.Revisar contra la spec, no contra la intención.
La revisión no debe basarse en un vago "se ve bien". Debe responder a preguntas de control específicas basadas en las especificaciones escritas.
Fresh Context
Un revisor independiente (humano u otro agente en un chat nuevo) evalúa mejor el resultado porque no arrastra el "ruido" de la sesión de codificación.
“El reviewer mira el resultado final, no las excusas o desvíos ocurridos durante el proceso.”
Un solo agente no escala para siempre.
Cuando un proyecto crece, un único hilo de chat intentando explorar, documentar, planificar, codificar y testear al mismo tiempo colapsa rápidamente por saturación de contexto.
Aquí es donde la orquestación multiagente se vuelve indispensable.
Roles especializados de agentes
En lugar de pedirle a un solo agente que haga todo, dividimos las responsabilidades en roles bien definidos y aislados.
Inspecciona el repositorio para entender la estructura actual.
Redacta y actualiza las especificaciones escritas (specs).
Divide los requerimientos técnicos en un plan de tareas detallado.
Implementa el código estrictamente delimitado a una tarea.
Evalúa de forma independiente en un contexto limpio.
El programador humano no desaparece.
Cambia de rol.
Dejamos de ser escribas manuales de sintaxis de código para convertirnos en directores de arquitectura y validadores de intenciones.
- Formular el problema de fondo: Qué queremos resolver.
- Validar y refinar las especificaciones: Aprobar qué y cómo se construirá.
- Decidir prioridades estratégicas: Determinar los siguientes pasos.
- Revisar y verificar los resultados: Probar la experiencia directamente.
- Cuidar la dirección estética y conceptual: Mantener el alma del proyecto.
Paper Zero como puerta de entrada a SDD.
Paper Zero es una herramienta diseñada para ayudar a artistas y creadores a estructurar ideas sin forzarlos a codificar.
“El formulario no produce código directamente. Produce la claridad de contexto necesaria para trabajar con un agente.”
Flujo integrado: De Paper Zero a SDD
El archivo Context.md generado en Paper Zero actúa como la chispa inicial que alimenta el desglose de documentos estructurados para el agente.
Ejercicio de Clase
Pasa de la teoría a la práctica.
Consigna:
Elige una idea web minimalista. Abre una nueva sesión con tu asistente de IA y ordénale que no escriba nada de código todavía. Haz que desglose las especificaciones usando este prompt base:
Actuá como asistente de Spec-Driven Development.
No escribas código todavía.
Convertí esta idea en:
1. proposal.md
2. functional_spec.md
3. technical_spec.md
4. tasks.md
Idea: [Escribe aquí tu idea web simple]¿Cuándo conviene aplicar SDD?
No todo desarrollo requiere el rigor completo de SDD. Elige tu herramienta según la complejidad:
👉 Prompt directo e interactivo
Ej: "Alineá este texto al centro", "Agregá un toggle de tema oscuro".👉 SDD Completo (Proposal + Specs + Tasks)
Ej: "Un reproductor de audio interactivo con playlist y presets".👉 SDD + Exploración previa
Ej: "Agregar un módulo de estadísticas al dashboard de administración actual".👉 SDD + Revisión en Fresh Context
Ej: "Reestructurar el almacenamiento de la base de datos local".Antes de construir, formular.
Spec-Driven Development no ralentiza la creación. Evita el desperdicio de construir rápidamente en la dirección incorrecta.
“La IA puede producir código. Nuestra tarea humana es producir claridad.”