ben-eddy74/agent-skills

Workflow Quarkus BCE Backend

Escopo e Limite de Diretório

• LIMITE ESTRITO: Operar APENAS dentro de backend/. Nunca tocar em arquivos de frontend/.
• Arquitetura: Padrão Adam Bien BCE estrito (com.app.<dominio>.{boundary, control, entity}).
• Stack Tecnológico: Quarkus, Jakarta EE (jakarta.* APENAS—nunca javax.* ou org.springframework.*).

Portão de Execução em 2 Fases

Fase 1: Contrato e Espinha Dorsal (PARAR PARA REVISÃO HUMANA)

1. entity: Criar/atualizar payloads imutáveis em Java record (com @NotNull, @NotBlank, @Schema) e entidades JPA/Panache dentro de ..<dominio>.entity. Zero dependências de control ou boundary.
2. boundary: Criar/atualizar assinaturas de recurso JAX-RS @Path (@Transactional, @RolesAllowed, @Operation) dentro de ..<dominio>.boundary.
3. Testes: Criar/atualizar stubs de teste JUnit @QuarkusTest ou testes unitários com falha em backend/src/test/java/..<dominio>/boundary/.
4. PAUSA: Mostrar o diff de entity, boundary e testes ao usuário. Aguardar aprovação antes de escrever a implementação de control.

Fase 2: Implementação e Exportação do Contrato

1. control: Implementar lógica de negócios dentro de ..<dominio>.control (@ApplicationScoped). Nunca chamar o control de outro domínio diretamente; sempre passar pelo boundary dele.
2. Verificar e Exportar Contrato: Executar dentro de backend/:

   ./mvnw test
   

Regras de Linguagem e JVM Java 25 LTS (Obrigatório)

Alvo exclusivo Java 25 LTS (<maven.compiler.release>25</maven.compiler.release>). Nunca escrever código legado Java 8/11/17:

1. Switch Exaustivo e Decomposição de Records (control & entity):
   • Modelar resultados de domínio e máquinas de estado usando sealed interface + implementações record em entity.
   • Em control, processá-los usando expressões switch exaustivas com decomposição de records e cláusulas when guardadas (ex.: case PaidOrder(var id, var total) when total > 1000 -> ...).
   • NUNCA incluir uma ramificação default em um switch de uma sealed interface para que o compilador Java 25 force a exaustividade quando novos estados forem adicionados.
2. Corpos de Construtores Flexíveis (JEP 513):
   • Realizar validação fail-fast e normalização de dados diretamente dentro dos construtores antes de chamar super(...) ou this(...) em vez de criar métodos auxiliares estáticos inchados.
3. Variáveis Sem Nome (_):
   • Sempre usar _ para parâmetros lambda não utilizados, variáveis de exceção ignoradas ou componentes de records não utilizados (ex.: case Order(var id, _, _)).
4. Threads Virtuais e Scoped Values (JEP 506):
   • Para endpoints de I/O bloqueantes em boundary do Quarkus, preferir @RunOnVirtualThread em vez de cadeias reativas Uni<T> a menos que streaming seja necessário.
   • Nunca usar ThreadLocal; sempre usar ScopedValue<T> do Java 25 se estado contextual precisar ser passado dentro de um escopo de thread.
5. Coleções Modernas e Stream Gatherers (JEP 485):
   • Usar métodos de SequencedCollection (.getFirst(), .getLast(), .reversed()) em vez de cálculos de índice list.get(list.size() - 1).
   • Usar Stream.gather(Gatherers.windowFixed(...)) em vez de loops manuais de particionamento.
6. Sem Flags de Preview a Menos que Solicitado:
   • Manter-se nos recursos finalizados do Java 25 LTS (não habilitar --enable-preview para padrões primitivos JEP 507 ou concorrência estruturada JEP 505 a menos que explicitamente solicitado).