backend-claude-code 1.0.0

package/rules/entity-patterns.md

@@ -0,0 +1,70 @@
+---
+paths:
+  - "**/entity/**/*.java"
+  - "**/domain/**/*.java"
+---
+# Entity 패턴
+
+## 클래스 구조
+
+```java
+@Entity
+@Table(name = "foos")
+@Getter
+@Setter
+public class Foo extends BaseEntity {
+    @Id
+    @Column(name = "foo_id", length = 255)
+    private String id;
+}
+```
+
+## ID
+
+- 타입: `String`
+- 생성: `UUID.randomUUID().toString().replace("-", "")` 또는 프로젝트 공통 ID 생성기 사용
+- DB auto-increment 사용 금지 — 서비스에서 생성 후 주입
+
+## Enum 컬럼
+
+```java
+@Enumerated(EnumType.STRING)
+@Column(length = 30, nullable = false)
+private FooStatus status = FooStatus.ACTIVE;
+```
+
+- `EnumType.STRING` 필수 — `ORDINAL` 사용 금지
+- `length = 30` 설정 (값 추가 시 마이그레이션 불필요)
+
+## 기본값 처리
+
+nullable 컬럼 기본값은 `@PrePersist`에서 처리한다.
+
+```java
+@PrePersist
+void applyDefaults() {
+    if (content == null) content = "";
+    if (count == null) count = 0;
+}
+```
+
+## 연관관계
+
+`@ManyToOne`, `@OneToMany` 매핑 대신 **ID 참조**를 선호한다.
+조인이 필요하면 Repository(QueryDSL)에서 명시적으로 처리한다.
+
+```java
+// 권장
+private String ownerId;
+
+// 지양 (필요한 경우에만 사용)
+@ManyToOne(fetch = FetchType.LAZY)
+@JoinColumn(name = "owner_id")
+private Owner owner;
+```
+
+## 금지 사항
+
+- `FetchType.EAGER` 사용 금지
+- 엔티티에서 DTO import 금지
+- 비즈니스 로직을 엔티티에 과도하게 집중시키지 않음 (상태 전이 메서드는 허용)

package/rules/error-handling.md

@@ -0,0 +1,56 @@
+---
+paths:
+  - "**/*.java"
+---
+# 에러 처리 패턴
+
+## 예외 클래스 구조
+
+도메인 예외는 HTTP 상태코드 기반으로 분류하고 `@RestControllerAdvice`에서 중앙 처리한다.
+
+```java
+// 사용할 예외 클래스 (프로젝트에 맞게 정의)
+throw new BadRequestException("잘못된 요청입니다.");
+throw new NotFoundException("리소스를 찾을 수 없습니다.");
+throw new ForbiddenException("접근 권한이 없습니다.");
+throw new ConflictException("이미 존재합니다.");
+throw new UnauthorizedException("인증이 필요합니다.");
+```
+
+## GlobalExceptionHandler
+
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler(NotFoundException.class)
+    ResponseEntity<ErrorResponse> handleNotFound(NotFoundException ex) {
+        return ResponseEntity.status(HttpStatus.NOT_FOUND)
+            .body(ErrorResponse.of(404, ex.getMessage()));
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException ex) {
+        String message = ex.getBindingResult().getFieldErrors().stream()
+            .map(e -> e.getField() + ": " + e.getDefaultMessage())
+            .collect(Collectors.joining(", "));
+        return ResponseEntity.badRequest().body(ErrorResponse.of(400, message));
+    }
+}
+```
+
+## 에러 응답 포맷
+
+```json
+{
+  "status": 404,
+  "code": "NOT_FOUND",
+  "message": "리소스를 찾을 수 없습니다."
+}
+```
+
+## 규칙
+
+- 비즈니스 예외는 반드시 커스텀 예외 클래스 사용 — `RuntimeException` 직접 throw 금지
+- catch 블록에서 예외 무시(swallow) 금지 — 반드시 로깅하거나 재throw
+- 예외 메시지에 민감한 정보(비밀번호, 토큰 등) 포함 금지

package/rules/hooks.md

@@ -0,0 +1,73 @@
+---
+paths:
+  - "**/*.java"
+  - "**/pom.xml"
+  - "**/build.gradle"
+  - "**/build.gradle.kts"
+---
+# Java Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with Java-specific content.
+
+## PostToolUse 훅
+
+`.claude/settings.json`에 설정:
+
+### 컴파일 검증
+
+Java 파일 편집 후 자동 컴파일:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "command": "if echo \"$FILE_PATH\" | grep -q '\\.java$'; then (./mvnw compile -q --no-transfer-progress 2>&1 | tail -5 || ./gradlew compileJava -q 2>&1 | tail -5) && echo '[Hook] Compile OK' || echo '[Hook] Compile failed'; fi",
+        "description": "Java 파일 편집 후 컴파일 검증"
+      }
+    ]
+  }
+}
+```
+
+### Checkstyle 검사
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "command": "if echo \"$FILE_PATH\" | grep -q '\\.java$'; then ./mvnw checkstyle:check -q 2>&1 | tail -3 || echo '[Hook] Checkstyle failed'; fi",
+        "description": "Java 파일 편집 후 스타일 검사"
+      }
+    ]
+  }
+}
+```
+
+## Stop 훅
+
+### 최종 빌드 검증
+
+세션 종료 시:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "command": "(./mvnw verify -q --no-transfer-progress 2>&1 | tail -10 || ./gradlew check -q 2>&1 | tail -10) && echo '[Hook] Final verify OK' || echo '[Hook] Verify failed'",
+        "description": "세션 종료 시 전체 빌드/테스트 검증"
+      }
+    ]
+  }
+}
+```
+
+## 권장 순서
+
+1. 컴파일 검증 (빠른 피드백)
+2. Checkstyle (스타일 강제)
+3. 최종 `verify` (커버리지 포함 전체 검사)

package/rules/repository-patterns.md

@@ -0,0 +1,75 @@
+---
+paths:
+  - "**/repository/**/*.java"
+---
+# Repository 패턴
+
+## 3단계 구조
+
+복잡한 쿼리가 있는 엔티티는 3개 파일로 구성한다.
+
+```java
+// 1. JPA 인터페이스
+public interface FooRepository extends JpaRepository<Foo, String>, FooRepositoryCustom {
+    Optional<Foo> findByOwnerId(String ownerId);
+    List<Foo> findAllByAccountId(String accountId);
+}
+
+// 2. Custom 인터페이스
+public interface FooRepositoryCustom {
+    List<Foo> findByCondition(String accountId, FooStatus status);
+}
+
+// 3. QueryDSL 구현체
+@Repository
+@RequiredArgsConstructor
+public class FooRepositoryImpl implements FooRepositoryCustom {
+    private final JPAQueryFactory queryFactory;
+
+    @Override
+    public List<Foo> findByCondition(String accountId, FooStatus status) {
+        QFoo foo = QFoo.foo;
+        return queryFactory
+            .selectFrom(foo)
+            .where(foo.accountId.eq(accountId), foo.status.eq(status))
+            .fetch();
+    }
+}
+```
+
+## QueryDSL 규칙
+
+- Q-type은 메서드 내 지역 변수로 선언: `QFoo foo = QFoo.foo`
+- `.fetchOne()` — 정확히 하나 기대 (없으면 null, 둘 이상이면 예외)
+- `.fetchFirst()` — 첫 번째 또는 null (유니크 보장 쿼리에 사용 금지)
+- `.fetch()` — 리스트
+- null-safe 집계: `.sum()`, `.count()` 뒤에 `.coalesce(0)` 체이닝
+
+```java
+QFoo foo = QFoo.foo;
+QBar bar = QBar.bar;
+
+Integer total = queryFactory
+    .select(foo.amount.sum().coalesce(0))
+    .from(foo)
+    .join(bar).on(bar.id.eq(foo.barId))
+    .where(foo.accountId.eq(accountId))
+    .fetchOne();
+```
+
+## JPA vs QueryDSL 분리 기준
+
+```java
+// JPA 네이밍으로 충분
+Optional<Foo> findByBarId(String barId);
+List<Foo> findAllByAccountIdOrderByCreatedAtDesc(String accountId);
+
+// QueryDSL 사용 (조인, 집계, 동적 조건)
+List<Foo> findByMultipleConditions(String accountId, List<FooStatus> statuses);
+```
+
+## 금지 사항
+
+- `FetchType.EAGER` 사용 금지
+- 루프 내 지연 로딩 호출 금지 (N+1 유발)
+- Repository에서 비즈니스 로직 작성 금지

package/rules/security.md

@@ -0,0 +1,101 @@
+---
+paths:
+  - "**/*.java"
+  - "**/application*.yml"
+  - "**/application*.properties"
+---
+# Java Security
+
+> This file extends [common/security.md](../common/security.md) with Java-specific content.
+
+## 시크릿 관리
+
+- 절대 소스 코드에 API 키, 토큰, 자격 증명을 하드코딩하지 않기
+- 환경 변수 사용: `System.getenv("API_KEY")`
+- 프로덕션 시크릿에는 시크릿 관리자 사용 (Vault, AWS Secrets Manager)
+- 시크릿이 있는 로컬 설정 파일은 `.gitignore`에 포함
+
+```java
+// BAD
+private static final String API_KEY = "sk-abc123...";
+
+// GOOD — 환경 변수
+String apiKey = System.getenv("PAYMENT_API_KEY");
+Objects.requireNonNull(apiKey, "PAYMENT_API_KEY must be set");
+```
+
+## SQL 인젝션 방지
+
+- 항상 파라미터화된 쿼리 사용 — 사용자 입력을 SQL에 절대 연결하지 않기
+- `PreparedStatement` 또는 프레임워크의 파라미터화 쿼리 API 사용
+
+```java
+// BAD — 문자열 연결로 SQL 인젝션 위험
+String sql = "SELECT * FROM orders WHERE name = '" + name + "'";
+
+// GOOD — PreparedStatement
+PreparedStatement ps = conn.prepareStatement("SELECT * FROM orders WHERE name = ?");
+ps.setString(1, name);
+
+// GOOD — JDBC 템플릿
+jdbcTemplate.query("SELECT * FROM orders WHERE name = ?", mapper, name);
+
+// GOOD — Spring Data JPA 파라미터
+@Query("select o from Order o where o.name = :name")
+List<Order> findByName(@Param("name") String name);
+```
+
+## 입력 검증
+
+- 처리 전 시스템 경계에서 모든 사용자 입력 검증
+- Bean Validation 사용 (`@NotNull`, `@NotBlank`, `@Size`) — DTO에 적용
+- 파일 경로와 사용자 제공 문자열 새니타이즈
+- 검증 실패 시 명확한 오류 메시지와 함께 거부
+
+```java
+// Spring Boot DTO 검증
+public record CreateOrderRequest(
+    @NotBlank @Size(max = 100) String customerName,
+    @NotNull @Positive BigDecimal amount,
+    @NotNull @FutureOrPresent LocalDate deliveryDate
+) {}
+
+// 컨트롤러에서 @Valid 적용
+@PostMapping("/orders")
+ResponseEntity<OrderResponse> create(@Valid @RequestBody CreateOrderRequest request) {
+    return ResponseEntity.status(HttpStatus.CREATED)
+        .body(orderService.create(request));
+}
+```
+
+## 인증 및 인가
+
+- 절대 커스텀 암호화 구현 금지 — 검증된 라이브러리 사용
+- 비밀번호는 bcrypt 또는 Argon2로 저장, MD5/SHA1 금지
+- 서비스 경계에서 인가 검사 강제
+- 로그에서 민감 데이터 제거 — 비밀번호, 토큰, PII 절대 로깅 금지
+
+## 의존성 보안
+
+- `mvn dependency:tree` 또는 `./gradlew dependencies`로 전이 의존성 감사
+- OWASP Dependency-Check 또는 Snyk으로 알려진 CVE 스캔
+- 의존성 최신 상태 유지 — Dependabot 또는 Renovate 설정
+
+## 오류 메시지
+
+- API 응답에 스택 트레이스, 내부 경로, SQL 오류 절대 노출 금지
+- 핸들러 경계에서 예외를 안전하고 일반적인 클라이언트 메시지로 매핑
+- 서버 측에 상세 오류 로깅; 클라이언트에는 일반 메시지 반환
+
+```java
+@ExceptionHandler(Exception.class)
+ResponseEntity<ApiResponse<Void>> handleGeneric(Exception ex) {
+    log.error("Unexpected error", ex);                    // 서버 로그에만 상세 정보
+    return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+        .body(ApiResponse.error("Internal server error")); // 클라이언트에 일반 메시지
+}
+```
+
+## 참고
+
+skill: `springboot-security` — Spring Security 인증/인가 패턴

package/rules/service-patterns.md

@@ -0,0 +1,70 @@
+---
+paths:
+  - "**/service/**/*.java"
+---
+# Service 레이어 패턴
+
+## 클래스 구조
+
+```java
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class FooService {
+    private final FooRepository fooRepository;
+}
+```
+
+모든 의존성은 `@RequiredArgsConstructor` + `private final`. `@Autowired` 사용 금지.
+
+## @Transactional
+
+- `org.springframework.transaction.annotation.Transactional` 만 사용 — `jakarta.transaction.Transactional` 금지
+- SELECT만 수행하는 메서드: `@Transactional(readOnly = true)` 필수
+- INSERT/UPDATE/DELETE 또는 다른 `@Transactional` 메서드 호출: `@Transactional`
+
+```java
+@Transactional(readOnly = true)
+public FooDtos.FooResponse getFoo(String id) { ... }
+
+@Transactional
+public FooDtos.FooResponse createFoo(String ownerId, FooDtos.CreateRequest request) { ... }
+```
+
+## 조회 + 소유권 체크 패턴
+
+엔티티 조회 후 소유권 검증이 반복되면 private 메서드로 분리한다.
+
+```java
+private Foo findOwnedFoo(String ownerId, String fooId) {
+    Foo foo = fooRepository.findById(fooId)
+        .orElseThrow(() -> new NotFoundException("리소스를 찾을 수 없습니다."));
+    if (!foo.getOwnerId().equals(ownerId)) {
+        throw new ForbiddenException("접근 권한이 없습니다.");
+    }
+    return foo;
+}
+```
+
+## Service 분리 기준
+
+단일 Service가 커질 때:
+- **파이프라인 단계별**: `FooService` → `FooProcessingService`, `FooQueryService`
+- **외부 서비스별**: `AuthService` → `AppleAuthService`, `KakaoAuthService`
+- **내부 호출 전용**: `FooInternalService` — Kafka 컨슈머 등에서만 호출
+
+## 입력 정규화
+
+null 또는 유효하지 않은 값은 서비스 진입점에서 정규화한다.
+
+```java
+private int normalizeDuration(Integer duration) {
+    return (duration == null || duration < 0) ? 0 : duration;
+}
+```
+
+## 금지 사항
+
+- `@Transactional(readOnly = true)` 메서드에서 엔티티 변경 금지
+- Service 간 순환 의존 금지
+- HTTP 관련 객체(HttpServletRequest 등) Service에서 직접 사용 금지

package/rules/testing.md

@@ -0,0 +1,174 @@
+---
+paths:
+  - "**/*.java"
+  - "**/pom.xml"
+  - "**/build.gradle"
+  - "**/build.gradle.kts"
+---
+# Java Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Java-specific content.
+
+## 테스트 프레임워크
+
+- **JUnit 5** (`@Test`, `@ParameterizedTest`, `@Nested`, `@DisplayName`)
+- **AssertJ** — 유창한 단언문 (`assertThat(result).isEqualTo(expected)`)
+- **Mockito** — 의존성 모킹
+- **Testcontainers** — 데이터베이스나 서비스가 필요한 통합 테스트
+
+## 테스트 구성
+
+```
+src/test/java/com/example/app/
+  service/           # 서비스 레이어 단위 테스트
+  controller/        # 웹 레이어 / API 테스트
+  repository/        # 데이터 접근 테스트
+  integration/       # 교차 레이어 통합 테스트
+```
+
+`src/main/java` 패키지 구조를 `src/test/java`에 미러링.
+
+## 단위 테스트 패턴
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+
+    @Mock
+    private OrderRepository orderRepository;
+
+    private OrderService orderService;
+
+    @BeforeEach
+    void setUp() {
+        orderService = new OrderService(orderRepository);
+    }
+
+    @Test
+    @DisplayName("findById가 존재하는 주문을 반환")
+    void findById_existingOrder_returnsOrder() {
+        var order = new Order(1L, "Alice", BigDecimal.TEN);
+        when(orderRepository.findById(1L)).thenReturn(Optional.of(order));
+
+        var result = orderService.findById(1L);
+
+        assertThat(result.customerName()).isEqualTo("Alice");
+        verify(orderRepository).findById(1L);
+    }
+
+    @Test
+    @DisplayName("findById가 주문 없을 때 예외 발생")
+    void findById_missingOrder_throws() {
+        when(orderRepository.findById(99L)).thenReturn(Optional.empty());
+
+        assertThatThrownBy(() -> orderService.findById(99L))
+            .isInstanceOf(OrderNotFoundException.class)
+            .hasMessageContaining("99");
+    }
+}
+```
+
+## 웹 레이어 테스트 (MockMvc)
+
+```java
+@WebMvcTest(OrderController.class)
+class OrderControllerTest {
+    @Autowired MockMvc mockMvc;
+    @MockBean OrderService orderService;
+
+    @Test
+    @DisplayName("POST /orders — 201 Created 반환")
+    void createOrder_returns201() throws Exception {
+        when(orderService.create(any())).thenReturn(orderResponse());
+
+        mockMvc.perform(post("/api/orders")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("""{"customerName":"Alice","amount":100}"""))
+            .andExpect(status().isCreated())
+            .andExpect(jsonPath("$.data.customerName").value("Alice"));
+    }
+}
+```
+
+## 통합 테스트 (Testcontainers)
+
+```java
+@Testcontainers
+class OrderRepositoryIT {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16");
+
+    private OrderRepository repository;
+
+    @BeforeEach
+    void setUp() {
+        var dataSource = new PGSimpleDataSource();
+        dataSource.setUrl(postgres.getJdbcUrl());
+        dataSource.setUser(postgres.getUsername());
+        dataSource.setPassword(postgres.getPassword());
+        repository = new JdbcOrderRepository(dataSource);
+    }
+
+    @Test
+    void save_and_findById() {
+        var saved = repository.save(new Order(null, "Bob", BigDecimal.ONE));
+        var found = repository.findById(saved.getId());
+        assertThat(found).isPresent();
+    }
+}
+```
+
+## 테스트 슬라이스 선택
+
+| 테스트 대상 | 사용할 어노테이션 |
+|------------|----------------|
+| 서비스 단위 테스트 | `@ExtendWith(MockitoExtension.class)` |
+| 컨트롤러 테스트 | `@WebMvcTest` |
+| JPA 레포지토리 테스트 | `@DataJpaTest` |
+| 통합 테스트 | `@SpringBootTest` + `@AutoConfigureMockMvc` |
+
+## 테스트 이름 규칙
+
+- 메서드명: `methodName_scenario_expectedBehavior()`
+- `@DisplayName`: 사람이 읽기 좋은 설명
+
+## 커버리지 (JaCoCo)
+
+Maven:
+```xml
+<plugin>
+  <groupId>org.jacoco</groupId>
+  <artifactId>jacoco-maven-plugin</artifactId>
+  <version>0.8.14</version>
+  <executions>
+    <execution><goals><goal>prepare-agent</goal></goals></execution>
+    <execution>
+      <id>report</id>
+      <phase>verify</phase>
+      <goals><goal>report</goal></goals>
+    </execution>
+    <execution>
+      <id>check</id>
+      <goals><goal>check</goal></goals>
+      <configuration>
+        <rules>
+          <rule>
+            <limits>
+              <limit>
+                <counter>LINE</counter>
+                <value>COVEREDRATIO</value>
+                <minimum>0.80</minimum>
+              </limit>
+            </limits>
+          </rule>
+        </rules>
+      </configuration>
+    </execution>
+  </executions>
+</plugin>
+```
+
+## 참고
+
+skill: `springboot-tdd` — MockMvc와 Testcontainers를 사용한 Spring Boot TDD 패턴