Claude Code works well on a Spring Boot project when you treat it as a fast pair programmer that can run your build and tests. The agent understands Maven or Gradle, JPA entity mapping, controller/service layering, and JUnit 5, but it needs concrete rules in CLAUDE.md to match your project. See Claude Code for the baseline workflow.
Where Claude Code fits in a Spring Boot project
Most Spring Boot projects share predictable conventions: @RestController, @Service, JpaRepository, application.yml, and Testcontainers. Claude Code can generate a working controller plus DTO plus service call faster than typing the boilerplate, but the real value is that it can also run ./mvnw test and read compiler and stack traces. It is best used for mechanical changes such as renaming a field across entity, DTO, mapper and tests, or for clarifying hidden coupling like cascade types, lazy loading and context configuration. Because Spring Boot relies heavily on annotations and conventions, the agent can propose a plausible implementation quickly; the risk is that the plausible implementation violates your project’s layering or transaction boundaries.
Preparing the repo with a focused CLAUDE.md
Create a CLAUDE.md in the repository root. Keep it focused; you can extend it over time. The file should define exact build and test commands, the package and architecture layout, and Spring Boot-specific constraints. Do not write prose about your whole domain; write rules the agent can check while editing.
A short but useful CLAUDE.md for a Maven project looks like this:
# Build and test commands
- full test: ./mvnw test
- single test: ./mvnw -Dtest=OrderServiceTest test
- run: ./mvnw spring-boot:run
- integration tests: ./mvnw -Pintegration-test verify
# Layout
- controllers live in com.acme.order.api and only convert DTOs.
- services live in com.acme.order.service and own transactions.
- repositories extend JpaRepository in com.acme.order.persistence.
- DTOs are Java records in com.acme.order.api.dto.
- mapper classes live in com.acme.order.api.mapper unless a simple constructor body is enough.
# Spring Boot rules
- Constructor injection only; no @Autowired on fields.
- @Transactional only on service methods that write more than one aggregate.
- Never put JPA entity mapping annotations on DTOs or vice versa.
- Keep bidirectional associations consistent in helper methods, not in controllers.
- Repository tests use @DataJpaTest with a PostgreSQL Testcontainer; service tests use plain JUnit with Mockito.
- Controller layer tests use @WebMvcTest with MockMvc and do not start the full context.
- Do not change the Spring Boot parent version, add starters or change application.yml without asking first.If you use Gradle, replace ./mvnw with ./gradlew and adapt the test filter. The key is giving the agent exact commands so it does not invent mvn test if your project uses the wrapper, and so it knows when integration tests need Docker. For larger refactors, start from plan mode, as covered in Claude Code plan mode: plan first, then let it build.
The daily loop: plan, edit, test, review
Run Claude Code with claude in the project directory. For anything beyond a one-line fix, start in plan mode. Ask it to describe the files it will change, the tests it will add, and the expected build result before letting it edit. Then have it implement in small commits and run the relevant test slice after each step. Review the diff before accepting; the agent sometimes changes application.yml, pom.xml or test configurations unnecessarily. The Claude Code best practices: a practical checklist applies: keep tasks narrow, ask for one behavior at a time, and check the diff.
Useful prompts for common Spring Boot changes:
Add POST /api/orders that accepts an OrderRequest record, maps it to an Order entity with embedded OrderItems, persists it transactionally in OrderService, and returns 201 with an OrderResponse. Follow the existing package and mapping style.Refactor OrderTotalCalculator out of OrderService. Make it a pure function with no Spring dependencies and add unit tests for promotions and tax rounding.Fix LazyInitializationException in GET /api/orders/{id}. Determine whether to use a fetch join in the repository or change the DTO mapping, then update tests.Write a Testcontainers integration test for OrderRepository that inserts a customer with two orders and asserts orphan removal when orders are cleared.Run ./mvnw test and fix only the failures introduced by the recent controller change.
High-value tasks and risky areas in Spring Boot
Claude Code handles repetitive Spring Boot changes well, but Spring Boot’s magic makes some errors appear only at runtime.
| Typical task | Good prompt | Watch for |
|---|---|---|
| Add a CRUD endpoint | Add a REST controller for Product with validation and use ProductService for persistence. | Controller absorbing business logic; DTO leak; missing @Valid. |
| Add a repository query | Add a derived query in OrderRepository to find orders by customerId and status, with pagination. | Wrong method name; missing @Param for named queries; N+1 from default fetch. |
| Write a slice test | Write a @WebMvcTest for OrderController with mocked OrderService. | Starting full context instead of slice; not asserting JSON error responses. |
| Change transaction behavior | Make OrderService.cancelOrder roll back both order update and stock reservation. | @Transactional on private method or self-invocation; missing rollbackFor for checked exceptions. |
Watch closely for these Spring Boot-specific problems:
- JPA entity equality with bidirectional associations: the agent may generate Lombok @Data on entities, causing recursion or broken equals/hashCode.
- Lazy loading: the agent may return entities from controllers or map them in a transaction-less context, causing LazyInitializationException during serialization.
- Transactions: the agent may add @Transactional to read-only queries or to controllers, changing exception boundaries and connection timing.
- Autoconfiguration and dependencies: the agent may add a starter or change a property to make a test pass locally while breaking the production bean graph or configuration profile.
- Testcontainers image management: the agent may hard-code Docker image versions or instantiate a new container per test class instead of using a shared, reusable configuration, which slows suites and can fail in CI.
Verifying with slice tests and Testcontainers
Make the agent run the exact Maven or Gradle command before calling a task done. For a Maven project, the green path is ./mvnw test for unit and slice tests, and ./mvnw -Pintegration-test verify when Testcontainers are involved. Ask the agent to separate those two phases instead of running everything every time.
For Spring Boot specifically:
- Use @DataJpaTest plus a PostgreSQL Testcontainer for repository tests. Let the agent start the container once per test run where possible; if there are multiple @DataJpaTest classes, use a shared container or ensure the existing test base class is followed.
- Use @WebMvcTest with MockMvc for controllers. Do not accept a full @SpringBootTest just to test one endpoint.
- Use plain Mockito unit tests for services, especially around transaction boundaries and DTO mapping.
- When the agent writes a Testcontainers test, check that it does not use hard-coded ports or image hashes and that it cleans up after the run.
- After each change, ask for the specific test slice that covers the change, then the full suite before merging.
Parallel workstreams with AgentVera
AgentVera runs multiple coding agents such as Claude Code side by side in one desktop window, each in its own real terminal and optionally its own git worktree. That is useful for a Spring Boot project because one agent can work on a controller while another writes repository migration tests without overwriting files. Automatic code review at the end of each turn catches transaction or lazy-loading mistakes before they enter main, and checkpoints let you undo a bad autoconfiguration or schema change in one click. Token budgets keep agent work auditable across a day. For running several native Claude Code agents in parallel, see How to run multiple Claude Code agents in parallel.
Final recommendations
Claude Code can be a productive addition to a Spring Boot team when you invest the first few minutes in a tight CLAUDE.md and keep changes small. Let it run the Maven or Gradle build and JUnit 5 tests continuously, but always review the diff around transactions, entity mapping and configuration. With clear rules and a test-first loop, most Spring Boot tasks become mechanical enough for the agent to handle safely.