# 자기개선 루프 DB/서비스 구현 실행계획

**작성일**: 2026-03-03
**상태**: 미구현
**목표**: 로빙의 `예측 -> 행동 -> 평가 -> 반성` 루프를 운영 가능한 데이터 구조로 고정

---

## 1) 범위
- 코드 기능 확장 전에 DB/로그 구조를 먼저 고정한다.
- 기존 자산(`intent_review_queue`, `ir_deck_feedback`, `conversation_log`)을 재사용한다.
- 부족한 영역(정책 버전/반성 기록)을 신규 테이블로 보완한다.
- 구조/구현 원칙은 [311_backend_coding_principles](../../book/300_architecture/311_backend_coding_principles.md)을 단일 기준으로 따른다.

## 1-1) 로컬 개발자 실행 경계 (필수)

### 로컬 개발자가 할 수 있는 것
- `rb8001`, `robeing-gateway`, `robeing-monitor` 코드 수정
- 단위 테스트/통합 테스트(로컬) 작성 및 실행
- DDL/API 스펙 문서화, 마이그레이션 SQL 초안 작성
- `run_id` 전파 로직, `/api/message` 자동 적재 로직 구현

### 로컬 개발자가 할 수 없는 것 (운영 확인 필요)
- 23/24 서버 배포 반영 및 실서비스 재시작 확인
- 게이트웨이(23) 실제 프록시 규칙 반영 여부 최종 확정
- 운영 DB 실제 적재량/운영 지표 기준선 확정
- 운영 경유 E2E(`gateway -> rb8001 -> monitor`) 최종 판정

### 완료 판정 규칙
- 로컬 완료: 코드/테스트/문서 기준 충족
- 운영 완료: 서버 반영 + 운영 E2E 증거(로그/응답/DB 적재) 확인
- 운영 증거 없이는 "전체 완료"로 보고하지 않는다

## 2) 구현 대상 (핵심)

### A. 정책 버전 테이블 추가
- 테이블명: `robeing_policy_versions`
- 목적: 어떤 정책으로 답했는지 추적
- 핵심 필드:
  - `id`, `robeing_id`, `policy_type`, `version`
  - `config_json`, `is_active`
  - `created_at`, `created_by`

### B. 루프 실행 로그 테이블 추가
- 테이블명: `robeing_self_improvement_runs`
- 목적: 예측/행동/평가/반성 스냅샷 저장
- 핵심 필드:
  - `run_id`, `robeing_id`, `request_type`
  - `predict_snapshot`, `act_snapshot`
  - `evaluate_snapshot`, `reflect_snapshot`
  - `policy_version`, `created_at`

### C. 지표 표준 키 고정
- intent:
  - `accuracy`, `f1`, `correction_rate`
- feedback:
  - `up_ratio`, `down_ratio`, `rephrase_rate`
- emotion:
  - `kl_divergence`, `brier_score`, `entropy_diff`

## 2-1) 우선 반영 결정 (확신도 90% 이상)

### D. 공통 실행키(`run_id`) 데이터 계약 고정 (95%)
- 모든 루프 이벤트(프롬프트/밸류에이션/일기/피드백)를 `run_id`로 연결한다.
- 저장/조회 API 모두 `run_id`를 필수 입력으로 사용한다.

### E. 밸류에이션 1차 성과 라벨 고정 (90%)
- 성공/실패 라벨의 1차 기준을 아래 2개로 고정한다.
  - `follow_on_funding` (후속 투자 유치 여부)
  - `survival_period` (생존 기간)

### F. 예측 단계 필수 스키마 고정 (92%)
- 예측 단계 저장 필드를 최소 4개로 고정한다.
  - `hypothesis`
  - `probability`
  - `confidence`
  - `expected_impact`

### G. 전역 하드 게이트 1차 도입 (93%)
- 안전/정확도 임계치 미달 시 자동 롤백을 기본 동작으로 고정한다.
- 프롬프트 실험 게이트와 서비스 전역 게이트를 분리해 기록한다.

### H. 폐루프 E2E 시나리오 1개 필수 (91%)
- `질문 -> 응답 -> 사용자 반응 -> 정책 반영` 전 과정을 단일 테스트로 고정한다.
- 릴리스 전 이 시나리오 통과를 필수 조건으로 둔다.

### I. 철학-구현 1:1 매핑표 작성 (94%)
- 철학 원칙 문장마다 연결되는 테이블/필드/API/잡을 1:1로 문서화한다.
- 문서 링크는 상대경로로만 연결한다.

## 2-2) 실행 스펙 확정안

### J. DDL/API 필드 단위 확정

#### 1) 테이블: `robeing_self_improvement_runs`
- PK:
  - `run_id UUID`
- 필수 컬럼:
  - `robeing_id UUID`
  - `request_type TEXT`
  - `policy_version TEXT`
  - `created_at TIMESTAMPTZ`
- 스냅샷 컬럼(JSONB):
  - `predict_snapshot`
  - `act_snapshot`
  - `evaluate_snapshot`
  - `reflect_snapshot`
- 제약조건:
  - `request_type <> ''`
  - `policy_version <> ''`
- 인덱스:
  - `(robeing_id, created_at DESC)`
  - `(policy_version, created_at DESC)`
  - `GIN(evaluate_snapshot)`
  - `GIN(reflect_snapshot)`

#### 2) API 최소 계약
- `POST /self-improvement/runs`: 루프 실행 스냅샷 저장
- `GET /self-improvement/runs/{run_id}`: 단건 조회
- `GET /self-improvement/runs?robeing_id=&from=&to=`: 기간/대상 목록 조회

### K. 운영 게이트 임계치 확정
- 정확도 게이트:
  - 최근 7일 `first_response_resolution < 0.60`이면 승격 차단
- 안전 게이트:
  - 최근 24시간 `critical_safety_events >= 1`이면 즉시 롤백
- 비용 게이트:
  - 최근 7일 `cost_per_success`가 기준 대비 `+20%` 초과면 승격 차단
- 공통 판정 규칙:
  - 2개 이상 위반: 자동 롤백
  - 1개 위반: 수동 승인 모드 전환

### L. 코드 경로별 저장 지점 매핑 확정
- `rb8001`:
  - 루프 스냅샷 생성/저장 단일 진입점
  - `POST /self-improvement/runs` 호출 책임
- `robeing-monitor`:
  - 집계/대시보드/게이트 판정 책임
  - runs 기반 메트릭 계산 및 상태 노출
- `robeing-gateway`:
  - `run_id` 전파(`X-Run-Id`) 책임
  - 데이터 변환 없이 전달만 수행
- 불변 원칙:
  - 저장 책임은 `rb8001`으로 단일화
  - 운영 판정 책임은 `robeing-monitor`로 단일화
  - 라우팅/추적 책임은 `robeing-gateway`로 단일화

### M. 대화 회상 질의 처리 원칙(LangGraph)
- 대상 질문 예:
  - `로빙 이전에 우리가 평가했던 스타트업 있잖아 그거 뭐지?`
- 처리 방식:
  - LangGraph 상태 그래프로 처리한다.
  - 기본 전이: `retrieve -> disambiguate -> ask_clarification -> wait -> close_no_response`
  - 모든 노드에서 동일 `run_id`를 유지한다.
- 무응답 처리:
  - 24시간 무응답 시 `closed_no_response`로 종료
  - `feedback_signal=abandon`, `first_response_resolution=false` 기록
  - `reflect_snapshot`에 모호 질의 패턴 저장

### N. TDD 계획(필수)
- 원칙:
  - 구현 전에 테스트를 먼저 작성한다.
  - 최소 1개 E2E + 핵심 노드 단위 테스트를 함께 유지한다.
- 단위 테스트:
  - retrieval 결과 0/1/N건 분기 검증
  - disambiguate 시 후보 다건일 때 확인질문 생성 검증
  - no-response 타임아웃 종료(`closed_no_response`) 검증
- 통합 테스트:
  - `gateway -> rb8001 -> monitor` 구간에서 `X-Run-Id` 보존 검증
  - 저장 스냅샷(`predict/act/evaluate/reflect`) 일관성 검증
- E2E 테스트:
  - 질문 -> 후보 제시/확인질문 -> 무응답 종료까지 전 과정 검증

## 2-3) 완성도 상향(잔여 8%) 실행안
- DDL 마이그레이션 우선 확정:
  - 문서 스펙을 실제 SQL 마이그레이션으로 고정해 해석 오차를 제거한다.
- 기준선 2주 측정 후 게이트 보정:
  - 현재 운영 데이터 기준선(정확도/안전/비용)을 수집한 뒤 임계치를 재보정한다.
- `X-Run-Id` E2E 검증 1개 추가:
  - `gateway -> rb8001 -> monitor` 전 구간에서 동일 `run_id` 추적이 유지되는지 테스트로 고정한다.

## 2-4) 프롬프트 DB화와 병행 원칙 (설계 병행, 실행 분리)
- 설계는 병행:
  - 자기개선 루프 DB 계획과 프롬프트 DB화 계획을 같은 스프린트에서 정합성 있게 설계한다.
- 실행은 분리:
  - 1차 릴리스는 `run_id` 기반 루프 수집/판정 골격을 우선 배포한다.
  - 프롬프트 자동 승격/롤백은 관측 데이터 확보 후 2차 릴리스로 분리한다.
- 운영 기본 모드:
  - `자동 제안 + 사람 승인`을 기본으로 유지한다.
- RAG 적용 원칙:
  - RAG는 필수 선행조건이 아니다.
  - 다만 반성/정책 업데이트 품질 향상을 위해 보조 경로로 제한 도입한다.
  - 초기 적용 범위는 `reflect` 단계의 유사 사례 검색(Top-k)으로 한정한다.
- 연결 문서:
  - [프롬프트 동적 관리 시스템 계획](./251225_프롬프트_동적관리_계획.md)

## 3) 단계별 실행

### Phase 1. 스키마 확정 (1일)
- DDL 초안 작성
- 컬럼명/타입/인덱스/보존기간 확정
- 롤백 기준 정의

### Phase 2. 저장 경로 연결 (2~3일)
- `rb8001`에서 루프 스냅샷 저장 지점 추가 설계
- `robeing-monitor`에서 조회 API 설계
- `robeing-gateway` 프록시 경로 확인

### Phase 3. 운영 검증 (2일)
- 대표 시나리오(미팅 요약) 20건 반복 테스트
- 대표 시나리오(대화 회상 질의) 무응답 포함 20건 반복 테스트
- 지표 변화 측정:
  - `싫어요 비율`
  - `수정 요청 비율`
  - `첫 응답 해결률`

### Phase 4. 정책 업데이트/롤백 (1일)
- 정책 버전 상승 규칙 적용
- 성능 악화 시 즉시 이전 버전 롤백 검증

## 4) 산출물
- DB 스키마 문서
- API 계약(입력/출력/오류)
- 루프 대시보드 최소 지표 정의
- 운영 체크리스트

## 5) 리스크 및 대응
- 리스크: 피드백 수집 편향(좋아요/싫어요 불균형)
  - 대응: 암묵 신호(재질문/수정요청) 병행
- 리스크: 정책 잦은 변경으로 품질 흔들림
  - 대응: 버전 게이트 + 롤백 기준 고정
- 리스크: 로그 과다 적재
  - 대응: 요약 스냅샷 중심 저장, 원문 보존 기간 분리

## 6) 성공 판정
- 2주 관찰 기준:
  - `down_ratio` 감소
  - `correction_rate` 감소
  - `first_response_resolution` 증가

## 7) 연결 문서
- [자기개선 루프 시나리오](../scenarios/260303_자기개선루프_미팅요약_피드백_시나리오.md)
- [자기개선 루프 구현 리서치](../research/260303_자기개선루프_DB_서비스_구현_리서치.md)
- [프롬프트 동적 관리 시스템 계획](./251225_프롬프트_동적관리_계획.md)
