# 사용자 행동 시나리오 및 요구사항

> 작성일: 2026-01-07
> 목적: EvalVault를 사용하는 핵심 사용자(AI 엔지니어/개발자/데이터 분석가)의 행동 시나리오를 정의하고, 목표 달성을 위한 요구사항과 추가 개발 항목을 정리한다.

---

## 1) 전제 및 목표

- 사용자는 RAG 시스템 구축/개선 과정에서 성능을 높이기 위해 EvalVault를 사용한다.
- 목표는 RAGAS 평가, 단계별 성능 확인, 데이터/결과 분석, 전 데이터 저장, 개선 방안 도출, 개선안 반영까지 하나의 루프로 연결하는 것이다.
- 개선안은 AI/아키텍처/데이터 분석/사용자/고객 관점에서 모두 납득 가능한 수준의 전문성을 갖추어야 한다.

---

## 2) 핵심 사용자 역할

- **AI 엔지니어**: 모델/프롬프트/리트리버 조합을 설계하고 품질 개선을 설계한다.
- **개발자**: CLI/Web UI 기반 실행, 저장, 통합, 배포 경로를 유지한다.
- **데이터 분석가**: 데이터 품질, 성능 지표, 트렌드 분석을 통해 개선안을 도출한다.

---

## 3) 사용자 행동 시나리오

### 시나리오 A: 환경 설정 및 데이터셋 온보딩
- 설정 파일과 프로필을 준비하고 데이터셋 스키마를 검증한다.
- 데이터셋 버전을 기록하고 향후 비교를 위해 메타데이터를 저장한다.
- 기대 결과: 재현 가능한 평가 입력이 준비되고, 데이터셋의 기준선이 확정된다.

### 시나리오 B: RAGAS 평가 실행 및 저장/추적
- `evalvault run`으로 평가를 실행하고 결과를 DB에 저장한다.
- 트래커(Phoenix/Langfuse/MLflow)에 실행을 기록해 추적성을 확보한다.
- 기대 결과: 평가 점수, 임계값, 트레이스, 아티팩트가 연결된다.

### 시나리오 C: 단계별 성능 진단
- stage events를 수집하고 단계별 요약/메트릭을 계산한다.
- 지연/실패/품질 저하 원인을 단계별로 추적한다.
- 기대 결과: 병목 단계와 원인 범주가 정량화된다.

### 시나리오 D: 데이터/결과 분석
- 데이터 자체에 대한 분석(NLP/통계)을 수행한다.
- 실행 히스토리와 결과 데이터를 비교/요약한다.
- 기대 결과: 데이터 품질 이슈와 성능 저하 요인이 분리된다.

### 시나리오 E: 개선안 생성(다중 관점)
- 평가/단계/데이터 분석 결과를 종합해 개선안을 작성한다.
- AI/아키텍처/데이터/사용자/고객 관점별로 근거와 기대 효과를 제시한다.
- 기대 결과: 합의 가능한 개선안이 생성되고 실행 우선순위가 결정된다.

### 시나리오 F: 개선안 적용 및 재평가(수동/자동)
- 개선안을 적용하고 재평가로 효과를 검증한다.
- 결과가 기준선을 넘는 경우 개선안을 확정한다.
- 기대 결과: 개선안이 다음 RAG 시스템/데이터셋에 반영된다.

### 시나리오 G: 운영 모니터링 및 드리프트 대응
- 드리프트를 감지하고 품질 게이트를 실행한다.
- 리포트/릴리스 노트를 생성해 공유한다.
- 기대 결과: 운영 중 품질 저하를 조기에 차단한다.

---

## 4) 요구사항 정리

### 기능 요구사항

1. **데이터/데이터셋 관리**
   - JSON/CSV/XLSX 입력과 스키마 검증
   - 데이터셋 버전/메타데이터 기록

2. **평가 및 저장**
   - RAGAS 기반 평가 + 커스텀 메트릭
   - 실행 결과/임계값/메타데이터 저장

3. **단계별 성능 분석**
   - stage events 수집/요약/메트릭 계산
   - 단계별 병목 및 품질 저하 식별

4. **데이터/결과 분석**
   - 데이터 자체 분석(자연어 포함)
   - 실행 결과 비교/추세/이상치 분석

5. **개선안 생성**
   - 분석 결과를 다중 관점 개선안으로 정리
   - 개선안 우선순위/근거/예상효과 포함

6. **피드백 루프**
   - 개선안 반영(수동/자동) 및 재평가
   - 개선 전/후 비교 리포트 제공

7. **관측/추적**
   - 트레이싱 및 실험/데이터셋 연동
   - 릴리스 노트/운영 알림 지원

### 비기능 요구사항

- 재현성(동일 입력/설정에서 동일 결과)
- 추적성(모든 실행/분석/개선안의 근거 연결)
- 확장성(포트/어댑터 기반 교체 가능성)
- 안정성(대용량 데이터 처리, 스트리밍 지원)
- 보안성(시크릿 분리, 환경 변수 기반 관리)

---

## 5) 우선 작업(시나리오 기반)

### P0: 평가/벤치마크 기반 고정
- 평가 파이프라인과 retriever 연계 완성
- 벤치마크 실행 및 결과 저장 기준 고정
- 평가/벤치마크 결과를 동일한 저장/리포트 흐름으로 묶기

### P1: 단계별 분석 + 개선안 생성
- stage events 기반 성능 요약과 병목 분석
- 데이터/결과 분석 파이프라인 강화
- 개선안 템플릿과 관점별 가이드 확립

### P2: 자동화/확장
- 자동 재평가/게이트 실행
- 대규모 데이터 처리 최적화
- 개선안 자동 적용과 승인 절차

---

## 6) 추가 개발 항목(현재 대비 격차)

- Evaluator에 retriever 주입 경로 추가
- 평가 결과에서 검색 품질 메트릭 산출 추가
- stage events와 평가 결과를 통합한 분석 뷰 제공
- 데이터/결과 분석 산출물을 통합 저장하고 라인리지를 유지
- 개선안 생성 로직(규칙 기반 + 템플릿) 정립
- 개선안 적용/재평가를 잇는 피드백 루프 자동화
- Web UI에서 개선안/분석 결과를 시각화
- 버전/표기 정합성 자동화(문서/CLI/리포트)

---

## 7) 완료 기준(DoD)

- 시나리오 A~G가 최소 1회 재현 가능해야 함
- 평가/분석/개선안/재평가 흐름이 단절 없이 연결되어야 함
- 개선안이 데이터셋/도메인에 반영되는 경로가 문서화되어야 함

---

## 8) 참고 문서

- docs/PROJECT_OVERVIEW.md
- docs/PROJECT_SOURCE_GUIDE.md
- docs/status/ROADMAP.md
- docs/status/STATUS.md
- docs/guides/USER_GUIDE.md
- docs/guides/CLI_GUIDE.md
- docs/guides/OBSERVABILITY_PLAYBOOK.md
- docs/internal/status/STATUS.md
