quarkus-application-development - Claude MCP Skill

# 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.