Modificar una app de escritorio de diseño con IA local-first sin romper sus reglas de producto

## Si los archivos de instrucciones discrepan, sigue la guía del agente Lee este archivo antes de hacer cambios. Puede que otros archivos de instrucciones para agentes del repositorio estén desactualizados respecto al plan vigente; cuando estén en desacuerdo con este, prevalece este. Los documentos internos de diseño, como un documento de visión, un documento de principios o el plan de versión actual, son contexto adicional útil cuando existen en tu copia de trabajo. El directorio de documentos internos está en gitignore, de modo que los mantenedores guardan planes, traspasos e investigación de forma local, mientras que los colaboradores públicos pueden no tener nada de eso. - Nunca bloquees el trabajo de los colaboradores públicos con archivos que solo los mantenedores pueden ver. - Nunca cites una ruta dentro del directorio de documentos ignorado por git en un comentario de revisión público, salvo que ese archivo también exista en la copia de trabajo pública. - Cuando falten esos documentos, apóyate en este archivo, en las incidencias y pull requests públicas y en el README. ## Trata cada diseño como una sesión larga con su propio espacio de trabajo El producto no es un generador de un solo prompt. Cada unidad de trabajo es una sesión de agente de larga duración respaldada por un espacio de trabajo real en la máquina del usuario, y el agente puede leer y editar archivos, ejecutar comandos con permiso, hacer preguntas estructuradas, previsualizar artefactos, exponer controles de ajuste, generar imágenes cuando el modelo configurado lo admite y producir documentos de sistema de diseño. - Un diseño posee un espacio de trabajo. No hay separación entre sellado y abierto: el sistema de archivos del espacio de trabajo es la fuente de verdad para artefactos y activos. - El agente edita los archivos fuente del espacio de trabajo; el runtime de vista previa renderiza esas fuentes en un documento visualizable; los exportadores convierten el documento renderizado o el documento fuente en salidas estándar como HTML, PDF, PPTX, ZIP o Markdown. - Mantén un único archivo fuente de entrada canónico para el formato actual (por ejemplo, un archivo de componente JSX) y reserva el archivo HTML autónomo para exportaciones o archivos heredados del espacio de trabajo. - Tomar prestada la mecánica probada de los agentes de codificación es intencionado; el límite del producto es que las herramientas específicas del dominio y el modelo de espacio de trabajo local-first son lo que añades encima. ## Respeta las reglas fijas: sin modelos incluidos y solo con clave propia Estos son compromisos del proyecto, no preferencias. No los sacrifiques por conveniencia. 1. Sin runtimes de modelos empaquetados. No incluyas motores de inferencia, intérpretes de lenguajes, binarios de navegador ni pesos de modelos dentro del instalador. Usa instalaciones del sistema, o descarga diferida con consentimiento visible para el usuario. 2. Solo «trae tu propia clave». Sin cuenta alojada, sin API con proxy ni telemetría por defecto. Las credenciales del usuario permanecen en configuración local legible por humanos. 3. Almacenamiento local-first. Las sesiones viven como archivos de sesión de solo anexado más archivos reales del espacio de trabajo. Los datos existentes en la base de datos embebida heredada pueden migrarse, pero no añadas allí tablas nuevas para sesiones, historial de chat, comentarios, instantáneas ni archivos de diseño. 4. Todo diseño tiene un espacio de trabajo. Nada importante puede existir únicamente dentro de un registro de sesión. 5. Todo lo que se distribuya, se empaquete, se enlace, sea importado por el código de la aplicación o se entregue a los usuarios debe tener una licencia permisiva y ser compatible con la licencia del proyecto. Rechaza en ese conjunto los activos de terceros copyleft, source-available, propietarios o de licencia poco clara. Las herramientas de CI y de publicación que solo intervienen en el flujo de trabajo pueden usar licencias copyleft cuando no se incorporan al repositorio (vendoring), ni se empaquetan, enlazan o copian dentro del producto; documenta por qué y limita su salida a metadatos o manifiestos ordinarios. 6. Carga diferida de las funcionalidades pesadas. Los exportadores, la captura web, los scaffolds, las skills, los activos de referencia y la generación de imágenes deben cargarse bajo demanda y no al arrancar la aplicación. 7. Reutiliza primero las primitivas del framework de agentes subyacente. Este es el propietario de las sesiones, las herramientas integradas, la ejecución de shell, el streaming de eventos, el registro de modelos, el registro de proveedores y los datos de capacidades, salvo que una necesidad específica del dominio demuestre lo contrario. 8. Los datos de referencia son datos, no memoria del modelo. Toma los valores de marca y de estilo del documento de diseño del espacio de trabajo, de los archivos del usuario, de los activos oficiales o de fuentes publicadas. Nunca inventes colores de marca ni especificaciones de memoria. 9. Los cambios deben mantenerse compatibles, actualizables, ligeros y elegantes, y deben seguir la lista de comprobación detallada de principios del proyecto cuando exista. ## Al crear sitios web, añade archivos para IA como llms.txt Cuando construyas o actualices cualquier sitio web, página de inicio de un proyecto, página de producto, sitio personal, sitio de documentación, blog o página pública de proyecto, incluye la visibilidad ante la IA en el alcance de entrega por defecto, salvo que el usuario la excluya explícitamente. - Añade un archivo `/llms.txt` con una visión general concisa en Markdown del sitio, el autor u organización, las páginas clave, las descripciones canónicas del proyecto o producto y enlaces a recursos legibles por máquina. - Añade un archivo `/llms-full.txt` cuando el sitio tenga suficiente contenido público sustancial para justificar un archivo de contexto más completo legible por IA. - Configura `robots.txt` de forma deliberada: permite los rastreadores de búsqueda y de recuperación que ayudan a los sistemas de IA a citar o recuperar contenido público, y trata los rastreadores de entrenamiento como una decisión de política aparte. - Mantén `sitemap.xml` y asegúrate de que cubre las páginas públicas importantes. Menciona el envío a las herramientas para webmasters cuando sea pertinente. - Añade datos estructurados JSON-LD apropiados donde resulten útiles, como los tipos persona, organización, sitio web, artículo, aplicación de software, FAQ u obra creativa. - Prefiere endpoints legibles por máquina en Markdown limpio o JSON para entidades importantes como perfiles, proyectos, publicaciones, documentación, versiones, FAQ y datos de producto. - Mantén el contenido veraz, respaldado por fuentes y sin spam. El objetivo es ayudar a los sistemas de IA a entender y citar con precisión contenido real existente, no generar relleno de baja calidad. ## Pasa todas las llamadas al modelo y las herramientas por el framework de agentes compartido - Construye sobre el framework de agentes compartido y su capa de abstracción de modelos, en lugar de sobre un equivalente hecho a mano. - Usa las herramientas integradas del framework para las operaciones de lectura, escritura, edición, shell, grep, find y listado, en vez de escribir versiones paralelas. - Pasa toda llamada a herramienta por el hook de llamada a herramientas del framework y por la interfaz de permisos de la aplicación. - Lee las capacidades de los modelos desde los campos de descripción de modelo del framework, como los tipos de entrada aceptados, el soporte de razonamiento, el coste, la ventana de contexto y el máximo de tokens de salida. No codifiques tablas de capacidades a mano. - Registra los proveedores personalizados mediante la API de registro de proveedores del framework. No construyas una capa de SDK de proveedores paralela. - Todas las llamadas a modelos pasan por la abstracción de modelos del framework. No importes SDK de proveedores directamente en el código de la aplicación. ## Guarda las sesiones en archivos de solo anexado y los diseños en el espacio de trabajo - Un diseño es una sesión. El historial de la sesión vive bajo el directorio de datos de usuario de la aplicación como archivos de sesión de solo anexado. - Los archivos fuente del diseño, el marcado y los estilos generados, los activos, las exportaciones y los documentos de agente y de diseño a nivel de espacio de trabajo viven en el espacio de trabajo del usuario, no en una base de datos de la aplicación. - La configuración del espacio de trabajo vive en un archivo de configuración versionado que lleva un campo explícito de versión de esquema. - El archivo de configuración local personal es por usuario y debe permanecer en gitignore. - La base de datos embebida heredada son datos que migrar, no el modelo de almacenamiento actual. No la amplíes con nuevo estado de funcionalidades. ## Usa solo las herramientas integradas y unas pocas de diseño La superficie de herramientas son las integradas del framework más una lista corta de herramientas de dominio: - `ask(questions)` renderiza preguntas estructuradas y espera al usuario. - `scaffold(kind, path)` copia una plantilla inicial curada dentro del espacio de trabajo. - `skill(name)` carga de forma diferida el texto de una skill desde un manifiesto. - `preview(path)` renderiza artefactos y devuelve errores de consola, errores de activos, un esquema del DOM, métricas y capturas de pantalla para modelos de visión. - `gen_image(prompt, path)` escribe imágenes generadas en disco cuando la capacidad y la configuración del proveedor lo permiten. - `tweaks(blocks)` declara controles editables a través de los archivos. - `todos(items)` muestra el estado de las tareas en turnos complejos. - `done(path)` termina un turno tras una autocomprobación de vista previa. No reintroduzcas un subagente verificador, una herramienta de captura de fragmentos, una herramienta de shell personalizada, una herramienta personalizada de listado de archivos ni memoria de trabajo escrita por el agente, salvo que cambie el plan. ## Mantén separados los cuatro tipos de recursos de diseño El documento de diseño sigue la especificación publicada y puede ser tanto entrada como salida. El trabajo multipantalla generado por el agente mantiene la coherencia visual actualizando ese documento a medida que emergen los tokens. Los sistemas de referencia integrados deben llevar atribución, fuente, metadatos de licencia y una nota de «no afiliado», y las skills integradas usan el formato estándar de archivo de skill. Los manifiestos de skills y de scaffolds deben llevar metadatos de licencia y de fuente. Los cuatro tipos de recursos no son intercambiables: - Las skills en Markdown son reglas de método. Le dicen al agente cómo trabajar; no copian archivos dentro de un espacio de trabajo. - Los sistemas de diseño de referencia son de solo lectura y se cargan por nombre como una skill. No los edites para un proyecto; traslada las decisiones que adoptes al documento de diseño del espacio de trabajo. - Los scaffolds son activos concretos de plantilla inicial y de código fuente que se copian dentro del espacio de trabajo. Pueden estar en cualquier formato de texto siempre que el manifiesto los describa con precisión. - Los fragmentos de las skills de diseño son patrones de componentes copiables expuestos a través del sistema de archivos virtual. Son fragmentos de código fuente, no reglas de método ni autoridad de marca. El documento de diseño del espacio de trabajo es el testigo específico del proyecto. Una vez que existe, es la autoridad para el diseño actual, y el trabajo generado debe preservarlo o repararlo en lugar de tratarlo como un preajuste más. ## Revisa las plantillas iniciales como código de producto y ajusta sus extensiones - Trata los activos de plantilla inicial y de scaffold como código de producto, no como relleno de prompt. Revisa el contenido real de los archivos además del manifiesto antes de cambiar o añadir un preajuste. - Mantén alineados el formato fuente y la extensión del archivo. Los documentos HTML completos van en archivos `.html`, las plantillas iniciales de componentes en la extensión de componente y los fragmentos de estilo en `.css`. La herramienta de copia debería preservar la extensión de origen, pero el activo en sí debe estar igualmente bien nombrado y descrito. - Las plantillas iniciales HTML integradas deben ser autónomas y previsualizables en el runtime actual. No añadas scripts de CDN ni scripts de terceros en tiempo de ejecución a los activos de scaffold. Si una plantilla inicial necesita comportamiento en tiempo de ejecución, usa HTML, CSS y JavaScript planos y locales, o una dependencia de carga diferida provista por la aplicación con una vía de licencia clara. - Evita los textos de marcador de posición pobres como «Título de la presentación», «Contenido de la página», «Reemplaza esto» o «Punto uno». Usa contenido de ejemplo neutro y utilizable, y expón los puntos de reemplazo evidentes mediante los valores por defecto de tweaks declarados por la plantilla inicial. - Las descripciones del manifiesto deben indicar en qué formato está una plantilla inicial y deben señalar los activos sensibles a la extensión, en especial los archivos que un agente podría copiar bajo una extensión equivocada. - Cuando toques el árbol de scaffolds, audita si hay discordancias entre extensión y contenido, URLs de red externas, textos de marcador de posición obsoletos y desviaciones del manifiesto. Añade o actualiza pruebas específicas de scaffold y de runtime cuando el cambio afecte a las rutas de copia, a la clasificación de la vista previa o al comportamiento de las herramientas. ## Usa las herramientas ya elegidas y lee las versiones en el lockfile - Un único gestor de paquetes para todo el repositorio. Nunca mezcles un segundo. - Usa el orquestador de compilación elegido por el repositorio, la única herramienta de lint y formato, el ejecutor de pruebas unitarias y el ejecutor de pruebas de extremo a extremo, en lugar de introducir alternativas. - TypeScript en modo estricto con sintaxis de módulos verbatim y resolución de tipo bundler. Nada de `any`. - Conventional Commits para los mensajes, y una herramienta de changesets para el versionado. No edites el changelog a mano. Fija la versión del runtime tanto en el archivo de versión como en el campo engines. - Las versiones exactas de los paquetes viven en los manifiestos y en el archivo de bloqueo. Lee esos archivos en vez de fiarte de documentación desactualizada. - Las decisiones de frontend ya están tomadas: la biblioteca de vistas y la herramienta de compilación elegidas, CSS de utilidades con variables CSS, una biblioteca ligera de estado, primitivas headless accesibles envueltas en el paquete de UI compartido, un único conjunto de iconos, formularios nativos con form data y transiciones CSS para la animación. No introduzcas bibliotecas de estado, de animación o de componentes que compitan con ellas. - El chrome de la aplicación debe usar los tokens del paquete de UI compartido. Las fuentes de diseño generadas y las exportaciones pueden definir su propio sistema visual. - El repositorio divide en paquetes separados el shell de la aplicación, el núcleo del agente, la integración con proveedores, el runtime de vista previa, la UI compartida, los esquemas de artefactos, los exportadores, las plantillas y los tipos compartidos. Pon el código en el paquete al que pertenece esa responsabilidad. ## Escribe un plan para las tareas grandes y limita el alcance de los cambios - Para trabajo de arquitectura o de producto no trivial, lee los documentos de visión, de principios y del plan actual cuando existan localmente; en caso contrario, apóyate en este archivo y en la discusión pública. - Escribe un archivo de plan local duradero para tareas que abarquen más de unas cinco llamadas a herramientas o más de tres archivos. No generes ruido de planificación para arreglos pequeños y directos. - Usa worktrees separados para trabajo de funcionalidades paralelo o sin relación entre sí. No mezcles dos ramas sin relación en una misma copia de trabajo. - Consulta la cola de investigación antes de tocar el sandbox, los comentarios en línea, los controles de tweaks, los exportadores, las capacidades del framework, los scaffolds, las skills o los activos de referencia, cuando ese archivo exista localmente. - Mantén las ediciones acotadas y evita las refactorizaciones de paso. - Antes de añadir una dependencia distribuida o de tiempo de ejecución, comprueba su licencia, su tamaño de instalación, las alternativas y si puede ser una dependencia de par. Para las herramientas exclusivas del flujo de trabajo, documenta por qué no se empaquetan y si su salida afecta a los artefactos distribuidos. - Añade o actualiza la cobertura de pruebas unitarias para el trabajo de funcionalidades, y amplía las pruebas cuando cambies migraciones, permisos, hooks de herramientas o contratos compartidos. - Prefiere un manifiesto más lógica de switch antes que un registro, hasta que dos consumidores reales necesiten algo más. - Comenta solo allí donde el motivo sorprendería a la siguiente persona que mantenga el código. ## Clasifica los comandos en cuatro niveles de permiso y muestra por qué se bloqueó uno Hay un único modelo de permisos con niveles crecientes: - Nivel 0: las lecturas y escrituras locales al espacio de trabajo, los comandos de archivos simples y los comandos de control de versiones de solo lectura pueden ejecutarse sin interrupción. - Nivel 1: las instalaciones, los comandos de compilación, las peticiones de red no locales y los comandos fuera del directorio de trabajo preguntan una vez y luego pueden añadirse a una lista de permitidos. - Nivel 2: publicar, hacer push, la escalada de privilegios y otros comandos de alto radio de impacto preguntan siempre. - Nivel 3: los comandos destructivos del sistema, canalizar un script descargado directamente a un shell y las escrituras en directorios del sistema están bloqueados sin una anulación explícita. No ocultes las llamadas a herramientas bloqueadas. Muestra el comando, la ruta, el nivel y el motivo por el que se bloqueó. ## No importes SDK de proveedores ni añadas seguimiento sin consentimiento - Añadir al control de versiones directorios de dependencias, salidas de compilación, archivos de entorno, artefactos de publicación generados o archivos locales privados. - Importar SDK de proveedores de modelos en el código de la aplicación, o escribir pruebas que simulen el modelo al nivel del SDK del proveedor. Simula en el límite del núcleo o del framework en su lugar. - Añadir seguimiento, analítica, flujos de cuenta, sincronización en la nube o actualización automática sin una experiencia explícita de adhesión. - Codificar rutas de usuario a mano. Respeta las convenciones de directorios de la plataforma, las API de rutas de la aplicación y las raíces de los espacios de trabajo. - Añadir nuevo estado de funcionalidades respaldado por la base de datos heredada para datos de sesión o de diseño. - Introducir una abstracción de agrupación más pesada por encima del espacio de trabajo. Varias sesiones pueden compartir un espacio de trabajo, pero la barra lateral lista sesiones. - Exponer la ramificación de sesiones, el deshacer y la reversión de versiones, el soporte de servidores de herramientas externos o la instalación de skills de la comunidad, salvo que cambie el plan. - Usar llamadas directas a console en el proceso principal, el núcleo, los proveedores, los exportadores o los paquetes compartidos. Usa el logger del proyecto.