quarkus-application-development

# Quarkus Application Development Scope: application code inside an existing Quarkus project. Project creation is `create-quarkus-project`; Dev Services and tests are `quarkus-dev-services-and-testing`; native and container images are `quarkus-native-and-container`; core JPA mapping and query design can use the optional `java-hibernate-jpa` skill if installed (otherwise see the Hibernate ORM guide, <https://quarkus.io/guides/hibernate-orm>, and the Jakarta Persistence docs). ## Agent rules 1. Detect first: read `pom.xml`/`build.gradle` for `quarkus.platform.version`, the Java release, and the extensions already present. Keep the version; use what the project already uses (for example `quarkus-resteasy*` stays if present). 2. Add extensions with `quarkus extension add <name>` or `./mvnw quarkus:add-extension -Dextensions=<name>`; never guess artifact ids or versions by hand (the platform BOM manages them). List candidates with `quarkus extension list --installable --search=<text>`. 3. Ask the user before adding Kafka, OIDC/Keycloak or any new infrastructure dependency (they start containers in dev/test and change deployment needs). 4. Never use the Spring compatibility extensions (`quarkus-spring-*`) unless the project already does. 5. Verify with dev mode (`./mvnw quarkus:dev`, then `/q/dev-ui`) and `./mvnw verify`; write a `@QuarkusTest` per feature. Do not claim something works without running it. 6. Use `jakarta.*` imports, records for DTOs, thin resources delegating to services. 7. Never hard-code secrets or add credentials to `application.properties`; see `references/config-cdi.md`. ## Quick decisions | Need | Use | Details | |---|---|---| | JSON REST API | `quarkus-rest-jackson`, `quarkus-hibernate-validator`, `quarkus-smallrye-openapi` | `references/rest.md` | | Typed config | `@ConfigMapping`; `@ConfigProperty` for single values | `references/config-cdi.md` | | Beans | `@ApplicationScoped` (default), `@Singleton` only for plain stateless holders | `references/config-cdi.md` | | Database | `quarkus-hibernate-orm-panache` + JDBC driver, repository pattern | `references/persistence.md` | | Async / blocking | Imperative by default; `@RunOnVirtualThread` or `Uni` when needed | `references/reactive-messaging.md` | | Messaging | `quarkus-messaging-kafka` (SmallRye Reactive Messaging) | `references/reactive-messaging.md` | | AuthN/AuthZ | `quarkus-oidc`, `@RolesAllowed` | `references/security-oidc.md` | | Ops | `quarkus-smallrye-health`, `quarkus-micrometer-registry-prometheus`, `quarkus-opentelemetry`, `quarkus-smallrye-fault-tolerance` | `references/observability-resilience.md` | | Outbound HTTP, scheduling, caching | `quarkus-rest-client-jackson`, `quarkus-scheduler`, `quarkus-cache` | `references/observability-resilience.md` | ## Pitfalls that cost time - Quarkus resolves CDI at build time: an unused bean may be removed. Beans only looked up programmatically need `@Unremovable`. - Do not read or write public fields of a normal-scoped bean (`@ApplicationScoped`) from another bean or test: you hit the client proxy, not the instance (verified: a counter field read through the proxy returned 0). Use methods. - Do not block on the event loop (`@NonBlocking` methods, `Uni`/`Multi` return types running on I/O threads). Remove any existing `@NonBlocking` from the method (combining it with `@Blocking` or `@RunOnVirtualThread` fails the build), then add `@Blocking` or `@RunOnVirtualThread` (see `references/reactive-messaging.md`). - Changes to build-time properties need a rebuild; run-time properties can be overridden by env vars (`QUARKUS_DATASOURCE_JDBC_URL`). - Do not configure URLs for databases/brokers/Keycloak in `%dev`/`%test`: that disables Dev Services. - `drop-and-create` schema management is for dev/test only; use Flyway or Liquibase for production. Verified on Quarkus 3.40.1 and 3.27.6 (Java 21 target, Maven) with a scaffolded app and `mvn verify` (15 tests: REST+validation+mapper, OpenAPI, config mapping, Panache on PostgreSQL Dev Services, Kafka Dev Service round trip, Keycloak Dev Service tokens, health, metrics, fault tolerance, cache, scheduler). Re-check names against the project's version.