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 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 covers invocation; the project file below is what makes the agent reliable on a Spring Boot repo.
# 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 otherwiseA 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/ordersendpoint. 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.cancelOrderso 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
OrderRepositoryagainst PostgreSQL. Use@SpringBootTestand@Testcontainers, start a matching PostgreSQL image, and assert create, read, update, and delete operations. - The test
OrderServiceTest.cancelOrder_throwsWhenShippedis 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:
./mvnw -Dtest=OrderControllerTest,OrderServiceTest testRun the full verification before merging:
./mvnw clean verifyFor 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 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.