Tu app no es un archivo: es un sistema de piezas

Quiero una app para reservar mesas en mi restaurante: los clientes eligen día y hora, pagan una señal y reciben un correo de confirmación.

Usa el skill app-por-piezas. Primero hazme el mapa de piezas en ARCHITECTURE.md (capas, módulos, qué depende de qué) y espera mi visto bueno antes de escribir código.

Ya tengo una app hecha con IA y no sé dónde mirar cuando algo falla.

Usa el skill app-por-piezas, pero sin cambiar código todavía: léela entera y dibuja el mapa de lo que existe en ARCHITECTURE.md. Dime qué módulos están mezclados y qué sacarías primero.

---
name: app-por-piezas
description: Planifica y construye una app como un monolito modular, pieza por pieza (interfaz, servidor, base de datos, servicios externos), con módulos que no se mezclan. Úsalo al empezar una app nueva, al pedir una función que toca varias partes, cuando algo "se rompe" y no sabes dónde mirar, o cuando se hable de arquitectura, módulos o estructura de carpetas. Plan and build an app as a modular monolith, one piece at a time.
---

# App por piezas

Una app no es un archivo de código: es un sistema de piezas que se hablan entre sí. Tu trabajo con este skill es que esas piezas existan **por escrito antes de que existan en código**, y que cada una se construya y se pruebe por separado.

Habla con el usuario en su idioma. Si no es técnico, usa la analogía del restaurante:

| Pieza | En el restaurante | En la app |
|---|---|---|
| Interfaz | El salón: lo que ve el cliente | Pantallas, formularios, botones |
| Servidor | La cocina: donde se decide y se prepara todo | La lógica: reglas, cálculos, permisos |
| Datos | La despensa: donde se guarda todo | Base de datos, archivos |
| Servicios externos | Los repartidores: salen del local | Pagos, correos, mapas, otras APIs |

## Regla de oro

No se escribe código de la app hasta que exista `ARCHITECTURE.md` y el usuario lo haya visto. Si el usuario insiste en empezar ya, haz una versión mínima del mapa (pasos 1 y 2) en 5 minutos y sigue.

## Paso 1. Entender, sin interrogar

Pregunta lo mínimo (máximo 5 preguntas, en un solo mensaje) y propón tú un valor por defecto para cada una:

1. ¿Qué hace la app, en una frase, y quién la usa?
2. ¿Qué información guarda? (nombres de cosas: usuarios, reservas, pedidos…)
3. ¿Qué tiene que hacer con servicios de fuera? (cobrar, enviar correos, mapas…)
4. ¿Cuántos usuarios esperas al principio y cuántos en un año?
5. ¿Hay algo con riesgo? (dinero, datos personales, salud…)

## Paso 2. Dibujar el mapa de piezas

Copia `plantillas/ARCHITECTURE.md` a la raíz del proyecto y rellénala:

- **Capas**: qué pieza del restaurante es cada cosa en ESTA app.
- **Módulos**: uno por cada "sustantivo" del negocio (usuarios, reservas, pagos, avisos…). Para cada uno, usa `plantillas/MODULO.md`: responsabilidad en una frase, datos que posee, qué ofrece a los demás, de qué depende y **qué NO hace**.
- **Mapa de dependencias**: una lista simple `reservas → usuarios, pagos`. Si dibujas un círculo (A depende de B y B de A), el límite está mal puesto: reparte la responsabilidad o crea un módulo intermedio.

Enseña el documento al usuario y espera su visto bueno.

## Paso 3. Reglas que no se rompen

1. **Una sola app**, dividida en módulos. No crees servicios separados por defecto.
2. **Un módulo solo habla con otro por su puerta pública** (su archivo `index` / su interfaz). Nunca importa sus archivos internos ni lee sus tablas.
3. **Cada módulo es dueño de sus datos.** Si otro necesita un dato, se lo pide al dueño.
4. **Todo lo de fuera pasa por un adaptador**: un único archivo por servicio externo (pagos, correo…) dentro del módulo que lo usa. Si cambias de proveedor, solo cambias ese archivo.
5. **Los secretos nunca en el código**: variables de entorno, y un `.env.example` sin valores.
6. **Cada módulo deja rastro con su nombre** en los registros (`[reservas] pago rechazado, id=…`). Así, cuando algo falla, el mensaje ya dice en qué pieza buscar.

## Paso 4. Construir pieza por pieza

Orden recomendado: datos → módulo núcleo → resto de módulos → interfaz. De uno en uno:

1. Anuncia qué pieza vas a construir y qué NO vas a tocar.
2. Constrúyela dentro de su carpeta (`src/modulos/<nombre>/`).
3. Escribe una prueba mínima de su puerta pública y córrela.
4. Actualiza `ARCHITECTURE.md` si algo cambió.
5. Solo entonces pasa a la siguiente pieza.

Si una petición del usuario obliga a tocar dos módulos, hazlo en dos pasos separados, cada uno por la puerta pública del otro.

## Paso 5. Cuándo separar un módulo (y cuándo no)

Un módulo se saca a un servicio aparte **solo si hay una razón que se pueda medir**, y se anota en `ARCHITECTURE.md` → Decisiones con el dato:

- Consume una parte desproporcionada de CPU o memoria, o necesita escalar distinto (con números).
- Cambia a otro ritmo o lo mantiene otro equipo, y los despliegues se pisan.
- Exige aislamiento por seguridad o normativa (pagos, datos sensibles).
- Necesita otra tecnología que no cabe en la app (por ejemplo, GPU).

"Por si acaso", "porque es lo moderno" y "porque lo hace una empresa grande" no son razones. Si no hay dato, se queda dentro del monolito.

## Cuando algo falla: busca por piezas

Antes de tocar código, responde en este orden y deja de buscar en cuanto una respuesta sea "sí":

1. **Interfaz**: ¿lo que ve el usuario está mal aunque los datos estén bien? (consola del navegador)
2. **Servidor**: ¿la petición llega y la respuesta es errónea? (registros del servidor, buscando el nombre del módulo)
3. **Datos**: ¿el dato guardado está mal o falta? (consulta directa)
4. **Servicios externos**: ¿el proveedor falló o cambió algo? (estado del proveedor, respuesta cruda del adaptador)

Resume al usuario: "El fallo está en <pieza>, módulo <nombre>, porque <evidencia>".

## Qué no hacer

- No empieces por la interfaz sin saber qué datos hay detrás.
- No mezcles en un solo archivo pantalla, reglas y consultas.
- No inventes módulos "genéricos" (utils, helpers, common) que todos importan: son el nuevo desorden.
- No añadas colas, microservicios ni cachés sin una razón medida (Paso 5).