ben-eddy74/agent-skills

Flujo de Trabajo del Backend Quarkus BCE

Alcance y Límite del Directorio

• LÍMITE ESTRICTO: Operar SOLO dentro de backend/. Nunca tocar archivos de frontend/.
• Arquitectura: Patrón BCE estricto de Adam Bien (com.app.<dominio>.{boundary, control, entity}).
• Stack Tecnológico: Quarkus, Jakarta EE (jakarta.* SOLAMENTE—nunca javax.* o org.springframework.*).

Puerta de Ejecución en 2 Fases

Fase 1: Contrato y Esqueleto (PARAR PARA REVISIÓN HUMANA)

1. entity: Crear/actualizar record inmutables de Java con carga útil (con @NotNull, @NotBlank, @Schema) y entidades JPA/Panache dentro de ..<dominio>.entity. Cero dependencias de control o boundary.
2. boundary: Crear/actualizar firmas de recursos JAX-RS @Path (@Transactional, @RolesAllowed, @Operation) dentro de ..<dominio>.boundary.
3. Pruebas: Crear/actualizar pruebas JUnit @QuarkusTest o stubs de prueba unitaria fallidos en backend/src/test/java/..<dominio>/boundary/.
4. PAUSA: Mostrar el diff de entity, boundary y las pruebas al usuario. Esperar la aprobación antes de escribir la implementación de control.

Fase 2: Implementación y Exportación del Esquema

1. control: Implementar la lógica de negocio dentro de ..<dominio>.control (@ApplicationScoped). Nunca llamar directamente al control de otro dominio; siempre a través de su boundary.
2. Verificar y Exportar Contrato: Ejecutar dentro de backend/:

   ./mvnw test
   

Reglas del Lenguaje Java 25 LTS y JVM (Obligatorias)

Apuntar exclusivamente a Java 25 LTS (<maven.compiler.release>25</maven.compiler.release>). Nunca escribir código boilerplate heredado de Java 8/11/17:

1. Switch Exhaustivo y Deconstrucción de Registros (control y entity):
   • Modelar resultados del dominio y máquinas de estado usando sealed interface + implementaciones de record en entity.
   • En control, procesarlos usando expresiones switch exhaustivas con deconstrucción de patrones de registro y cláusulas when guardadas (ej., case PaidOrder(var id, var total) when total > 1000 -> ...).
   • NUNCA incluir una rama default en un switch para una sealed interface, de modo que el compilador de Java 25 imponga la exhaustividad cuando se agreguen nuevos estados.
2. Cuerpos de Constructores Flexibles (JEP 513):
   • Realizar validación rápida de fallos y normalización de datos directamente dentro de los constructores antes de llamar a super(...) o this(...), en lugar de crear métodos auxiliares estáticos hinchados.
3. Variables Sin Nombre (_):
   • Usar siempre _ para parámetros lambda no utilizados, variables de excepción ignoradas o componentes de registros deconstruidos no utilizados (ej., case Order(var id, _, _)).
4. Hilos Virtuales y Valores de Ámbito (JEP 506):
   • Para puntos finales de E/S bloqueantes en boundary de Quarkus, preferir @RunOnVirtualThread sobre cadenas reactivas Uni<T> a menos que se requiera streaming.
   • Nunca usar ThreadLocal; siempre usar ScopedValue<T> de Java 25 si se debe pasar estado contextual dentro de un ámbito de hilo.
5. Colecciones Modernas y Recolectores de Streams (JEP 485):
   • Usar métodos de SequencedCollection (.getFirst(), .getLast(), .reversed()) en lugar de matemáticas de índice list.get(list.size() - 1).
   • Usar Stream.gather(Gatherers.windowFixed(...)) en lugar de bucles de fragmentación manuales.
6. Sin Banderas de Vista Previa a Menos Que Se Solicite:
   • Mantenerse en las características finalizadas de Java 25 LTS (no habilitar --enable-preview para JEP 507 de patrones primitivos o JEP 505 de concurrencia estructurada a menos que se solicite explícitamente).