# 사용자 행동 시나리오 기반 실행 계획

> 작성일: 2026-01-07
> 목적: 사용자 행동 시나리오를 구현 가능한 작업 단위로 분해하고, 순서/의존성/구현 방식을 정리한다.
> 최종 산출물: `docs/internal/reference/USER_SCENARIO_REQUIREMENTS.md`

---

## 1) 전제

- 사용자: AI 엔지니어, 개발자, 데이터 분석가가 RAG 시스템 성능 향상을 위해 사용한다.
- 목표: RAGAS 평가, 단계별 성능 분석, 데이터/결과 분석, 전 결과 저장, 개선 방안 생성, 개선안 반영(자동/수동)을 통해 지속적 성능 향상을 달성한다.

---

## 2) 범위

### 포함
- 시나리오 정의, 요구사항 정리, 우선순위 작업 설계
- 평가 파이프라인/단계별 분석/데이터 분석/저장/개선안/피드백 루프 전 과정

### 제외
- 실제 구현/코드 변경 (본 문서는 계획 단계)
- 외부 인프라 구축/운영 자동화 세부 스크립트 변경

---

## 3) 작업 분해(Workstreams)

1. **데이터/데이터셋 관리**: 스키마 검증, 버전 관리, 대용량 로딩 정책
2. **평가 파이프라인**: RAGAS 평가 통합, retriever 연계, 평가 결과 저장
3. **단계별 성능 분석**: stage events 수집/계산/요약
4. **데이터/결과 분석**: NLP 분석 및 결과 데이터 분석(비교/추세)
5. **저장/계보(라인리지)**: 평가/분석 산출물 통합 저장 및 추적
6. **개선안 생성**: 도메인/데이터셋 기반 개선안 생성 로직
7. **피드백 루프**: 개선안 적용(수동/자동) + 재평가
8. **관측성/리포팅**: Phoenix/Langfuse 트레이싱 및 리포트 생성
9. **UX/문서화**: CLI/Web UI 작업 흐름 정리, 문서 업데이트

---

## 4) 순서/구현 방식(Phase Plan)

### Phase 0: 기준선 정리
- 문서 기준(SSoT) 확정 및 시나리오-요건-백로그 매핑
- 구현 방식: 현행 문서/코드 스냅샷을 기준으로 격차 목록화

### Phase 1: 평가 + 벤치마크 기반 고정 (P0)
- 목표: RAGAS 평가를 retriever/벤치마크까지 E2E로 연결
- 구현 방식:
  - Evaluator에 retriever 주입 경로 확보
  - 평가/벤치마크 결과 저장 포맷 통합
  - 최소 스모크 테스트와 문서/CLI 기준 동기화

### Phase 2: 단계별 성능/분석 파이프라인 연결 (P1)
- 목표: stage events와 분석 파이프라인을 통합해 원인 분석 가능하게 함
- 구현 방식:
  - stage ingest/summary/compute-metrics 기준 정리
  - 분석 파이프라인에 결과 데이터/메트릭 입력 연결

### Phase 3: 개선안 생성 + 피드백 루프(수동) (P1)
- 목표: 도메인/데이터셋 기반 개선안 생성과 재평가 흐름 확보
- 구현 방식:
  - 개선안 템플릿/규칙 정의
  - 개선안 적용 전후 비교 리포트 생성

### Phase 4: 자동화/확장/성능 (P2)
- 목표: 자동 Gate/재평가, 대용량 최적화, 운영 자동화 강화
- 구현 방식:
  - 자동 재평가 트리거와 승인 절차
  - 대규모 데이터 스트리밍/캐싱/성능 개선

---

## 5) 산출물 정의(DoD)

- 시나리오/요건/우선순위가 정리된 최종 문서 1종
- Phase별 작업 항목에 대한 구현 방식/의존성 정의
- 각 시나리오가 현재 기능과 어떻게 연결되는지 확인 가능

---

## 6) 리스크/의존성

- 문서 허브 경로 변경 등 기준 문서 변경 시 재정렬 필요
- 외부 서비스(Phoenix/Langfuse/LLM) 환경 의존성
- 평가/분석 산출물 저장 스키마 변경 시 호환성 검토 필요

---

## 7) 검증 방법

- 각 Phase별 체크리스트로 기능 존재 여부 확인
- 평가 실행/저장/비교/리포트 흐름이 끊기지 않는지 점검
- 시나리오별 입력-출력-개선 루프가 최소 1회 재현되는지 확인
