# AGENTS.md

## Objetivo del proyecto

Este repositorio contiene una aplicación Laravel que continuará en desarrollo mientras existe una versión estable desplegada en AWS.

## Reglas obligatorias

1. Nunca modificar directamente la rama `main`.
2. No ejecutar comandos sobre producción.
3. No modificar archivos `.env`.
4. No incluir contraseñas, tokens, llaves o credenciales en el código.
5. Todo cambio de estructura de base de datos debe realizarse mediante una migración.
6. Nunca ejecutar `migrate:fresh`, `db:wipe` o comandos destructivos sin autorización expresa.
7. No instalar, eliminar ni actualizar paquetes sin explicar:

   * motivo;
   * compatibilidad;
   * riesgos;
   * alternativas.
8. Antes de modificar código:

   * explicar el flujo actual;
   * identificar los archivos relacionados;
   * proponer el cambio;
   * señalar riesgos.
9. Mantener los controladores delgados.
10. Usar Form Requests para validaciones reutilizables o relevantes.
11. Usar Policies, Gates o permisos centralizados para autorización.
12. Colocar la lógica importante de negocio en clases claramente identificables.
13. Usar transacciones para procesos que modifican múltiples registros relacionados.
14. Evitar consultas dentro de ciclos y problemas N+1.
15. No cambiar nombres de tablas, columnas, rutas o contratos de API sin advertir el impacto.
16. Mantener compatibilidad con las versiones declaradas en `composer.json` y `package.json`.
17. Crear o actualizar pruebas para procesos críticos.
18. Ejecutar las pruebas relacionadas antes de dar una tarea por terminada.
19. No corregir archivos ajenos al alcance solicitado.
20. No hacer refactorizaciones extensas junto con una corrección pequeña.
21. Mostrar siempre:

* archivos modificados;
* resumen de cambios;
* comandos ejecutados;
* pruebas realizadas;
* riesgos o pendientes.

## Flujo de trabajo

Cada tarea debe realizarse en una rama independiente:

* `feature/nombre`: funcionalidad nueva.
* `fix/nombre`: corrección.
* `refactor/nombre`: mejora interna.
* `docs/nombre`: documentación.
* `audit/nombre`: auditorías.
* `release/x.y.z`: preparación de versión.

## Definición de terminado

Una tarea solamente se considera terminada cuando:

* cumple el requerimiento;
* no expone datos sensibles;
* las validaciones están implementadas;
* los permisos están verificados;
* las pruebas relacionadas pasan;
* no hay cambios accidentales;
* se documentan los pasos necesarios para desplegarla;
* se informa si requiere migraciones, colas, cron, caché o cambios de variables de entorno.