| name | java-spring-framework-generic |
| description | Comprehensive guidelines, patterns, and best practices for Spring Boot 3.x application development — covering REST APIs, data access, security, observability, async patterns, testing, and production readiness.
|
| version | 2.0.0 |
| kind | guidance |
| triggers | ["work on spring boot project","create spring boot application","spring rest api","spring data jpa","spring security","spring boot backend","spring framework"] |
| intent | execution |
| guardrails | ["Target Spring Boot 3.x (Jakarta EE 10+) and Java 21 LTS unless the project is explicitly pinned to an older version.","Always use constructor injection. Never field injection (@Autowired on fields), and setter injection only for genuinely optional dependencies.","Never expose JPA entities from REST controllers. Use dedicated DTO/record types for request and response payloads.","Annotate service-layer write operations with @Transactional. Never annotate controller methods.","Do not use System.out.println. Use SLF4J with parameterized messages.","Never hardcode secrets. Bind @ConfigurationProperties to environment variables or a secrets manager.","Validate incoming payloads with Jakarta Bean Validation (@Valid / @Validated) at the controller boundary — never in the service layer.","When starting a new app, check for an existing OpenAPI schema and build to it. Starting from scratch, write the schema before the implementation.","Always use MockMvc for testing REST controllers.","Use SDKMAN environment variables (JAVA_HOME, JAVA21_HOME, SDKMAN_CANDIDATES_DIR) when present.","When M2_HOME is set it is the shared Maven local repository — pass it through (-Dmaven.repo.local=\"$M2_HOME\") rather than letting the build default to ~/.m2.","Always build via the project wrapper (./mvnw or ./gradlew), never a globally installed tool."] |
| tools | ["bash"] |
| created_at | 2026-05-30T00:00:00.000Z |
| updated_at | 2026-07-29T00:00:00.000Z |
Spring Boot development guidelines
Spring Boot 3.x on Java 21. The guardrails above apply to every task; the
references below carry the detail for whichever layer you are working in.
Read next
| file | when |
|---|
references/foundations.md | starting or restructuring an app — version baseline, project layout, DI, configuration |
references/web-layer.md | REST controllers and the service layer |
references/data-access.md | repositories, entities, queries, transactions (Spring Data JPA) |
references/errors-validation.md | error responses, exception handlers, request validation |
references/security.md | authentication, authorization, filter chains |
references/testing.md | writing or reviewing tests |
references/operations.md | observability, async/concurrency, domain events, caching |
references/api-and-release.md | OpenAPI documentation, production readiness checklist |
When a task spans layers, load only the references it actually touches — these
are deliberately separable.
