작업 절차
- •엔티티 필드, 제약조건, 연관관계를 정의한다.
- •접근 패턴에 맞는 리포지토리 메서드를 설계한다.
- •스키마 변경 시 마이그레이션 스크립트를 추가/수정한다.
- •통합 테스트로 매핑/쿼리 동작을 검증한다.
규칙
- •컬럼명과 제약조건을 명시적으로 표현한다.
- •기본은 지연 로딩으로 두고 fetch 전략을 의도적으로 선택한다.
- •자주 조회/조인되는 컬럼에는 인덱스를 추가한다.
모듈 내부 배치 규칙
- •도메인 모델은
modules/domain, JPA/영속 구현은modules/infrastructure에 분리한다. - •권장 패키지:
- •
modules/domain:entity,valueobject,exception,policy(선택),domainservice(필요 시) - •
modules/infrastructure:repository,persistence/entity,persistence/mapper,client,config
- •
- •API 응답 DTO/컨트롤러 로직은 이 스킬 범위에 넣지 않는다.
완료 체크리스트
- •마이그레이션 경로와 롤백 가능성이 명확하다.
- •커스텀 리포지토리 쿼리를 통합 테스트로 검증한다.
- •성능 민감 쿼리는 인덱스 활용을 함께 검토한다.
번들 리소스
- •레퍼런스 인덱스:
references/INDEX.md - •엔티티/마이그레이션 체크리스트:
references/entity-migration-checklist.md - •JPA 엔티티/리포지토리 샘플:
references/jpa-entity-repository-sample.md - •Flyway 마이그레이션 샘플:
references/flyway-migration-sample.md - •리포지토리 통합 테스트 샘플:
references/repository-integration-test-sample.md - •프로젝트 백엔드 아키텍처 가이드:
../../../agents/guidelines/backend-architecture.md - •프로젝트 DB 스키마 가이드:
../../../agents/guidelines/database-schema.md - •프로젝트 리포지토리 테스트 가이드:
../../../agents/guidelines/repository-testing.md - •프로젝트 페이지네이션 가이드:
../../../agents/guidelines/pagination.md - •JPA 엔티티 스캐폴드 스크립트:
scripts/scaffold_jpa_entity.py - •JPA 엔티티 템플릿:
assets/jpa_entity_template.kt - •Flyway 템플릿:
assets/flyway_template.sql