spring-best-practices - SKILL.md Agent Skill

name: spring-best-practices description: Official Spring Framework and Spring Boot {version} reference docs with best practices and anti-patterns. Use for any work on a Spring project — writing, reviewing, or debugging Java/Kotlin/Scala code with Spring annotations (@SpringBootApplication, @RestController, @Service, @Repository, @Component, @Configuration, @Bean, @ConfigurationProperties, @KafkaListener, @FeignClient), editing application.yml / application.properties / bootstrap.yml, or touching build.gradle / pom.xml with spring-boot-starter dependencies. Also use when the user mentions Spring, Spring Boot, Spring Cloud, Spring Security, Spring Data, Spring AI, Actuator, Eureka, Feign, auto-configuration, or dependency injection.

Source: Official Spring {version} docs (auto-discovered from {project_count} projects) Generated: {generated_at}

Before writing any code, ask: does Spring already do this?

Auto-configuration backs off. Define your own @Bean and Boot's disappears.
@ConfigurationProperties > @Value. Typed, validated, IDE-friendly.
Starters > manual deps. spring-boot-starter-* manages compatible versions.
application.yml is the control panel. Most behaviors are property-toggleable.
Actuator is free observability. Health, metrics, tracing — all auto-configured.
Test slices exist for a reason. @WebMvcTest, @DataJpaTest — faster, focused.

Avoid	Spring way
`@Value` for property groups	`@ConfigurationProperties(prefix="...")`
`new RestTemplate()`	Inject `RestClient.Builder` or `WebClient.Builder`
Manual `ObjectMapper` bean	`Jackson2ObjectMapperBuilderCustomizer`
Manual `DataSource` config	`spring.datasource.*` properties
`@EnableWebMvc` (replaces Boot config)	`WebMvcConfigurer` bean to extend config
`@SpringBootTest` for everything	Slices: `@WebMvcTest`, `@DataJpaTest`, etc.
Hardcoded profile checks	`@Profile("prod")` + `spring.profiles.active`
Manual health endpoint	`HealthIndicator` bean + Actuator `/health`
Manual security filter chains	Use Spring Security's `SecurityFilterChain` bean
Blocking calls in WebFlux	Use reactive operators or `@Async`

Load the project you need, then drill into sections and topics. Do not load everything at once.

{project_index}

Check the anti-pattern table above first — the answer may already be there.
Open the relevant project's CONTENTS.md to see available sections.
Open the section's CONTENTS.md to see available topics.
Load only the specific topic file you need.
Before writing a custom @Bean, check if a spring.* property already controls the behavior.
Before writing a custom endpoint for health/metrics, check Actuator first.