Mantenimiento de prototipos

¿Qué hace Mantenimiento de prototipos?

Usa esta habilidad para hacer que un prototipo existente sea más fácil de modificar a lo largo de muchas rondas de iteración de producto.

El objetivo no es rediseñar el producto. Preserva el comportamiento actual y la dirección visual mientras mejoras la mantenibilidad, la propiedad de archivos y la velocidad de validación.

Alcance y entrega

• Usa esta habilidad para iteración estructural continua y mapeo de propiedad en un prototipo existente. Para división estática o empaquetado por primera vez, usa static-prototype-splitter cuando esté disponible; no es una dependencia obligatoria.
• Una solicitud pequeña de copia, diseño o comportamiento no requiere una reorganización de directorios. Divide solo las responsabilidades relevantes para la solicitud.
• Conserva el nombre de archivo de entrada existente, el marco de trabajo, el modelo de scripts y el flujo de trabajo de vista previa. El diseño app.html a continuación es un ejemplo, no un requisito de cambio de nombre.
• Sigue las reglas de autorización del usuario para reemplazo de archivos, configuración, dependencias, acceso a red, servidores locales y datos almacenados. Esta habilidad no otorga esos permisos.

Cuándo activar

Activa esta habilidad cuando el usuario solicite:

• Mejorar la velocidad de modificación futura del prototipo.
• Dividir JS por página, componente, campo, modal, almacén o capa de datos.
• Dividir CSS por ámbitos base, diseño, página, componente, modal y campo.
• Separar datos mock, datos semilla, esquemas y lógica de estado/almacén.
• Crear o actualizar un README de mantenimiento del prototipo.
• Crear o actualizar un CHANGE-MAP que asigne solicitudes futuras a archivos.
• Continuar optimizando un prototipo interactivo existente.
• Hacer que una vista previa combinada y los archivos divididos se mantengan mantenibles juntos.
• Explicar dónde se debe realizar un cambio futuro en el prototipo.

Principios predeterminados

• Sigue el lenguaje del usuario y la terminología existente del prototipo.
• Lee la entrada actual y las referencias de scripts activos antes de editar.
• Mantén el diseño visual original y la intención de interacción a menos que el usuario solicite un rediseño.
• No reescribas todo en un marco de trabajo a menos que se solicite explícitamente.
• Evita una segunda implementación divergente. La vista previa combinada debe cargar módulos compartidos/divididos o generarse a partir de ellos.
• Mantén los cambios centrados en la mantenibilidad y el comportamiento del producto solicitado.
• La división no está completa cuando simplemente se añaden nuevos archivos. Cada división también debe reducir la responsabilidad del archivo antiguo para que las futuras ediciones tengan un propietario obvio.
• Mantén los cambios no relacionados intactos y preserva la entrada original y los archivos reemplazados. Enfoca las ediciones autorizadas en la implementación activa; no elimines archivos heredados ni reemplaces documentos protegidos sin aprobación.
• Después de los cambios, verifica la sintaxis y la interacción principal de vista previa cuando sea práctico.

Estructura recomendada

Adapta los nombres al proyecto, pero prefiere esta forma para prototipos interactivos estáticos:

prototype/
├── app.html
├── README-prototype.md
├── CHANGE-MAP.md
├── assets/
│   ├── css/
│   │   ├── base.css
│   │   ├── layout.css
│   │   ├── components.css
│   │   ├── modals.css
│   │   ├── fields.css
│   │   └── pages/
│   │       ├── home.css
│   │       ├── editor.css
│   │       └── fill.css
│   └── js/
│       └── app/
│           ├── core.js
│           ├── runtime.js
│           ├── pages/
│           ├── components/
│           ├── fields/
│           ├── modals/
│           ├── data/
│           ├── store/
│           └── utils/
└── pages/
    └── ...

Usa nombres equivalentes cuando el dominio del prototipo difiera. La parte importante es la división de responsabilidades.

Para prototipos pequeños, una estructura más plana está bien. Para prototipos que cambian con frecuencia, prefiere la estructura de directorios anterior para que cada solicitud futura se asigne a un archivo pequeño.

Responsabilidades de las capas

Capa de entrada

Mantén la entrada de vista previa combinada actual; app.html es el nombre de ejemplo utilizado a continuación.

Debe contener:

• Marco de dispositivo o shell de vista previa, si lo hay.
• Contenedor raíz.
• Enlaces CSS.
• Referencias de scripts ordenadas.

No debe contener la mayor parte de la lógica de negocio.

Capa de página

Usa archivos de página para el renderizado de páginas y el diseño específico de página:

• Página de inicio/lista/búsqueda/pestañas.
• Página de editor/crear/editar.
• Página de llenado/vista previa/envío/detalle.
• Páginas de inicio de sesión/registro/incorporación.
• Páginas de configuración/cuenta.

Cuando el usuario solicite cambiar un diseño de página o copia de página, comienza aquí.

Si un archivo de página contiene múltiples subvistas editadas con frecuencia, divídelo nuevamente. Ejemplo:

pages/home/
├── index.js
├── search.js
├── my-forms.js
└── submitted.js

Capa de campo o componente

Usa archivos de campo/componente para bloques de UI repetidos:

• Etiquetas de tipo de campo.
• Valores predeterminados de campo.
• Vista previa de campo en el editor.
• Controles de página de llenado.
• Renderizadores de carga/archivo/imagen/radio/checkbox/OCR/fecha.

Cuando el usuario solicite cambiar un tipo de elemento, evita buscar en toda la aplicación primero. Comienza desde los archivos de configuración y renderizador de campo.

Cuando un prototipo tenga muchos controles de formulario o tarjetas repetidas, prefiere registros:

fields/
├── registry.js
├── text.js
├── image.js
├── file.js
├── options.js
└── ocr.js

Capa modal

Usa archivos de modal para:

• Hoja de configuración de campo.
• Hoja de selector de tipo.
• Cajón de ordenación.
• Diálogos de confirmación.
• Hoja de biblioteca de añadir elemento.

Mantén el estado modal local cuando sea posible, y solo confirma datos después de acciones de confirmación.

Capa de datos

Separa los datos del comportamiento del almacén.

Usa data/ para:

• Plantillas mock.
• Listas de industria/categoría.
• Definiciones de tipo de campo.
• Usuarios de demostración y ejemplos.
• Registros semilla y fixtures.

Usa store/ para:

• Claves de almacenamiento local.
• Guardar/eliminar/actualizar formularios.
• Guardar/eliminar/actualizar registros de envío.
• Normalización de datos y migraciones.

No mezcles reglas de almacenamiento en renderizadores de página a menos que el prototipo sea muy pequeño.

Cuando ya puedan existir datos locales existentes, preserva sus claves y las ediciones del usuario. Añade solo registros semilla faltantes mediante IDs estables y haz que la siembra sea idempotente; no sobrescribas registros editados, dupliques elementos ni reinicies el almacenamiento local al recargar. Trata las migraciones de esquema como una operación separada y autorizada con una ruta de recuperación documentada.

Capa CSS

Divide el CSS por propiedad, no solo por tamaño:

• base.css: variables, reseteo, tipografía.
• layout.css: shell, marco de dispositivo, contenedor de página, primitivas de cuadrícula.
• components.css: botones, entradas, tarjetas, pestañas, chips.
• modals.css: hojas, cajones, diálogos de confirmación, toast.
• fields.css: controles de campo y vistas previas de elementos de formulario.
• pages/*.css: diseño específico de página y excepciones.

Si un selector se reutiliza en varias páginas, mantenlo en components o fields. Si es específico de una página, muévelo al CSS de esa página.

Capa de mapa de cambios

Añade CHANGE-MAP.md para prototipos que se espera reciban muchas rondas de ediciones.

Debe asignar las solicitudes comunes del usuario directamente a archivos:

# Mapa de cambios

## Páginas
- Página de inicio: assets/js/app/pages/home/index.js
- Página de plantillas: assets/js/app/pages/templates/index.js
- Editor de formularios: assets/js/app/pages/editor/index.js

## Campos
- Campo de carga de imagen: assets/js/app/fields/image.js
- Campo de carga de archivo: assets/js/app/fields/file.js
- Campos de radio/checkbox: assets/js/app/fields/options.js

## Modales
- Modal de configuración de campo: assets/js/app/modals/field-settings.js
- Cajón de ordenación: assets/js/app/modals/sort.js

## Datos
- Datos de plantillas: assets/js/app/data/templates.js
- Categorías de industria: assets/js/app/data/industries.js

## Estilos
- Estilos de página de plantillas: assets/css/pages/templates.css
- Estilos de campo: assets/css/fields.css

Mantén CHANGE-MAP breve. Es un índice de edición, no documentación del producto.

Capa de tiempo de ejecución

Usa archivos de tiempo de ejecución para:

• Despacho de enrutador/renderizado.
• Delegación de eventos.
• Manejo de gestos.
• Despacho de acciones.
• Inicialización.

Si el tiempo de ejecución se vuelve grande, divídelo por tipo de interacción, pero mantén un punto de entrada claro.

README de mantenimiento

Cuando se solicite, añade o actualiza README-prototype.md en la raíz del prototipo.

Incluye:

• Entrada de vista previa total.
• URL de vista previa local y puertos reservados, si los hay.
• Mapa de página a archivo.
• Mapa de campo/componente a archivo.
• Mapa de modal a archivo.
• Ubicación de la capa de datos.
• Ubicación de la capa CSS.
• Ubicación de CHANGE-MAP.
• Cómo actualizar y validar después de los cambios.
• Ejemplos comunes de cambios futuros, como "cambiar campo de carga de imagen" o "cambiar página de envío de formulario".

Mantenlo conciso y útil. Es para humanos que mantienen el prototipo, no un diario de desarrollo largo.

Flujo de trabajo

1. Inspecciona los archivos de entrada activos.

   • Usa rg --files, grep y lecturas dirigidas.
   • Confirma qué scripts están realmente cargados por la vista previa combinada.
   • No asumas que los archivos divididos existentes están activos.

2. Identifica la propiedad actual.

   • Renderizadores de página.
   • Renderizadores/configuración de campo.
   • Modales/cajones.
   • Ayudantes de almacén/datos.
   • Manejadores de tiempo de ejecución/eventos.

3. Divide con cuidado.

   • Prefiere primero la extracción mecánica cuando preservar el comportamiento sea importante.
   • Mantén el orden de carga de scripts explícito en app.html.
   • Evita cambiar el comportamiento durante la división a menos que el usuario también haya solicitado cambios de comportamiento.
   • Después de extraer un módulo, elimina o reduce la responsabilidad correspondiente del archivo antiguo. No dejes dos propietarios activos para la misma página, componente, modal, conjunto de datos o selector CSS.
   • Deja los archivos combinados heredados sin usar en lugar de eliminarlos a menos que el usuario confirme la eliminación.
   • Preserva el modelo de script clásico o de módulo ES existente. Verifica el orden de carga, las exportaciones y los manejadores de eventos en línea después de mover funciones.
   • Haz explícitas las responsabilidades de montaje/desmontaje de vistas. Elimina los listeners y temporizadores obsoletos al salir de una vista para que la navegación repetida no duplique acciones.

4. Divide los datos cuando los datos estén creciendo.

   • Mueve los datos mock grandes fuera de los renderizadores de página y los archivos de almacén.
   • Mantén los fixtures semilla deterministas y fáciles de escanear.
   • Fusiona nuevos datos semilla en los datos locales existentes cuando sea posible.
   • Si los datos se mueven a data/, haz que los archivos de almacén/estado consuman esos datos en lugar de mantener una copia activa duplicada.

5. Divide CSS cuando los cambios visuales se estén volviendo lentos.

   • Comienza con base/layout/components/pages.
   • Mueve los selectores solo de página al CSS de página.
   • Mueve los controles reutilizables al CSS de components o fields.
   • Después de mover selectores, elimina los selectores activos duplicados de la hoja de estilo global anterior a menos que se conserven intencionalmente como estilos de componente compartidos.
   • Preserva el orden de cascada y los puntos de interrupción responsivos; reubica las rutas de CSS url(...), fuentes e importaciones relativas a la nueva ubicación del archivo.

6. Actualiza o crea README y CHANGE-MAP.

   • Documenta la estructura activa final.
   • Deja claro qué archivo editar para solicitudes futuras comunes.
   • Incluye la URL de vista previa local, los puertos reservados y las instrucciones de invalidación de caché cuando sea relevante.

7. Verifica.

   • Revisa recursivamente los archivos JavaScript realmente propiedad del prototipo, incluyendo archivos anidados de página/componente. Cuando Python y Node ya estén disponibles, este ejemplo verifica .js, .mjs y .cjs debajo de assets/js; adapta la raíz al proyecto. No instales tiempos de ejecución solo para ejecutarlo.

     python3 - <<'PY_CHECK'
     from pathlib import Path
     import subprocess
     import sys
     
     root = Path("assets/js")
     files = sorted(p for p in root.rglob("*")
                    if p.is_file() and p.suffix in {".js", ".mjs", ".cjs"}
                    and not {"node_modules", "vendor", ".git"}.intersection(p.parts))
     if not files:
         sys.exit("No se encontraron archivos JavaScript; verifica la raíz de verificación.")
     failed = False
     for path in files:
         failed |= subprocess.run(["node", "--check", str(path)]).returncode != 0
     sys.exit(1 if failed else 0)
     PY_CHECK
     

   • Para proyectos con marco de trabajo o un modo de módulo diferente, usa las verificaciones del proyecto existentes. Una verificación de sintaxis no prueba el comportamiento en el navegador.
   • Abre la vista previa combinada.
   • Compara el comportamiento afectado con la línea base, incluyendo la navegación hacia adelante/atrás, volver a visitar la vista editada, confirmar/cancelar modal y estado guardado después de la actualización cuando corresponda.
   • Verifica los errores de la consola del navegador cuando sea práctico.

Reglas de granularidad de división

Usa estas reglas para evitar tanto la subdivisión como la sobredivisión:

• Si un archivo se edita repetidamente para solicitudes no relacionadas, divídelo.
• Si una página contiene múltiples subvistas que cambian independientemente, divide las subvistas.
• Si los datos mock ocupan más espacio que la lógica que los rodea, muévelos a data/.
• Considera fields/ cuando varios tipos de campo/control cambien independientemente; no dividas solo para cumplir con un recuento.
• Considera modals/ cuando los diálogos o cajones tengan necesidades separadas de estado o mantenimiento.
• Si los cambios CSS requieren buscar en una hoja de estilo global grande, divide por página y componente.
• Si un archivo es estable y rara vez se edita, no lo dividas solo por estética.

Ayudantes de validación

Prefiere validación simple y sin dependencias para prototipos estáticos:

• Usa node --check para sintaxis JS.
• Para invalidación de caché, sustituye un valor real, como app.html?t=20261109-153000; Date.now() escrito literalmente en una URL es una cadena fija. Una consulta HTML por sí sola no actualiza JS/CSS almacenado en caché por separado, así que usa controles de caché del navegador o la estrategia de versionado de activos existente cuando sea necesario.
• Mantén el puerto de vista previa local estable cuando el usuario haya elegido uno.
• Verifica la interacción cambiada en el navegador después de las refactorizaciones estructurales.
• La apertura directa de archivos es aceptable para páginas estáticas compatibles. Los fragmentos obtenidos y los módulos ES del navegador generalmente requieren HTTP; documenta el modo de apertura y reutiliza el servidor de vista previa existente cuando esté disponible. Iniciar un nuevo servidor sigue las reglas de autorización del usuario.

Estilo de respuesta

Al terminar, informa al usuario:

• Qué se dividió o documentó.
• El archivo de entrada activo.
• Las rutas de archivos nuevos más importantes.
• Si se creó o actualizó README-prototype.md o CHANGE-MAP.md.
• Qué verificación se completó.
• Los archivos heredados que se dejaron intencionalmente en su lugar.

Mantén la respuesta final breve y práctica.