⚡ AI Tools ES Formación

M5SDD avanzado: specs para sistemas complejos

Semana 3 de 4 Carga 4 horas Entregable Árbol de specs para un proyecto completo

5.1 Cuándo una sola spec no es suficiente

En los módulos anteriores trabajaste con specs de feature única. Eso funciona para unidades de trabajo concretas y acotadas.

Pero hay casos donde una sola spec no basta:

En estos casos necesitas specs jerárquicas: un árbol de specs con distintos niveles de abstracción.

5.2 El árbol de specs

SYSTEM SPEC mapa del sistema · nivel 0 FEATURE SPEC funcionalidad · nivel 1 FEATURE SPEC funcionalidad · nivel 1 TASK SPEC una sesión · nivel 2 TASK SPEC una sesión · nivel 2 TASK SPEC una sesión · nivel 2

System spec una vez. Feature spec por funcionalidad. Task spec por sesión.

SYSTEM SPEC (nivel 0)
  Describe el sistema completo: qué es, qué hace, cómo se estructura.
  No describe implementación. Describe arquitectura y contratos entre partes.
  │
  ├── FEATURE SPEC (nivel 1)
  │     Describe una funcionalidad completa del sistema.
  │     Puede implementarse en una o varias sesiones.
  │     │
  │     ├── TASK SPEC (nivel 2)
  │     │     Unidad mínima de trabajo implementable.
  │     │     Se implementa en una sola sesión con la IA.
  │     │
  │     └── TASK SPEC (nivel 2)
  │
  └── FEATURE SPEC (nivel 1)
        │
        └── TASK SPEC (nivel 2)

La regla general:

5.3 System Spec — qué contiene

La system spec no es una spec de implementación. Es un mapa.

Estructura:

# SYSTEM SPEC: [Nombre del sistema]

## Propósito
Qué problema resuelve. Para quién. Por qué existe.

## Actores
Quién interactúa con el sistema (usuarios, otros sistemas, agentes).

## Módulos principales
Lista de las partes del sistema y responsabilidad de cada una.

## Contratos entre módulos
Cómo se comunican los módulos entre sí. APIs, eventos, dependencias.

## Invariantes del sistema
Cosas que siempre deben ser ciertas. Reglas que nunca se pueden violar.

## Stack y decisiones de arquitectura
Tecnologías elegidas y por qué (referencias a ADRs si existen).

## Lo que este sistema NO hace
Límites explícitos del sistema.

## Features planificadas
Lista de features con estado (pendiente / en progreso / completada).
Cada una enlaza a su Feature Spec.

Ejemplo: System Spec de gowy.es

# SYSTEM SPEC: gowy.es — Scraper de subastas públicas

## Propósito
Agregar subastas públicas de múltiples organismos españoles en un único lugar consultable,
permitiendo a usuarios privados seguir activos de su interés sin monitorizar fuentes dispersas.

## Actores
- Usuario anónimo: consulta y filtra subastas
- Usuario registrado: guarda favoritos, activa alertas
- Sistema scraper: obtiene subastas de fuentes externas (cron job)

## Módulos principales
- Scraper: obtiene subastas de fuentes externas, normaliza y persiste
- API: expone datos a la capa web (Next.js API Routes)
- Web: interfaz de consulta (Next.js 14, App Router)
- Auth: gestión de sesiones de usuario registrado (NextAuth)
- Notificaciones: alertas por email cuando aparece subasta de interés

## Contratos entre módulos
- Scraper → DB (Supabase): INSERT en tabla subastas, nunca UPDATE directo
- API ← Web: solo consume, nunca escribe directamente a DB
- Notificaciones ← API: recibe eventos de nuevas subastas que coinciden con alertas activas

## Invariantes del sistema
- Una subasta nunca se duplica (unique constraint en source_id)
- Un usuario no registrado nunca ve datos de otros usuarios
- El scraper no modifica subastas ya existentes, solo inserta nuevas

## Stack
- Frontend: Next.js 14, App Router, TypeScript, Tailwind
- DB: Supabase (PostgreSQL)
- Auth: NextAuth v5
- Deploy: Vercel
- Scraper: Node.js cron job (Vercel Cron o GitHub Actions)

## Lo que este sistema NO hace
- No compra ni gestiona pujas (solo informativo)
- No integra con sistemas de pago
- No almacena documentos de las subastas (solo metadatos)

## Features planificadas
| Feature | Estado | Spec |
|---|---|---|
| Listado de subastas con filtros | completada | specs/completadas/feature-listado.md |
| Sistema de favoritos | en progreso | specs/en-progreso/feature-favoritos.md |
| Alertas por email | pendiente | specs/pendientes/feature-alertas.md |
| Login/registro | pendiente | specs/pendientes/feature-auth.md |

5.4 Gestión de dependencias entre specs

Cuando tienes múltiples features, algunas dependen de otras. Gestionar mal estas dependencias causa bloqueos e inconsistencias.

Cómo documentar dependencias

En cada feature spec, añade un bloque:

## DEPENDENCIAS
- Requiere: feature-auth completada (el sistema de favoritos necesita usuario autenticado)
- Bloquea: feature-alertas (las alertas necesitan favoritos para saber qué monitorizar)

Regla de implementación con dependencias

Nunca implementes una feature que depende de otra no completada. Si necesitas avanzar, implementa con un mock de la dependencia y documéntalo:

## NOTAS TÉCNICAS
- Auth no implementada aún. En esta fase, asumir userId hardcoded = "test-user-001".
- Cuando feature-auth esté completada, reemplazar con useSession().userId

5.5 SDD con múltiples agentes

Cuando usas más de un agente de IA (Claude Code + MCP de Supabase, por ejemplo), las specs necesitan definir qué agente hace qué.

Spec multi-agente: ejemplo

## AGENTES IMPLICADOS

### Agente 1: Claude Code (implementación)
Responsabilidad: escribir el código del componente y la lógica de filtrado.
Input: esta spec + CLAUDE.md del proyecto.
Output: archivos modificados en /app y /components.

### Agente 2: Supabase MCP (datos)
Responsabilidad: confirmar el esquema de la tabla subastas antes de implementar.
Input: consulta al esquema de la tabla subastas.
Output: definición de columnas y tipos para usar en TypeScript.

### Orden de ejecución
1. Agente 2 confirma esquema → Agente 1 implementa
2. No al revés. Si el esquema no está confirmado, no se escribe código de datos.

5.6 Versionado de specs

Las specs cambian. Los requisitos evolucionan. ¿Qué haces cuando hay que actualizar una spec?

Cuándo actualizar una spec existente

Cómo actualizar (sin perder historial)

Añade un bloque de cambios al final de la spec:

## HISTORIAL DE CAMBIOS

| Versión | Fecha | Cambio | Motivo |
|---|---|---|---|
| v1.0 | 2026-06-01 | Spec inicial | — |
| v1.1 | 2026-06-03 | Añadido edge case: usuario sin conexión | Detectado en validación |
| v1.2 | 2026-06-05 | Modificado criterio de validación #3 | Requisito de negocio actualizado |

Cuándo crear una spec nueva en lugar de actualizar

Regla práctica: si cambias más del 30% de los bloques, crea una spec nueva y archiva la anterior.

5.7 SDD con MCPs: delegar con precisión

Los MCPs permiten que la IA interactúe con sistemas externos. Con SDD, puedes usar MCPs de forma controlada y trazable.

Principio: el MCP también tiene spec

Cuando instruyes a la IA para que use un MCP, trátalo como una task spec:

# TASK SPEC: Consultar esquema de tabla subastas via Supabase MCP

OBJETIVO:
Obtener la definición completa de la tabla subastas para usarla como
contexto en la implementación del filtro.

COMPORTAMIENTO ESPERADO:
- Usar Supabase MCP para consultar el esquema de la tabla subastas
- Retornar: nombre de columnas, tipos de datos, constraints
- Formatear el resultado como TypeScript interface

RESTRICCIONES:
- Solo lectura. No ejecutar ninguna query de escritura.
- No exponer datos de otras tablas.

CRITERIOS DE VALIDACIÓN:
- El resultado incluye la columna "estado" con sus valores posibles
- El TypeScript interface generado compila sin errores

Ejercicio M5

Elige uno de tus proyectos activos con al menos 3-4 features planificadas o en desarrollo.

  1. Escribe la System Spec del proyecto (usa la estructura del 5.3)
  2. Lista todas las features con su estado actual
  3. Para las 2-3 features más prioritarias, escribe la Feature Spec
  4. Mapea las dependencias entre features
  5. Si alguna feature usa un MCP, escribe la Task Spec del uso del MCP

El resultado es tu árbol de specs: el mapa completo del trabajo pendiente y en curso.

Entregable M5

Carpeta con:

Resumen del Módulo 5