Instructions for this repo

Project overview

• Spring Boot WebFlux (Reactive) application with AI-assisted development workflows.
• See README.md and spring-boot-development-best-practices.md for full details.
• Best practices are documented in spring-boot-development-best-practices.md.
• Reusable examples live in ./snippets/.

How to use this guide

• Use these instructions as persistent session context for Claude.
• Before large changes, scan the "Best Practices" doc.
• Prefer patterns and examples from ./snippets/ when generating code or reviews.
• When uncertain, ask for solutions that align with these docs.

Code style & architecture

• Follow the architecture and patterns described in spring-boot-development-best-practices.md.
• Prefer established Spring WebFlux patterns (reactive layers, configuration, testing strategies) from that doc.
• Do not introduce new frameworks or libraries unless explicitly requested.

Commands

• Build: ./mvnw clean package
• Tests: ./mvnw test
• Run: ./mvnw spring-boot:run

Safety & scope

• Propose a plan before changing more than a few files.
• Keep changes within the described architecture and conventions.
• If instructions conflict, prefer the Best Practices guide.

Development expectations

• Follow the layering and patterns from the Best Practices guide.
• Prefer existing libraries and approaches already used in the codebase.
• Suggest tests for new behavior, using the testing patterns from the guide.
• Keep snippets short and align with the surrounding file style.

What to Include

1. Project overview - app purpose, key domains
2. Tech stack - Spring Boot version, database, security, messaging
3. Layering rules - controller/service/repo boundaries
4. Spring-specific patterns - constructor injection, @Transactional, test slices
5. Maven/Gradle commands - build, test, run, profiles
6. DTO/validation patterns - request/response separation

Key Spring Boot Conventions Section

Spring Boot Conventions

Architecture:

• Layered: Controller → Service → Repository
• Controllers thin: validation + delegation only
• Services: business logic + reactive transactions when needed (e.g., using Spring’s TransactionalOperator or other reactive transaction management)
• Repositories: Spring Data R2DBC or ReactiveMongoRepository

Dependency Injection:

• Constructor injection only (no @Autowired fields)
• @Service, @Repository, @RestController stereotypes
• @ConfigurationProperties for external config

DTOs:

• Separate request/response DTOs from entities
• @Valid + Bean Validation on controllers
• MapStruct/Lombok for entity↔DTO mapping

Services:

• Keep business logic in services; controllers only validate and delegate.
• Use constructor injection and reactive transactions when needed.
• Return Mono/Flux from service methods; avoid blocking calls.

Testing:

• @WebFluxTest for controllers
• @ExtendWith(MockitoExtension.class) for service unit tests
• @DataR2dbcTest or reactive test slices for repositories
• @SpringBootTest for integration only
• Use WebTestClient for HTTP layer tests

HTTP:

• @RestControllerAdvice global exception handling
• RESTful paths: /api/v1/resources

Reactive:

• End-to-end Mono/Flux in controllers/services/repos
• Avoid blocking calls (block(), subscribe() in production paths)
• Use reactive drivers (R2DBC, Reactive Mongo)

Security:

• Method security: @PreAuthorize
• Use reactive security (SecurityWebFilterChain)
• Secrets via env vars / Vault

Claude Code Skills for Spring Boot

Reactive skills are in snippets/skills/:

• spring-controller
• spring-service
• spring-repository
• spring-exception
• spring-test
• spring-config
• spring-security

Usage examples (Claude):

/spring-controller UserController --feature users
/spring-service UserService
/spring-test UserController.java

Architecture Patterns and Code Snippets

Recommended Project Structure

src/main/java/com/example/demo/
├── config/              # @Configuration classes
├── controller/          # @RestController (WebFlux)
├── dto/                 # Request/response DTOs
│   ├── request/
│   └── response/
├── service/             # @Service business logic (reactive)
├── repository/          # Reactive repositories (R2DBC/Mongo)
├── model/               # Domain entities/documents
├── exception/           # Custom exceptions
└── Application.java

src/test/java/
├── controller/          # @WebFluxTest + WebTestClient
├── service/             # @ExtendWith(MockitoExtension.class) unit tests
├── repository/          # @DataR2dbcTest / reactive repo tests
└── integration/         # @SpringBootTest

REST Controller + DTO Pattern

// dto/request/CreateUserRequest.java
public record CreateUserRequest(
    @NotBlank String name,
    @Email String email,
    @Size(min=8) String password
) {}

// dto/response/UserResponse.java
record UserResponse(String id, String name, String email) {}

@RestController
@RequestMapping("/api/v1/users")
class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @PostMapping
    public Mono<ResponseEntity<UserResponse>> create(
            @Valid @RequestBody Mono<CreateUserRequest> request) {
        return request
            .flatMap(userService::create)
            .map(user -> ResponseEntity.created(URI.create("/api/v1/users/" + user.id()))
                .body(user));
    }
}

Commands

• Build: ./mvnw clean package
• Tests: ./mvnw test
• Run: ./mvnw spring-boot:run

Review behavior

• When reviewing code, check alignment with the Best Practices guide.
• Highlight deviations and suggest concrete alternatives.
• Call out blocking or non-reactive code in WebFlux paths.