# AGENTS.md ## Ámbito y objetivo Estas instrucciones se aplican a todo el monorepo, salvo que un `AGENTS.md` descendiente las concrete o restrinja sin duplicarlas innecesariamente. Trabajar mediante cambios correctos, mínimos, comprobables, seguros, coherentes con la arquitectura y fáciles de revisar y mantener. Priorizar claridad y explicitud frente a abstracción prematura. ## Entorno Trabajar en WSL2 Ubuntu mediante Linux y `bash`, usando la ruta canónica: ```text /home/david/dev/uecko-control-tiempos ``` Antes de una tarea de código relevante, ejecutar: ```bash pwd git rev-parse --show-toplevel git status --short node --version pnpm --version ``` El entorno objetivo es Node.js 24.x y PNPM 11.25.0. Si no coincide, identificar la causa antes de modificar código. No usar Windows, PowerShell, rutas UNC, `/mnt/c`, copias antiguas ni workspaces alternativos salvo petición expresa. No cambiar runtime, gestor de paquetes ni `packageManager` como efecto colateral. ## Secretos y configuración local No exponer, copiar en respuestas, registrar ni versionar secretos, credenciales, claves, tokens, contraseñas o cadenas de conexión. No modificar configuración local salvo que la tarea lo requiera expresamente. ## Antes de modificar código Para cambios no triviales: 1. Inspeccionar el código y flujo relevantes. 2. Identificar módulos, contratos, consumidores, dependencias, persistencia, tests, documentación y efectos laterales afectados. 3. Buscar patrones equivalentes antes de crear una abstracción, clase, servicio, hook, componente, mapper, repositorio, schema, tipo o mecanismo de validación. 4. Localizar la causa raíz de un bug; no aplicar fixes especulativos. 5. Determinar alcance y validación antes de implementar cuando corresponda. Reutilizar o extender soluciones existentes cuando sean adecuadas. No crear abstracciones solo para eliminar una duplicación pequeña y local. ## Control del alcance Modificar solo lo necesario. No realizar refactors, renombrados, movimientos, reformateos masivos, limpiezas, cambios de API, actualizaciones de dependencias o configuración global ajenos a la tarea. Informar de problemas adicionales y no corregirlos salvo que bloqueen el objetivo o estén incluidos expresamente. ## Documentación normativa Antes de modificar un área, consultar el documento aplicable y no violar sus límites: - [Visión general](docs/arquitectura/vision-general.md): módulos, dependencias y composición. - [Backend](docs/arquitectura/backend.md): capas, contratos HTTP, casos de uso, dominio, errores y seguridad. - [Convenciones](docs/arquitectura/convenciones.md): TypeScript, naming, async, comentarios, dependencias y documentación. - [Datos y persistencia](docs/arquitectura/datos-persistencia.md): ORM, transacciones, integridad, migraciones e histórico. - [Frontend](docs/arquitectura/frontend.md): estado, formularios, UI, accesibilidad e i18n. - [Testing](docs/arquitectura/testing.md): cobertura y estrategia de validación. - [Flujo de trabajo](docs/guias/flujo-chatgpt-codex.md) y [cierre de tareas](docs/guias/cierre-de-tareas.md): procedimiento operativo. - [Ficha del proyecto](docs/Ficha%20del%20proyecto%20UECKO.md): contexto e invariantes funcionales disponibles. No afirmar que una regla, tecnología o arquitectura esté implementada si no existe evidencia en el repositorio. ## Dependencias y seguridad No añadir ni actualizar dependencias sin necesidad real y justificada; comprobar primero alternativas existentes, mantenimiento, compatibilidad e impacto. No modificar lockfiles incidentalmente ni añadir supresiones de análisis sin justificación. Validar entradas externas, preservar autorización, aislamiento de datos y controles de seguridad definidos en la documentación normativa. Aplicar siempre el principio de menor privilegio. ## Validación Usar primero la validación más acotada que aporte evidencia suficiente. Consultar los scripts reales antes de ejecutarlos; no inventar comandos. Preferir el workspace afectado cuando baste y validación global para cambios transversales. Añadir o actualizar tests cuando cambie comportamiento observable. Informar exactamente de los comandos ejecutados y sus resultados. Distinguir fallos introducidos, preexistentes, ajenos al área y validaciones no ejecutadas; no atribuir ni ocultar fallos sin evidencia. ## Refactors, legacy y archivos generados Un refactor preserva comportamiento salvo indicación expresa. Para uno grande: auditar, identificar consumidores, dividir en fases y validar entre ellas. Antes de eliminar legacy, buscar referencias en todo el monorepo y revisar imports, rutas, entry points, composition roots, DI, modelos, repositorios, mappers, tests, scripts y documentación. Cuando resulte relevante, clasificar las referencias como activas, legacy no cableado, migraciones, documentación, tests o falsos positivos. Eliminar solo lo demostrado como no utilizado, documentar referencias residuales justificadas y ejecutar las validaciones relevantes después. No modificar manualmente archivos generados; utilizar su procedimiento oficial y no incluir artefactos no relacionados. ## Git Mantener cambios pequeños y revisables. Antes de finalizar ejecutar: ```bash git status --short git diff ``` Revisar cambios accidentales, formato, código temporal, logs, artefactos generados, secretos y lockfiles. No hacer commits, pushes, resets destructivos ni reescribir historial sin petición expresa. ## Cierre e informe Una tarea es completa solo cuando el objetivo y alcance están cubiertos, la arquitectura se respeta, las validaciones relevantes aportan evidencia, no hay cambios accidentales y se declaran limitaciones reales. Usar los estados `COMPLETA`, `PARCIAL` o `BLOQUEADA` según la guía de cierre. En tareas relevantes, informar de: estado, diagnóstico o causa raíz, cambios, decisiones relevantes, archivos principales, comandos de validación, resultados y riesgos o pendientes. ## Fuente de verdad y precedencia Para instrucciones operativas, prevalecen: requisito explícito de la tarea, `AGENTS.md` más cercano, `AGENTS.md` superiores, este fichero, guías operativas y convenciones existentes. Para producto y arquitectura, prevalecen: requisitos vigentes, documentación normativa, contratos e invariantes establecidos, tests de comportamiento intencionado, implementación, documentación auxiliar y suposiciones. No usar `AGENTS.md` para contradecir silenciosamente documentación normativa. Ante discrepancias relevantes entre código, tests y documentación, investigarlas y señalar el conflicto antes de cambiar comportamiento.