AGENTS.md Makes Your Java Codebase AI-Agent Ready

The year is 2026, and the way software is built has fundamentally shifted. We are no longer just writing code for other humans to read; we are building systems that AI coding agents, such as Cursor, GitHub Copilot Agent Mode, Claude Code, and autonomous CLI tools, will navigate, debug, and extend.

As Java developers, we are blessed with robust tooling. If you are using Quarkus, you already possess a superpower: Supersonic Subatomic Java with an ultra-fast developer loop, continuous testing, and built-in Dev Services.

However, AI agents frequently get tripped up by enterprise Java repositories. They overcomplicate simple architectures, write blocking code where reactive code belongs, or waste tokens trying to spin up manual Docker containers when Quarkus Dev Services could do it out of the box.

The fix? AGENTS.md. Let’s explore how to use this emerging open standard to make your Quarkus applications instantly digestible for AI agents.

What Is AGENTS.md?

The AGENTS.md specification is a tool-agnostic open standard (pioneered by the Agentic AI Foundation) designed to sit at the root of a repository.

Think of your standard README.md as human onboarding documentation: it contains high-level architecture narratives, badges, and project philosophy.

AGENTS.md, on the other hand, is an executable runtime instruction layer for AI. It is concise, deterministic, imperative, and explicitly structured to prevent "context window bloat" while giving autonomous agents the exact boundaries and commands they need to succeed.

The Anatomy of an Agent-Ready Quarkus Codebase

When an AI agent initializes inside your workspace, it reads your project structure. Because Quarkus spans both imperative and reactive paradigms, an unguided AI agent will often hallucinate or mix patterns.

An effective AGENTS.md for a Quarkus ecosystem must explicitly define three pillars:

1. Operational commands: The exact Maven/Gradle sequences for running, testing, and live-reloading.
2. Architectural boundaries: Strict rules regarding blocking vs. non-blocking code and data access patterns.
3. Infrastructure management: Forcing the agent to utilize Quarkus Dev Services rather than provisioning external databases.

Hands-On: The Ultimate Quarkus AGENTS.md Template

Drop this exact AGENTS.md file into the root of your Quarkus repository to drastically improve the quality of AI-generated code and autonomous refactoring tasks.

## Tech Stack & Ecosystem Context
- **Runtime**: Java 25, Quarkus 3.x (Supersonic Subatomic Java).
- **Build Tool**: Maven (`mvnw` wrapper present).
- **Extensions**: REST, Hibernate ORM with Panache, Quarkus Dev Services.
- **Database**: PostgreSQL (Managed entirely via Dev Services).

## Critical Operational Commands
- **Launch Development Mode**: `./mvnw quarkus:dev`
- **Execute All Tests**: `./mvnw test`
- **Continuous Testing**: Start `./mvnw quarkus:dev` and press `r` to toggle background testing.
- **Production Package**: `./mvnw package`

## Architectural Boundaries & Coding Standards

### 1. Reactive vs. Blocking Rules
- Default to **REST**. Endpoints returning `Uni<T>` or `Multi<T>` must NEVER invoke blocking operations.
- If a method blocks, annotate it explicitly with `@Blocking`.

### 2. Data Access (Hibernate ORM with Panache)
- Use the **Panache Active Record pattern** extending `PanacheEntity`. Do NOT write custom repositories or explicit DAO layers unless complex business logic demands it.
- **Transaction Management**: Annotate mutate operations with `@Transactional`. Never manage transactions manually.

```java
// Correct Agent Output Example:
@Entity
public class Developer extends PanacheEntity {

    public String name;
    public String specialty;

    public static Uni<Developer> findByName(String name) {
        return find("name", name).firstResult();
    }

}

```

## Scaffolding Lifecycle for New Microservices
When scaffolding a new microservice (e.g., "Scaffold a new microservice for user billing"), the agent follows this deterministic lifecycle:

### 1. Reads the Command Layer
- **Bypass manual configuration**: Do NOT generate raw `pom.xml` text by hand, which frequently leads to version mismatches or missing dependency management blocks.
- **Use Quarkus tooling**: Rely on the official Quarkus Maven plugin command structure.

### 2. Executes the Tooling
- **Command**: Run the explicit `mvn io.quarkus.platform:quarkus-maven-plugin:create` command directly inside your terminal workspace.
- **Example**:

```bash
mvn io.quarkus.platform:quarkus-maven-plugin:3.x.x:create \
  -DprojectGroupId=com.example \
  -DprojectArtifactId=billing-service \
  -DclassName="com.example.billing.BillingResource" \
  -Dpath="/billing"
```

### 3. Applies Core Extensions
- **Guarantee essential extensions** are baked in from the first second:
  - `hibernate-orm-panache` for data access
  - `quarkus-rest` for REST endpoints
- **Add extensions during creation**:
```bash
mvn io.quarkus.platform:quarkus-maven-plugin:create \
  ... \
  -Dextensions="hibernate-orm-panache,quarkus-rest,jdbc-postgresql"
```
- This prevents the agent from creating legacy or blocking code templates down the line.

### 4. Validates Context
- **Transition to Testing**: Once scaffolded, immediately verify that the out-of-the-box generated test suite runs cleanly.
- **Validation command**: `./mvnw test`
- **Expected outcome**: All generated tests pass without modification, confirming the scaffold is valid and ready for development.

### Post-Scaffold Checklist
- [ ] Project structure follows standard Maven layout (`src/main/java`, `src/test/java`)
- [ ] `application.properties` contains Dev Services configuration (auto-configured for PostgreSQL)
- [ ] At least one REST endpoint exists with a corresponding test
- [ ] `./mvnw test` passes cleanly
- [ ] `./mvnw quarkus:dev` starts without errors

Testing and Local Infrastructure

• Never manually configure Testcontainers or hardcode local JDBC connections inside application.properties for local development.
• Rely 100% on Quarkus Dev Services. The PostgreSQL container is automatically spun up during ./mvnw quarkus:dev or @QuarkusTest.

Verification Protocol

Before declaring a task complete, you MUST:

1. Run ./mvnw compile to ensure zero compilation or annotation processor failures.
2. Run ./mvnw test and confirm all integration tests pass cleanly.

Note: Find the solution repository: https://github.com/danieloh30/agents-md-for-java-quarkus.git

### Sample Demo Walkthrough: Put it to the Test
To see the power of this setup, let’s imagine a standard demo repository structured as follows:

agents-md-for-java-quarkus/src/main/java/com/example/billing/
|____com
| |____example
| | |____billing
| | | |____Invoice.java
| | | |____BillingResource.java
| | | |____InvoiceItem.java
|____pom.xml
|____README.md <-- For humans
|____AGENTS.md <-- For the AI Agents

The Experiment

You open this repository inside an AI-native workspace and issue a vague, autonomous prompt:

"Add a new REST endpoint to fetch a developer by their specialty, write a test for it, and verify that the app works."

Without AGENTS.md

The agent might look at pom.xml, realize it's a Java app, and write a legacy, blocking JAX-RS endpoint. It might attempt to spin up a Docker container inside the test via a manual DockerClient or throw an error because it doesn't know how to supply a PostgreSQL URL.

With AGENTS.md

1. Reads context: The agent parses AGENTS.md instantly. It recognizes that it must write a reactive Uni<Developer> endpoint using Panache’s Active Record pattern.
2. Generates code: It appends a clean, reactive finder method directly onto the Developer entity.
3. Executes environment: Instead of guessing how to launch your app, it executes ./mvnw quarkus:dev.
4. Leverages dev services: It sees that Quarkus handles the database automatically. It writes a clean @QuarkusTest integration test, triggers the validation, checks the terminal logs, and corrects its own syntax if a compilation check fails.

By defining the boundaries upfront, you prevent the agent from writing code that compiles but violates your team's architectural standards.

Conclusion: Treat Context as Code

Providing an AI agent with free rein over an enterprise Java codebase without boundaries is like letting a junior developer deploy to production on day one without code reviews.

By adopting AGENTS.md alongside the rapid developer feedback loops built natively into Quarkus, you bridge the gap between human intent and machine execution. Spend 10 minutes writing an AGENTS.md file today, and unlock massive productivity gains for the agentic future of software development.