backend-claude-code 1.0.0

package/skills/java-coding-standards/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: java-coding-standards
+description: "Java coding standards for Spring Boot services: naming, immutability, Optional usage, streams, exceptions, generics, and project layout."
+origin: ECC
+---
+
+# Java Coding Standards
+
+Spring Boot 서비스에서 읽기 쉽고 유지보수 가능한 Java (17+) 코드 표준.
+
+## When to Activate
+
+- Spring Boot 프로젝트에서 Java 코드 작성 또는 리뷰
+- 명명, 불변성, 예외 처리 관례 강제
+- records, sealed classes, pattern matching 작업 (Java 17+)
+- Optional, streams, generics 사용 리뷰
+- 패키지 및 프로젝트 레이아웃 구성
+
+## Core Principles
+
+- 영리함보다 명확성 우선
+- 기본적으로 불변; 공유 가변 상태 최소화
+- 의미 있는 예외로 빠른 실패
+- 일관된 명명 및 패키지 구조
+
+## Naming
+
+```java
+// PASS: 클래스/레코드: PascalCase
+public class OrderService {}
+public record Money(BigDecimal amount, Currency currency) {}
+
+// PASS: 메서드/필드: camelCase
+private final OrderRepository orderRepository;
+public OrderResponse findByOrderNumber(String orderNumber) {}
+
+// PASS: 상수: UPPER_SNAKE_CASE
+private static final int MAX_PAGE_SIZE = 100;
+private static final Duration TOKEN_EXPIRY = Duration.ofHours(24);
+
+// PASS: 패키지: 소문자 역방향 도메인
+// com.example.app.service
+// com.example.app.controller
+// com.example.app.domain
+```
+
+## Immutability
+
+```java
+// PASS: record와 final 필드 선호
+public record OrderDto(Long id, String customerName, BigDecimal amount, OrderStatus status) {}
+
+public class Order {
+  private final Long id;
+  private final String customerName;
+  private final BigDecimal amount;
+
+  // getter만, setter 없음
+  public Long getId() { return id; }
+}
+
+// PASS: 컬렉션 방어적 복사
+public List<OrderItem> getItems() {
+  return List.copyOf(items); // 불변 복사 반환
+}
+
+// FAIL: 가변 컬렉션 직접 반환
+public List<OrderItem> getItems() {
+  return items; // 외부에서 수정 가능 — 위험
+}
+```
+
+## Optional Usage
+
+```java
+// PASS: finder 메서드에서 Optional 반환
+Optional<Order> findByOrderNumber(String orderNumber);
+
+// PASS: map/flatMap 사용, get() 금지
+return orderRepository.findByOrderNumber(orderNumber)
+    .map(OrderResponse::from)
+    .orElseThrow(() -> new OrderNotFoundException(orderNumber));
+
+// PASS: 기본값
+String name = Optional.ofNullable(dto.name()).orElse("Unknown");
+
+// FAIL: Optional.get() 직접 사용
+Order order = repo.findById(id).get(); // NoSuchElementException 위험
+
+// FAIL: 매개변수로 Optional
+public void process(Optional<String> name) {} // 그냥 null 허용으로
+```
+
+## Streams Best Practices
+
+```java
+// PASS: 변환에 스트림 사용, 파이프라인 짧게
+List<String> activeNames = orders.stream()
+    .filter(o -> o.status() == OrderStatus.ACTIVE)
+    .map(Order::customerName)
+    .sorted()
+    .toList(); // Java 16+
+
+// PASS: 메서드 참조
+List<OrderResponse> responses = orders.stream()
+    .map(OrderResponse::from) // 람다보다 간결
+    .toList();
+
+// FAIL: 복잡한 중첩 스트림 — 루프 사용
+orders.stream()
+    .flatMap(o -> o.items().stream()
+        .filter(i -> i.price().compareTo(BigDecimal.TEN) > 0)
+        .map(i -> new ItemDto(o.id(), i.name(), i.price())))
+    .collect(Collectors.toList());
+// → 이런 경우 명시적 루프가 더 명확
+```
+
+## Exceptions
+
+```java
+// PASS: 도메인 예외 — 컨텍스트 포함
+public class OrderNotFoundException extends RuntimeException {
+  public OrderNotFoundException(Long id) {
+    super("Order not found: id=" + id);
+  }
+  public OrderNotFoundException(String orderNumber) {
+    super("Order not found: orderNumber=" + orderNumber);
+  }
+}
+
+// PASS: 기술적 예외 래핑
+try {
+  return externalPaymentApi.charge(request);
+} catch (HttpClientErrorException ex) {
+  throw new PaymentException("Payment failed: " + ex.getStatusCode(), ex);
+}
+
+// FAIL: 빈 catch 블록
+try {
+  doSomething();
+} catch (Exception e) {} // 절대 금지
+
+// FAIL: 너무 광범위한 예외 포착
+try {
+  service.process(request);
+} catch (Exception e) { // RuntimeException 이상을 잡으면 안 됨
+  log.error("Error", e);
+}
+```
+
+## Modern Java Features
+
+```java
+// Records (Java 16+) — DTO에 이상적
+public record CreateOrderRequest(
+    @NotBlank String customerName,
+    @NotNull @Positive BigDecimal amount) {}
+
+// Sealed interfaces (Java 17+) — 닫힌 타입 계층
+public sealed interface PaymentResult
+    permits PaymentResult.Success, PaymentResult.Failure {
+  record Success(String transactionId) implements PaymentResult {}
+  record Failure(String errorCode, String message) implements PaymentResult {}
+}
+
+// Pattern matching instanceof (Java 16+)
+if (event instanceof OrderCreatedEvent e) {
+  log.info("Order created: id={}", e.orderId()); // 캐스트 불필요
+}
+
+// Switch expressions (Java 14+)
+String statusLabel = switch (order.status()) {
+  case PENDING -> "대기 중";
+  case ACTIVE -> "처리 중";
+  case COMPLETED -> "완료";
+  case CANCELLED -> "취소됨";
+};
+
+// Text blocks (Java 15+) — SQL 쿼리에 유용
+String query = """
+    SELECT o.id, o.customer_name, o.amount
+    FROM orders o
+    WHERE o.status = :status
+    ORDER BY o.created_at DESC
+    """;
+```
+
+## Project Structure
+
+```
+src/main/java/com/example/
+├── controller/          # REST 컨트롤러
+│   └── OrderController.java
+├── service/             # 비즈니스 로직
+│   └── OrderService.java
+├── repository/          # 데이터 접근
+│   └── OrderRepository.java
+├── domain/              # 도메인 모델/엔티티
+│   ├── Order.java       # 도메인 객체
+│   └── OrderEntity.java # JPA 엔티티
+├── dto/                 # 요청/응답 DTO
+│   ├── CreateOrderRequest.java
+│   └── OrderResponse.java
+├── exception/           # 도메인 예외
+│   └── OrderNotFoundException.java
+└── config/              # Spring 설정
+    ├── SecurityConfig.java
+    └── JpaConfig.java
+```
+
+## Logging Standards
+
+```java
+// PASS: SLF4J, 구조적 매개변수
+private static final Logger log = LoggerFactory.getLogger(OrderService.class);
+
+log.info("order_created id={} customer={}", order.getId(), order.getCustomerName());
+log.warn("order_not_found id={}", id);
+log.error("payment_failed orderId={} error={}", orderId, ex.getMessage(), ex);
+
+// FAIL: 문자열 연결 (매개변수 사용)
+log.info("Order created: " + order.getId()); // 성능 낭비
+
+// FAIL: 민감 데이터 로깅
+log.info("User login email={} password={}", email, password); // 절대 금지
+```
+
+## Testing Expectations
+
+- `@ExtendWith(MockitoExtension.class)` 서비스 단위 테스트
+- `@WebMvcTest` 컨트롤러 단위 테스트
+- `@DataJpaTest` 레포지토리 테스트
+- `@SpringBootTest` 통합 테스트에만
+- JaCoCo 라인 커버리지 80% 최소
+
+**Remember**: 명확하게 명명, 불변성 유지, 빠른 실패, 예외에 컨텍스트 포함, 모던 Java 기능으로 표현력 향상.

package/skills/jpa-patterns/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: jpa-patterns
+description: JPA/Hibernate patterns for entity design, relationships, query optimization, transactions, auditing, indexing, pagination, and pooling in Spring Boot.
+origin: ECC
+---
+
+# JPA/Hibernate Patterns
+
+Spring Boot에서 데이터 모델링, 레포지토리, 성능 튜닝에 사용.
+
+## When to Activate
+
+- JPA 엔티티 및 테이블 매핑 설계
+- 관계 정의 (@OneToMany, @ManyToOne, @ManyToMany)
+- 쿼리 최적화 (N+1 방지, fetch 전략, 프로젝션)
+- 트랜잭션, 감사, 소프트 삭제 설정
+- 페이지네이션, 정렬, 커스텀 레포지토리 메서드 설정
+- HikariCP 연결 풀링 또는 2레벨 캐싱 튜닝
+
+## Entity Design
+
+```java
+@Entity
+@Table(name = "orders", indexes = {
+  @Index(name = "idx_orders_customer_id", columnList = "customer_id"),
+  @Index(name = "idx_orders_status_created", columnList = "status, created_at")
+})
+@EntityListeners(AuditingEntityListener.class)
+public class OrderEntity {
+  @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
+  private Long id;
+
+  @Column(nullable = false, length = 100)
+  private String customerName;
+
+  @Column(nullable = false, precision = 19, scale = 4)
+  private BigDecimal amount;
+
+  @Enumerated(EnumType.STRING)
+  @Column(nullable = false, length = 20)
+  private OrderStatus status = OrderStatus.PENDING;
+
+  @CreatedDate
+  @Column(updatable = false)
+  private Instant createdAt;
+
+  @LastModifiedDate
+  private Instant updatedAt;
+
+  @Version
+  private Long version; // 낙관적 잠금
+}
+```
+
+감사 활성화:
+```java
+@Configuration
+@EnableJpaAuditing
+class JpaConfig {}
+```
+
+## Relationships and N+1 Prevention
+
+```java
+// 부모 엔티티
+@Entity
+public class OrderEntity {
+  @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true, fetch = FetchType.LAZY)
+  private List<OrderItemEntity> items = new ArrayList<>();
+}
+
+// N+1 방지 — JOIN FETCH 사용
+@Query("select o from OrderEntity o left join fetch o.items where o.id = :id")
+Optional<OrderEntity> findWithItems(@Param("id") Long id);
+
+// 또는 @EntityGraph 사용
+@EntityGraph(attributePaths = {"items"})
+Optional<OrderEntity> findById(Long id);
+```
+
+## Repository Patterns
+
+```java
+public interface OrderRepository extends JpaRepository<OrderEntity, Long> {
+  // 파생 쿼리
+  Page<OrderEntity> findByStatus(OrderStatus status, Pageable pageable);
+  Optional<OrderEntity> findByOrderNumber(String orderNumber);
+
+  // JPQL 쿼리
+  @Query("select o from OrderEntity o where o.amount >= :minAmount and o.status = :status")
+  Page<OrderEntity> findByMinAmountAndStatus(
+      @Param("minAmount") BigDecimal minAmount,
+      @Param("status") OrderStatus status,
+      Pageable pageable);
+
+  // 집계
+  @Query("select count(o) from OrderEntity o where o.status = :status")
+  long countByStatus(@Param("status") OrderStatus status);
+}
+```
+
+## DTO Projections (성능 최적화)
+
+엔티티 전체 로딩 없이 필요한 필드만 조회:
+
+```java
+// 인터페이스 프로젝션
+public interface OrderSummary {
+  Long getId();
+  String getCustomerName();
+  BigDecimal getAmount();
+  OrderStatus getStatus();
+}
+
+Page<OrderSummary> findAllBy(Pageable pageable);
+
+// 클래스 기반 프로젝션 (DTO 생성자)
+public record OrderSummaryDto(Long id, String customerName, OrderStatus status) {}
+
+@Query("select new com.example.dto.OrderSummaryDto(o.id, o.customerName, o.status) from OrderEntity o")
+Page<OrderSummaryDto> findSummaries(Pageable pageable);
+```
+
+## Transactions
+
+```java
+@Service
+public class OrderService {
+  @Transactional
+  public OrderResponse updateStatus(Long id, OrderStatus newStatus) {
+    OrderEntity entity = repo.findById(id)
+        .orElseThrow(() -> new OrderNotFoundException(id));
+    entity.setStatus(newStatus);
+    return OrderResponse.from(entity); // dirty checking으로 자동 저장
+  }
+
+  @Transactional(readOnly = true)
+  public Page<OrderResponse> findByStatus(OrderStatus status, Pageable pageable) {
+    return repo.findByStatus(status, pageable).map(OrderResponse::from);
+  }
+
+  @Transactional(propagation = Propagation.REQUIRES_NEW)
+  public void auditOrderChange(Long orderId, String action) {
+    // 별도 트랜잭션에서 감사 로그 저장
+    auditRepo.save(new AuditLog(orderId, action));
+  }
+}
+```
+
+## Pagination
+
+```java
+// 기본 페이지네이션
+PageRequest page = PageRequest.of(0, 20, Sort.by("createdAt").descending());
+Page<OrderEntity> orders = repo.findByStatus(OrderStatus.PENDING, page);
+
+// 멀티 정렬
+PageRequest page = PageRequest.of(0, 20,
+    Sort.by(Sort.Order.desc("status"), Sort.Order.asc("createdAt")));
+```
+
+## Indexing and Performance
+
+- 공통 필터에 인덱스 추가 (`status`, `customerId`, FK)
+- 쿼리 패턴에 맞는 복합 인덱스 (`status, created_at`)
+- `select *` 지양 — 필요한 컬럼만 프로젝션
+- `saveAll`과 `hibernate.jdbc.batch_size`로 배치 쓰기
+
+## Connection Pooling (HikariCP)
+
+```yaml
+spring:
+  datasource:
+    hikari:
+      maximum-pool-size: 20
+      minimum-idle: 5
+      connection-timeout: 30000
+      idle-timeout: 600000
+      max-lifetime: 1800000
+      validation-timeout: 5000
+  jpa:
+    properties:
+      hibernate:
+        jdbc:
+          batch_size: 50
+        order_inserts: true
+        order_updates: true
+```
+
+## Migrations
+
+- Flyway 또는 Liquibase 사용 — 프로덕션에서 Hibernate auto DDL 금지
+- 마이그레이션은 멱등성과 추가적으로 유지; 계획 없이 컬럼 삭제 금지
+
+```sql
+-- V1__create_orders_table.sql
+CREATE TABLE orders (
+    id BIGSERIAL PRIMARY KEY,
+    customer_name VARCHAR(100) NOT NULL,
+    amount NUMERIC(19, 4) NOT NULL,
+    status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    version BIGINT NOT NULL DEFAULT 0
+);
+
+CREATE INDEX idx_orders_status_created ON orders (status, created_at DESC);
+```
+
+## Testing Data Access
+
+```bash
+# SQL 디버깅
+logging.level.org.hibernate.SQL=DEBUG
+logging.level.org.hibernate.orm.jdbc.bind=TRACE
+```
+
+**Remember**: 엔티티는 작게, 쿼리는 의도적으로, 트랜잭션은 짧게. fetch 전략과 프로젝션으로 N+1 방지, 읽기/쓰기 경로를 위한 인덱싱.

package/skills/postgres-patterns/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: postgres-patterns
+description: PostgreSQL database patterns for query optimization, schema design, indexing, and security. Based on Supabase best practices.
+origin: ECC
+---
+
+# PostgreSQL Patterns
+
+Quick reference for PostgreSQL best practices. For detailed guidance, use the `database-reviewer` agent.
+
+## When to Activate
+
+- Writing SQL queries or migrations
+- Designing database schemas
+- Troubleshooting slow queries
+- Implementing Row Level Security
+- Setting up connection pooling
+
+## Quick Reference
+
+### Index Cheat Sheet
+
+| Query Pattern | Index Type | Example |
+|--------------|------------|---------|
+| `WHERE col = value` | B-tree (default) | `CREATE INDEX idx ON t (col)` |
+| `WHERE col > value` | B-tree | `CREATE INDEX idx ON t (col)` |
+| `WHERE a = x AND b > y` | Composite | `CREATE INDEX idx ON t (a, b)` |
+| `WHERE jsonb @> '{}'` | GIN | `CREATE INDEX idx ON t USING gin (col)` |
+| `WHERE tsv @@ query` | GIN | `CREATE INDEX idx ON t USING gin (col)` |
+| Time-series ranges | BRIN | `CREATE INDEX idx ON t USING brin (col)` |
+
+### Data Type Quick Reference
+
+| Use Case | Correct Type | Avoid |
+|----------|-------------|-------|
+| IDs | `bigint` | `int`, random UUID |
+| Strings | `text` | `varchar(255)` |
+| Timestamps | `timestamptz` | `timestamp` |
+| Money | `numeric(10,2)` | `float` |
+| Flags | `boolean` | `varchar`, `int` |
+
+### Common Patterns
+
+**Composite Index Order:**
+```sql
+-- Equality columns first, then range columns
+CREATE INDEX idx ON orders (status, created_at);
+-- Works for: WHERE status = 'pending' AND created_at > '2024-01-01'
+```
+
+**Covering Index:**
+```sql
+CREATE INDEX idx ON users (email) INCLUDE (name, created_at);
+-- Avoids table lookup for SELECT email, name, created_at
+```
+
+**Partial Index:**
+```sql
+CREATE INDEX idx ON users (email) WHERE deleted_at IS NULL;
+-- Smaller index, only includes active users
+```
+
+**RLS Policy (Optimized):**
+```sql
+CREATE POLICY policy ON orders
+  USING ((SELECT auth.uid()) = user_id);  -- Wrap in SELECT!
+```
+
+**UPSERT:**
+```sql
+INSERT INTO settings (user_id, key, value)
+VALUES (123, 'theme', 'dark')
+ON CONFLICT (user_id, key)
+DO UPDATE SET value = EXCLUDED.value;
+```
+
+**Cursor Pagination:**
+```sql
+SELECT * FROM products WHERE id > $last_id ORDER BY id LIMIT 20;
+-- O(1) vs OFFSET which is O(n)
+```
+
+**Queue Processing:**
+```sql
+UPDATE jobs SET status = 'processing'
+WHERE id = (
+  SELECT id FROM jobs WHERE status = 'pending'
+  ORDER BY created_at LIMIT 1
+  FOR UPDATE SKIP LOCKED
+) RETURNING *;
+```
+
+### Anti-Pattern Detection
+
+```sql
+-- Find unindexed foreign keys
+SELECT conrelid::regclass, a.attname
+FROM pg_constraint c
+JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY(c.conkey)
+WHERE c.contype = 'f'
+  AND NOT EXISTS (
+    SELECT 1 FROM pg_index i
+    WHERE i.indrelid = c.conrelid AND a.attnum = ANY(i.indkey)
+  );
+
+-- Find slow queries
+SELECT query, mean_exec_time, calls
+FROM pg_stat_statements
+WHERE mean_exec_time > 100
+ORDER BY mean_exec_time DESC;
+
+-- Check table bloat
+SELECT relname, n_dead_tup, last_vacuum
+FROM pg_stat_user_tables
+WHERE n_dead_tup > 1000
+ORDER BY n_dead_tup DESC;
+```
+
+### Configuration Template
+
+```sql
+-- Connection limits (adjust for RAM)
+ALTER SYSTEM SET max_connections = 100;
+ALTER SYSTEM SET work_mem = '8MB';
+
+-- Timeouts
+ALTER SYSTEM SET idle_in_transaction_session_timeout = '30s';
+ALTER SYSTEM SET statement_timeout = '30s';
+
+-- Monitoring
+CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+
+-- Security defaults
+REVOKE ALL ON SCHEMA public FROM public;
+
+SELECT pg_reload_conf();
+```
+
+## Related
+
+- Agent: `database-reviewer` - Full database review workflow
+- Skill: `clickhouse-io` - ClickHouse analytics patterns
+- Skill: `backend-patterns` - API and backend patterns
+
+---
+
+*Based on Supabase Agent Skills (credit: Supabase team) (MIT License)*