401-frameworks-quarkus-core

Original：🇺🇸 English
Translated

Use when building or reviewing core Quarkus applications with CDI beans and scopes, SmallRye Config and profiles, lifecycle, interceptors and events, health probes, virtual threads, and test-friendly design. Part of the skills-for-java project

3installs
Sourcejabrena/cursor-rules-java
Added on

NPX Install

npx skill4agent add jabrena/cursor-rules-java 401-frameworks-quarkus-core

Tags

Translated version includes tags in frontmatter
quarkus-corecdi-beanssmallrye-configjava-backendvirtual-threads

SKILL.md Content

View Translation Comparison →

Quarkus Core Guidelines

Apply Quarkus core guidelines for CDI beans, configuration, profiles, and lifecycle.
What is covered in this Skill?
  • @QuarkusMain and application entry (when custom main is needed)
  • CDI scopes: @ApplicationScoped, @Singleton, @Dependent; bean disambiguation (@Default, @Alternative, @Named)
  • Constructor injection with @Inject
  • CDI interceptors (@Interceptor, @InterceptorBinding) for cross-cutting concerns
  • CDI events: @Observes StartupEvent / ShutdownEvent, @ObservesAsync for async dispatch
  • Programmatic injection with Instance<T> for dynamic bean selection
  • @ConfigMapping and structured configuration with Bean Validation (@Valid)
  • Profile-specific properties (%dev, %test, %prod) and @IfBuildProfile
  • Startup and shutdown observers (@Startup, @PreDestroy)
  • SmallRye Health probes (@Liveness, @Readiness)
  • Virtual threads with @RunOnVirtualThread (Java 21+)
  • Native-image safety: @RegisterForReflection, @DisabledOnNativeImage
Scope: Apply recommendations based on the reference rules and good/bad code examples.

Constraints

Before applying any Quarkus changes, ensure the project compiles. If compilation fails, stop immediately. After applying improvements, run full verification.
  • MANDATORY: Run 
    ./mvnw compile
    or 
    mvn compile
    before applying any change
  • PREREQUISITE: Project must compile successfully before applying Quarkus core improvements
  • SAFETY: If compilation fails, stop immediately — compilation failure is a blocking condition
  • BLOCKING CONDITION: Compilation errors must be resolved by the user before proceeding
  • VERIFY: Run 
    ./mvnw clean verify
    or 
    mvn clean verify
    after applying improvements
  • BEFORE APPLYING: Read the reference for detailed rules, good/bad patterns, and constraints

When to use this skill

  • Review Java code for Quarkus application structure and CDI
  • Apply best practices for Quarkus configuration and beans
  • Improve CDI interceptors, events, or programmatic injection in Quarkus
  • Add SmallRye Health probes or virtual-thread configuration

Reference

For detailed guidance, examples, and constraints, see references/401-frameworks-quarkus-core.md.