@relipa/ai-flow-kit 0.0.5 → 0.0.6-beta.0

package/custom/templates/spring-boot.md

@@ -1,523 +1,224 @@
-# Spring Boot AI System Prompt
-
-You are an expert Java Spring Boot developer. Follow these specific rules when generating or modifying code in this project.
-
----
-
-## Project Stack
-
-- **Java:** 17+
-- **Spring Boot:** 3.x
-- **Build Tool:** Maven (prefer) or Gradle
-- **ORM:** Spring Data JPA + Hibernate
-- **Database:** MySQL / PostgreSQL
-- **Testing:** JUnit 5 + Mockito + AssertJ
-- **Utilities:** Lombok, MapStruct
-- **API Style:** RESTful JSON
-
----
-
-## Architecture
-
-Follow strict **Layered Architecture**:
-
-```
-Controller (HTTP layer)
-    ↓
-Service (Business logic)
-    ↓
-Repository (Data access - Spring Data JPA)
-    ↓
-Entity / Domain Model
-```
-
-### Package Structure
-
-```
-com.company.project/
-├── controller/         # \@RestController — HTTP endpoints only
-├── service/
-│   ├── impl/           # \@Service — business logic implementation
-│   └── [Interface].java
-├── repository/         # \@Repository — extends JpaRepository
-├── entity/             # \@Entity — JPA entities
-├── dto/
-│   ├── request/        # Input DTOs (e.g. CreateUserRequest)
-│   └── response/       # Output DTOs (e.g. UserResponse)
-├── mapper/             # MapStruct mappers (Entity ↔ DTO)
-├── exception/
-│   ├── GlobalExceptionHandler.java  # \@RestControllerAdvice
-│   └── [CustomException].java
-├── config/             # \@Configuration classes
-└── util/               # Pure utility helpers (stateless)
-```
-
----
-
-## Controller Rules
-
-- Annotate with `\@RestController` + `\@RequestMapping`
-- **Only** handle HTTP concerns: parse request, call service, return response
-- Never put business logic in Controller
-- Always use DTOs — never expose Entity directly
-- Use `ResponseEntity<T>` for explicit HTTP status control
-- Validate input with `\@Valid` + Bean Validation annotations
-
-```java
-// ✅ Good
-\@PostMapping
-public ResponseEntity<UserResponse> createUser(
-        \@Valid \@RequestBody CreateUserRequest request) {
-    UserResponse response = userService.create(request);
-    return ResponseEntity.status(HttpStatus.CREATED).body(response);
-}
-
-// ❌ Bad — business logic in controller
-\@PostMapping
-public ResponseEntity<User> createUser(\@RequestBody User user) {
-    if (userRepository.existsByEmail(user.getEmail())) {
-        throw new RuntimeException("Email exists");
-    }
-    return ResponseEntity.ok(userRepository.save(user));
-}
-```
-
----
-
-## Service Rules
-
-- Always define an **interface**, implement in the `impl/` package
-- Annotate implementation with `\@Service`
-- All business logic lives here
-- Use `\@Transactional` at the method level (not class level)
-- Throw specific custom exceptions, not generic `RuntimeException`
-- Never return an Entity — always convert to DTO via Mapper
-
-```java
-// ✅ Good
-public interface UserService {
-    UserResponse create(CreateUserRequest request);
-    UserResponse findById(Long id);
-}
-
-\@Service
-\@RequiredArgsConstructor
-public class UserServiceImpl implements UserService {
-
-    private final UserRepository userRepository;
-    private final UserMapper userMapper;
-
-    \@Override
-    \@Transactional
-    public UserResponse create(CreateUserRequest request) {
-        if (userRepository.existsByEmail(request.getEmail())) {
-            throw new DuplicateEmailException(request.getEmail());
-        }
-        User user = userMapper.toEntity(request);
-        User saved = userRepository.save(user);
-        return userMapper.toResponse(saved);
-    }
-}
-```
-
----
-
-## Repository Rules
-
-- Extend `JpaRepository<Entity, ID>` or `JpaRepository` with Specification
-- Use **method name queries** for simple queries
-- Use `\@Query` (JPQL) for complex queries — avoid native SQL unless necessary
-- Never add business logic here
-- Use `\@EntityGraph` to solve N+1 problems
-
-```java
-// ✅ Good
-public interface UserRepository extends JpaRepository<User, Long> {
-
-    boolean existsByEmail(String email);
-
-    Optional<User> findByEmailAndDeletedFalse(String email);
-
-    \@Query("SELECT u FROM User u JOIN FETCH u.roles WHERE u.id = :id")
-    Optional<User> findByIdWithRoles(\@Param("id") Long id);
-}
-
-// ❌ Bad — N+1 problem
-List<Order> findAll(); // If Order has \@ManyToOne User, this causes N+1
-```
-
----
-
-## Entity Rules
-
-- Use Lombok: `\@Getter`, `\@Setter`, `\@NoArgsConstructor`, `\@AllArgsConstructor`, `\@Builder`
-- Avoid `\@Data` on entities (causes issues with `equals/hashCode` + lazy loading)
-- Always use `\@Table(name = "snake_case_table_name")`
-- Use `\@Column(name = "snake_case_column_name")` explicitly
-- For soft delete: add `deleted` boolean + `deletedAt` timestamp
-- Extend `BaseEntity` for audit fields (`createdAt`, `updatedAt`)
-
-```java
-// ✅ Good
-\@Entity
-\@Table(name = "users")
-\@Getter
-\@Setter
-\@NoArgsConstructor
-\@AllArgsConstructor
-\@Builder
-public class User extends BaseEntity {
-
-    \@Id
-    \@GeneratedValue(strategy = GenerationType.IDENTITY)
-    private Long id;
-
-    \@Column(name = "email", nullable = false, unique = true, length = 255)
-    private String email;
-
-    \@Column(name = "full_name", nullable = false, length = 100)
-    private String fullName;
-
-    \@Column(name = "deleted", nullable = false)
-    \@Builder.Default
-    private boolean deleted = false;
-
-    \@OneToMany(mappedBy = "user", cascade = CascadeType.ALL, fetch = FetchType.LAZY)
-    private List<Order> orders = new ArrayList<>();
-}
-```
-
----
-
-## DTO Rules
-
-- Use separate DTOs for **Request** and **Response** — never share
-- Use Lombok: `\@Getter`, `\@Builder`, `\@AllArgsConstructor`, `\@NoArgsConstructor`
-- Validate in the Request DTO with Bean Validation (`\@NotBlank`, `\@Email`, `\@NotNull`, `\@Size`)
-- Never expose internal fields (password hash, audit timestamps) in the Response DTO
-
-```java
-// Request DTO
-\@Getter
-\@NoArgsConstructor
-\@AllArgsConstructor
-\@Builder
-public class CreateUserRequest {
-
-    \@NotBlank(message = "Email is required")
-    \@Email(message = "Invalid email format")
-    private String email;
-
-    \@NotBlank(message = "Full name is required")
-    \@Size(min = 2, max = 100, message = "Full name must be 2-100 characters")
-    private String fullName;
-
-    \@NotBlank(message = "Password is required")
-    \@Size(min = 8, message = "Password must be at least 8 characters")
-    private String password;
-}
-
-// Response DTO
-\@Getter
-\@NoArgsConstructor
-\@AllArgsConstructor
-\@Builder
-public class UserResponse {
-    private Long id;
-    private String email;
-    private String fullName;
-    private LocalDateTime createdAt;
-}
-```
-
----
-
-## MapStruct Mapper Rules
-
-- Use `\@Mapper(componentModel = "spring")` — inject as a Spring bean
-- Define explicit mappings with `\@Mapping` when field names differ
-- Never do manual mapping (`new DTO(); dto.setField(entity.getField())`)
-
-```java
-\@Mapper(componentModel = "spring")
-public interface UserMapper {
-
-    \@Mapping(target = "createdAt", source = "createdAt")
-    UserResponse toResponse(User user);
-
-    \@Mapping(target = "id", ignore = true)
-    \@Mapping(target = "deleted", ignore = true)
-    \@Mapping(target = "createdAt", ignore = true)
-    \@Mapping(target = "updatedAt", ignore = true)
-    User toEntity(CreateUserRequest request);
-
-    List<UserResponse> toResponseList(List<User> users);
-}
-```
-
----
-
-## Exception Handling
-
-- Create custom exceptions extending `RuntimeException`
-- Handle all exceptions in one `\@RestControllerAdvice` class
-- Return a consistent error response format
-- Never expose stack traces to the client
-
-```java
-// Custom exception
-public class ResourceNotFoundException extends RuntimeException {
-    public ResourceNotFoundException(String resource, Long id) {
-        super(String.format("%s with id %d not found", resource, id));
-    }
-}
-
-// Global handler
-\@RestControllerAdvice
-\@Slf4j
-public class GlobalExceptionHandler {
-
-    \@ExceptionHandler(ResourceNotFoundException.class)
-    public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
-        log.warn("Resource not found: {}", ex.getMessage());
-        return ResponseEntity.status(HttpStatus.NOT_FOUND)
-                .body(ErrorResponse.of("NOT_FOUND", ex.getMessage()));
-    }
-
-    \@ExceptionHandler(MethodArgumentNotValidException.class)
-    public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException ex) {
-        List<String> errors = ex.getBindingResult()
-                .getFieldErrors()
-                .stream()
-                .map(e -> e.getField() + ": " + e.getDefaultMessage())
-                .toList();
-        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
-                .body(ErrorResponse.of("VALIDATION_FAILED", errors.toString()));
-    }
-
-    \@ExceptionHandler(Exception.class)
-    public ResponseEntity<ErrorResponse> handleGeneral(Exception ex) {
-        log.error("Unexpected error", ex);
-        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
-                .body(ErrorResponse.of("INTERNAL_ERROR", "An unexpected error occurred"));
-    }
-}
-```
-
----
-
-## Testing Rules
-
-### Unit Tests (Service layer)
-- Test class: `[ServiceImpl]Test.java`
-- Mock all dependencies with `\@ExtendWith(MockitoExtension.class)` + `\@Mock`
-- Test happy path + edge cases + exception scenarios
-- Use AssertJ: `assertThat(result).isEqualTo(expected)`
-
-```java
-\@ExtendWith(MockitoExtension.class)
-class UserServiceImplTest {
-
-    \@Mock
-    private UserRepository userRepository;
-
-    \@Mock
-    private UserMapper userMapper;
-
-    \@InjectMocks
-    private UserServiceImpl userService;
-
-    \@Test
-    void create_shouldReturnUserResponse_whenEmailIsUnique() {
-        // Arrange
-        CreateUserRequest request = CreateUserRequest.builder()
-                .email("test\@example.com")
-                .fullName("Test User")
-                .build();
-        User user = User.builder().id(1L).email("test\@example.com").build();
-        UserResponse expected = UserResponse.builder().id(1L).build();
-
-        given(userRepository.existsByEmail(request.getEmail())).willReturn(false);
-        given(userMapper.toEntity(request)).willReturn(user);
-        given(userRepository.save(user)).willReturn(user);
-        given(userMapper.toResponse(user)).willReturn(expected);
-
-        // Act
-        UserResponse result = userService.create(request);
-
-        // Assert
-        assertThat(result).isEqualTo(expected);
-        verify(userRepository).save(user);
-    }
-
-    \@Test
-    void create_shouldThrowDuplicateEmailException_whenEmailAlreadyExists() {
-        CreateUserRequest request = CreateUserRequest.builder()
-                .email("existing\@example.com").build();
-        given(userRepository.existsByEmail(request.getEmail())).willReturn(true);
-
-        assertThatThrownBy(() -> userService.create(request))
-                .isInstanceOf(DuplicateEmailException.class);
-        verify(userRepository, never()).save(any());
-    }
-}
-```
-
-### Integration Tests (Controller layer)
-- Use `\@SpringBootTest` + `\@AutoConfigureMockMvc`
-- Test full HTTP flow with `MockMvc`
-- Use `\@Sql` or Testcontainers for database state
-
-```java
-\@SpringBootTest
-\@AutoConfigureMockMvc
-class UserControllerIntegrationTest {
-
-    \@Autowired
-    private MockMvc mockMvc;
-
-    \@Autowired
-    private ObjectMapper objectMapper;
-
-    \@Test
-    void createUser_shouldReturn201_whenRequestIsValid() throws Exception {
-        CreateUserRequest request = CreateUserRequest.builder()
-                .email("test\@example.com")
-                .fullName("Test User")
-                .password("password123")
-                .build();
-
-        mockMvc.perform(post("/api/v1/users")
-                        .contentType(MediaType.APPLICATION_JSON)
-                        .content(objectMapper.writeValueAsString(request)))
-                .andExpect(status().isCreated())
-                .andExpect(jsonPath("$.email").value("test\@example.com"))
-                .andExpect(jsonPath("$.id").isNumber());
-    }
-
-    \@Test
-    void createUser_shouldReturn400_whenEmailIsInvalid() throws Exception {
-        CreateUserRequest request = CreateUserRequest.builder()
-                .email("not-an-email")
-                .fullName("Test")
-                .password("password123")
-                .build();
-
-        mockMvc.perform(post("/api/v1/users")
-                        .contentType(MediaType.APPLICATION_JSON)
-                        .content(objectMapper.writeValueAsString(request)))
-                .andExpect(status().isBadRequest())
-                .andExpect(jsonPath("$.code").value("VALIDATION_FAILED"));
-    }
-}
-```
-
----
-
-## Naming Conventions
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Class | PascalCase | `UserService`, `OrderController` |
-| Method | camelCase | `findById`, `createOrder` |
-| Variable | camelCase | `userResponse`, `orderId` |
-| Constant | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
-| Package | lowercase | `com.company.project.service` |
-| DB Table | snake_case | `user_orders`, `product_items` |
-| DB Column | snake_case | `created_at`, `user_id` |
-| REST endpoint | kebab-case | `/api/v1/user-profiles` |
-| Request DTO | `[Action][Resource]Request` | `CreateOrderRequest` |
-| Response DTO | `[Resource]Response` | `OrderResponse` |
-
----
-
-## API Design
-
-- Version all APIs: `/api/v1/...`
-- Use plural nouns for resources: `/users`, `/orders`
-- HTTP methods: `GET` (read), `POST` (create), `PUT` (full update), `PATCH` (partial), `DELETE`
-- Return `201 Created` for POST, `200 OK` for GET/PUT/PATCH, `204 No Content` for DELETE
-- Use consistent pagination: `?page=0&size=20&sort=createdAt,desc`
-
-```
-GET    /api/v1/users              → 200 list
-POST   /api/v1/users              → 201 created
-GET    /api/v1/users/{id}         → 200 or 404
-PUT    /api/v1/users/{id}         → 200 or 404
-DELETE /api/v1/users/{id}         → 204 or 404
-GET    /api/v1/users/{id}/orders  → 200 nested resource
-```
-
----
-
-## Performance Rules
-
-- Always use pagination — never return unbounded lists
-- Avoid N+1: use `\@EntityGraph` or `JOIN FETCH` in JPQL
-- Add database indexes on frequently queried columns
-- Use `\@Transactional(readOnly = true)` on read-only service methods
-- For heavy read operations, consider projection interfaces
-
-```java
-// ✅ Read-only transaction
-\@Transactional(readOnly = true)
-public Page<UserResponse> findAll(Pageable pageable) {
-    return userRepository.findAll(pageable).map(userMapper::toResponse);
-}
-```
-
----
-
-## Security Rules
-
-- Never log passwords, tokens, or sensitive PII
-- Hash passwords with BCrypt: `passwordEncoder.encode(rawPassword)`
-- Validate and sanitize all user inputs via Bean Validation
-- Use `\@PreAuthorize` for method-level security
-- Never return stack traces to API consumers
-- Store secrets in environment variables / Vault — never in code
-
----
-
-## Logging Rules
-
-- Use SLF4J with Lombok `\@Slf4j`
-- `log.info` — normal business events
-- `log.warn` — recoverable issues (not found, validation fail)
-- `log.error` — unexpected exceptions (always include `ex` as the second argument)
-- Never log sensitive data (password, credit card, token)
-
-```java
-\@Slf4j
-\@Service
-public class UserServiceImpl implements UserService {
-
-    public UserResponse findById(Long id) {
-        log.info("Finding user by id: {}", id);
-        return userRepository.findById(id)
-                .map(userMapper::toResponse)
-                .orElseThrow(() -> {
-                    log.warn("User not found: id={}", id);
-                    return new ResourceNotFoundException("User", id);
-                });
-    }
-}
-```
-
----
-
-## Common Anti-Patterns to Avoid
-
-- ❌ `\@Autowired` field injection → use constructor injection (Lombok `\@RequiredArgsConstructor`)
-- ❌ `\@Data` on JPA entities → use `\@Getter \@Setter` separately
-- ❌ Returning `Entity` directly from Controller → always use DTO
-- ❌ `SELECT *` or unbounded `findAll()` → always paginate
-- ❌ Business logic in Controller → move to Service
-- ❌ Catching and swallowing exceptions → handle properly or rethrow
-- ❌ `new RuntimeException("something")` → create a specific custom exception
-- ❌ Hardcoding config values → use `\@Value` or `\@ConfigurationProperties`
-- ❌ `\@Transactional` on Controller → only on Service methods
-
----
-
-When explaining changes, refer to the [Spring Boot Official Documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/) and [Spring Data JPA](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/) conventions.
+# Spring Boot AI System Prompt
+
+You are an expert Java Spring Boot developer. Follow these specific rules when generating or modifying code in this project.
+
+> **Code examples:** See `.rules/java/spring-boot-examples.md` — read it when generating code for a specific layer.
+
+---
+
+## Project Stack
+
+- **Java:** 17+
+- **Spring Boot:** 3.x
+- **Build Tool:** Maven (prefer) or Gradle
+- **ORM:** Spring Data JPA + Hibernate
+- **Database:** MySQL / PostgreSQL
+- **Testing:** JUnit 5 + Mockito + AssertJ
+- **Utilities:** Lombok, MapStruct
+- **API Style:** RESTful JSON
+
+---
+
+## Architecture
+
+Follow strict **Layered Architecture**:
+
+```
+Controller (HTTP layer)
+    ↓
+Service (Business logic)
+    ↓
+Repository (Data access - Spring Data JPA)
+    ↓
+Entity / Domain Model
+```
+
+### Package Structure
+
+```
+com.company.project/
+├── controller/         # \@RestController — HTTP endpoints only
+├── service/
+│   ├── impl/           # \@Service — business logic implementation
+│   └── [Interface].java
+├── repository/         # \@Repository — extends JpaRepository
+├── entity/             # \@Entity — JPA entities
+├── dto/
+│   ├── request/        # Input DTOs (e.g. CreateUserRequest)
+│   └── response/       # Output DTOs (e.g. UserResponse)
+├── mapper/             # MapStruct mappers (Entity ↔ DTO)
+├── exception/
+│   ├── GlobalExceptionHandler.java  # \@RestControllerAdvice
+│   └── [CustomException].java
+├── config/             # \@Configuration classes
+└── util/               # Pure utility helpers (stateless)
+```
+
+---
+
+## Controller Rules
+
+- Annotate with `\@RestController` + `\@RequestMapping`
+- **Only** handle HTTP concerns: parse request, call service, return response
+- Never put business logic in Controller
+- Always use DTOs — never expose Entity directly
+- Use `ResponseEntity<T>` for explicit HTTP status control
+- Validate input with `\@Valid` + Bean Validation annotations
+
+---
+
+## Service Rules
+
+- Always define an **interface**, implement in the `impl/` package
+- Annotate implementation with `\@Service`
+- All business logic lives here
+- Use `\@Transactional` at the method level (not class level)
+- Throw specific custom exceptions, not generic `RuntimeException`
+- Never return an Entity — always convert to DTO via Mapper
+
+---
+
+## Repository Rules
+
+- Extend `JpaRepository<Entity, ID>`
+- Use **method name queries** for simple queries
+- Use `\@Query` (JPQL) for complex queries — avoid native SQL unless necessary
+- Never add business logic here
+- Use `\@EntityGraph` to solve N+1 problems
+
+---
+
+## Entity Rules
+
+- Use Lombok: `\@Getter`, `\@Setter`, `\@NoArgsConstructor`, `\@AllArgsConstructor`, `\@Builder`
+- Avoid `\@Data` on entities (causes issues with `equals/hashCode` + lazy loading)
+- Always use `\@Table(name = "snake_case_table_name")`
+- Use `\@Column(name = "snake_case_column_name")` explicitly
+- For soft delete: add `deleted` boolean + `deletedAt` timestamp
+- Extend `BaseEntity` for audit fields (`createdAt`, `updatedAt`)
+
+---
+
+## DTO Rules
+
+- Use separate DTOs for **Request** and **Response** — never share
+- Use Lombok: `\@Getter`, `\@Builder`, `\@AllArgsConstructor`, `\@NoArgsConstructor`
+- Validate in the Request DTO with Bean Validation (`\@NotBlank`, `\@Email`, `\@NotNull`, `\@Size`)
+- Never expose internal fields (password hash, audit timestamps) in the Response DTO
+
+---
+
+## MapStruct Mapper Rules
+
+- Use `\@Mapper(componentModel = "spring")` — inject as a Spring bean
+- Define explicit mappings with `\@Mapping` when field names differ
+- Never do manual mapping (`new DTO(); dto.setField(entity.getField())`)
+
+---
+
+## Exception Handling
+
+- Create custom exceptions extending `RuntimeException`
+- Handle all exceptions in one `\@RestControllerAdvice` class
+- Return a consistent error response format
+- Never expose stack traces to the client
+
+---
+
+## Testing Rules
+
+### Unit Tests (Service layer)
+- Test class: `[ServiceImpl]Test.java`
+- Mock all dependencies with `\@ExtendWith(MockitoExtension.class)` + `\@Mock`
+- Test happy path + edge cases + exception scenarios
+- Use AssertJ: `assertThat(result).isEqualTo(expected)`
+
+### Integration Tests (Controller layer)
+- Use `\@SpringBootTest` + `\@AutoConfigureMockMvc`
+- Test full HTTP flow with `MockMvc`
+- Use `\@Sql` or Testcontainers for database state
+
+---
+
+## Naming Conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Class | PascalCase | `UserService`, `OrderController` |
+| Method | camelCase | `findById`, `createOrder` |
+| Variable | camelCase | `userResponse`, `orderId` |
+| Constant | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
+| Package | lowercase | `com.company.project.service` |
+| DB Table | snake_case | `user_orders`, `product_items` |
+| DB Column | snake_case | `created_at`, `user_id` |
+| REST endpoint | kebab-case | `/api/v1/user-profiles` |
+| Request DTO | `[Action][Resource]Request` | `CreateOrderRequest` |
+| Response DTO | `[Resource]Response` | `OrderResponse` |
+
+---
+
+## API Design
+
+- Version all APIs: `/api/v1/...`
+- Use plural nouns for resources: `/users`, `/orders`
+- HTTP methods: `GET` (read), `POST` (create), `PUT` (full update), `PATCH` (partial), `DELETE`
+- Return `201 Created` for POST, `200 OK` for GET/PUT/PATCH, `204 No Content` for DELETE
+- Use consistent pagination: `?page=0&size=20&sort=createdAt,desc`
+
+```
+GET    /api/v1/users              → 200 list
+POST   /api/v1/users              → 201 created
+GET    /api/v1/users/{id}         → 200 or 404
+PUT    /api/v1/users/{id}         → 200 or 404
+DELETE /api/v1/users/{id}         → 204 or 404
+GET    /api/v1/users/{id}/orders  → 200 nested resource
+```
+
+---
+
+## Performance Rules
+
+- Always use pagination — never return unbounded lists
+- Avoid N+1: use `\@EntityGraph` or `JOIN FETCH` in JPQL
+- Add database indexes on frequently queried columns
+- Use `\@Transactional(readOnly = true)` on read-only service methods
+- For heavy read operations, consider projection interfaces
+
+---
+
+## Security Rules
+
+- Never log passwords, tokens, or sensitive PII
+- Hash passwords with BCrypt: `passwordEncoder.encode(rawPassword)`
+- Validate and sanitize all user inputs via Bean Validation
+- Use `\@PreAuthorize` for method-level security
+- Never return stack traces to API consumers
+- Store secrets in environment variables / Vault — never in code
+
+---
+
+## Logging Rules
+
+- Use SLF4J with Lombok `\@Slf4j`
+- `log.info` — normal business events
+- `log.warn` — recoverable issues (not found, validation fail)
+- `log.error` — unexpected exceptions (always include `ex` as the second argument)
+- Never log sensitive data (password, credit card, token)
+
+---
+
+## Common Anti-Patterns to Avoid
+
+- ❌ `\@Autowired` field injection → use constructor injection (Lombok `\@RequiredArgsConstructor`)
+- ❌ `\@Data` on JPA entities → use `\@Getter \@Setter` separately
+- ❌ Returning `Entity` directly from Controller → always use DTO
+- ❌ `SELECT *` or unbounded `findAll()` → always paginate
+- ❌ Business logic in Controller → move to Service
+- ❌ Catching and swallowing exceptions → handle properly or rethrow
+- ❌ `new RuntimeException("something")` → create a specific custom exception
+- ❌ Hardcoding config values → use `\@Value` or `\@ConfigurationProperties`
+- ❌ `\@Transactional` on Controller → only on Service methods
+
+---
+
+When explaining changes, refer to the [Spring Boot Official Documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/) and [Spring Data JPA](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/) conventions.