Imported from thiagosalaberryj-bit/APP-AHRE-DEMO (AGENTS.md). Install upstream with npx skills add thiagosalaberryj-bit/APP-AHRE-DEMO. Copyright stays with the author.

AGENTS.md

Propósito

Este archivo define las reglas de desarrollo para mantener el proyecto consistente, legible, modular y fácil de mantener. Se aplica a todo el repositorio, salvo que exista otro AGENTS.md en una subcarpeta con instrucciones más específicas para ese ámbito.

La aplicación actual es un proyecto Expo/React Native en JavaScript, orientado principalmente a Android y con funcionamiento local/offline. Su estructura principal incluye src/base-datos, src/navegacion, src/pantallas, src/servicios y src/estilos.

Prioridad y alcance de los cambios

• Antes de modificar archivos, analizar la estructura existente, las convenciones del código cercano y la documentación relevante, especialmente la arquitectura descrita en docs/ARQUITECTURA.md.
• Mantener la organización y las convenciones actuales siempre que no entren en conflicto con una solicitud explícita del usuario.
• Trabajar únicamente dentro del alcance solicitado. No realizar refactorizaciones grandes, cambios de arquitectura, migraciones, reorganizaciones masivas ni modificaciones en áreas no relacionadas sin informar previamente al usuario y obtener su aprobación explícita.
• No cambiar contratos públicos, flujos de navegación, esquema de base de datos, almacenamiento local o comportamiento funcional como efecto secundario de una mejora de estilo o estructura, salvo que la solicitud lo requiera.
• Preservar los cambios existentes del usuario y evitar sobrescribir trabajo no relacionado.

Dependencias y herramientas

• Está prohibido instalar, eliminar, actualizar o reemplazar dependencias sin la aprobación explícita del usuario.
• Esto incluye modificar package.json, package-lock.json o cualquier otro archivo de bloqueo para incorporar cambios de dependencias.
• Antes de sugerir o ejecutar una acción que pueda modificar dependencias, explicar qué se quiere cambiar y por qué, y esperar la aprobación del usuario.
• No ejecutar comandos de instalación o actualización de paquetes como parte de una verificación rutinaria sin autorización explícita.
• Priorizar las dependencias, APIs y utilidades que ya existen en el proyecto.

Convenciones de nombres

Todos los identificadores nuevos creados dentro del proyecto deben escribirse en español. Esto incluye variables, constantes, funciones, métodos, clases, hooks, componentes, props, estados, parámetros, tipos, interfaces, servicios y utilidades.

Se exceptúan:

• palabras reservadas y elementos propios de la sintaxis del lenguaje, como true, false, null, undefined, return, async, await, import, export y default;
• nombres obligatorios definidos por JavaScript, React, React Native, Expo, React Navigation, SQLite u otras librerías;
• nombres de paquetes, módulos, componentes externos, métodos de APIs externas, eventos, opciones de configuración y claves de objetos que deban conservar su forma original para que la integración funcione;
• nombres de archivos generados o exigidos por una herramienta cuando no sea posible cambiarlos.

Cuando un identificador de una librería se use como parte de una integración, conservar su nombre original y nombrar en español el código propio que lo rodea. No renombrar identificadores existentes de forma masiva solo para aplicar esta regla; aplicar la convención a los elementos nuevos y a los que se modifiquen de manera acotada.

Formato de identificadores

• Variables, constantes, funciones, métodos, hooks, clases y componentes propios: camelCase.
• Si React, JSX o una librería exige técnicamente una forma distinta para que un componente o integración funcione, esa forma se considera una excepción propia de la tecnología y debe limitarse al identificador obligatorio.
• Constantes que formen parte de una API o configuración externa: conservar el formato obligatorio de esa API. Para constantes propias, preferir camelCase salvo que el código existente del mismo módulo establezca otra convención.
• Archivos y carpetas nuevos: kebab-case, usando nombres en español cuando sea posible. Por ejemplo, pantalla-inicio.js y servicio-finanzas.js.
• No introducir nombres nuevos en inglés cuando exista una alternativa clara en español.

Organización del código

• Revisar primero los estilos compartidos de src/estilos/estilos-globales.js y reutilizar estilosGlobales, colores y las composiciones existentes antes de crear estilos nuevos.
• Si una pantalla o componente necesita estilos específicos, colocarlos en un archivo separado dedicado exclusivamente a esa pantalla o componente. El nombre del archivo debe respetar kebab-case.
• Evitar mezclar en un mismo archivo la interfaz, los estilos y la lógica de negocio. Mantener, según corresponda, la siguiente separación:
  • pantallas y componentes para la maquetación y la composición visual;
  • archivos de estilos para estilos compartidos o específicos;
  • servicios para acceso a datos y lógica de negocio;
  • src/base-datos para el esquema y el acceso a SQLite;
  • navegación para stacks, tabs y configuración de rutas;
  • hooks y utilidades para lógica reutilizable.
• Mantener cada archivo con una estructura interna clara y ordenada. Siempre que sea razonable, organizarlo en este orden:
  1. importaciones;
  2. constantes y configuraciones locales;
  3. hooks y estado;
  4. funciones auxiliares y lógica derivada;
  5. eventos y efectos;
  6. maquetación o retorno visual;
  7. exportaciones.
• Adaptar ese orden a las convenciones del archivo existente cuando ya haya una estructura establecida; la claridad y la consistencia local tienen prioridad.
• Extraer la lógica reutilizable a funciones, servicios, hooks o utilidades independientes cuando hacerlo reduzca duplicación o mejore la legibilidad.
• Evitar extraer abstracciones prematuras para una sola línea o un único uso si no aportan claridad.

Componentes, pantallas y responsabilidades

• Cada componente debe tener una única responsabilidad, un propósito identificable y una interfaz de props clara.
• Evitar que un componente crezca innecesariamente. Si combina varias responsabilidades, demasiada lógica de estado, acceso a datos y presentación, o una maquetación difícil de leer, dividirlo en componentes más pequeños y cohesivos.
• Mantener la lógica de negocio fuera de los componentes visuales siempre que sea razonable, especialmente el acceso a SQLite, autenticación, cálculos financieros y transformaciones de datos.
• Mantener la pantalla responsable de la composición y del flujo de interacción, delegando el acceso a datos y la lógica reutilizable a las capas correspondientes.
• No duplicar estilos o lógica que ya exista en otra pantalla o servicio sin justificarlo.

Estado, eventos y efectos

• Diferenciar claramente el estado local, el estado derivado, los datos obtenidos de servicios y las constantes.
• Mantener juntos y claramente identificables los hooks de estado relacionados.
• Usar efectos únicamente para sincronizar con sistemas externos, suscripciones, navegación, almacenamiento o ciclos de vida; no usar useEffect para cálculos que puedan realizarse directamente durante el renderizado.
• Declarar los eventos cerca de los elementos que los utilizan o extraerlos a funciones con nombres descriptivos cuando su complejidad lo requiera.
• Gestionar estados de carga, error y ausencia de datos cuando una operación asíncrona los pueda producir.
• Limpiar suscripciones, listeners, temporizadores y efectos secundarios cuando corresponda.

Proceso antes de implementar

1. Identificar los archivos y módulos relacionados con la solicitud.
2. Analizar cómo están organizados y qué convenciones utilizan.
3. Revisar primero las soluciones, estilos, servicios y utilidades existentes que puedan reutilizarse.
4. Definir el cambio mínimo necesario para cumplir la solicitud.
5. Si el cambio implica una refactorización grande, una modificación de arquitectura o un efecto fuera del alcance pedido, detenerse, explicarlo y solicitar aprobación antes de continuar.
6. Implementar respetando las convenciones de nombres, separación de responsabilidades y estructura del proyecto.
7. Ejecutar las verificaciones disponibles sin instalar ni actualizar dependencias.
8. Informar al usuario qué se modificó, qué verificaciones se ejecutaron y cualquier limitación o decisión que requiera su atención.

Verificación y entrega

• Validar los archivos modificados y revisar los cambios para detectar errores de sintaxis, imports inválidos, nombres inconsistentes y duplicación innecesaria.
• Preferir verificaciones enfocadas en el área modificada.
• No ocultar fallos de validación ni corregirlos mediante cambios no relacionados.
• Si una verificación requiere una dependencia no instalada o un cambio en el entorno, informar al usuario y solicitar aprobación antes de modificarlo.
• Mantener la documentación actualizada solo cuando el cambio solicitado afecte su contenido o cuando el usuario lo pida.

Regla general

Ante la duda, elegir el cambio más pequeño que resuelva correctamente la solicitud, reutilizar lo que ya existe, conservar la consistencia del proyecto y consultar al usuario antes de tomar decisiones técnicas de amplio alcance.