Skip to content

project rulesBackend and APIsjavaspring-boot

Spring Boot Rules

Project rules for Spring Boot services: controller, service and repository layers, constructor injection, typed properties, validation and test slices.

npx workspacetemplates add spring-boot-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file24 lines · 1.3 KBFile
# Project rules: Spring Boot

## Layers
- Package by feature (`orders/`, `billing/`), each with controller, service and repository. Controllers only translate HTTP; services hold business rules; repositories hold queries.
- Use constructor injection with `final` fields. No field `@Autowired`.
- Expose records or DTO classes at the API edge. Never serialize JPA entities.

## Configuration
- Bind settings with `@ConfigurationProperties` on a record and `@Validated`. Avoid scattered `@Value`.
- Profiles for environments; secrets come from environment variables or a vault, never from committed YAML.

## Web
- Validate request bodies with `@Valid` and Jakarta constraints. Handle failures in one `@RestControllerAdvice` returning `ProblemDetail`.
- Return `ResponseEntity` only when you need to set status or headers.

## Data
- `@Transactional` belongs on service methods, not controllers. Keep reads `readOnly = true`.
- Prevent N+1 with fetch joins or entity graphs. Manage schema with Flyway or Liquibase, not `ddl-auto`.

## Tests
- `@WebMvcTest` for controllers, `@DataJpaTest` for repositories, plain JUnit 5 and Mockito for services. Use `@SpringBootTest` sparingly, with Testcontainers for real databases.

## Before finishing
Run `./mvnw verify` (or `./gradlew check`) and fix every warning you introduced.

What it does

Spring Boot makes it easy to wire almost anything, which is why services drift into field injection, fat controllers and slow tests. These rules set the layering and the testing approach up front.

The agent learns to bind configuration into typed classes, validate at the edge, and choose the narrowest test annotation that proves the behavior.

Example

you › Add an endpoint to refund an order line

agent › The agent adds a validated request record, a service method marked transactional, a ProblemDetail response for already refunded lines, and a WebMvcTest plus a service unit test.

Questions

Does it work for Gradle and Maven?
Yes. Only the final verify command differs, and the file names both.
Why avoid ddl-auto?
It changes the schema without review. A migration tool makes every schema change a visible, versioned file.
  • ASP.NET Core Web API Rules

    Project rulesdotnet

    Free
  • Django Rules

    Project rulespython

    Free
  • Flask Rules

    Project rulespython

    Free
  • Go Service Rules

    Project rulesgo

    Free