uecko-control-tiempos/AGENTS.md

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:

/home/david/dev/uecko-control-tiempos

Antes de una tarea de código relevante, ejecutar:

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: módulos, dependencias y composición.
• Backend: capas, contratos HTTP, casos de uso, dominio, errores y seguridad.
• Convenciones: TypeScript, naming, async, comentarios, dependencias y documentación.
• Datos y persistencia: ORM, transacciones, integridad, migraciones e histórico.
• Frontend: estado, formularios, UI, accesibilidad e i18n.
• Testing: cobertura y estrategia de validación.
• Flujo de trabajo y cierre de tareas: procedimiento operativo.
• Ficha del proyecto: 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. Eliminar solo lo demostrado como no utilizado y documentar referencias residuales justificadas.

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:

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.