CLAUDE.md for Spring Boot: 13 Rules That Make AI Write Production-Ready Java Web Applications

Spring Boot is the framework where AI assistance produces the widest range of output quality.

On one end: AI that follows Spring idioms, uses constructor injection, writes proper layered architecture, and generates code a senior Java engineer would approve. On the other end: AI that uses field injection everywhere, puts business logic in controllers, ignores transaction boundaries, and generates N+1 queries with JPA.

The difference between these outcomes isn't the model. It's whether you've defined what "correct Spring Boot" means for your project.

These 13 rules cover the patterns that matter most — the ones where AI consistently drifts without explicit instruction.

---

Rule 1: Constructor injection only — no field injection

Dependency injection: constructor injection exclusively.
Banned: @Autowired on fields. @Autowired on setters.
Required: final fields. All dependencies injected via constructor.
Use: Lombok @RequiredArgsConstructor to reduce boilerplate.

Field injection is the single most common AI-generated Spring anti-pattern. It makes classes untestable without a Spring container, hides dependencies, and creates circular dependency problems that surface at runtime.

// Banned — field injection
@Service
public class OrderService {
    @Autowired
    private OrderRepository orderRepository;  // Hidden dependency, untestable
}

// Required — constructor injection
@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository orderRepository;  // Explicit, testable, immutable
}

Constructor injection makes every dependency explicit. The class can be instantiated in a unit test with new OrderService(mockRepository) without any Spring context.

---

Rule 2: Layered architecture — controller, service, repository, domain

Architecture layers (strict separation):
- @RestController: HTTP only — request mapping, validation, response shaping.
- @Service: business logic. No HTTP types. No JPA entity graph decisions.
- @Repository: data access. JPA queries, JDBC, caching.
- Domain: POJOs / records. No Spring annotations.
- Cross-layer: use DTOs. Never pass JPA entities to controllers.

AI puts business logic in controllers because it's the fastest path to a working endpoint. This produces controllers with 200 lines of logic that can't be tested without HTTP infrastructure.

// Wrong — business logic in controller
@PostMapping("/orders")
public ResponseEntity<Order> createOrder(@RequestBody OrderRequest req) {
    // 50 lines of business logic here
    if (inventory.getStock(req.getProductId()) < req.getQuantity()) {
        throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Insufficient stock");
    }
    // ...
}

// Right — controller delegates to service
@PostMapping("/orders")
public ResponseEntity<OrderResponse> createOrder(@Valid @RequestBody OrderRequest req) {
    OrderResponse order = orderService.createOrder(req);
    return ResponseEntity.status(HttpStatus.CREATED).body(order);
}

---

Rule 3: DTOs for every API boundary — never expose JPA entities

API contracts:
- Request: dedicated request DTO with @Valid validation annotations.
- Response: dedicated response DTO. Never return @Entity classes.
- Mapping: MapStruct for DTO-entity mapping. No manual getters/setters chains.
- Records: use Java records for immutable DTOs where appropriate.

Exposing JPA entities from REST controllers leaks database structure, creates circular serialization issues with bidirectional relationships, and makes schema changes break API contracts.

// Banned — entity in response
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
    return userRepository.findById(id).orElseThrow();  // Exposes everything
}

// Required — response DTO
public record UserResponse(Long id, String email, String displayName) {}

@GetMapping("/users/{id}")
public UserResponse getUser(@PathVariable Long id) {
    User user = userRepository.findById(id).orElseThrow(() -> new ResourceNotFoundException("User", id));
    return userMapper.toResponse(user);
}

---

Rule 4: Transaction boundaries in the service layer

Transactions:
- @Transactional on service methods, not controllers or repositories.
- Read-only queries: @Transactional(readOnly = true) — enables query optimizations.
- Never @Transactional on repository methods for business operations.
- Checked exceptions do NOT trigger rollback by default — use rollbackFor if needed.
- No @Transactional on private methods — Spring AOP won't intercept them.

AI generates @Transactional wherever it sees database access, including on private methods where it has no effect, and on controllers where it creates unnecessarily long transactions.

// Wrong — @Transactional on private method (no effect)
@Service
public class PaymentService {
    @Transactional
    private void processPayment(Order order) { ... }  // AOP proxy can't intercept this
}

// Right — transaction on public service method
@Service
public class PaymentService {
    @Transactional(rollbackFor = PaymentException.class)
    public PaymentResult processPayment(Long orderId) {
        Order order = orderRepository.findById(orderId).orElseThrow();
        // business logic
    }

    @Transactional(readOnly = true)
    public List<PaymentSummary> getPaymentHistory(Long userId) { ... }
}

---

Rule 5: JPA — explicit fetch strategies, no lazy loading surprises

JPA fetch strategy:
- Default all associations to LAZY. Never EAGER on @ManyToOne or @OneToMany.
- Load what you need via JPQL JOIN FETCH or @EntityGraph.
- No accessing lazy collections outside a transaction (LazyInitializationException).
- Named queries or Spring Data specifications for complex queries.
- Pagination: always use Pageable — never load unbounded collections.

EAGER loading is the JPA equivalent of N+1 — it fetches everything whether you need it or not, at the cost of joins on every query.

// Banned — EAGER by default (fetches User on every Order query)
@ManyToOne(fetch = FetchType.EAGER)
private User user;

// Required — LAZY, explicit when needed
@ManyToOne(fetch = FetchType.LAZY)
private User user;

// Load explicitly in the query that needs it
@Query("SELECT o FROM Order o JOIN FETCH o.user WHERE o.status = :status")
List<Order> findByStatusWithUser(@Param("status") OrderStatus status);

---

Rule 6: Validation at the boundary — Bean Validation on DTOs

Validation:
- All input validation via Bean Validation annotations on DTOs (@NotNull, @Size, @Email, @Pattern).
- @Valid on controller method parameters — triggers validation automatically.
- @Validated on service beans for method-level validation.
- Custom validators: implement ConstraintValidator for business rules.
- Never validate in service layer what can be validated at the boundary.

public record CreateUserRequest(
    @NotBlank @Email String email,
    @NotBlank @Size(min = 8, max = 100) String password,
    @NotBlank @Size(min = 2, max = 50) String displayName
) {}

@PostMapping("/users")
public ResponseEntity<UserResponse> createUser(@Valid @RequestBody CreateUserRequest req) {
    // req is guaranteed valid here — no manual null checks needed
    return ResponseEntity.status(HttpStatus.CREATED).body(userService.createUser(req));
}

---

Rule 7: Exception handling via @ControllerAdvice — no scattered @ExceptionHandler

Error handling:
- Global exception handler: one @RestControllerAdvice class.
- Typed exception hierarchy: domain exceptions extend RuntimeException.
- Standard error response shape: { error, message, path, timestamp }.
- Never catch Exception broadly in service layer without rethrowing.
- HTTP status mapping in the advice class, not in service or repository.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ErrorResponse handleNotFound(ResourceNotFoundException ex, HttpServletRequest req) {
        return new ErrorResponse("not_found", ex.getMessage(), req.getRequestURI());
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorResponse handleValidation(MethodArgumentNotValidException ex, HttpServletRequest req) {
        String message = ex.getBindingResult().getFieldErrors().stream()
            .map(e -> e.getField() + ": " + e.getDefaultMessage())
            .collect(Collectors.joining(", "));
        return new ErrorResponse("validation_failed", message, req.getRequestURI());
    }
}

---

Rule 8: Configuration via @ConfigurationProperties — not @Value scattered everywhere

Configuration:
- Group related config in @ConfigurationProperties classes.
- Validate with @Validated + Bean Validation annotations.
- No @Value on individual fields across multiple classes.
- Profiles: application-{profile}.yml for environment differences.
- Secrets: externalize via environment variables or secret manager — never in application.yml.

@ConfigurationProperties(prefix = "app.payment")
@Validated
public record PaymentConfig(
    @NotBlank String apiKey,
    @NotNull @Min(1) Integer timeoutSeconds,
    @NotBlank String webhookSecret
) {}

---

Rule 9: Security — Spring Security properly configured

Security:
- Explicit SecurityFilterChain bean — no WebSecurityConfigurerAdapter (deprecated Spring Boot 3+).
- CSRF: disabled for stateless REST APIs using JWT. Enable for session-based apps.
- CORS: configure via CorsConfigurationSource bean, not annotations on controllers.
- Password encoding: BCryptPasswordEncoder only. Never store plain text or MD5.
- Method security: @PreAuthorize on service methods for business-level authorization.

AI still generates WebSecurityConfigurerAdapter (removed in Spring Boot 3) and forgets to configure CORS when the frontend is on a different origin.

---

Rule 10: Testing — slice tests, not full context loads

Testing strategy:
- Unit tests: plain JUnit 5 + Mockito. No Spring context. Constructor injection makes this trivial.
- Web layer: @WebMvcTest for controllers. Mocks the service layer.
- Data layer: @DataJpaTest with H2 or Testcontainers for repositories.
- Integration: @SpringBootTest(webEnvironment = RANDOM_PORT) for full stack only.
- Never use @SpringBootTest for unit or slice tests — it's 10x slower.

// Web layer test — fast, no full context
@WebMvcTest(OrderController.class)
class OrderControllerTest {
    @Autowired MockMvc mockMvc;
    @MockBean OrderService orderService;

    @Test
    void createOrder_validRequest_returns201() throws Exception {
        given(orderService.createOrder(any())).willReturn(sampleOrderResponse());
        mockMvc.perform(post("/orders").contentType(APPLICATION_JSON).content(validOrderJson()))
            .andExpect(status().isCreated());
    }
}

---

Rule 11: Actuator and observability — configure from the start

Observability:
- Spring Boot Actuator: enabled with health, info, metrics endpoints.
- Health checks: custom HealthIndicator for external dependencies (DB, cache, external API).
- Metrics: Micrometer with Prometheus registry.
- Logging: structured JSON logging in production (logstash-logback-encoder).
- Correlation IDs: MDC for request tracing across log lines.

---

Rule 12: Async operations — @async with explicit executors

Async:
- @EnableAsync on configuration class.
- @Async methods: dedicated @Bean ThreadPoolTaskExecutor — not the default SimpleAsyncTaskExecutor.
- Return CompletableFuture<T> from async methods, not void (for error handling).
- Never call @Async methods from the same class — Spring AOP proxy won't intercept.
- Scheduled tasks: @Scheduled with fixedDelay or cron, with @EnableScheduling.

---

Rule 13: The CLAUDE.md block for Spring Boot

## Spring Boot Standards

**Version:** Spring Boot 3.x | Java 21+ | Gradle (Kotlin DSL)

### Architecture
- Strict layering: Controller → Service → Repository → Domain
- DTOs at every API boundary — never expose @Entity directly
- MapStruct for DTO-entity mapping

### Dependency Injection
- Constructor injection only. @Autowired on fields is banned.
- Use Lombok @RequiredArgsConstructor to reduce boilerplate.

### JPA / Database
- All associations: FetchType.LAZY by default
- Explicit JOIN FETCH or @EntityGraph when loading associations
- @Transactional(readOnly = true) on all read-only service methods
- Always paginate with Pageable — no unbounded findAll()

### Validation & Errors
- Bean Validation (@Valid) on all request DTOs
- One @RestControllerAdvice for all exception handling
- Typed exception hierarchy extending RuntimeException

### Security
- SecurityFilterChain bean (not WebSecurityConfigurerAdapter)
- BCryptPasswordEncoder for passwords
- @PreAuthorize on service methods for authorization

### Testing
- Unit tests: JUnit 5 + Mockito, no Spring context
- Controller tests: @WebMvcTest
- Repository tests: @DataJpaTest + Testcontainers
- @SpringBootTest only for integration tests

---

Why this matters for Spring Boot specifically

Spring Boot's "convention over configuration" model is powerful — and it means AI has strong defaults to lean on. The problem is those defaults aren't always the right ones for production.

EAGER fetch is the JPA default. Field injection works. WebSecurityConfigurerAdapter was the pattern for years. Business logic in controllers produces working code. None of these fail in development.

They fail when your database handles real load, when you need to write unit tests without starting a container, or when you upgrade Spring Boot and discover the deprecated APIs.

The CLAUDE.md block above defines what "Spring Boot done right" means for your project before AI generates a single line. The 15 minutes you spend writing it pays back on every controller, service, and repository the AI generates from then on.