Este archivo define cómo los agentes de IA deben trabajar con este repositorio. Siempre leer este archivo completo antes de realizar cualquier cambio en el código. --- ## Flujo de trabajo Antes de empezar cualquier tarea en este repositorio: 1. Leer `/ai/PROJECT_CONTEXT.md` 2. Leer `/ai/AGENT_MEMORY.md` 3. Leer `/ai/TASK_LOG.md` 4. Revisar la carpeta `/plans` para entender planes existentes. Usar esos archivos como fuente de verdad del proyecto. --- ## Reglas - Tomar solo una tarea a la vez desde `TASK_LOG.md` - Hacer cambios pequeños y trazables - No realizar refactors masivos sin justificación - Mantener consistencia con la arquitectura existente --- ## Commits - Cada tarea debe implementarse en commits pequeños y claros. - Evitar commits grandes con múltiples cambios no relacionados. - Usar mensajes de commit descriptivos. --- ## Después de completar una tarea 1. Actualizar `/ai/TASK_LOG.md` 2. Si hubo aprendizaje nuevo, actualizar `/ai/AGENT_MEMORY.md` 3. Si hubo mejora del proceso, actualizar `/ai/IMPROVEMENTS.md` 4. Realizar una revisión UX puntual del cambio implementado: - Verificar que el copy (etiquetas, mensajes de error, confirmaciones) sea claro y consistente con el resto del sistema. - Comprobar que los estados vacíos, de carga y de error estén cubiertos visualmente. - Si se detecta alguna mejora concreta y pequeña, proponerla — no implementarla sin aprobación. --- ## Tests Toda función crítica del sistema debe tener tests unitarios o de integración. Se considera función crítica cualquier lógica que involucre: - Cálculos financieros (amortización, intereses, moratorios, enganches, plazos) - Validaciones de negocio (asignación de lotes, cambios de estatus, publicación de plantillas) - Servicios con lógica compleja (ingesta de SVG, extracción de nodos, sanitización) Reglas: - Al implementar una función crítica, crear el test en el mismo commit o en el siguiente inmediato. - Los tests deben cubrir el caso exitoso, casos borde y errores esperados. - Ubicar los tests en `tests/Unit/` para lógica pura y `tests/Feature/` para flujos HTTP. - No se considera completa una tarea crítica si no tiene al menos un test que la cubra. --- ## Consistencia de diseño y arquitectura ### Antes de escribir cualquier código nuevo 1. Buscar si ya existe un componente, helper, servicio o patrón que resuelva lo mismo. 2. Revisar vistas similares ya implementadas para replicar estructura y estilo. 3. Si existe algo parecido, extenderlo o reutilizarlo — nunca duplicarlo con variaciones. ### UI y vistas Blade - Usar siempre los mismos componentes Blade (``, cards, badges, botones) que el resto del sistema. - La ubicación de acciones debe ser consistente: botones primarios a la izquierda, secundarios/cancelar a la derecha. - Los formularios, tablas y modales deben seguir la misma estructura visual que las vistas existentes. - Antes de escribir HTML ad-hoc, verificar si ya existe un componente o partial reutilizable. ### Código PHP y servicios - Si una operación ya existe en un Service, Controller o Model, usarla — no reimplementarla inline. - Los métodos nuevos en servicios deben seguir el mismo estilo de retorno y manejo de errores que los existentes. - Consultar `app/Services/`, `app/Models/` y `app/Http/Controllers/` antes de crear lógica nueva. --- ## Trabajo con planes Al implementar nuevas funcionalidades: 1. Buscar en `/plans` si ya existe un plan relacionado. 2. Si no existe, crear un nuevo plan dentro de `/plans` con el siguiente formato: `{fecha}-titulo-del-plan.md`. 3. Revisar y validar el plan antes de comenzar a programar. 4. Implementar el plan en commits pequeños y enfocados. 5. Actualizar el estado del plan conforme avance la implementación.