Spec-Driven Development: El fin del Vibe Coding amateur y el inicio de la ingeniería de sistemas para UX

El concepto de [[Vibe Coding]] es atractivo. Escribes en lenguaje natural, la IA escupe código, y en minutos tienes un prototipo. Funciona perfecto si estás haciendo un script de 100 líneas. Si intentas escalar eso a un producto real, el sistema colapsa.

Me reuní con Ryan Edge para desglosar exactamente cómo está utilizando agentes de [[IA]] para construir software complejo. El consenso es claro: depender de interfaces de chat para programar tiene un techo de cristal. Pierdes el contexto, la IA alucina, sobrescribe lógica existente y terminas haciendo trabajo manual para corregir a un robot.

La solución no es pedirle menos a la IA. La solución es darle un contrato determinista. Esto es [[Spec-Driven Development]] (SDD).

Este post es la documentación exhaustiva de cómo migrar de ser un “vibe coder” casual a operar como un arquitecto de sistemas. Si eres un diseñador UX, estás en una posición de ventaja injusta: ya piensas en estados, flujos y reglas. Solo necesitas cambiar tu medio de Figma a Markdown.

1. La trampa del Chat y la ilusión de la memoria en los LLMs

[!warning] El problema de la interfaz gráfica “El chat no es una buena interfaz para estar en estado de flujo. Destruye la productividad”.

La mayoría de la gente interactúa con la IA a través de ventanas web (ChatGPT, Claude). Esto es ineficiente por tres motivos técnicos:

  1. La ventana de contexto se satura: Los Modelos de Lenguaje Grande (LLMs) no tienen memoria persistente. Tienen un límite de tokens. Cuando pasas días iterando sobre un proyecto en una misma ventana de chat, el modelo comienza a “olvidar” las instrucciones iniciales. El resultado es que la IA rompe funcionalidades que ya funcionaban.
  2. Ciclos de retroalimentación en llamas (“Going into flames”): Cuando un LLM pierde el contexto y genera código erróneo, a menudo intenta arreglarlo parcheando sobre el error. Esto crea un ciclo destructivo donde los datos van del cliente al servidor, rebotan en validaciones erróneas y la aplicación se rompe en tiempo real.
  3. Fricción de copiar y pegar: Mover código del navegador a tu editor rompe tu estado de flujo. El desarrollo asistido por IA debe ocurrir donde vive el código.

El chat te obliga a ser reactivo. Necesitamos un sistema proactivo.

spec driven design diagram

2. ¿Qué es el Spec-Driven Development (SDD)?

El SDD es la antítesis de la improvisación. Es un marco de trabajo donde el comportamiento del software se define exhaustivamente en un documento antes de escribir una sola línea de código.

En la era pre-IA, el SDD era útil pero tedioso. Hoy, en la era de la IA generativa, el SDD es el sistema operativo del desarrollo.

En lugar de decirle a la IA: “Añade un modo oscuro a la aplicación”. Le dices a la IA: “Lee el archivo specs/dark-mode.md. Analiza la máquina de estados, respeta las reglas de la arquitectura, revisa el checklist de tareas, y ejecuta el plan.”

El “Spec” como memoria externa

Un Spec (Especificación) actúa como un documento de requerimientos que vive directamente en tu repositorio de código. Funciona como la memoria a largo plazo de la IA.

[!info] Mecánica de la Memoria SDD Si apagas tu computadora un viernes y vuelves el lunes, un agente basado en chat no sabe en qué te quedaste. Un agente operando bajo SDD lee el Spec, revisa qué tareas del checklist están marcadas con una [x], y retoma la ejecución exactamente donde la dejó. El Spec es una base de datos de progreso.

3. La ventaja del UX Designer

Si eres diseñador, la programación tradicional te parece críptica porque se centra en la sintaxis. Pero el SDD no requiere que sepas escribir sintaxis. Requiere que sepas estructurar sistemas lógicos.

Figma ya te enseñó a hacer esto. Cada vez que construyes un prototipo complejo o un Design System, estás haciendo ingeniería de sistemas visuales.

La traducción directa para entender el SDD desde UX:

  • Figma Variants -> Máquina de Estados: Cuando diseñas un botón en estado Default, Hover, Active, y Disabled, estás definiendo un modelo de estado explícito. En SDD, obligas a la IA a declarar estos estados antes de que intente pintar la UI.
  • Figma Auto-Layout -> Reglas de Renderizado: En UX defines restricciones lógicas (espaciado dinámico, padding). En SDD, traduces esto a requerimientos de comportamiento responsivo.
  • Figma Prototyping -> Event Bus / Routing: Cuando conectas una pantalla con otra mediante una flecha que dice “On Click -> Navigate To”, estás definiendo el flujo de datos.
  • Design Tokens -> Variables Globales: Entiendes que un color primario no se escribe a mano ("#FF0000") cada vez. Se referencia como una variable. En SDD, ordenas a la IA que construya utilizando una arquitectura centralizada de tokens.

[!quote] “Cada diseño de Figma está contando una historia de inputs, outputs, declaraciones if/else, y lógica condicional. Podemos mapear eso en pseudo-código, es un lenguaje que todos en el negocio pueden entender.”

El desarrollador junior entra en pánico cuando el código no compila. El diseñador UX operando con SDD no se preocupa por el error de compilación; revisa el Spec para ver si la instrucción lógica era ambigua. Controlas la lógica, la IA controla la sintaxis.

4. La Arquitectura de un Spec: El método de 3 Capas

Un sistema no usa un solo debe usar un documento caótico. Usa una arquitectura de archivos separada por propósito. En tu repositorio (o documentado aquí en tu [[Obsidian]]), el SDD se divide en tres documentos críticos que tú controlas.

Documento 1: La Propuesta

proposal.md Este es el contexto de alto nivel. Si el agente de IA no sabe por qué está construyendo algo, tomará decisiones arquitectónicas equivocadas.

Componentes clave de una propuesta:

  1. El Problema: (Ej. “El sistema actual mezcla lógica de estado heredada con nuevos patrones, creando deuda técnica”).
  2. El Objetivo: (Ej. “Migrar todas las pantallas del flujo de configuración a la nueva arquitectura unificada”).
  3. Scope (Alcance): Qué está dentro del trabajo y qué está estrictamente prohibido tocar.

Documento 2: El Diseño del Sistema

design.md Este es el núcleo de tu trabajo como UX. Aquí defines las reglas.

[!important] Regla de Oro del SDD NUNCA incluyas código de implementación real en tu Spec. Si pones código real (ej. function toggleTheme() {...}), tu Spec quedará obsoleto en el momento en que un humano o un agente actualice la base de código.

En lugar de código, utilizas Pseudo-código y BDD (Behavior-Driven Development).

Ejemplo de BDD (Formato Given-When-Then):

## Escenario: Generación de clase de estado
* **GIVEN** (Dado que) una clase de estado está definida en el sistema.
* **WHEN** (Cuando) el código se compila.
* **THEN** (Entonces) los métodos copyWith, equals y toString se generan automáticamente.

Esta estructura le dice a la IA exactamente cómo debe comportarse el componente sin dictar qué librería o sintaxis específica usar.

Documento 3: El Checklist de Tareas

tasks.md El agente no lee el documento de diseño y escribe todo de golpe. Eso excede sus capacidades cognitivas. El agente traduce el diseño a una lista granular de tareas secuenciales.

Ejemplo de desglose de tareas:

## Fase 1: Setup
- [x] Definir constantes de estado.
- [ ] Configurar inyección de dependencias.

## Fase 2: Vistas (Views)
- [ ] Migrar el componente Header a una función pura.
- [ ] Extraer la lógica de negocio a un controlador independiente.

Este archivo es tu panel de control. Mientras la IA ejecuta, tú ves cómo las casillas se van marcando solas en tiempo real.

5. Herramientas de Ejecución: Orquestación desde la Terminal

Abandona las interfaces web. El desarrollo profesional asistido por IA sucede en la línea de comandos (CLI). Ryan y yo discutimos dos herramientas fundamentales para este proceso:

A. Conductor (El Orquestador)

Conductor es una herramienta Gemini CLI diseñada específicamente para el paradigma SDD. No es un chat. Es un motor de ejecución.

Comandos básicos de Conductor:

  1. conductor setup: Configura tu proyecto y entiende la arquitectura base.
  2. conductor new track: Este comando lee tus archivos de propuesta y diseño, y genera el plan de ejecución (tasks.md). Todos tienen la duda de “¿Cómo creo un Spec?”. Con este comando, le pasas tus notas y la IA crea la estructura técnica.
  3. conductor implement: El botón de arranque. El agente lee el tasks.md, elige la primera tarea incompleta, analiza tu base de código actual, implementa la solución, y marca la tarea con una [x].

B. OpenCode (La Interfaz Agente)

OpenCode vive en tu editor. Te permite traer contexto profundo de tu código a la IA. La característica principal de OpenCode es la flexibilidad de modelos.

No necesitas estar atado al ecosistema cerrado de OpenAI. Puedes invocar diferentes motores según la tarea presionando un comando.

6. Economía de LLMs: Token Routing para eficiencia

Usar el modelo más potente del mundo para hacer tareas repetitivas es quemar dinero. Ryan mencionó cómo el costo de una mala gestión de tokens destruye el ROI de usar IA.

[!danger] La penalización de contexto largo Modelos como Claude Opus duplican su precio por token una vez que superas los 200,000 tokens en la ventana de contexto. Si le pasas toda tu aplicación a Opus para que simplemente cambie un texto de error, estás pagando un impuesto masivo por ineficiencia.

La solución: El enrutamiento de modelos (Model Routing) vía OpenRouter. OpenRouter es una API que agrupa docenas de modelos. La estrategia correcta es asignar modelos basándote en la complejidad cognitiva de la fase del SDD:

  1. Fase de Arquitectura (La Mente): Para leer la Propuesta, generar el Diseño, y estructurar las Tareas.
    • Modelos: Claude Opus, GPT 5.2.
    • Por qué: Son lentos y costosos, pero su capacidad de razonamiento espacial y arquitectónico es superior. Ellos arman el plano.
  2. Fase de Implementación (El Músculo): Para ejecutar las tareas mecánicas de la lista, escribir el boilerplate y actualizar el UI.
    • Modelos: Claude Sonnet, Claude Haiku, Gemini Flash, o modelos chinos como Kimi (Kimi cuesta una fracción minúscula en comparación y tiene una ventana de contexto enorme).
    • Por qué: Solo necesitan seguir instrucciones claras paso a paso. Son baratos, ridículamente rápidos, y gracias al SDD, no necesitan “pensar” en la arquitectura profunda, solo implementar el contrato.

7. El Workflow de Equipo: Source of Truth

¿Cómo se ve esto en un equipo real donde colaboran diseñadores y desarrolladores?

  1. El PR del Spec: En lugar de empezar a programar (o pedirle a la IA que programe), el diseñador UX / Product Manager crea el archivo design.md documentando el flujo de datos y las reglas condicionales.
  2. Revisión (Code Review del Spec): Envías este archivo de Markdown como un Pull Request (PR) al repositorio. El equipo de ingeniería lo lee. Discuten casos límite. “Oye, en este estado, ¿qué pasa si el servidor devuelve un 404?”. Se corrige el Spec, no el código.
  3. Aprobación y Merge: Una vez que todo el equipo está de acuerdo, el PR se aprueba. Este Spec se convierte en la única fuente de la verdad (Source of Truth).
  4. Ejecución Descentralizada: Una vez fusionado, cualquier persona en el equipo —desde un arquitecto senior hasta un desarrollador junior o tú mismo como diseñador— puede abrir la terminal, escribir conductor implement, y dejar que su agente de IA lea el contrato y construya la aplicación.

No hay fricción. No hay interpretaciones ambiguas de tu diseño de Figma. El comportamiento está bloqueado por el Spec.

8. Cuándo usar SDD vs Cuándo usar Chat (Triage de Problemas)

El SDD es un sistema pesado. No lo usas para todo. Tienes que saber cuándo activar la burocracia y cuándo aplicar Vibe Coding rápido.

Escenarios para Vibe Coding (Chat / Inline Prompt):

  • “Cambia el color de este botón de azul a verde oscuro.”
  • “Añade un padding de 16px a este contenedor de texto.”
  • “Arregla este error de typo en el componente de alerta.”
  • Regla: Cambios aislados, puramente visuales, sin ramificaciones lógicas.

Escenarios para Spec-Driven Development:

  • “Migrar el sistema de autenticación de Supabase a Firebase.”
  • “Implementar un flujo completo de onboarding de 5 pasos con validación asíncrona.”
  • “Crear un modo oscuro que guarde el estado localmente y escuche las preferencias del OS.”
  • Regla: Cualquier funcionalidad que te tomaría más de 1 día de trabajo manual programar. Cualquier cambio que toque múltiples archivos y capas de estado.

Conclusión: Controla el Sistema, No la Sintaxis

Como diseñador enfocado en la eficiencia, el Spec-Driven Development es el puente que cierra la brecha entre el diseño visual y el producto final desplegado.

La codificación manual es cada vez más irrelevante. Tratar a la IA como un pasante al que le hablas por chat es ineficiente. El futuro del desarrollo de producto recae en quienes sepan escribir contratos precisos.

Al adoptar el SDD:

  1. Eliminas la ambigüedad en la entrega (Handoff).
  2. Obligas a la IA a seguir tus altos estándares lógicos.
  3. Te vuelves independiente. Con un Spec claro y un orquestador CLI, puedes construir sistemas de grado empresarial sin escribir la sintaxis subyacente.

Define el estado. Documenta el flujo. Configura el agente. Y deja de desperdiciar tiempo en el chat.

Y por supuesto, no olvides seguir a Ryan Edge.

arrow_back Volver al Blog