💜 Cómo trabajar con Lovable y Spec-Driven Development

---

🌍 Par de idioma / Language pair

• Español: 17-trabajar-con-lovable.md
• English: ../en/17-working-with-lovable.md

🗣️ Prompt amigable (copiar y pegar)

Usa esto cuando no eres técnico y quieres que la IA haga la integración + guía completa:

Usando https://github.com/juanklagos/spec-driven-development-template, crea todo lo necesario para llevar a cabo mi proyecto de principio a fin.
Mi proyecto es: [explica tu proyecto en lenguaje simple].

Si mi proyecto es nuevo, inicialízalo con este template y GitHub Spec Kit.
Si mi proyecto ya existe, adáptalo a idea/specs/bitacora sin romper el comportamiento actual.
Guíame paso a paso según mi nivel (principiante/intermedio/avanzado), con lenguaje claro.
No omitas especificación, plan, tareas, traza de refinamiento, bitácora y validación.

[!TIP] Inicio recomendado (baja fricción): no necesitas clonar este repositorio si ya estás trabajando en un proyecto. Lovable entiende perfectamente esta estructura si se la provees como contexto.

🎯 Objetivo de esta guía

El objetivo de esta guía es enseñarte cómo utilizar Lovable (o asistentes visuales similares) en conjunto con el Spec-Driven Development. Cuando combinas la capacidad de escritura de código de Lovable con el rigor de las especificaciones, obtienes aplicaciones de alta calidad, cero alucinaciones y mantenimiento real a largo plazo.

Hemos estructurado esta guía en 3 niveles de profundidad para que la adoptes a tu propio ritmo.

---

🟢 Nivel 1: Principiante (El flujo básico)

Este nivel es ideal si nunca has usado la estructura de specs y quieres resultados rápidos con Lovable.

1. Preparar el terreno

Antes de darle órdenes a Lovable, necesitas tener los requisitos claros. No uses a Lovable para “pensar” el producto de cero sin dejar un rastro.

Requisito	Archivo donde vive
Idea clara	idea/IDEA_GENERAL.md
Especificación	specs/001-feature/spec.md

2. El Prompt Mágico para Lovable

Copia y pega este prompt inicial en tu chat de Lovable, adjuntando tus archivos .md:

Actúa como desarrollador experto. Usa estos documentos adjuntos como tu fuente de la verdad para esta sesión:
- spec.md (Requerimientos de negocio)
- plan.md (Arquitectura técnica, si existe)

Reglas estrictas:
1. No implementes nada que no esté en la spec.
2. Si un requerimiento es ambiguo, detente y pregúntame.
3. Al finalizar, muéstrame exactamente qué archivos modificaste.

3. Flujo Visual Principiante

graph TD
    A[Escribir spec.md de tu idea] --> B[Subir a Lovable]
    B --> C[Lovable escribe el código]
    C --> D[Pruebas visuales en Lovable]
    D --> E[Aprobar o Revertir]

---

🟡 Nivel 2: Intermedio (Calidad y Control)

Aquí dejamos de ser operadores básicos y empezamos a comportarnos como ingenieros de software controlando una IA.

1. Requisitos Técnicos

Además de la spec.md, ahora requieres planificación técnica. Este nivel exige que tú o tu arquitecto (otra IA) redacten un plan.md y tasks.md.

Herramienta	Acción requerida
Control de versiones	No hagas commits directo a main. Usa ramas: git checkout -b feature/001
Tareas	Sigue estrictamente el archivo specs/001-feature/tasks.md

2. Flujo de Ejecución por Tareas

En lugar de pedirle a Lovable que haga “todo el feature”, divídelo por tareas:

Hoy implementaremos únicamente la [TAREA 1] descrita en tasks.md.
Asegúrate de ejecutar y mantener libre de errores de lint y pruebas antes de decir que terminaste. Pídeme que revise cuando estés en un estado estable.

3. Ejecutar y Validar Localmente

Lovable suele funcionar en la nube. Descarga el código a tu máquina local regularmente y ejecuta:

1. Instalación: npm install
2. Desarrollo: npm run dev
3. Validaciones: Pasa tu mouse visualmente, verifica logs de consola.

[!CAUTION] No te confíes de la vista previa de Lovable. Siempre verifica que el código funciona en tu máquina local antes de dar la tarea por cerrada.

sequenceDiagram
    participant Humano
    participant Lovable
    participant Git Local
    Humano->>Lovable: Sube tasks.md y plan.md
    Lovable->>Lovable: Genera código para Tarea 1
    Lovable-->>Humano: Entrega cambios
    Humano->>Git Local: Descarga e integra
    Humano->>Git Local: npm run dev
    Humano-->>Lovable: Reporta errores de consola

---

🔴 Nivel 3: Avanzado (Automatización y GitHub Spec Kit)

En este nivel integramos Lovable con herramientas de línea de comandos, CI/CD, y automatización estricta.

1. Sincronización con GitHub Spec Kit

No escribimos las specs a mano. Usamos Spec Kit para automatizar la carpeta y el estado:

specify implement . –ai lovable

2. Prompt Estratégico de Ingeniería

Asume tu rol como Ingeniero de Software Principal.
Estamos operando bajo el estándar de Spec-Driven Development.

Aquí está nuestro contexto:
[adjuntar/leer specs/002-feature/spec.md]
[adjuntar/leer specs/002-feature/contracts/]

Reglas de Calidad (Strict Mode):
- Todo componente nuevo debe estar tipado (TypeScript).
- Cobertura de tests requerida (Jest/Vitest) para lógicas de negocio.
- Si rompes el linter, no estás terminado.

Genera el código y entrega un reporte de "Handoff" al terminar detallando los riesgos técnicos.

3. Reporte Handoff y Cierre

Exige a Lovable que te entregue un reporte formal al terminar sus tareas, que deberás guardar en bitacora/handoffs/YYYY-MM-DD.md.

Formato de Handoff a exigir:

1. Archivos totales afectados (+ / -)
2. Librerías nuevas instaladas y justificación
3. Decisiones de arquitectura tomadas
4. Comandos a ejecutar en el entorno local (migraciones de BD, reconstrucción de dependencias)

flowchart LR
    subgraph Lovable Cloud
    A[Generación de Código] --> B[Tests en Vercel/Lovable Preview]
    end
    subgraph Local Dev
    C[git fetch & pull] --> D[Validación SDD Strict]
    D --> E[Actualizar history.md]
    end
    subgraph CI Pipeline
    F[GitHub Actions] --> G[Despliegue Producción]
    end

    B -- Sincronización GitHub --> C
    E --> F

---

⭐ Uso explícito del repositorio base

[!NOTE] Siempre mantén este repositorio como tu brújula:
https://github.com/juanklagos/spec-driven-development-template

🆕 Caso: Configurar proyecto para Lovable desde cero

Manda este prompt a tu IA favorita (local o ChatGPT) antes de entrar a Lovable:

Usando https://github.com/juanklagos/spec-driven-development-template inicializa la estructura local para un proyecto nuevo de [REACT/VUE/ETC].
Solo crea los archivos; Lovable hará el código más adelante. Guíame paso a paso para definir la primera spec. No saltes pasos.

♻️ Caso: Lovable rompió un proyecto existente

A veces Lovable “alucina” en proyectos grandes. Manda este prompt para detener el caos:

Usando https://github.com/juanklagos/spec-driven-development-template y su guía, vamos a pausar la escritura de código.
Analiza nuestro código roto, integra la estructura idea/specs/bitacora, y ayúdame a crear una spec basada en lo que *debería* estar haciendo el código para arreglarlo de forma metódica.

💡 Tips rápidos

• Empieza con una descripción corta del proyecto en lenguaje simple.
• Pide a la IA confirmar la spec activa antes de programar.
• Cierra cada sesión con validación y próximo paso claro.

📊 Flujo visual

flowchart LR
  A["Idea del proyecto"] --> B["Spec aprobada"]
  B --> C["Plan alineado"]
  C --> D["Tareas priorizadas"]
  D --> E["Implementación"]
  E --> F["Validación + Bitácora"]