# Codex Spring Boot: A Practical Guide for Java Developers

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

Learn how to use Codex with Spring Boot: setup, AGENTS.md, prompts, testing, and parallel agents. Practical tips for controllers, services, JPA, JUnit 5.

**In short:**

- Codex works best in a Spring Boot project when AGENTS.md defines build, test, and package-by-feature conventions.
- Treat Codex as a pair programmer: plan small steps, run ./mvnw test after every change, and review the git diff.
- Use Testcontainers and JUnit 5 for integration checks, and watch transaction boundaries and bean configuration pitfalls.

Open your Spring Boot project folder, run `codex`, and give it a concrete task that touches controllers, services, Spring Data JPA, or tests. With a short AGENTS.md and a regular test loop, Codex is most useful as a fast pair programmer for Spring Boot: it handles the repetitive Java and configuration work, while you review the diff and enforce your project’s architecture. The rest of this guide covers setup, prompts, and verification for Spring Boot work.

## Why Codex suits Spring Boot work

Spring Boot has clear, repeatable layers: controllers, services, repositories, DTOs, and configuration. Codex reads those files well and can add consistent code when the conventions are written down. It is effective at generating JUnit 5 tests, Spring Data derived queries, validation annotations, and exception handlers. Because Maven and Gradle builds run from the command line, the agent can execute the same `./mvnw test` or `./gradlew test` that you use, and it can read the failure output to fix its own work.

The key is to treat Codex as an agent that operates on your repository, not as a code generator that returns snippets. Start it inside the project, point it at AGENTS.md, and ask for small, testable changes. If you are new to working with the CLI, the step-by-step guide on [how to use Codex CLI](/en/blog/how-to-use-codex-cli/) explains the basic loop.

## AGENTS.md for a Spring Boot project

Put a short AGENTS.md in the repository root. Codex reads it on startup, so the file should contain only the commands and rules that prevent wrong moves. For Spring Boot, define the build and test commands, the package layout, and a few hard rules about layering, DTOs, and test containers.

Here is a realistic example for a Maven project:

```markdown
# AGENTS.md

Spring Boot 3.3, Java 21, Maven.

## Commands
- Build: `./mvnw -q -DskipTests package`
- Test: `./mvnw test`
- Run: `./mvnw spring-boot:run`
- Format/lint: `./mvnw spotless:check`

## Folder conventions
- `src/main/java/com/example/orders`
  - `api` for controllers and DTOs
  - `application` for services and ports
  - `domain` for entities and business exceptions
  - `infrastructure` for JPA repositories and configuration
- `src/test/java` mirrors the package structure.

## Spring Boot rules
- Controllers only validate input, call a service, and return a DTO.
- Services are `@Transactional` where they write; use constructor injection.
- Repositories are Spring Data JPA interfaces; do not use `EntityManager` directly in services.
- Never expose JPA entities in controller responses.
- Use `@RestControllerAdvice` for consistent error responses.
- Tests: JUnit 5; integration tests use Testcontainers PostgreSQL; unit tests use Mockito.
```

Keep the file focused. Long AGENTS.md files dilute the rules the agent actually follows. For Gradle, swap in `./gradlew test`, `./gradlew bootRun`, and `./gradlew check`.

## A practical work loop: plan, implement, test, review

Use a small plan, implement, test, diff loop. Before each task, say what files may change and what the acceptance test is. After Codex edits, run the test command yourself or ask the agent to run it and read the output. Then review `git diff` for accidental changes to configuration, dependencies, or application properties.

Example prompts for Spring Boot work:

- "Add a `POST /orders` endpoint to `OrderController` that accepts an `OrderRequest` record, validates fields, calls `OrderService.placeOrder`, and returns 201 with `OrderResponse`."
- "Write a JUnit 5 unit test for `OrderService.cancelOrder`: when the order status is SHIPPED, throw `OrderAlreadyShippedException`; when CANCELLED, return the order unchanged."
- "Add a Spring Data JPA method `List<Order> findByCustomerIdAndStatus(Long customerId, OrderStatus status)` and use it in `OrderService.getCustomerOrdersByStatus`."
- "Create a Testcontainers integration test for `OrderRepository` using PostgreSQL that saves an order and finds it by customer id."
- "Refactor `OrderController` to use constructor injection with a record for the request and return `ResponseEntity<OrderResponse>` with correct status codes."

After a change, run `./mvnw test` and inspect the diff. If Codex changed `application.yml` or added a dependency, understand why before accepting.

## Spring Boot tasks Codex handles well, and where to double-check

Codex handles the common vertical slice well: controller, request/response record, service method, repository query, and tests. It is also useful for reducing boilerplate around exception handling, bean validation, and MapStruct-style mappers when instructed. The table shows where to direct it and where to check carefully.

| Task | Good prompt | Watch closely |
|------|-------------|---------------|
| REST endpoint | Add `GET /orders/{id}` returning `OrderResponse` or 404 | DTO fields, `@Valid`, status codes, error body |
| Service method | Add `cancelOrder` with business rules | `@Transactional` on writes, exceptions, idempotency |
| Repository query | Add `findByCustomerIdAndStatus` | Query derivation, pagination, fetch size |
| Configuration | Add a `@ConfigurationProperties` for payment settings | Bean name conflicts, prefix, profile-specific values |

Specific Spring Boot pitfalls: an agent may put business logic in the controller, forget `@Transactional` on a service method that writes to JPA, return an entity instead of a DTO, or introduce constructor injection mismatches after changing a record. It may generate a test that starts the full context when `@WebMvcTest` or `@DataJpaTest` would be faster. Also watch Spring Boot version compatibility: if the agent suggests a dependency, check that it is managed by the Spring Boot BOM rather than pinning a random version.

## Running JUnit and Testcontainers with Codex

Require the agent to run `./mvnw test` after every Spring Boot change and to fix only the failures it introduced. For unit tests, JUnit 5 with Mockito is usually enough: ask for `@ExtendWith(MockitoExtension.class)` and focused service tests. For persistence or web slices, prefer `@DataJpaTest` or `@WebMvcTest` over `@SpringBootTest` unless the task truly needs the whole context.

Integration tests with Testcontainers should use a static `@Container` PostgreSQL and `@ServiceConnection` so Spring Boot knows the datasource. Ask for rollback or cleanup between tests, and make sure the agent does not leave `spring.datasource.url` hard-coded to a developer machine. After the agent creates a test, run `./mvnw verify` once to catch failsafe or quality-plugin issues before merging.

## Parallel Codex agents on one Spring Boot project with AgentVera

When a Spring Boot feature spans several endpoints or modules, running multiple agents in AgentVera helps if you isolate work. The app runs each agent in its own git worktree, so one agent can edit a controller while another writes the repository without overwriting files. After each turn, [automatic code review](/en/blog/ai-code-review/) links findings to file:line, which catches missing transaction boundaries or broken DTO mapping. Checkpoints let you undo a bad refactor and replay the session, while token budgets keep parallel Spring Boot work from running away unnoticed. This fits the workflow described in [AI agent workflow: teams, parallel parts and flows](/en/blog/ai-agent-workflow-pipeline/).

## Final notes

Codex is practical for Spring Boot when the repository has an AGENTS.md, the tasks are small, and the test command is the source of truth. Keep controllers thin, services transactional, repositories declarative, and tests sliced. Run the tests, read the diff, and use worktrees or parallel agents for isolated features.

## Frequently asked questions

**How do I start Codex in a Spring Boot project?** Open the project folder in a terminal and run codex. Before the first task, add an AGENTS.md with your Maven or Gradle test command, package layout, and Spring Boot conventions, then ask for a small change in a controller or service.

**Can Codex write Spring Boot controllers, services, and repositories?** Yes, it can generate a vertical slice when the task is specific. Review the output for thin controllers, transactional services, DTO mapping, and Spring Data repository method names.

**Does Codex work with both Maven and Gradle Spring Boot projects?** Yes, Codex runs the commands you put in AGENTS.md, so use ./mvnw or ./gradlew. There is no Codex-specific build configuration; the agent simply executes the project’s normal build and test commands.

**How do I get Codex to write reliable Spring Boot tests?** Ask for JUnit 5 unit tests with Mockito and integration tests with Testcontainers. Specify the test slice, such as @WebMvcTest or @DataJpaTest, and require the agent to run the test command before finishing.

---

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