CLAUDE instructions for this repo

Project overview

• Spring Boot application with AI-assisted development workflows.
• See README.md and spring-boot-development-best-practices.md for full details.

How to use this guide

• Before large changes, scan the "Best Practices" doc.
• Prefer patterns and examples from ./snippets/.
• When in doubt, 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 Boot patterns (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.

Spring Boot conventions

Architecture:

• Layered: Controller → Service → Repository
• Controllers thin: validation + delegation only
• Services: business logic + @Transactional
• Repositories: Spring Data JPA interfaces

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 (only if approved)

Testing:

• @WebMvcTest for controllers
• @ExtendWith(MockitoExtension.class) for service unit tests
• @DataJpaTest for repositories
• @SpringBootTest for integration only

HTTP:

• @RestControllerAdvice global exception handling
• RESTful paths: /api/v1/resources
• HATEOAS links where appropriate

Security:

• Method security: @PreAuthorize
• Secrets via env vars / Vault

Claude code skills for Spring Boot

Ready-to-use skills in snippets/:

Skill	Trigger	Purpose
spring-config	/spring-config	Configuration patterns and property binding
spring-controller	/spring-controller <name>	REST controller + DTOs + validation
spring-exception	/spring-exception	Exception handling patterns
spring-repository	/spring-repository <name>	Repository patterns and queries
spring-security	/spring-security	Security patterns and configuration
spring-service	/spring-service <name>	@Transactional service + tests
spring-test	/spring-test	Correct test slice for file
spring-review	/spring-review	Spring Boot best practices review

Usage examples:

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