Modificar un repositorio de backend y frontend con varios módulos sin romper la compilación

## Empezar en la raíz del repositorio y leer las reglas de cada módulo afectado Abra y coordine el proyecto desde la raíz del repositorio, aunque una tarea parezca limitada a un solo subproyecto. Trate las instrucciones de agente del nivel raíz como base y los archivos de instrucciones anidados como reglas locales adicionales. Antes de editar, identifique todos los módulos a los que pueda afectar la tarea y cargue el archivo de instrucciones de cada uno. Una tarea que cruza módulos debe respetar todas las reglas locales pertinentes, no solo las del archivo más cercano al primer cambio propuesto. ## Aclarar de qué se encarga cada módulo y cambiar backend y frontend a la vez Mantenga un mapa de responsabilidades para las áreas principales: - el módulo de API pública es responsable de los puntos de extensión, los contratos de servicio y las abstracciones de seguridad; - la aplicación backend es responsable de la lógica de negocio, los servicios reactivos, el enrutamiento, la seguridad, las migraciones y el empaquetado; - el espacio de trabajo frontend es responsable de las interfaces administrativas y de usuario, los paquetes compartidos y el cliente de API generado; - los módulos de la plataforma de dependencias son responsables de las restricciones de la aplicación y de las extensiones dependientes; - la documentación para desarrolladores es responsable de la arquitectura y las indicaciones de flujo de trabajo destinadas a las personas. Trate los cambios de backend y frontend como una sola tarea de pila completa siempre que los contratos, las cargas útiles, la autenticación, la navegación o la experiencia de usuario crucen ese límite. Mantenga sincronizados en el mismo cambio los contratos públicos, los controladores del backend y el uso en el frontend. ## Regenerar el cliente cuando cambie la API, sin editarlo a mano Evalúe el impacto en el frontend siempre que cambien los tipos públicos de solicitud o respuesta, las rutas, los contratos del enrutador, las anotaciones del esquema de API, los esquemas generados, la autenticación o el comportamiento de las sesiones. Después de actualizar el contrato fuente, regenere la descripción de la API y el cliente mediante los comandos prescritos por el repositorio. Nunca edite directamente los archivos de cliente generados. Corrija el contrato o la entrada del generador, regenere la salida y revise la diferencia resultante. Pida confirmación antes de realizar cambios destructivos en la salida generada o de modificar una API pública de la que puedan depender consumidores posteriores. ## Comprobar cómo se empaqueta el frontend dentro de la compilación del backend Comprenda cómo entra la salida del frontend en el artefacto desplegable del backend. Si la compilación del backend incorpora la interfaz compilada en los recursos de la aplicación, todo cambio en la salida del frontend también afecta a la ruta de empaquetado del backend y debe verificarse allí. Ejecute desde la raíz la coordinación entre capas para que la compilación del backend, el empaquetado de la interfaz y las pruebas utilicen el mismo grafo de dependencias. Trate las descargas realizadas durante la compilación, las extensiones predefinidas y los recursos de distribución copiados como parte del contrato de compilación, no como archivos accesorios. ## Tomar las versiones y las reglas de formato de sus archivos designados Lea las versiones de las dependencias, la versión del proyecto, la versión del lenguaje, las versiones de los complementos y las dependencias del frontend desde sus catálogos, archivos de propiedades, scripts de compilación y manifiestos de paquetes designados. No codifique de forma fija una versión que ya tenga una fuente autorizada. Utilice el formateador y el analizador configurados como fuente de verdad para la sangría, el ancho de línea y la sintaxis admitida. Respete la versión declarada del lenguaje, incluido `release 21` cuando así se especifique, y mantenga las reglas de formato del nivel raíz en el ámbito donde las espera la compilación. ## No meter E/S bloqueante en el código reactivo y mantener la base de datos en su sitio No introduzca entrada o salida bloqueantes en las rutas de ejecución reactivas, aunque los hilos virtuales estén habilitados en otros lugares. Conserve el motor de migración elegido por el proyecto en lugar de sustituirlo silenciosamente por otro, y mantenga las migraciones específicas de cada dialecto en sus directorios de base de datos designados. Mantenga los esquemas de extensiones, los datos JSON de ejecución, la configuración específica de cada perfil y el directorio de trabajo reemplazable en sus ubicaciones correspondientes. Use rutas de archivo absolutas para las bases de datos integradas basadas en archivos; un URI relativo puede crear directorios no deseados bajo el módulo de la aplicación y cambiar la base de datos que se abre. ## Elegir las pruebas según la parte que cambió Seleccione las comprobaciones según el alcance real: - los cambios exclusivos del backend requieren el formateo del repositorio y las pruebas del backend afectadas; - los cambios exclusivos del frontend requieren el formateo del frontend, la comprobación de tipos, el análisis estático y las pruebas unitarias pertinentes; - los cambios de contrato requieren generar la descripción de la API, regenerar el cliente, validar el frontend y ejecutar las pruebas del backend; - los cambios entre capas requieren verificar el artefacto final empaquetado, además de ambos lados del contrato. Ejecute primero las comprobaciones específicas y amplíe después el alcance según sea necesario. Añada o actualice pruebas para cada comportamiento modificado y no presente el trabajo mientras sigan fallando las comprobaciones obligatorias de integración continua. ## Comprobar el repositorio de origen correcto antes de enviar y preparar solo los archivos de la tarea Identifique el repositorio actual e inspeccione sus remotos antes de enviar cambios o abrir una revisión. Seleccione el repositorio de origen correcto para esa copia de trabajo; utilizar el origen de un repositorio público o propietario relacionado puede resultar costoso de revertir. Empiece el trabajo desde la base prevista del repositorio de origen y siga las convenciones de ramas del repositorio, como `upgrade/gradle-X`, `feat/name`, `fix/name` o `improvement/name`. Prepare solo los archivos pertenecientes a la tarea; nunca use `git add -A` ni `git add .` cuando puedan existir salidas de compilación o artefactos de base de datos. Si un árbol de trabajo obsoleto bloquea la rama principal, inspeccione la lista de árboles de trabajo y retire explícitamente solo la entrada cuya obsolescencia haya confirmado. No use una limpieza general como sustituto de identificar al propietario exacto del bloqueo. ## Preguntar antes de migraciones o nuevas dependencias y nunca hacer commit de secretos Utilice tres niveles de control: - trabaje siempre desde la raíz, cargue todas las reglas anidadas aplicables, prepare los archivos de forma explícita, regenere desde la fuente los clientes derivados, añada pruebas para los comportamientos modificados e indique en la descripción de la revisión que el material recibió asistencia de IA; - pida confirmación antes de cambiar API públicas, añadir dependencias de compilación o de paquetes, escribir migraciones de base de datos, modificar la configuración de seguridad o los flujos de integración continua, o reemplazar de forma destructiva la salida generada; - nunca confirme secretos en el repositorio, codifique de forma fija versiones autorizadas, añada operaciones bloqueantes a rutas reactivas, edite directamente clientes generados ni abra una revisión sin confirmar el repositorio de origen correcto. Estos límites se aplican aunque la implementación sea sencilla. La facilidad de programación no reduce los riesgos de compatibilidad, seguridad, datos o publicación. ## Evitar trampas conocidas de la compilación, como las rutas relativas a la base de datos Preserve las invariantes conocidas y específicas de las herramientas: 1. Las ubicaciones de bases de datos integradas basadas en archivos deben resolverse como rutas absolutas del sistema de archivos; las rutas relativas pueden crear directorios de módulo no deseados y hacer que la aplicación abra una base de datos equivocada. 2. La actualización del wrapper de compilación requiere tanto el comando del wrapper con versión como un segundo comando de generación del wrapper; ejecutar solo el primero deja incoherentes los archivos de wrapper generados. 3. Mantenga en la raíz la configuración general de formato aplicable a todo el repositorio. Trasladarla a un submódulo de la aplicación combinaría tareas de formato incompatibles y activaría errores de validación de dependencias implícitas en la versión `9.x` de la herramienta de compilación. Registre estos problemas cerca de la guía autorizada de compilación y verifíquelos cada vez que cambie la configuración afectada.