Hace unas semanas un developer del canal me contó lo que había pasado en su último proyecto.
Seis horas. Eso tardó en planificar un proyecto greenfield con SDD usando slices verticales. Tenía un spec global, features bien definidas, tareas granulares. Parecía perfecto.
Ejecutó el primer slice con su agente IA. La app funcionaba. Autenticación, flujo de datos, navegación — todo correcto.
Y era completamente gris. Sin estilos. Sin diseño. Una interfaz que parecía sacada de 1998.
No había especificado nada sobre la UI en su spec. Ni colores, ni componentes, ni sistema de diseño. El agente hizo exactamente lo que se le pidió: implementar la lógica. Y lo hizo bien.
El problema no era el agente. Era el spec.
El error que nadie te dice sobre SDD en proyectos nuevos
Spec-Driven Development (SDD) es una metodología en la que cada feature comienza con un documento de especificación estructurado — el spec — antes de escribir código. El spec define qué hace la feature, cómo se ve, y qué criterios debe cumplir para considerarse completa.
Cuando descubres SDD, la primera intuición es clara: especifica todo antes de escribir una línea de código. Visión, usuarios, funcionalidades, arquitectura, flujos.
Y esa intuición es correcta… pero incompleta.
Hay dos errores que se cometen casi siempre en un proyecto greenfield con SDD:
El primero es intentar especificar el proyecto completo antes de tocar el teclado. Un spec monolítico de 40 páginas que detalla hasta la última feature antes de que exista una sola línea de código. Es atractivo. Se siente seguro. Y casi siempre es un error.
El segundo es lo que le pasó a ese developer: especificar las features en términos de lógica y flujos, pero olvidar que las features tienen una cara visible. Que los usuarios las ven. Que el diseño no es una capa que se añade al final — es parte de la feature.
Ambos errores llevan al mismo resultado: rediseño tardío, deuda técnica, y la sensación de que SDD no funciona cuando el problema real es la estrategia, no la metodología.
La estructura que sí funciona: spec global ligero + slices con UI
La solución tiene dos capas. Una sesión corta de spec global que define las reglas del juego, y luego un ciclo de feature-por-feature donde cada spec incluye explícitamente la UI.
Capa 1: El spec global ligero
Este documento no especifica features. Especifica el contexto en el que todas las features van a vivir. Se hace una sola vez, en una sola sesión, y no debería tomar más de 45 minutos.
# Spec Global — [Nombre del proyecto]
_Versión: 1.0 | Fecha: YYYY-MM-DD_
## Visión
[Una sola frase que describe qué es el producto y para quién.]
## Stack técnico
- Frontend: Angular 22 con Signals
- Backend: NestJS + Supabase
- Estilos: Tailwind CSS v4
- Testing: Jest + Testing Library
## Sistema de diseño
- Librería de componentes: Angular Material / PrimeNG / custom
- Paleta de colores: primario #1A73E8, fondo #F8FAFC, texto #0F172A
- Tipografía: Inter, base 16px
- Espaciado: escala de 4px (4, 8, 12, 16, 24, 32, 48...)
- Breakpoints: sm 640px / md 768px / lg 1024px / xl 1280px
## Convenciones de arquitectura
- Estructura: feature-based (cada feature es un módulo independiente)
- Estado global: NgRx Signal Store
- Llamadas HTTP: Resource API (Angular 22)
- Validación: Zod en schemas compartidos
## Decisiones técnicas ya tomadas
- Autenticación: Supabase Auth (no reinventar)
- Despliegue: Vercel (frontend) + Railway (backend)
- No usar: Redux clásico, Class Components, módulos NgModule legacy
## Features planificadas (sin detallar)
1. Autenticación
2. Dashboard principal
3. Gestión de proyectos
4. Reportes
Eso es todo. No más. El spec global no detalla cómo funciona cada feature — solo establece las reglas que todas van a respetar.
Lo más importante de ese documento son las secciones de sistema de diseño y convenciones de arquitectura. Son el contrato que el agente va a respetar en cada feature. Si no las defines aquí, las decide él — y probablemente no va a coincidir con lo que tienes en la cabeza.
Capa 2: El spec de cada feature — con sección UI obligatoria
Aquí está el cambio que lo transforma todo. Cuando vas a implementar una feature, escribes su spec detallado en ese momento, no antes. Y ese spec siempre incluye una sección de UI/UX.
# Feature 1: Autenticación
_Contexto: spec global v1.0 | Estado: en implementación_
## Qué hace
Permite al usuario crear cuenta, iniciar sesión y recuperar contraseña.
Usa Supabase Auth. No hay lógica de autenticación propia.
## Flujos principales
1. Registro: email + contraseña → verificación por email → redirect a dashboard
2. Login: email + contraseña → redirect a dashboard (o a la ruta que intentaba visitar)
3. Recuperación: email → link con token → nueva contraseña → login
## UI/UX (obligatorio)
- Layout: columna centrada, max-width 400px, padding 24px
- Componentes a usar: InputField, Button, Alert — todos del sistema de diseño global
- Estados visuales a implementar:
- Loading: botón con spinner, campos desactivados
- Error: Alert rojo con mensaje específico (no "algo salió mal")
- Éxito: redirect inmediato, sin pantalla intermedia
- Mobile first: el form debe funcionar bien en 320px
- No inventar componentes nuevos — usar los del spec global
## Criterios de aceptación
- [ ] El usuario puede registrarse con email válido
- [ ] El usuario recibe email de verificación
- [ ] El usuario puede iniciar sesión y llega al dashboard
- [ ] Los estados de loading y error son visibles
- [ ] El form es usable en móvil
## Lo que NO hace esta feature
- No maneja OAuth (Twitter, Google) — queda para v2
- No maneja roles de usuario — eso es responsabilidad del dashboard
La sección UI/UX no es opcional. Es donde especificas exactamente qué tiene que ver el usuario cuando interactúa con esta feature. Si la omites, el agente tomará esa decisión por ti, y probablemente tomará la decisión más rápida, no la más correcta.
Spec total upfront vs spec incremental — la comparativa real
La tentación de escribir el spec completo del proyecto antes de arrancar tiene sentido desde afuera. La realidad es diferente.
| Spec total upfront | Spec incremental (global ligero + features) | |
|---|---|---|
| Tiempo inicial | 2-3 días o más | 45 min (spec global) — hasta 20× más rápido para arrancar |
| Riesgo | Alto — cambias de opinión cuando ves el código real | Bajo — ajustas cada feature antes de implementarla |
| UI/UX | Probablemente omitida o abstracta | Concreta en cada feature, con contexto real |
| Consistencia | Dependes de que el spec inicial fuera perfecto | El spec global garantiza coherencia entre features |
| Deuda de redesign | Alta — aparece cuando el 80% del código ya existe | Baja — se elimina en cada ciclo de validación visual |
| Útil con agentes IA | Solo si el agente tiene memoria perfecta (no la tiene) | Sí — cada prompt incluye contexto concreto y actualizado |
El spec incremental no significa improvisación. Significa que el contexto que tienes cuando implementas la feature 4 es mejor que el que tenías antes de escribir una sola línea de código. Y ese contexto — los componentes que ya existen, las decisiones que ya se tomaron, los problemas que ya aparecieron — enriquece el spec de la siguiente feature.
Este enfoque es una variación de la Vertical Slice Architecture documentada por Jimmy Bogard, aplicada al contexto de specs con agentes IA.
El rediseño tardío no ocurre porque el spec sea incremental. Ocurre porque no hay spec en absoluto.
El ciclo de trabajo en un proyecto greenfield SDD
El flujo que funciona es simple, y se repite para cada feature:
- Escribe el spec de esa feature (con sección UI incluida)
- Dáselo al agente como contexto completo
- Implementa
- Valida visualmente antes de marcar como hecho
- Usa lo aprendido para enriquecer el spec de la siguiente feature
El paso 4 es crítico y muchos lo saltan. Validar visualmente significa abrir el navegador, probar el flujo como lo haría un usuario real, y confirmar que los estados de loading, error y éxito se ven como los especificaste. No basta con que los tests pasen.
Si en el paso 4 descubres que algo no se ve bien, arréglalo antes de avanzar. El coste de arreglar un componente mal implementado en la feature 1 es mínimo. El coste de arreglar el mismo patrón cuando ya está repetido en las features 1, 3, 5 y 7 es considerable.
Lo que cambia cuando tienes el spec global
El spec global tiene un efecto que no es obvio hasta que lo usas en producción.
Cuando llegas a la feature 4, el agente tiene contexto. Sabe que los inputs van con Tailwind, que el estado global es NgRx Signal Store, que los errores se muestran con el componente Alert del sistema de diseño. Si estás usando Angular 22, también puedes aprovechar la Resource API para centralizar las llamadas HTTP en el spec desde el principio — sin que el agente invente su propio patrón. No lo tienes que repetir en cada prompt.
Y cuando llega alguien nuevo al proyecto — o cuando tú mismo vuelves al código tres meses después — entiende en 10 minutos las decisiones que se tomaron y por qué.
Eso no lo da el código. Lo da el spec.
Si quieres profundizar en la metodología completa, en el libro de Spec-Driven Development tienes el framework completo: cómo estructurar specs, cómo trabajar con agentes IA de forma efectiva, y los patrones que se usan en proyectos reales de producción.
La UI no es una capa. Es un contrato.
El error del developer que me escribió no fue usar SDD. Fue asumir que SDD significa especificar todo el proyecto antes de arrancar.
SDD significa especificar lo suficiente, en el momento correcto, con el nivel de detalle correcto. El spec global define el campo de juego. El spec de cada feature define las reglas de ese momento.
Y la UI no es una capa que se añade al final. Es parte del contrato de cada feature.
Si quieres ver este flujo en acción — desde el spec hasta el commit — en el curso Construye con IA: De la Idea al Producto aplicamos exactamente esta metodología: spec global, slices verticales, validación visual antes de avanzar. Con agentes IA reales, en proyectos que no son de juguete.
Y si prefieres el formato comunidad, en Dominicode Labs compartimos los specs reales de los proyectos que construimos juntos — con las decisiones que se tomaron y las que se descartaron.
El spec no te quita velocidad. Te quita el coste de arreglar lo que nadie especificó.
FAQ
¿Cuánto tiempo debería tardar el spec global de un proyecto real?
Entre 30 y 60 minutos. Si tardas más, estás especificando features en el spec global, y eso no es su función. El spec global define el contexto y las reglas. Las features se detallan una a una cuando llega su turno.
¿Es obligatoria la sección UI/UX en el spec de cada feature?
En proyectos con interfaz visible, sí. Si estás construyendo una API sin frontend, la sección UI/UX no aplica, pero deberías incluir una sección de contratos de API: endpoints, tipos de respuesta, códigos de error. El principio es el mismo: especifica todo lo que el agente necesita para no tomar decisiones que tú deberías tomar.
¿Cómo manejo las features que dependen de otras que aún no están implementadas?
En el spec de la feature con dependencia, añades una sección “Asunciones” que documenta qué esperas de las features previas. Si la feature A aún no existe, especificas el contrato que A debería cumplir — y cuando implementes A, ese contrato ya está documentado. Es una forma de diseño by contract que funciona muy bien con agentes.
Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
