Haga cambios pequeños y probados en un gran monorepositorio TypeScript

## Conozca la estructura y las herramientas del repositorio antes de editar Trate la guía canónica para agentes del repositorio como única fuente de instrucciones. Mantenga las entradas alternativas para agentes como referencias breves y actualice la guía canónica cuando cambien la arquitectura, las herramientas, las versiones, los flujos de trabajo o las reglas de contribución. Identifique: - la raíz real del repositorio, el área principal de código fuente, el área de scripts de compilación, la documentación, las aplicaciones de prueba y los espacios de trabajo generados; - la rama base obligatoria, la versión del entorno de ejecución, el gestor de paquetes, el orquestador de tareas, el analizador, el formateador y los sistemas operativos de CI; - las exportaciones externas frente a las declaradas explícitamente como internas; - los verificadores de tipos específicos de cada paquete y cualquier diferencia de versión del compilador entre las comprobaciones del repositorio, las herramientas del editor y los consumidores posteriores de la API. Mantenga la configuración compartida válida para todas las rutas de compilación compatibles. No adopte una opción ni una sintaxis solo porque la acepte el verificador más reciente. En herramientas de interfaz modulares, distinga los renderizadores de ejecución, los motores de empaquetado y las integraciones que combinan ambos con la configuración del marco. Conserve arquitecturas de arranque rápido, como la indexación estática anterior a la carga en ejecución; un módulo de usuario inválido no debe derribar toda la interfaz de navegación o administración. ## Ejecute solo las compilaciones y comprobaciones que necesita el cambio Ejecute los comandos desde el directorio de trabajo documentado y use nombres de proyecto del espacio de trabajo, no nombres de paquetes publicados, al dirigirse al grafo de tareas. Empiece con tareas no productivas que aprovechen la caché y conozcan las dependencias: 1. compile el proyecto o conjunto de paquetes afectado; 2. ejecute verificaciones de tipos acotadas; 3. formatee y analice los archivos modificados; 4. ejecute las pruebas pertinentes más cercanas; 5. valide el comportamiento en la interfaz interna de desarrollo. Pase a la configuración de producción, a entornos aislados generados o a flujos equivalentes a CI solo cuando el cambio dependa de la integración de plantillas, la conexión de tareas de producción o el comportamiento entre paquetes. Respete las dependencias de tareas salvo que reanude deliberadamente desde una fase posterior ya verificada. No inicie servidores de desarrollo de larga duración como acción predeterminada. Los comandos que requieran una plantilla, un objetivo o un entorno deben recibirlos explícitamente. Cuando falle un entorno aislado generado, use la interfaz interna documentada como alternativa de diagnóstico antes de cambiar la arquitectura de compilación. ## Elija el tipo de prueba según el código y evite que las pruebas se afecten entre sí Ajuste la forma de prueba al comportamiento: - pruebe los componentes renderizados mediante ejemplos ubicados junto a ellos y funciones de interacción, incluidos la accesibilidad y el comportamiento del usuario; - use pruebas unitarias para utilidades puras, ganchos y módulos que no renderizan; - use herramientas visuales para la apariencia; - use suites de extremo a extremo, de humo o de ejecución para los contratos de integración. Pruebe el comportamiento exportado y los efectos secundarios observables, no los detalles internos de implementación. No duplique garantías ya impuestas por los tipos, las reglas de análisis, las interacciones de los ejemplos o las pruebas de navegador de nivel superior. Para código de sistema de archivos, prefiera un sistema de archivos en memoria en lugar de directorios temporales reales o la sustitución completa de módulos. Restablezca el estado virtual antes de cada prueba, redirija solo los métodos necesarios del sistema de archivos y compruebe el estado del disco virtual cuando resulte útil. Nunca asigne directamente valores globales del entorno en las pruebas. Use sustitutos globales controlados por el entorno de pruebas y restáurelos después de cada prueba, incluidas las claves que antes no existían. La asignación directa crea fugas entre archivos que dependen del orden de ejecución. Normalice las rutas esperadas con las utilidades de rutas del entorno para que las comprobaciones del sistema de archivos funcionen tanto en Unix como en Windows. ## Compruebe primero las suposiciones y no añada abstracciones innecesarias Verifique las suposiciones sobre el entorno con una pequeña prueba desechable antes de basar en ellas la arquitectura. No convierta una creencia no comprobada sobre empaquetadores, metadatos, cargadores o resultados generados en un comentario o una abstracción permanentes. Codifique primero las suposiciones duraderas mediante tipos y reglas de análisis existentes. Si no resulta práctico imponerlas estáticamente, añada una aserción de ejecución económica en el límite para que las infracciones fallen cerca de su origen. Prefiera eliminar lo innecesario y aplicar una solución directa antes que añadir flexibilidad especulativa. No agregue abstracciones, rutas alternativas ni puntos de extensión para consumidores que no existen. Los comentarios son documentación de mantenimiento, no transcripciones de una investigación. Explique la razón duradera en una o dos frases; omita códigos de incidencias, historiales de pruebas, relatos de comparaciones de bytes y referencias frágiles a números de línea. Use una cobertura amplia de casos límite en rutas sensibles para la seguridad y en migraciones antiguas. Limite el código de compatibilidad a un intervalo explícito de versiones para poder retirarlo cuando termine el periodo de soporte. ## No toque los archivos generados sin motivo y use las herramientas de formato y registros del repositorio Ejecute el formateador del repositorio después de editar; después, analice los archivos modificados y ejecute las pruebas pertinentes. Use las herramientas configuradas: no sustituya analizadores retirados ni dé formato manual al código que controla el formateador. Ejecute los scripts TypeScript nuevos mediante la ruta nativa actual del repositorio y use extensiones de importación TypeScript explícitas cuando la configuración lo exija. Migre cargadores antiguos solo dentro del alcance afectado. Use la abstracción de registros del proyecto en el código normal de servidor y cliente. Reserve las llamadas directas a la consola para scripts aislados en los que importar el registrador no sea razonable. Nunca confirme cambios accidentales en archivos generados. Un artefacto generado solo puede cambiar cuando sea una consecuencia determinista de un cambio intencional en el código fuente dentro del mismo trabajo. En cualquier otro caso, déjelo intacto e informe de las desviaciones recurrentes del generador. Tenga en cuenta tanto Unix como Windows en rutas, subprocesos y pruebas. Trate la cobertura de plataformas de CI como un requisito de compatibilidad, no como una limpieza opcional. ## Termine un cambio comprobando su comportamiento, no solo que compile Para un cambio normal: 1. instale dependencias solo cuando sea necesario; 2. compile el grafo de dependencias pertinente; 3. realice la edición coherente más pequeña; 4. vuelva a compilar los paquetes afectados; 5. ejecute verificaciones de tipos acotadas, formato, análisis y pruebas adecuadas al contrato; 6. valide en la interfaz interna; 7. añada comprobaciones de entorno aislado o equivalentes a producción solo cuando sean directamente pertinentes. Para integrar un renderizador, marco, constructor o complemento, edite el paquete propietario, compile primero sin modo de producción y después pruebe con una aplicación generada compatible y con el flujo de ejecución o de extremo a extremo pertinente. Si una compilación falla, actualice las dependencias y vuelva a intentar la compilación acotada antes de aumentar la memoria o cambiar la arquitectura. Inspeccione los resultados generados y las cachés cuando el entorno aislado se comporte de forma distinta a la interfaz interna. No declare que el cambio está listo solo porque compila. Las pruebas necesarias son el conjunto mínimo que cubre el límite del paquete modificado, las rutas de compilación compatibles, el comportamiento observable, las suposiciones multiplataforma y el flujo de integración directamente afectado.