Agent-skills-standard spring-boot-architecture

Structure Spring Boot 3+ projects with feature packaging and clean layering. Use when structuring Spring Boot 3 projects, defining layers, or applying architecture patterns. (triggers: pom.xml, build.gradle, structure, layering, dto, controller, @RestController, @Service, @Repository, @Entity, @Bean, @Configuration)

install

source · Clone the upstream repo

git clone https://github.com/HoangNguyen0403/agent-skills-standard

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/HoangNguyen0403/agent-skills-standard "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/spring-boot/spring-boot-architecture" ~/.claude/skills/hoangnguyen0403-agent-skills-standard-spring-boot-architecture && rm -rf "$T"

manifest: skills/spring-boot/spring-boot-architecture/SKILL.md

source content

Spring Boot Architecture Standards

Priority: P0 (CRITICAL)

Organize by Feature

Package by Feature: Prefer
```
com.app.feature
```
(e.g.,
```
user
```
,
```
order
```
) over technical layers (
```
controllers
```
) for scalability.
Dependency Rule: Outer layers (Web) depend on Inner (Service). Inner layers MUST NOT depend on Outer.
DTO Pattern: ALWAYS use DTOs for API inputs/outputs. NEVER return
```
@Entity
```
directly.
Java Records: Use
```
record
```
for DTOs to ensure immutability (Java 17+).

See implementation examples for Java Record DTOs, controller patterns, and global exception handling.

Define Layer Responsibilities

Controller (Web): Handle HTTP, Validation (
```
@Valid
```
), DTO mapping. Delegate logic to Service.
Service (Business): Transaction boundaries, orchestration. Returns Domain/DTOs.
Repository (Data): Database interactions only. Returns Entities/Projections.

Design API Layer

Global Error Handling: Use
```
@RestControllerAdvice
```
with
```
ProblemDetails
```
(RFC 7807).
Validation: Use Jakarta Bean Validation (
```
@NotNull
```
,
```
@Size
```
) on DTOs.
Response: Use
```
ResponseEntity
```
for explicit status or
```
ResponseStatusException
```
.

Verification Checklist (Mandatory)

No Entities in API: all API responses using DTOs/Records instead of JPA Entities?
Validation:
```
@Valid
```
and Jakarta Bean Validation constraints present on all input DTOs?
Layer coupling: Services depend on Controllers? (Prohibited)
Transactionality: business transactions correctly bounded with
```
@Transactional
```
in Service layer?
Error Details:
```
ProblemDetails
```
used for consistent error responses?

Anti-Patterns

No Fat Controllers: Move business logic to Services.
No Leaking Entities: Use DTOs instead of JPA Entities in APIs.
No Circular Dependencies: Use Events or refactor to decouple services.
No God Classes: Split large services into single-responsibility components.

References

Implementation Examples