Cursor Rules for Java: Builds, Frameworks, and Tests

Cursor rules for Java tell the AI assistant which build tool your project uses, how to run tests, which annotations and patterns are standard for your framework, and what it must not change without asking. A Java project built with Gradle and Quarkus needs very different rules from one built with Maven and Spring Boot.

The framework choices your team made — why Spring Boot was chosen over Quarkus, why a particular data access pattern was standardized, which Java version is required — belong in fenbs as Decisions. The rules file captures what to do; fenbs captures why, keeping both readable for the next assistant.

What Java rules should cover

• Build tool and commands: exact Maven or Gradle commands for building, testing, and running the application.
• Java version: the minimum and target version your project compiles against.
• Package structure: the base package, any module boundaries, and directories the AI may not touch.
• Framework conventions: Spring annotations versus Quarkus CDI, dependency injection style, bean scopes.
• Test framework: JUnit 5, TestNG, or other; how to run unit tests and integration tests separately.
• Dependency policy: whether the AI may add new dependencies and what approval is needed.

Maven template

# Java project rules — Maven / Spring Boot

## Build
- Build: mvn clean package -DskipTests
- Test: mvn test
- Integration tests: mvn verify
- Run locally: mvn spring-boot:run

## Java version
- Source and target: Java 21

## Package structure
- Base package: com.example.app
- Do not create classes in the root package.

## Spring conventions
- Use constructor injection, not field injection.
- Annotate service classes with @Service, repositories with @Repository.
- Keep controllers thin: business logic belongs in services.
- Use @Transactional at the service layer, not the controller.

## Dependencies
- Do not add a new dependency to pom.xml without asking.

## Tests
- Write unit tests with JUnit 5 and Mockito.
- Integration tests extend a base class that starts the context.

Gradle and Quarkus adaptations

# Java project rules — Gradle / Quarkus

## Build
- Build: ./gradlew build
- Test: ./gradlew test
- Dev mode: ./gradlew quarkusDev
- Native build: ./gradlew build -Dquarkus.package.type=native (ask first)

## Java version
- Source and target: Java 21

## Quarkus conventions
- Use @ApplicationScoped for long-lived beans.
- Use @Inject for dependency injection.
- RESTEasy Reactive for REST endpoints: annotate with @Path and HTTP method annotations.
- Use Panache for data access unless told otherwise.

## Dependencies
- Do not add an extension to build.gradle without asking.

Code quality and static analysis

Java projects commonly use Checkstyle, PMD, SpotBugs, or a combination for static analysis. If your project enforces these tools in CI, add the commands and their expected outcomes to the rules. An assistant that writes code without knowing your style enforcement will produce changes that fail the CI pipeline on the first review.

## Code quality
- Checkstyle: mvn checkstyle:check (or ./gradlew checkstyleMain)
- SpotBugs: mvn spotbugs:check (or ./gradlew spotbugsMain)
- All checks: mvn verify -DskipTests
- Do not suppress warnings without asking.

Add any package or import restrictions your project enforces through ArchUnit or a similar tool. If the architecture test suite includes rules like "domain classes must not import Spring annotations," stating those rules in the Cursor rules file gives the assistant a check it can apply before code review catches the violation.

Dependency version rules

Java projects managed with a BOM (Bill of Materials) have version constraints that apply across many dependencies. If your project uses the Spring Boot BOM or the Quarkus BOM, add a rule that version numbers for managed dependencies must not be overridden without a reason. An assistant that adds a version tag to a managed dependency can override the BOM and introduce incompatibilities that are difficult to track down.

The same applies to parent POM versions in Maven. A rule that says "do not change the parent POM version without asking" prevents accidental upgrades to a Spring Boot or Quarkus version that has not been tested. See Cursor rules examples for how to express dependency constraints clearly in a rules file.

Framework decisions and why they matter

A rules file can tell an assistant to use constructor injection. It cannot explain why your team moved away from field injection two years ago when a testing framework incompatibility surfaced. That explanation belongs in fenbs as a Decision, linked to any tasks that touched that change.

When an assistant reads both the rules and the project context in fenbs, it can answer questions an assistant with only the rules file cannot: why a particular pattern is standard, what problem it was solving, and whether an exception is appropriate for the current task.

How to set up Java rules with fenbs

1. Create a free account and add your Java project to fenbs. Record the framework choices as Decisions: why Maven or Gradle, which Java version and why, any architecture decisions about layering.
2. Add the appropriate template above to your project's .cursor/rules/ directory and replace the placeholder package names and commands with your actual values.
3. Connect Cursor to fenbs over MCP from Integrations. Ask the assistant to read the project context at session start, including the framework Decisions.
4. When the team agrees to change a convention — a new annotation style, a different test approach — update the Decision in fenbs and the rules file in the same change.

What to watch for

Java projects often have a mix of old and new patterns. If your codebase has legacy code that uses field injection alongside newer code with constructor injection, say so in the rules. An assistant given an inconsistent codebase without this context will pick one style and apply it everywhere, creating noise in the diff.

Native Quarkus builds are slow and resource-intensive. Add an explicit rule that the assistant must ask before running a native build. The same applies to any command that takes significant time or changes infrastructure, not just Java-specific ones.

Annotation processing is another source of unexpected behavior. Tools like Lombok, MapStruct, and Hibernate Validator all use annotation processing at compile time, and the generated code may not be visible in the IDE. A rule that notes which annotations are generated and should not be manually implemented prevents an assistant from writing code that duplicates what the processor already creates. If your project uses Lombok, add a list of the annotations in use and what each one generates, so the assistant does not rewrite their generated methods by hand.