# Working with Gemini CLI on Spring Boot Projects

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

Learn how to use Gemini CLI inside a Spring Boot codebase: set up GEMINI.md with build commands, run focused tests, and handle JPA and Testcontainers work.

**In short:**

- Set up GEMINI.md with exact Maven or Gradle commands and Spring Boot conventions before starting gemini.
- Ask for a plan, make small changes, and run focused JUnit tests after every step.
- Review JPA mappings, application.yml diffs, and Testcontainers setup closely because those are common agent mistakes.

Gemini CLI is a terminal coding agent that can read your repository, edit Java code, and run Maven or Gradle commands. On a Spring Boot project, the fastest way to get useful work is to start it with `gemini` in the project root and keep a project-specific `GEMINI.md` beside the code. This guide covers setup, a reliable working loop, task selection, testing, and running several agents without conflicts.

## Where Gemini CLI saves time in Spring Boot work

Spring Boot development has a tight feedback loop: compile, run tests, inspect the application context. A coding agent that can execute `./mvnw test` or `./gradlew test` after a change closes that loop without leaving the terminal. [Gemini CLI](/en/agents/gemini-cli/) reads the repository context and can inspect Java classes, `application.yml`, JPA mappings, migrations, and test output together. The framework’s strong conventions also make it easier for an agent to produce predictable code: controllers talk to services, services use repositories, and exceptions map to HTTP responses. Treat it like a focused junior engineer: define the task boundaries, require tests, and review the diff yourself.

## Put Maven or Gradle commands and Spring rules in GEMINI.md

Create a `GEMINI.md` file at the repository root. Keep it specific and updated. Include the exact build, test, and lint commands; the package layout; and rules that are easy for an agent to get wrong in Spring Boot. If your project uses Gradle, write `./gradlew` equivalents. For first-run basics, the [step-by-step guide](/en/blog/how-to-use-gemini-cli/) covers invocation; the project file below is what makes the agent reliable on a Spring Boot repo.

```markdown
# GEMINI.md

## Commands
- Build: `./mvnw clean verify`
- Run one test: `./mvnw -Dtest=OrderServiceTest test`
- Format check: `./mvnw spotless:check`
- Apply format: `./mvnw spotless:apply`
- Run app: `./mvnw spring-boot:run`

## Project layout
- Base package: `com.acme.order`
- Feature packages: `order`, `payment`, `customer`
- In each feature: `controller`, `service`, `repository`, `dto`, `model`
- Tests mirror production packages under `src/test/java`

## Spring Boot rules
- Java 21, Spring Boot 3.x, Maven wrapper only
- Controllers must stay thin: validate input, call one service method, map to DTO
- All public service methods need JUnit 5 tests
- JPA entities are persistence only; do not add controller JSON annotations there
- Use records or immutable DTOs for request/response bodies
- External resources in tests must use Testcontainers, not embedded servers or mocks
- Keep `application.yml` environment-specific values in variables; never commit secrets
- Do not change dependency versions unless the Spring Boot BOM says otherwise
```

A long file is worse than a short one. Keep commands exact and rules tied to mistakes that would otherwise cost you a review cycle.

## A plan-first loop with test-verified small changes

The most productive loop is plan, implement in small steps, run focused tests, review the diff. Ask the agent to show its plan before writing code. Then let it make a narrow change and run the specific test class, not the entire suite, while it is iterating. Once the task is done, run a wider verification and inspect `git diff` for accidental changes to configuration or unrelated classes. Do not accept a large pull request that changes ten files at once; ask the agent to split it. If a test failure appears, ask for the smallest fix and have it re-run only the affected class.

Example prompts:

- Add a `POST /api/orders` endpoint. First list the controller, service, DTO, and JPA entity changes you plan, then implement them and run the focused test class.
- Write a JPA repository method and service method to fetch orders by customer id and status with pagination. Use a derived query or a Specification, whichever is cleaner.
- Refactor `OrderService.cancelOrder` so validation logic is extracted into a separate component. Do not change behavior, and run the existing service tests before and after.
- Create a Testcontainers integration test for `OrderRepository` against PostgreSQL. Use `@SpringBootTest` and `@Testcontainers`, start a matching PostgreSQL image, and assert create, read, update, and delete operations.
- The test `OrderServiceTest.cancelOrder_throwsWhenShipped` is failing. Read the Maven Surefire output, propose the smallest fix, and only change code that affects that behavior.

If you prefer a list instead of a long thread, the same loop works: keep each prompt limited to one layer or one failure.

## Where to trust the agent and which Spring Boot pitfalls to review

Gemini CLI is strong at mechanical Spring Boot work: adding controllers, services, repositories, DTO mapping, validation annotations, exception handlers, and configuration properties. It can also write JUnit 5 tests and update Maven or Gradle dependencies.

Watch these areas closely:

| Task | Where to watch closely |
|------|------------------------|
| New endpoint | It may add an extra exception handler or change security defaults without being asked |
| JPA relationships | Check fetch types, possible N+1 queries, and `@Transactional` boundaries |
| Testcontainers tests | Confirm the database image and startup wait strategy match your runtime |
| Dependency changes | Verify the dependency is actually used and its version is managed by the Spring Boot BOM |
| Configuration edits | Diff `application.yml` or `application.properties`; make sure no local secret is committed |

The agent tends to over-abstract small classes and sometimes creates a full `@SpringBootTest` when a `@WebMvcTest` or `@DataJpaTest` would be faster. Review those choices before accepting the change. When the agent creates a new entity, check that it does not add bidirectional relationships without cascade or orphan removal unless required. Spring Data JPA will happily persist a graph, but lazy loading can fail outside a transaction. Check that DTO mapping is not done inside entities, and that validation annotations belong on DTOs, not on service method arguments.

## Enforce Spring Boot test boundaries and verify every claim

Require the agent to run tests, not just claim they pass. Start with a focused test during iteration:

```bash
./mvnw -Dtest=OrderControllerTest,OrderServiceTest test
```

Run the full verification before merging:

```bash
./mvnw clean verify
```

For Spring Boot, insist that unit tests avoid loading the full Spring context. Integration tests should use Testcontainers for real dependencies. After a change, ask the agent to summarize which tests ran, what failed, and why. Then run the same command yourself. If a failure appears, ask for the smallest fix and have it re-run only the affected test. If the agent suggests disabling a failing test with `@Disabled`, reject that unless you asked for it. Ask it to explain the test context: does it need a mocked bean, a real container, or an `application-test.yml` profile? This keeps the loop tight and prevents hidden failures.

## Run multiple agents without file collisions using AgentVera

AgentVera is a desktop app that runs coding agents' real command line tools, including Gemini CLI, side by side in one window, each in its own terminal panel. For Spring Boot work, the most valuable parts are parallel agents in separate git worktrees so they don’t overwrite files, automatic code review where a second model catches JPA or test-lifecycle mistakes with file:line links, and checkpoints that let you undo any turn and replay a session step by step. This is more practical than switching terminals when one agent builds a feature while another writes integration tests against the same branch. [AI coding agent orchestration](/en/blog/ai-coding-agent-orchestration/) covers the broader pattern.

## Closing notes

Gemini CLI works well on Spring Boot projects when you give it exact build commands in `GEMINI.md`, keep tasks small, and verify every change with Maven or Gradle and your own diff review. Use focused prompts for controller-service-repository additions, rely on Testcontainers for integration coverage, and review JPA, configuration, and test-context changes carefully. With that discipline, the agent can carry a meaningful share of the daily Spring Boot work.

## Frequently asked questions

**Can Gemini CLI work with both Maven and Gradle Spring Boot projects?** Yes. Put the exact wrapper commands in GEMINI.md, such as ./mvnw test or ./gradlew test, and the agent will use them. It reads that file at the start of a session, so keep it current.

**What should I put in GEMINI.md for a Spring Boot project?** Include build, test, format, and run commands, the package layout, and Spring-specific rules like thin controllers, service tests, JPA entity boundaries, and Testcontainers for integration tests. Keep it short and update it when conventions change.

**How do I stop Gemini CLI from writing slow integration tests in Spring Boot?** Tell it to use @WebMvcTest or @DataJpaTest for isolated tests and Testcontainers only for real resource integration. Require a focused test command during iteration and review any @SpringBootTest it adds.

**Does Gemini CLI understand application.yml profiles and environment variables?** It can read YAML and properties, but you must declare rules about environment-specific values and secrets in GEMINI.md. Ask it to avoid committing secrets and to use ${VAR} placeholders instead.

---

**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/