Strengthen prompt dynamic management plan with rollout, metrics, and guardrails

journey/plans/251225_프롬프트_동적관리_계획.md

@@ -1,72 +1,241 @@
 # 프롬프트 동적 관리 시스템 계획
 
-**날짜**: 2025-12-25
+**날짜**: 2025-12-25  
-**작성자**: happybell80
+**최종 보강**: 2026-03-03  
-**상태**: 미구현
+**작성자**: happybell80, Claude  
+**상태**: 미구현 (실행 계획 보강)
 
-**원칙 참조** (구현 전 필수 확인):
+**원칙 참조**:
-- `311_백엔드_구조_원칙.md`: 계층 분리, DB는 state 경유, 섹션 6-1 스키마 확인
+- `book/300_architecture/311_백엔드_구조_원칙.md` (계층 분리, DB state 경유)
-- `312_문서_작성_원칙.md`: 핵심만 간결, 파일명:줄번호
+- `book/300_architecture/312_문서_작성_원칙.md`
-- `315_테스트_원칙.md`: 테스트는 TDD로 진행 (Red → Green → Refactor)
+- `book/300_architecture/315_테스트_원칙.md` (TDD)
+- `book/300_architecture/313_Gemini_프롬프트_설계_원칙.md`
 
 ---
 
-## 목표
+## 1. 목표
 
-프롬프트 DB화를 통한 동적 변경 및 개인화 구현
+하드코딩 프롬프트를 DB 정책으로 전환해 다음을 달성한다.
+- 무중단 프롬프트 수정
+- 사용자/로빙/작업별 개인화
+- A/B 실험 기반 자동 개선
+- 안전한 자동 승격 + 즉시 롤백
 
 ---
 
-## DB 스키마 설계
+## 2. 현재 상태 요약 (2026-03-03 기준)
 
-**테이블**: `prompt_templates`
+- rb8001 코드 하드코딩 프롬프트 템플릿: 약 40개
-- scope_level: 'global', 'robeing', 'user', 'task'
+- 사용자 핵심 UX 경로 프롬프트 유형: 약 8~10종
-- scope_id: robeing_id, user_id, task_type 등
+  - chat(감정 반영), summarize, analyze, extract, calendar_confirm 등
-- prompt_type: 'system', 'chat', 'extract', 'calendar_confirm', 'ir_analysis' 등
+- 현재 문제:
-- content: JSONB (템플릿 내용 + 변수 정의)
+  - 프롬프트 수정 시 코드 배포 필요
-- version, is_active, created_at, updated_at
+  - 버전/실험/성과 추적이 일관되지 않음
+  - 회귀 시 신속 롤백이 어려움
 
 ---
 
-## 프롬프트 분류 기준
+## 3. 범위
 
-### 계층적 범위(Scope)
+### 포함
-- Global: 모든 사용자 공통 기본 프롬프트
+- `rb8001` LLM 경로의 시스템/작업별 프롬프트
-- Robeing: 특정 로빙 공통
+- 감정 기반 동적 규칙(톤/길이/금지 규칙)
-- User: 사용자별 개인화
+- A/B 실험, 메트릭 수집, 자동 승격 정책
-- Task: 작업 타입별
 
-### 병합 로직
+### 제외
-- Global → Robeing → User 순서로 조회
+- 모델 자체 교체/튜닝
-- 각 레벨별 개별 쿼리 후 애플리케이션에서 병합
+- 감정 분류기 모델 재학습
+- 인프라 토폴로지 변경
 
 ---
 
-## 구현 Phase
+## 4. 데이터 모델 (최소 스키마)
 
-### Phase 1: DB 스키마 및 기본 인프라 (TDD 진행)
+### 4.1 `prompt_templates`
-- `rb8001/app/state/repositories/prompt_repository.py` (신규): prompt_templates 테이블 생성, PromptService 클래스 (조회, 병합, 캐싱)
+- purpose: 프롬프트 논리 단위(식별자)
-- 기본 프롬프트 마이그레이션 (하드코딩 → DB)
+- 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`
 
-### Phase 2: 핵심 프롬프트 DB화
+### 4.2 `prompt_versions`
-- `rb8001/app/services/llm/gemini_handler.py`, `rb8001/app/services/llm/llm_service.py`: 시스템 프롬프트 DB 조회로 변경
+- purpose: 템플릿 버전 이력
-- 작업 타입별 프롬프트 (chat, extract, calendar_confirm) DB화
+- columns:
-- 폴백 로직: DB 조회 실패 시 기존 `_get_system_prompt()` 메서드 사용
+  - `id`, `template_id`, `version`
+  - `content` (TEXT/JSONB)
+  - `variables_schema` (JSONB)
+  - `status` (`draft`, `candidate`, `active`, `retired`)
+  - `created_by`, `change_reason`, `created_at`
 
-### Phase 3: 개인화 및 동적 프롬프트
+### 4.3 `prompt_experiments`
-- `rb8001/app/services/llm/prompt_service.py` (신규): 사용자별 프롬프트 오버라이드, 감정 기반 동적 프롬프트 조합, 변수 치환 시스템
+- 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`
 
-### Phase 4: A/B 테스트 및 모니터링
+### 4.4 `prompt_events`
-- 프롬프트 버전 관리, A/B 테스트 지원, 롤백 기능
+- 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`
-- `../ideas/250828_dynamic_system_prompt_memory.md`
+- `journey/troubleshooting/250806_happybell80_동적프롬프트구현.md`
-- `troubleshooting/250806_happybell80_동적프롬프트구현.md` - 동적 프롬프트 구현 기록
-- `book/300_architecture/311_백엔드_구조_원칙.md` - 계층 분리 원칙