# 프롬프트 동적 관리 시스템 계획

**날짜**: 2025-12-25  
**최종 보강**: 2026-03-03  
**작성자**: happybell80, Claude  
**상태**: 미구현 (실행 계획 보강)

**원칙 참조**:
- `book/300_architecture/311_백엔드_구조_원칙.md` (계층 분리, DB state 경유)
- `book/300_architecture/312_문서_작성_원칙.md`
- `book/300_architecture/315_테스트_원칙.md` (TDD)
- `book/300_architecture/313_Gemini_프롬프트_설계_원칙.md`

---

## 1. 목표

하드코딩 프롬프트를 DB 정책으로 전환해 다음을 달성한다.
- 무중단 프롬프트 수정
- 사용자/로빙/작업별 개인화
- A/B 실험 기반 자동 개선
- 안전한 자동 승격 + 즉시 롤백

---

## 2. 현재 상태 요약 (2026-03-03 기준)

- rb8001 코드 하드코딩 프롬프트 템플릿: 약 40개
- 사용자 핵심 UX 경로 프롬프트 유형: 약 8~10종
  - chat(감정 반영), summarize, analyze, extract, calendar_confirm 등
- 현재 문제:
  - 프롬프트 수정 시 코드 배포 필요
  - 버전/실험/성과 추적이 일관되지 않음
  - 회귀 시 신속 롤백이 어려움

---

## 3. 범위

### 포함
- `rb8001` LLM 경로의 시스템/작업별 프롬프트
- 감정 기반 동적 규칙(톤/길이/금지 규칙)
- A/B 실험, 메트릭 수집, 자동 승격 정책

### 제외
- 모델 자체 교체/튜닝
- 감정 분류기 모델 재학습
- 인프라 토폴로지 변경

---

## 4. 데이터 모델 (최소 스키마)

### 4.1 `prompt_templates`
- purpose: 프롬프트 논리 단위(식별자)
- columns:
  - `id`, `template_key` (unique)  
  - `prompt_type` (`system`, `chat`, `extract`, `calendar_confirm`, ...)
  - `scope_level` (`global`, `robeing`, `task`, `user`)
  - `scope_id` (nullable)
  - `is_enabled`
  - `created_at`, `updated_at`

### 4.2 `prompt_versions`
- purpose: 템플릿 버전 이력
- columns:
  - `id`, `template_id`, `version`
  - `content` (TEXT/JSONB)
  - `variables_schema` (JSONB)
  - `status` (`draft`, `candidate`, `active`, `retired`)
  - `created_by`, `change_reason`, `created_at`

### 4.3 `prompt_experiments`
- purpose: 실험 라우팅
- columns:
  - `id`, `experiment_key`, `template_key`
  - `control_version_id`, `treatment_version_id`
  - `traffic_ratio` (예: 90:10)
  - `guardrail_config` (JSONB)
  - `status` (`running`, `paused`, `completed`)
  - `started_at`, `ended_at`

### 4.4 `prompt_events`
- purpose: 요청 단위 결과 로그
- columns:
  - `id`, `request_id`, `template_key`, `version_id`, `variant`
  - `user_id`, `robeing_id`, `task_type`
  - `latency_ms`, `tokens_in`, `tokens_out`
  - `feedback_signal` (up/down/reask/abandon)
  - `created_at`

### 4.5 `prompt_metrics_daily`
- purpose: 일별 집계
- columns:
  - `date`, `template_key`, `version_id`, `variant`
  - `success_rate`, `reask_rate`, `fallback_rate`
  - `avg_latency_ms`, `avg_tokens`, `feedback_score`

---

## 5. 런타임 병합 규칙

### 5.1 해석 순서 (낮음 → 높음 우선순위)
1. Global
2. Robeing
3. Task
4. User
5. Runtime modifier(감정/리스크 규칙)

### 5.2 병합 원칙
- 문자열 덮어쓰기 금지, 섹션 단위 병합(`role`, `constraints`, `output_format`)
- 금지 규칙(예: 민감 라벨 직접 노출 금지)은 항상 최종 승자
- 해석 실패 시 즉시 fallback (최근 stable active 버전)

---

## 6. 자동 개선 정책

### 6.1 실험 지표
- 1차 품질 지표:
  - `reask_rate` (낮을수록 좋음)
  - `negative_feedback_rate` (낮을수록 좋음)
  - `task_success_rate` (높을수록 좋음)
- 2차 비용/성능 지표:
  - `avg_latency_ms`
  - `avg_tokens`
  - `fallback_rate`

### 6.2 자동 승격 조건(예시)
- 최소 샘플 수 충족 (예: n >= 500)
- treatment가 control 대비:
  - `reask_rate` 10% 이상 개선
  - `negative_feedback_rate` 악화 없음
  - `latency_ms` 15% 이상 악화 없음
- guardrail 위반 0건

### 6.3 자동 롤백 조건
- 15분 윈도우 기준 `fallback_rate` 급증
- `negative_feedback_rate` 임계치 초과
- 5xx/파싱 실패 연쇄 발생

### 6.4 운영 모드
- 기본: **자동 제안 + 사람 승인 후 승격**
- 완전 자동 승격은 초기 1개월 관찰 후 제한 적용

---

## 7. 구현 단계

### Phase 1: 인벤토리/스키마/TDD
- 하드코딩 프롬프트 인벤토리 확정(파일/함수/용도)
- `prompt_templates`, `prompt_versions` 생성
- Repository + Service 뼈대 구현
- 테스트:
  - 스키마 생성/마이그레이션
  - 버전 조회/활성 버전 선택

### Phase 2: 읽기 경로 전환 (safe fallback)
- `llm_service.py`, `gemini_handler.py`에 DB 조회 연결
- 기존 하드코딩은 fallback로 유지
- 테스트:
  - DB 성공 시 DB 프롬프트 사용
  - DB 실패 시 하드코딩 fallback

### Phase 3: 병합/개인화/감정 modifier
- scope 병합 및 변수 치환
- 감정/리스크 modifier를 DB 규칙으로 부분 이관
- 테스트:
  - 병합 우선순위
  - 금지 규칙 우선 적용

### Phase 4: 실험/메트릭/자동 승격
- `prompt_experiments`, `prompt_events`, `prompt_metrics_daily` 구현
- 실험 라우터 + 승격/롤백 워커 구현
- 테스트:
  - 라우팅 결정 일관성
  - guardrail 위반 시 자동 중단/롤백

---

## 8. 수용 기준 (Definition of Done)

- 하드코딩 의존 프롬프트 80% 이상 DB 전환
- 핵심 UX 경로(chat/summarize/extract/calendar_confirm) DB 관리
- 실험 대시보드에서 버전별 지표 확인 가능
- 자동 롤백 시나리오 리허설 1회 이상 통과
- 장애 시 서비스 무중단 fallback 확인

---

## 9. 위험과 대응

- 위험: 잘못된 프롬프트 배포로 UX 악화
  - 대응: candidate → canary → full 단계적 승격
- 위험: 과도한 개인화로 톤 불안정
  - 대응: immutable safety constraints 최종 적용
- 위험: 지표 왜곡/샘플 편향
  - 대응: 최소 샘플 수 + 시간/사용자 분산 조건

---

## 10. 체크리스트 (누락 방지)

### 설계
- [ ] 실제 하드코딩 인벤토리 목록화 완료
- [ ] scope 우선순위 충돌 규칙 정의
- [ ] 안전 제약(금지 규칙) 최종 우선순위 명시

### 구현
- [ ] Repository/DDL/Service 동시 반영
- [ ] fallback 경로(코드/DB) 모두 테스트
- [ ] 실험 라우팅 deterministic 보장

### 운영
- [ ] 승격/롤백 가드레일 임계값 합의
- [ ] 대시보드/알람 연결
- [ ] 장애 훈련(롤백 drill) 수행

---

## 11. 2회 점검 기록 (2026-03-03)

### 1차 점검에서 추가한 누락 항목
- 자동 승격 조건(샘플 수/가드레일)
- 자동 롤백 조건
- 이벤트/메트릭 테이블 분리
- 현재 하드코딩 인벤토리 규모 반영

### 2차 점검에서 확정한 항목
- scope 병합 우선순위 명시
- immutable safety constraints 최종 우선 적용 명시
- DoD/운영 체크리스트/리허설 항목 추가

---

## 참고 문서
- `book/300_architecture/311_백엔드_구조_원칙.md`
- `book/300_architecture/312_문서_작성_원칙.md`
- `book/300_architecture/315_테스트_원칙.md`
- `book/300_architecture/313_Gemini_프롬프트_설계_원칙.md`
- `journey/troubleshooting/250806_happybell80_동적프롬프트구현.md`