Zoha/agent-skills

NestJS Elasticsearch

NestJS GraphQL + MongoDB 애플리케이션에 Elasticsearch 기반 검색을 추가하기 위한 통합 가이드입니다. 아키텍처 경계(일반 하부구조, 공유 검색 레이어, 피처별 소유 인덱스)를 정의한 후, 전체 수명 주기를 다룹니다: 검색 프로젝션, 인덱싱 및 동기화, MongoDB 수화를 통한 ID 전용 쿼리, 커서 페이징, 교차 엔터티 파생 필드, 설정 가능한 백엔드 시임을 통한 검색 옵션화, 라이브 클러스터 없이 테스트, 그리고 이 모든 것에 대한 운영 및 개발 경험(DX)을 포함합니다.

핵심 계약은 Elasticsearch가 찾고, MongoDB가 제공한다입니다: Elasticsearch는 식별자만 반환하는 순수 검색 인덱스이며, 요청된 엔터티는 항상 진실 공급원인 MongoDB에서 수화됩니다.

적용 시점

다음 상황에서 이 가이드라인을 참조하세요:

• 기존 NestJS GraphQL + MongoDB 애플리케이션에 검색 추가
• @nestjs/elasticsearch 클라이언트 및 공유 검색 레이어 와이어링
• 인덱스 매핑 또는 검색 프로젝션 정의/변경
• MongoDB-Elasticsearch 동기화, 재색인, 또는 인덱스 마이그레이션 구현
• 검색 쿼리, 커서 페이징, 또는 결과 수화 작성
• 엔터티 간 파생 값(개수, 평점) 검색 가능 유지
• 검색을 옵션화하거나, 클러스터 없이 설정에서 백엔드 교체
• 목업 백엔드 시임 또는 실제 임시 클러스터로 검색 테스트
• 오래된 검색 결과 또는 인덱싱 폭풍 디버깅

우선순위별 규칙 카테고리

우선순위	카테고리	영향	접두사
1	아키텍처	CRITICAL	arch-
2	인덱싱 및 동기화	CRITICAL	sync-
3	스키마 및 매핑	HIGH	map-
4	쿼리	HIGH	query-
5	교차 엔터티	MEDIUM-HIGH	rel-
6	운영 및 DX	MEDIUM	ops-
7	설정 및 환경	HIGH	cfg-
8	테스트	MEDIUM-HIGH	test-

빠른 참조

1. 아키텍처 (CRITICAL)

• arch-base-search-repository - 공유 인덱스 및 쿼리 로직을 베이스 리포지토리에 배치
• arch-entity-vs-search-document - Elasticsearch 필드를 엔터티에서 분리 유지
• arch-feature-owned-index - 각 피처가 자신의 인덱스를 소유하고 등록하도록 허용
• arch-infra-module - Elasticsearch 클라이언트를 일반 하부구조 모듈로 격리

2. 인덱싱 및 동기화 (CRITICAL)

• sync-bulk-index - 벌크 API로 배치 인덱싱
• sync-debounce-same-id - 동일 ID 버스트 디바운스
• sync-delete-immediately - 인덱스에서 즉시 삭제
• sync-enqueue-index - 인덱싱을 큐에 넣고; Elasticsearch에 인라인 쓰지 않음
• sync-full-reindex-alias-swap - 버전 관리된 인덱스로 재색인 후 별칭 교체
• sync-idempotent-index-creation - 결정적 이름으로 멱등적 인덱스 생성

3. 스키마 및 매핑 (HIGH)

• map-analyzers - 텍스트 분석기를 신중하게 선택
• map-derived-fields - 배치 매퍼에서 파생 및 관계 필드 계산
• map-exclude-non-search-fields - 검색 목적이 있는 필드만 인덱싱
• map-mapping-object - 매핑을 타입화된 객체로 선언
• map-typed-search-document - 엔터티에 대해 검색 문서 타입화

4. 쿼리 (HIGH)

• query-cursor-pagination - search_after로 페이지네이션
• query-hydrate-restore-order - MongoDB에서 수화하고 관련성 순서 복원
• query-ids-only-search - 검색은 ID만 반환
• query-sort-tiebreaker - 항상 고유한 정렬 타이브레이커 포함

5. 교차 엔터티 (MEDIUM-HIGH)

• rel-derived-counter-cache - 소유 문서에 파생 카운터 캐싱
• rel-owning-module-subscribes - 소유 모듈이 구독하고; 다른 모듈은 자체 이벤트 발행

6. 운영 및 DX (MEDIUM)

• ops-cli-scripts - 마이그레이션 및 재색인 CLI 명령 제공
• ops-explain-debug - Explain 훅 제공
• ops-health-check - 헬스 체크에 Elasticsearch 포함
• ops-log-es-requests - Elasticsearch 요청 및 응답 로깅
• ops-no-cron-for-indexing - 인프로세스 타이머로 인덱싱 예약하지 않음

7. 설정 및 환경 (HIGH)

• cfg-mongo-fallback-backend - 결정적 MongoDB 파인더로 폴백
• cfg-search-backend-seam - 검색을 백엔드 시임 뒤에 배치

8. 테스트 (MEDIUM-HIGH)

• test-mock-elasticsearch-seam - 단위 테스트에서 검색 백엔드 시임 목업
• test-real-es-for-query-semantics - 실제 Elasticsearch로 쿼리 의미론 테스트

사용 방법

자세한 설명과 코드 예제는 개별 규칙 파일을 읽으세요:

rules/arch-entity-vs-search-document.md
rules/sync-full-reindex-alias-swap.md
rules/query-ids-only-search.md

각 규칙 파일에는 다음이 포함됩니다:

• 왜 중요한지와 어떤 레이어에 적용되는지에 대한 간략한 설명
• 설명이 포함된 잘못된 코드 예제
• 설명이 포함된 올바른 코드 예제
• 추가 컨텍스트 및 참조

다른 스킬과의 관계

• nestjs-graphql-structure — 파일 배치. 이 스킬은 피처에 search/ 폴더와 common/search/ + infra/elasticsearch/ 레이어를 추가합니다; 해당 스킬의 피처-모듈, 리포지토리, 이벤트 규칙을 따릅니다.
• nestjs-best-practices — 이 스킬의 예제가 기반으로 하는 서비스, 이벤트, 큐, 설정, 헬스 체크에 대한 동작 규칙.
• 하나의 의도적인 예외 — nestjs-graphql-structure의 service-background-jobs 규칙은 프로세서를 소유 피처에 두도록 합니다. 검색 파이프라인은 common/search/에서 한 번 실행되며 대신 인덱스 레지스트리를 통해 각 피처의 리포지토리를 해결합니다. 왜냐하면 파이프라인은 모든 피처에 대해 동일하기 때문입니다; arch-base-search-repository 참조.

전체 컴파일 문서

모든 규칙이 단일 문서로 확장된 전체 가이드는 AGENTS.md를 참조하세요.