A CLAUDE.md Template for Quarkus Projects

A CLAUDE.md file in your Quarkus project tells Claude Code which extensions your application uses, how to start the dev server, which configuration profiles are in play, and what the test commands are. Without it, Claude Code has to read your build files and infer those facts each session — and it may infer them wrong.

Tools like fenbs are a good place for the decisions that change across projects: which database your team chose, which security approach is approved, which design tradeoffs were made. Your CLAUDE.md then stays focused on the stable, repo-level facts. This page gives you a template to copy and adapt.

What belongs in a CLAUDE.md for Quarkus

Quarkus projects have a few conventions that are easy for an assistant to get wrong without guidance: the difference between JVM and native builds, the meaning of the %dev, %test, and %prod configuration profiles, and the correct way to add an extension without breaking the existing build. Cover those first.

• The extensions list or a pointer to where it lives in the build file (pom.xml or build.gradle).
• The commands to start the dev server, run tests, and build for production.
• Which configuration profiles are used and what application.properties files cover each one.
• Whether the project targets JVM mode, native mode, or both, and the command for each.
• Any constraints on adding new extensions — approval process, version pinning, or incompatibilities to avoid.

The template

Copy this into a CLAUDE.md at your project root and fill in the bracketed sections. See CLAUDE.md examples for how other project types structure their files.

# [Project name] — Quarkus project

## Key extensions
This project uses the following Quarkus extensions (see pom.xml for current versions):
- quarkus-resteasy-reactive (REST endpoints)
- quarkus-hibernate-orm-panache (data access)
- quarkus-jdbc-postgresql (database driver)
- quarkus-smallrye-openapi (API docs)
- [add others]

## Commands
```
# Start dev server (live reload enabled)
./mvnw quarkus:dev

# Run tests only
./mvnw test

# Build for JVM
./mvnw package

# Build native executable (requires GraalVM or container build)
./mvnw package -Pnative
./mvnw package -Pnative -Dquarkus.native.container-build=true
```

## Configuration profiles
- `%dev` — application.properties for local development (in-memory or local DB)
- `%test` — used during test runs; test DB is configured here
- `%prod` — production values; secrets come from environment variables, not the file

Do not hardcode production secrets in any .properties file.
Environment variable names are documented in [your config reference location].

## Database
[Describe the database: type, how migrations are managed (Flyway/Liquibase/manual SQL),
and the rule about schema changes (always add migration scripts, never modify existing ones).]

## Adding extensions
Add extensions with `./mvnw quarkus:add-extension -Dextensions="[extension-id]"`.
Check the [Quarkus extension registry](https://code.quarkus.io/) for compatibility
before adding an extension that was not previously used.
New extensions require a review from [name or team] before merging to main.

## Testing
- Unit tests use @QuarkusTest with the test profile.
- Integration tests that require the full application context use @QuarkusIntegrationTest.
- Run `./mvnw test` before committing. All tests must pass.

## Build targets
This project targets [JVM mode / native mode / both]. Do not change the build target
without a recorded decision approving the change.

Configuration profiles in practice

Quarkus activates the dev profile automatically during quarkus:dev and the test profile during test runs. If your CLAUDE.md does not explain this, Claude Code may suggest hardcoding values that belong in a profile-specific property, or may not realize that a dev database setting should not appear in the prod config.

Write down which properties differ between profiles and where each profile's file lives. If you use environment variable substitution for secrets in prod, say so explicitly. That one rule prevents a common mistake: an assistant setting a database password directly in application.properties rather than reading it from an environment variable.

Extension and dependency constraints

Quarkus extensions interact in ways that are easy to miss. Some pairs conflict; others require a specific version of a dependency already in your build. If your team has learned through experience which extensions cause problems together, record those constraints in CLAUDE.md. A short list of "do not add X without checking Y" instructions is more useful than a general warning.

The Quarkus guides↗ (opens in a new tab) describe each extension's configuration options and known compatibility notes. Point Claude Code there for details on a specific extension rather than trying to replicate the documentation in your CLAUDE.md.

Testing setup is worth documenting in detail. Quarkus has two test annotations with different behavior: @QuarkusTest runs the full application in test mode, while @QuarkusIntegrationTest tests the packaged application. If your project uses both, explain when each is appropriate. Add the command to run only a specific test class — ./mvnw test -Dtest=MyServiceTest — so Claude Code does not always run the full suite when you are iterating on one area.

If your project uses Panache for data access, include a rule about transaction handling in tests. Panache tests typically need @TestTransaction to roll back changes after each test. A missing annotation can leave test data in the database and cause flaky test runs that are confusing to diagnose.

Architecture decisions belong elsewhere

Your CLAUDE.md is a stable file that describes how the project works today. Architecture decisions — why you chose Hibernate Panache over plain JDBC, which caching strategy was approved, whether reactive or imperative REST was selected — belong in a more durable place. When those decisions change, you want a record of what was decided, who decided it, and the reason.

Keeping those decisions in fenbs means they survive across sessions and are visible to every connected assistant. A new team member or a future Claude Code session can read the constraints before suggesting a change that contradicts an approved design.

How to do this with fenbs

1. Create a free account. Start a fenbs project for your Quarkus application and add its current tasks.
2. Add the key architecture decisions — extension choices, build target, database strategy — as Decisions and rules. Note who made each decision and the reason.
3. Connect Claude Code to fenbs from Integrations and ask it to read the project context at the start of each session.
4. When a new decision is made — a new extension approved, a configuration pattern chosen — record it in fenbs before it is forgotten.
5. Copy the CLAUDE.md template above into your project root and fill in your specific commands, extensions, and constraints. Review it whenever you add a new extension or change the test setup.

If you work on multiple Quarkus services in the same repo, see Claude Code with multiple projects and CLAUDE.md for how to structure instructions at the workspace level versus the service level.