Haz que un agente de programación siga las reglas de un gran repositorio full-stack

## Pasa el pre-commit antes de cada push Ejecuta siempre la suite de pre-commit del repositorio sobre todos los archivos antes de subir commits. La integración continua falla cuando fallan las comprobaciones de pre-commit, así que esto es una barrera innegociable, no una preferencia. Cómo ejecutarla de forma eficiente: - Prepara primero los cambios en el área de staging. El pre-commit inspecciona únicamente los archivos preparados, por lo que una edición sin preparar se omite en silencio. - Para un ciclo interno rápido, ejecuta la suite sobre los archivos preparados, o ejecuta un único hook con nombre (comprobador de tipos, formateador, linter). Ejecuta la pasada sobre todos los archivos antes del push que abre o actualiza un pull request. - Activa el entorno virtual o el shell de la cadena de herramientas del proyecto antes de ejecutar. Las ubicaciones habituales varían según el desarrollador; si no se encuentra el comando, pregunta al usuario qué entorno activar en lugar de adivinar una ruta. - Algunos hooks corrigen automáticamente (formateadores, espacios en blanco al final). Vuelve a preparar los archivos corregidos y vuelve a ejecutar, porque la primera pasada informa de fallos que ya ha reparado. Espera tres clases de fallo: problemas de formato que se corrigen automáticamente, errores del comprobador de tipos que requieren correcciones manuales y errores de lint que requieren correcciones manuales. ## Escribe el código nuevo con los patrones a los que migra el repositorio Varias migraciones están activamente en curso. Todavía existe código que coincide con el patrón antiguo, así que su presencia no es permiso para escribir más de ese tipo. El código nuevo y el modificado siguen el patrón objetivo. - Frontend tipado: nada de tipos `any` como escapatoria, ni nuevos archivos de script sin tipar — escribe en el dialecto tipado y reutiliza las definiciones de tipos existentes. - Capa de componentes compartidos: importa los componentes de UI desde el paquete de sistema de diseño propio del proyecto en lugar de la biblioteca de terceros directamente, prefiere los tokens de tematización del sistema de diseño frente a los heredados y evita el CSS a medida en favor del estilizado soportado por la biblioteca de componentes. - Pirámide de pruebas: prefiere las pruebas unitarias sobre las de integración, y las de integración sobre las de extremo a extremo. Escribe las nuevas pruebas de extremo a extremo en el framework adoptado; el framework de extremo a extremo reemplazado está obsoleto y se eliminará cuando la migración se complete. - Tipado del backend: todo el código nuevo lleva anotaciones de tipo, los modelos usan anotaciones adecuadas y el comprobador de tipos debe pasar. - Migración de identificadores: los modelos nuevos usan identificadores únicos opacos como claves primarias, las API públicas exponen esos identificadores en lugar de los enteros secuenciales internos, y los modelos existentes incorporan el nuevo identificador junto al entero para una transición gradual. ## Juzga los problemas de seguridad según lo que puede hacer cada rol Antes de evaluar cualquier ruta de código en busca de problemas de seguridad, lee el documento canónico de política de seguridad del repositorio. Es la fuente autorizada del modelo de seguridad y es aquello con lo que se contrastan tanto los informantes humanos como los escáneres automatizados. La única prueba para determinar si un hallazgo está dentro del alcance: ¿permite a un principal realizar una acción a la que la matriz de roles y capacidades de la política de seguridad no le da derecho? Si es así, está dentro del alcance. Si no, no lo está. Tres límites de confianza enmarcan esa prueba: 1. El rol de administrador es un principal operativo plenamente confiable. Cualquier cosa que un administrador pueda hacer mediante la configuración, la API o la UI documentadas es una capacidad prevista, no una vulnerabilidad. 2. El operador es dueño de las decisiones del momento del despliegue: secretos, exposición de red, selección de feature flags, elección de conectores y códecs, destinos de notificación y plugins de terceros. Una mala configuración en esta capa es un defecto de despliegue, no una vulnerabilidad del producto. 3. La base de código es responsable de aplicar la matriz de roles y capacidades en todos los lugares donde expone funcionalidad a un principal — rutas de API, capas de comandos y de acceso a datos, manejadores de UI, trabajos en segundo plano y cualquier otro punto de entrada. Una comprobación de aplicación ausente o incorrecta está dentro del alcance sin importar dónde resida. El modelo asume que la infraestructura controlada por el operador — base de datos de metadatos, cachés, brokers de mensajes, almacenes de secretos, entorno de despliegue — permanece dentro del límite de confianza del operador. Un hallazgo válido debe demostrar una violación del límite por parte de un atacante que no controle ya esos sistemas. ## Usa la comprobación de permisos correcta para cada ruta y tipo de datos La autorización a nivel de ruta usa un decorador por clase de ruta, y el correcto depende del tipo de ruta: uno para la superficie moderna de API REST, uno para las rutas de vista JSON heredadas y uno para las rutas de vista HTML heredadas. Confundirlos es un fallo de aplicación incluso cuando parece haber una comprobación presente. La autorización a nivel de objeto es una segunda barrera, independiente. Se aplica a los recursos portadores de datos — dashboards, gráficos, conjuntos de datos y fuentes de datos, consultas, acceso a bases de datos y tablas, y contextos de consulta — y se invoca por objeto a través de la comprobación de acceso del gestor de seguridad. El código que omite la barrera por objeto en una ruta que devuelve o muta un objeto portador de datos concreto está dentro del alcance. Otros recursos — anotaciones, etiquetas, plantillas de estilo, informes, reglas de seguridad a nivel de fila y similares — se apoyan deliberadamente en el decorador a nivel de ruta más el ámbito de propiedad en los filtros base de la capa de acceso a datos. La ausencia de una comprobación por objeto en estos recursos es intencionada y no es un hallazgo. Seguir el patrón de autorización correcto para una clase de recurso no exime al código de otros problemas. La inyección, la falsificación de solicitudes del lado del servidor, el cross-site scripting y clases similares no guardan relación con la autorización y se evalúan por separado. ## Exige a los escáneres automáticos indicar la regla rota y el rol del atacante Los escáneres automatizados — escáneres de código basados en modelos, analizadores estáticos y herramientas de dependencias — deben, en cada hallazgo que presenten contra esta base de código, nombrar explícitamente dos cosas: 1. La fila concreta de la matriz de roles y capacidades de la política de seguridad que el hallazgo considera violada. 2. El principal que el hallazgo asume que posee el atacante: un principal anónimo o público, un rol autenticado de bajo privilegio, un rol de herramienta de consulta, un rol de autoría elevado, el rol de administrador, un token de invitado embebido o un rol personalizado con nombre y concesiones de capacidades explícitas. Un hallazgo que no pueda identificar ambos debe presentarse como una pregunta, no como una vulnerabilidad. Este requisito existe para que cada problema reportado sea comprobable frente al modelo de seguridad publicado, y para que los informes especulativos o basados solo en coincidencia de patrones queden fuera de la cola de triaje. ## Sigue los estándares de código del frontend y el backend Frontend: evita `any` y reutiliza los tipos existentes; escribe componentes funcionales con hooks; toma los componentes de UI del paquete compartido de sistema de diseño en lugar de importar la biblioteca de terceros directamente; usa el ejecutor de pruebas y la biblioteca de testing estándar del proyecto, no el renderizador heredado ya eliminado; usa el store global donde ya exista y estado local de hooks en los demás casos. Backend: las anotaciones de tipo son obligatorias para todo el código nuevo, el comprobador estático de tipos debe pasar, los modelos de datos llevan tipado adecuado y se usa el framework de pruebas estándar del proyecto para las pruebas. Al construir consultas, usa el operador de negación del ORM sobre una columna booleana en lugar de compararla con un literal falso, comparación que el linter marca. Cabeceras de licencia: los archivos de código fuente nuevos requieren la cabecera de licencia estándar del proyecto. Los archivos de instrucciones para agentes (este archivo y sus equivalentes por proveedor) se excluyen deliberadamente de ese requisito para no gastar tokens en la cabecera. Comentarios: evita el lenguaje ligado al momento, como «ahora», «actualmente» o «hoy», porque queda desfasado. Escribe comentarios que sigan siendo exactos cuando quiera que se lean. ## Actualiza la documentación y las notas de cambios incompatibles junto con el código La documentación forma parte del cambio, no es una tarea posterior: - Actualiza el árbol de documentación ante cualquier cambio visible para el usuario. - Registra los cambios incompatibles en el archivo dedicado de notas de actualización para que los operadores puedan encontrarlos en un solo sitio. - Escribe docstrings para cada nueva función y clase. Cuando un cambio afecta a un comportamiento que un operador o un usuario final puede observar, un pull request sin la edición de documentación correspondiente está incompleto. ## Corrige la documentación de componentes en las stories, no en el generador El portal de desarrolladores autogenera la documentación de componentes a partir de las stories del catálogo de componentes. Las stories son la única fuente de verdad, lo que impone dos reglas: cuando algo se renderiza incorrectamente, corrige primero el archivo de la story en lugar del generador, y mantén el generador ligero — extrae y transmite los datos de la story, así que resiste la tentación de añadirle casos especiales por componente. Para que la documentación de un componente se genere correctamente, su archivo de story debe: - Exportar el objeto de metadatos en línea como exportación por defecto, en lugar de asignarlo a una variable y exportar esa variable. - Nombrar las stories interactivas con un prefijo coherente más el nombre del componente. - Definir los valores por defecto de las props en los argumentos de la story. - Definir los tipos de argumento a nivel de story, no a nivel de metadatos, incluidos los tipos de control y las descripciones. - Usar las claves de parámetro documentadas para las cuadrículas de variantes, los hijos de muestra para los componentes que los necesiten, los bloques de código en vivo personalizados y las props de objetos complejos que no puedan analizarse en línea. Ten presentes el script generador, su componente envoltorio y el directorio de salida generado como las tres piezas móviles al diagnosticar un problema de documentación. ## Usa los helpers de prueba del repositorio en lugar de montar tu propia preparación El repositorio incluye helpers; úsalos en lugar de montar la configuración a mano. En el backend eso significa la clase base de pruebas compartida, decoradores para simular la configuración y activar o desactivar feature flags, helpers de autenticación para iniciar sesión con un rol dado y helpers de fábrica para crear los fixtures que una prueba necesita. En el frontend eso significa el helper de render personalizado que instala los providers estándar, la fábrica de envoltorios para store, router y tema, y el helper de interacción con selects. Reglas de mocking: usa un mock simple para los objetos de configuración y no recurras a un mock asíncrono cuando el código bajo prueba es síncrono. Cuando un modelo gana un campo nuevo, actualiza las listas de columnas esperadas en las pruebas de API. Debes saber cómo ejecutar cada suite: toda la suite de frontend, un único archivo de prueba de frontend, todas las pruebas de backend, un único archivo de prueba de backend, un directorio de pruebas de backend y la suite de extremo a extremo en los modos headless, interactivo, headed y de depuración. Si las pruebas de backend fallan por la configuración de la base de datos o del entorno y no por el código bajo prueba, pide al usuario que ejecute la configuración del entorno de pruebas en lugar de improvisar arreglos en su entorno. ## Comprueba el endpoint de salud de la aplicación antes de depurar Ejecuta primero la comprobación rápida de instalación: llama al endpoint de salud de la aplicación y confirma que responde antes de dedicar tiempo a un informe de error. Una comprobación de salud fallida suele significar que el espacio de trabajo nunca se configuró, no que el código esté roto. Si la comprobación de salud falla, dile al usuario que el entorno no parece estar configurado y remítelo a las instrucciones de instalación documentadas del proyecto para trabajar con agentes, en lugar de intentar reparar su entorno tú mismo. Conoce los archivos clave del proyecto al orientarte: el manifiesto del paquete de frontend para los scripts de build, test y lint y el puerto del servidor de desarrollo; el archivo de proyecto de Python para la configuración del linter y del comprobador de tipos; y la carpeta de requisitos de dependencias dividida en conjuntos base y de desarrollo. ## Rellena la plantilla de pull request y usa títulos en formato conventional commits Al abrir un pull request: 1. Lee el archivo actual de plantilla de pull request del repositorio antes de redactar. Lee siempre el archivo real en lugar de reutilizar contenido en caché, porque la plantilla cambia con el tiempo. 2. Rellena cada sección que la plantilla defina — resumen, evidencia del antes y el después, instrucciones de prueba e información adicional. 3. Titula el pull request usando el formato de conventional commits `type(scope): description`, por ejemplo `fix(dashboard): load charts correctly`. Los tipos válidos son `fix`, `feat`, `docs`, `style`, `refactor`, `perf`, `test` y `chore`. ## Aprende la estructura de carpetas y los patrones de archivos antes de editar código desconocido Dos hábitos mantienen los cambios en el lugar correcto dentro de un repositorio grande. Primero, aprende el mapa de directorios antes de editar: qué árbol contiene la aplicación de backend, sus endpoints de API, modelos de datos y conectores; qué árbol contiene el código fuente del frontend y sus áreas de componentes, constructor de gráficos, dashboards y editor de consultas; dónde vive el paquete compartido de sistema de diseño; y dónde se sitúan las pruebas, la documentación y el registro de cambios incompatibles. Segundo, conoce los patrones de archivo recurrentes para que una nueva funcionalidad aterrice en los archivos convencionales: el módulo de API para los endpoints con sus decoradores y docstrings que generan el esquema, el módulo de esquemas para la validación de solicitudes y respuestas que alimenta la especificación de API generada, la capa de comandos para la lógica de negocio envuelta en transacciones y la capa de modelos para la persistencia. La documentación de API generada se deriva de esos docstrings y esquemas, así que un cambio de endpoint sin actualizar el docstring la degrada en silencio. Las migraciones de base de datos siguen su propia convención: viven en el directorio de versiones de migraciones, se nombran con una marca de tiempo, un hash de revisión y una descripción, y deben llamar a los helpers de utilidad de migración compartidos en lugar de a operaciones ORM en crudo, para que sigan siendo compatibles entre motores de base de datos. Por último, ten en cuenta que este repositorio mantiene archivos de instrucciones paralelos para distintos proveedores de agentes. Mantenlos coherentes cuando cambies una regla que se aplique a todos ellos.