ntizar Project Spec Workflow — Spec antes que código
Cuándo se activa
AUTOMÁTICAMENTE cuando el usuario pide:
- Un proyecto nuevo ("hazme un visor de X", "crea un dashboard de Y")
- Una feature grande (>3 archivos, nueva pestaña, nuevo módulo)
- Un "rewrite" o reestructuración
NO se activa para:
- Fixes puntuales (1-2 archivos)
- Preguntas o consultas
- Cambios de estilo/contenido
- Tareas que el usuario ya ha especificado completamente
Principio fundamental
Sin spec, no codeas. Si el usuario no puede describir qué quiere en 5 minutos, el agente no puede construirlo en 5 horas.
Fase 1 — Detección y propuesta inicial
Cuando el usuario pide algo nuevo, el agente NO empieza a codear. En su lugar:
- Busca en memoria si hay proyectos similares del usuario (GTFSSpain, DataHubEspana, GBFSSpain, etc.)
- Busca en ChromaDB skills relevantes para el dominio
- Propone una visión inicial basándose en lo que ya sabe
Plantilla de propuesta inicial
He detectado que quieres [X]. Basándome en tu historial ([proyectos similares]),
propongo:
🎯 **Qué será:** [1 frase]
📊 **Datos:** [fuentes probables]
🗺️ **Pantallas:** [lista inicial]
⚡ **Stack:** [tecnologías]
🚫 **No incluye:** [non-goals iniciales]
Antes de construir nada, necesito que confirmes o ajustes estas decisiones:
Fase 2 — Preguntas estructuradas (NO abiertas)
El agente hace preguntas estructuradas con opciones, nunca preguntas abiertas tipo "¿qué quieres?". El usuario responde rápido, no tiene que pensar desde cero.
Bloque A — Alcance (qué hace y qué no)
A1. ¿Qué problema resuelve?
[ ] Panel de visualización de datos
[ ] Herramienta interactiva/análisis
[ ] Visor cartográfico
[ ] Otro: _____
A2. ¿Cuál es la pantalla principal?
[ ] Mapa a pantalla completa + panel lateral
[ ] Dashboard con tabs/pestañas
[ ] Lista/tabla + detalle
[ ] Otro: _____
A3. ¿Qué NO hace? (non-goals — tan importante como qué sí hace)
[ ] No tiene backend (todo client-side)
[ ] No tiene login/usuarios
[ ] No tiene modo offline
[ ] No guarda datos de usuario
[ ] Otro: _____
Bloque B — Datos
B1. ¿De dónde vienen los datos?
[ ] APIs públicas (cuáles: _____)
[ ] JSON estático (tamaño aproximado: _____)
[ ] Mixto (algunos estáticos + APIs en vivo)
[ ] No lo sé, propón tú
B2. ¿Cada cuánto se actualizan?
[ ] Tiempo real (segundos/minutos)
[ ] Diario
[ ] Estático (no cambia)
[ ] Mixto
B3. ¿Volumen de datos?
[ ] Pequeño (< 100 registros)
[ ] Medio (100-10K registros)
[ ] Grande (10K-1M registros)
[ ] No lo sé
Bloque C — Arquitectura y stack
C1. ¿Frontend, backend, o ambos?
[ ] Solo frontend (estático, GitHub Pages)
[ ] Frontend + proxy backend mínimo
[ ] Full-stack (backend con DB)
C2. ¿Tecnologías preferidas?
[ ] Vanilla JS (sin framework) ← recomendado para visores
[ ] React/Vue (si hay mucha interactividad)
[ ] Three.js (si hay 3D)
[ ] Lo que propongas tú
C3. ¿Deploy dónde?
[ ] GitHub Pages (estático)
[ ] NaN.builders (con backend)
[ ] No lo sé todavía
Bloque D — Lo que el usuario ya sabe
D1. ¿Hay algo que YA sabes cómo quieres que sea?
(colores, estilo, disposición, comportamiento específico)
→ El usuario describe. El agente anota como REQUISITOS.
D2. ¿Hay algo que HAYAS VISTO que te guste como referencia?
(URLs, proyectos, diseños)
→ El agente busca referencias visuales si hace falta.
D3. ¿Hay algo que TE HAYA PASADO antes que quieras evitar?
(bugs recurrentes, patrones que no funcionan)
→ El agente anota como ANTI-PATRONES.
Fase 3 — Generación de SPEC.md
Con las respuestas, el agente genera un documento SPEC.md en el repo del proyecto con esta estructura:
# [Nombre del proyecto] — SPEC
## Visión
[1 frase: qué es y para qué]
## Alcance
### Sí hace
- [lista de features]
### NO hace (non-goals)
- [lista explícita de lo que no]
## Pantallas
1. [Pantalla 1]: [descripción]
2. [Pantalla 2]: [descripción]
## Datos
| Fuente | Tipo | Actualización | Volumen |
|--------|------|---------------|---------|
| [fuente] | [API/JSON] | [frecuencia] | [tamaño] |
## Arquitectura
### Capas
| Capa | Archivo | Responsabilidad |
|------|---------|----------------|
| Datos | data/*.json | Datos estáticos |
| Estado | js/state.js | Estado global + carga |
| API | js/api.js | Fetch de APIs |
| UI | js/ui.js | Tabs, panels, eventos |
| Render | js/render.js | Gráficos, mapa, tablas |
### Estado global
[Diagrama de qué estado existe y quién lo posee]
### Interfaces entre módulos
[Qué funciones expone cada módulo]
## Stack
- Frontend: [tecnologías]
- Deploy: [plataforma]
## Criterios de éxito
- [métrica 1: ej, carga en < 3s]
- [métrica 2: ej, click → respuesta < 500ms]
- [métrica 3]
## Anti-patrones (lo que evitamos)
- [patrón 1: ej, no usar estado global esparcido]
- [patrón 2]
## Referencias
- [proyectos similares del usuario]
- [links de inspiración]
Fase 4 — Propuesta de arquitectura modular
El agente propone la estructura de archivos antes de codear:
proyecto/
├── SPEC.md ← La spec generada
├── index.html ← Solo estructura DOM, sin lógica
├── css/
│ └── styles.css ← Solo estilos
├── js/
│ ├── state.js ← Estado global + funciones de carga
│ ├── api.js ← Fetch de APIs externas
│ ├── map.js ← Solo mapa (init, markers, layers)
│ ├── charts.js ← Solo gráficos
│ ├── ui.js ← Tabs, panels, eventos de UI
│ └── main.js ← Orquestador: init + wiring
├── data/
│ └── *.json ← Datos estáticos
└── README.md ← Docs generadas desde SPEC
Regla de oro: Un archivo = una responsabilidad. Si el agente va a tocar 3+ archivos en una iteración simple, para y replantea.
Fase 5 — Human loop (aprobación obligatoria)
1. Agente presenta SPEC.md + arquitectura propuesta
2. Usuario revisa: ✅ o ajustes
3. Solo DESPUÉS del ✅ → empezar a codear
El agente NUNCA empieza a codear sin SPEC aprobada.
Fase 6 — Iteración segura (en cada cambio posterior)
Para cada feature nueva o cambio grande:
1. IMPACTO: ¿Qué archivos toca? ¿Qué no toca?
2. ¿Actualiza SPEC.md? (si el alcance cambia)
3. Implementar
4. Verificar que lo anterior sigue funcionando
5. Commit
Plantilla de iteración
## Iteración: [nombre]
### Qué quiero
[1 frase]
### Archivos que toca
- js/ui.js: [qué cambio]
- js/state.js: [qué cambio]
### Archivos que NO toca
- js/map.js
- js/charts.js
- data/*.json
### Verificación
- [ ] Lo anterior sigue funcionando
- [ ] Lo nuevo funciona
- [ ] No hay console errors
Detección automática
El agente debe detectar automáticamente cuándo activar este flujo. Señales:
- "hazme", "crea", "construye", "quiero un" + nombre de proyecto → proyecto nuevo
- "añade", "agrega", "ponle" + feature grande → iteración con spec
- "arregla", "cambia", "modifica" + cosa pequeña → fix directo, sin spec
Si hay duda, el agente pregunta: "¿Es un proyecto nuevo o un cambio en algo existente?"
Integración con memoria
El agente consulta memoria antes de proponer:
- ¿Hay proyectos similares del usuario? → usar como referencia
- ¿Hay preferencias de diseño? → aplicar (Aurora, colores, etc.)
- ¿Hay anti-patrones conocidos? → evitar
Pitfalls
- No sobre-preguntar: Si el usuario ya dio suficiente contexto en el primer mensaje, no hacer 20 preguntas. Hacer solo las que falten.
- No spec sin código: La spec no es un ensayo. Si pasa de 2 páginas, es demasiado. Specs ejecutables, concisas.
- No ignorar la spec: Una vez aprobada, la spec es el contrato. Si el agente se desvía, el usuario lo puede frenar con "vuelve a la spec".
- No codear sin ✅: El human loop es obligatorio. Sin aprobación, no hay código.
- Proyectos de 1 archivo: Si es algo pequeño (un solo HTML), la spec puede ser un comentario en el top del archivo. No necesita SPEC.md completo.
- Iteración sobre monolitos: Si el proyecto ya existe como monolito (ej: index.html de 11K líneas), la spec debe incluir un PLAN DE EXTRACCIÓN: qué sacar a archivos separados y en qué orden.