Cursor Agent Spring Boot: Practical Guide for Developers

Cursor Agent is the terminal coding agent from Cursor. Run cursor-agent in the root of a Spring Boot project, tell it how your project builds and tests through AGENTS.md or .cursor/rules, and use it for focused Java changes. This guide shows a reliable loop that keeps Maven or Gradle builds, JUnit 5 tests, and Testcontainers suites green. See Cursor Agent for the terminal agent itself.

Why Cursor Agent suits Spring Boot work

A Spring Boot codebase is usually layered and convention-driven: controllers call services, services call repositories, and tests follow predictable package names. Cursor Agent lives in the shell, so it reads pom.xml or build.gradle, application.yml, package layout, and Flyway migrations directly. It can run ./mvnw or ./gradlew and react to compiler errors or test failures in the same turn. That makes it useful for multi-file changes that would otherwise be tedious in an IDE: adding a REST endpoint touches a controller, a DTO, a service method, a repository, and at least two test classes. Because the agent reads AGENTS.md, you can keep those changes inside your project’s real conventions instead of a generic Java style.

Set up AGENTS.md or .cursor/rules for Spring Boot

Use one AGENTS.md file at the repository root. It should be short enough for the agent to consume every turn, and it should contain exact commands, package folders, and Spring Boot-specific rules. If you already keep developer instructions in .cursor/rules, put the same content there; do not maintain two conflicting copies.

For a Maven project, a realistic AGENTS.md looks like this:

# AGENTS.md

## Commands
- Build: ./mvnw clean verify
- Run tests: ./mvnw test
- Run one test: ./mvnw -Dtest=PaymentServiceTest test
- Run app: ./mvnw spring-boot:run
- Format/lint: ./mvnw spotless:check

## Package layout
- API controllers: src/main/java/com/acme/order/api
- Services: src/main/java/com/acme/order/service
- Repositories: src/main/java/com/acme/order/repository
- DTOs: src/main/java/com/acme/order/dto
- Tests: src/test/java

## Spring Boot rules
- Controllers accept and return DTOs only; never expose JPA entities.
- Services own transactions with @Transactional(readOnly = true) for reads and @Transactional for writes.
- Use Spring Data JPA repositories; do not hand-write SQL unless a named query is justified.
- Use Testcontainers for integration tests with PostgreSQL; do not use H2.
- Database changes go through Flyway migrations in src/main/resources/db/migration.
- Keep environment-specific values in application profiles, not hard-coded.

Keep the commands in the file exactly as you run them. If you use Gradle, replace ./mvnw with ./gradlew and adjust the test filter to ./gradlew test --tests PaymentServiceTest. Update the file when you change Java package names or add a new module. For command line workflow details, see How to use Cursor CLI: a step-by-step guide.

A working loop for Spring Boot changes

The safest loop is plan, small vertical slice, test, diff. Do not ask for a broad refactor in one turn. Instead, ask the agent to read the relevant package and propose a file-by-file plan first. Then ask it to implement only that slice, run the targeted tests, and show the diff.

For example:

• Add a POST /api/orders endpoint with an OrderRequest DTO, OrderResponse DTO, OrderService.createOrder, a JPA Order entity and repository, and a Testcontainers integration test. Follow AGENTS.md.
• Replace the RestTemplate call in CustomerClient with Spring’s RestClient. Keep the existing test green, and add a MockRestServiceServer test for the 404 case.
• Add pagination and sorting to GET /api/orders with Spring Data JPA Pageable. Return Page<OrderResponse> and update the controller test.
• Find all manual validation in OrderController and move it into a single OrderValidator component. Keep the controller slim and update the tests.
• Run ./mvnw clean verify, fix only the Spring context and Testcontainers failures in the order module, and show the final diff.

After each implementation step, run the test suite yourself or require the agent to paste the exact command and output. Then inspect git diff --stat and git diff to catch accidental changes to application.yml, migration scripts, or unrelated classes. Commit only when the relevant tests pass.

Where Cursor Agent is strong and where to watch it

Strong Spring Boot tasks include creating controller-service-repository slices, mapping entities to DTOs, adding Spring Data JPA derived queries, writing JUnit 5 and Testcontainers tests, and migrating old HTTP clients or validation code. Because these tasks follow clear patterns and produce compiler or test feedback, the agent can iterate quickly.

Watch these Spring Boot-specific pitfalls:

• LazyInitializationException: the agent may return a JPA entity or a lazily loaded collection from a service method outside a transaction. Always instruct it to return DTOs and keep read operations inside @Transactional(readOnly = true).
• N+1 queries: derived repository queries without fetch joins can load associations one by one. Ask the agent to review the generated SQL or add entity graphs and join fetches when a page of results references related entities.
• JSON serialization cycles: bidirectional JPA associations without DTOs or @JsonIgnore can cause stack overflow or huge responses. Keep DTO boundaries explicit.
• Testcontainers lifecycle: agents sometimes create a new container per test class or per test method. Prefer a shared base test class with a singleton container and @ServiceConnection for PostgreSQL.
• Migration changes: never let the agent modify an applied Flyway migration. It should add a new V{n}__*.sql file and leave the previous scripts alone.
• Profile-specific configuration: if a change touches application.yml, check that the default profile and test profile still resolve the right datasource and ports.

Testing and verification with Cursor Agent

Make verification part of every prompt. For Spring Boot, the useful checks are:

Use Testcontainers for integration tests instead of H2 when your production database is PostgreSQL. An in-memory database can hide dialect differences, transaction behavior, and migration issues. If the Docker daemon is not running, the agent should report that failure explicitly, not switch to H2 silently.

Running several agents on one Spring Boot project with AgentVera

For Spring Boot work, AgentVera is useful because it can run Cursor Agent alongside other CLIs in separate terminal panels, with each agent in its own git worktree so parallel changes to services and repositories don’t collide. Automatic code review flags Java-specific issues at file:line, which is important when agents touch transactions and DTO mapping. Checkpoints let you undo a turn that breaks the Spring context or Testcontainers setup without losing the session. Token budgets keep long Maven builds and multi-module test loops from consuming the whole day’s allowance. See Best tools to run AI coding agents in parallel (2026) for a practical view.

Wrap-up

Cursor Agent fits Spring Boot work best when you give it exact build and test commands, explicit package rules, and small well-scoped tasks. Use Testcontainers-backed integration tests as the gate, review the diff after every turn, and let AGENTS.md enforce your architectural boundaries. That keeps the agent productive without letting it turn a simple endpoint change into a schema migration or a Spring context surprise.