# Cursor Agent Spring Boot: Practical Guide for Developers

URL: https://agentvera.dev/en/blog/cursor-agent-for-spring-boot/ · Published: 2026-11-01

Use Cursor Agent in a Spring Boot project: setup, AGENTS.md rules, working loop, testing with JUnit 5 and Testcontainers, and parallel agent workflows.

**In short:**

- Start cursor-agent in the project root and keep an AGENTS.md file with exact build, test, and package rules.
- Work in small vertical slices: plan, edit, run Maven or Gradle tests, and review the diff before committing.
- For Spring Data JPA and Testcontainers, require green integration tests and watch for lazy loading and N+1 pitfalls.

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](/en/agents/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:

```markdown
# 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](/en/blog/how-to-use-cursor-cli/).

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

| Verification step | Command or action |
|---|---|
| Unit tests | `./mvnw test` |
| Single failing test | `./mvnw -Dtest=OrderServiceTest#createOrder test` |
| Full build with integration tests | `./mvnw clean verify` |
| Review agent changes | `git diff -- src/main/java src/test` |
| Testcontainers startup | run one repository or service test that boots PostgreSQL before trusting Docker-based tests |

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)](/en/blog/best-tools-parallel-ai-coding-agents/) 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.

## Frequently asked questions

**How do I start Cursor Agent in a Spring Boot project?** Open a terminal in the project root and run cursor-agent. It reads AGENTS.md or .cursor/rules for project-specific instructions. Keep those files concise and update them when your build commands change.

**Can Cursor Agent run Maven or Gradle builds and tests?** Yes. It can run the exact commands listed in AGENTS.md, such as ./mvnw test or ./gradlew test. Ask it to run the test suite after each change and to paste the relevant failure output.

**What Spring Boot tasks should I let Cursor Agent handle first?** Start with controller-service-repository slices, DTO mapping, and JUnit 5 tests. Avoid letting it redesign transaction boundaries or Flyway migrations without a plan and a full test run.

**Does Cursor Agent work with Spring Data JPA and Testcontainers?** It works well when you define repository interfaces and Testcontainers configuration in AGENTS.md. Instruct it to use real database containers instead of H2 for integration tests and to review generated queries for N+1 problems.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/