ben-eddy74/agent-skills

Quarkus BCE 백엔드 워크플로우

범위 및 디렉터리 경계

• 엄격한 경계: backend/ 내부에서만 작동합니다. 절대 frontend/ 파일을 건드리지 마세요.
• 아키텍처: 엄격한 Adam Bien BCE 패턴 (com.app.<domain>.{boundary, control, entity}).
• 기술 스택: Quarkus, Jakarta EE (jakarta.*만 사용—절대 javax.*나 org.springframework.*를 사용하지 마세요).

2단계 실행 게이트

1단계: 계약 및 스켈레톤 (인간 검토를 위해 중지)

1. entity: 불변 Java record 페이로드(@NotNull, @NotBlank, @Schema 포함)와 JPA/Panache 엔티티를 ..<domain>.entity 내부에 생성/업데이트합니다. control 또는 boundary에 대한 의존성은 없습니다.
2. boundary: JAX-RS @Path 리소스 시그니처(@Transactional, @RolesAllowed, @Operation)를 ..<domain>.boundary 내부에 생성/업데이트합니다.
3. 테스트: backend/src/test/java/..<domain>/boundary/에 실패하는 JUnit @QuarkusTest 또는 단위 테스트 스텁을 생성/업데이트합니다.
4. 일시 중지: entity, boundary 및 테스트의 diff를 사용자에게 보여줍니다. control 구현을 작성하기 전에 승인을 기다립니다.

2단계: 구현 및 스키마 내보내기

1. control: ..<domain>.control 내부에 비즈니스 로직을 구현합니다(@ApplicationScoped). 다른 도메인의 control을 직접 호출하지 말고 항상 해당 boundary를 통해 호출하세요.
2. 계약 확인 및 내보내기: backend/ 내에서 다음을 실행합니다.

   ./mvnw test
   

Java 25 LTS 언어 및 JVM 규칙 (필수)

Java 25 LTS만 대상으로 합니다(<maven.compiler.release>25</maven.compiler.release>). 레거시 Java 8/11/17 상용구를 작성하지 마세요:

1. 완전한 Switch 및 Record 분해 (control 및 entity):
   • 도메인 결과 및 상태 머신을 entity에서 sealed interface + record 구현을 사용하여 모델링합니다.
   • control에서는 완전한 switch 표현식에 record 패턴 분해 및 가드 when 절을 사용하여 처리합니다(예: case PaidOrder(var id, var total) when total > 1000 -> ...).
   • sealed interface switch에 default 분기를 절대 포함하지 마세요. Java 25 컴파일러가 새 상태가 추가될 때 완전성을 강제합니다.
2. 유연한 생성자 본문 (JEP 513):
   • 비대해진 정적 헬퍼 메서드를 만드는 대신 super(...) 또는 this(...)를 호출하기 전에 생성자 내부에서 직접 빠른 실패 검증 및 데이터 정규화를 수행합니다.
3. 무명 변수 (_):
   • 사용되지 않는 람다 매개변수, 무시된 예외 변수 또는 사용되지 않는 분해된 record 구성 요소에는 항상 _를 사용합니다(예: case Order(var id, _, _)).
4. 가상 스레드 및 범위 값 (JEP 506):
   • Quarkus boundary의 블로킹 I/O 엔드포인트의 경우 스트리밍이 필요하지 않으면 반응형 Uni<T> 체인보다 @RunOnVirtualThread를 선호합니다.
   • ThreadLocal을 절대 사용하지 말고, 스레드 범위 내에서 컨텍스트 상태를 전달해야 하는 경우 항상 Java 25 ScopedValue<T>를 사용하세요.
5. 현대적인 컬렉션 및 스트림 수집기 (JEP 485):
   • 인덱스 수학 list.get(list.size() - 1) 대신 SequencedCollection 메서드(.getFirst(), .getLast(), .reversed())를 사용하세요.
   • 수동 청킹 루프 대신 Stream.gather(Gatherers.windowFixed(...))를 사용하세요.
6. 요청되지 않은 경우 미리보기 플래그 사용 금지:
   • 확정된 Java 25 LTS 기능만 사용하세요(명시적으로 요청하지 않는 한 JEP 507 기본형 패턴 또는 JEP 505 구조적 동시성을 위해 --enable-preview를 활성화하지 마세요).