# Prompts & Schemas — 프롬프트 설계 원칙 + 주요 프롬프트 상세

> 2026-04-15 보정: v10codex 기준. 프롬프트 원칙은 기본 유지, schema는 step 단위 contract로 관리.

## 프롬프트 관리 원칙

1. **DB-first, 파일 fallback**: prompt_template 테이블 우선, 없으면 파일 시스템
2. **버전 디렉토리**: `prompts/_base/{module}/{version}.{timestamp}/{name}.md`
3. **덮어쓰기 금지**: 새 버전 디렉토리 생성
4. **숫자식 정렬**: `_version_sort_key` 사용 (사전식 금지)
5. **시나리오 의존 금지**: 모든 프롬프트는 범용 (고유명사, 특정 캐릭터명 금지)

## 프롬프트 로딩 시스템

```python
load_prompt(module, name, db, **format_kwargs)
  # 1. DB: prompt_template WHERE module=?, name=?, is_active=true
  # 2. File: prompts/_base/{module}/{latest_version}/{name}.md
  # 3. format_kwargs로 {변수} 치환

load_schema(module, name, db)
  # JSON schema dict 반환 (structured output용)
```

---

## 핵심 프롬프트 상세

### scene_detail (scene_extractor_v2) — T2I 프롬프트 생성

**위치**: `prompts/_base/scene_extractor_v2/{version}/turn_scene_detail.md`

**핵심 규칙**:
- "Photorealistic cinematic still."로 시작
- 영어 3~5문장, 스틸 프레임에 보이는 것만
- **원어 예외**: 고유명사/지명은 원어 표기
- **프레임 배치 필수**: 인물/소품이 프레임 어디에 있는지 명시
- **소품 프레임 점유 40% 제한**: 단일 소품이 프레임 40% 이상 금지
- **카메라 구도 일관성**: wide shot인데 소품이 프레임 대부분 채우는 모순 금지
- **인물 방향/자세 필수**: character_angles 반영 (facing_camera, back_to_camera 등)
- **시선(gaze) 필수**: eyes→ 정보 반드시 t2i_prompt에 반영
- **얼굴 식별 불가 인물 — short_id 금지**: 실루엣/그림자/역광 → 보통명사 사용
- **포커스(focus) 필수**: 매 프롬프트에 "focus on ..." 포함
- **시점 혼합 금지**: 1인칭/3인칭 한 프롬프트에 섞지 말 것
- **단일 정지 순간만**: 시간 순서 행동 금지
- **카메라 기법 이름 금지**: "dutch_angle" 대신 시각적 묘사

**Short ID 규칙**:
- 인물: bare C## (복합 C##O## 금지 — 코드에서 조합)
- 배경: `[L01: 공간 묘사 20~30단어]` 대괄호 형식만
- 소품: P01, P03 등
- O## 단독 사용 금지

**변형 수**:
- shot_variation_count (ENV) 만큼 T2I 생성
- 각 변형은 다른 카메라 구도 + 색감

**스키마** (`scene_detail_schema.json`):
```json
{
  "representative_moment": "string",
  "t2i_variations": [{
    "t2i_prompt": "string",
    "camera_effect": "string",
    "outfit_assignments": [{"character_id": "C01", "outlook_id": "O02"}]
  }],
  "visible_entities": ["C01", "L02", "P03"]
}
```

---

### scene_consistency — 교차 샷 시각적 일관성

**위치**: `prompts/_base/scene_consistency/2.202604141200/system.md`

**역할**: 씬 내 2+ 샷에 걸쳐 동일하게 유지되어야 할 시각적 요소 식별

**고정 요소 유형**:
1. **character_state**: 사망/부상/의식불명 인물 — 자세, 상처, 문신, 혈흔 패턴까지 모든 디테일
2. **environment_state**: 깨진 창문, 열린 문, 벽 표식, 조명 상태
3. **persistent_prop**: 이동하지 않는 소품 위치/상태

**분석 원칙**:
- 2+ 샷 공통만 (단일 샷 전용 제외)
- 시각적 묘사만 (감정/스토리 금지)
- 영어로 작성 (T2I 직접 삽입용)
- **엔티티 ID 절대 금지** (보통명사만)
- 구체적 자세/위치 (모호한 "lying down" 금지)
- 인종/국적 명기
- **빠짐없이 수집**: 문신, 상처, 반점, 벽 표식 등 디테일까지

**스키마**:
```json
{
  "scene_index": 12,
  "analysis_summary": "한국어 요약",
  "fixed_elements": [{
    "element_id": "dead_minsook",
    "element_type": "character_state",
    "character_name": "민숙",
    "description": "A deceased middle-aged Korean woman...",
    "applies_to_shots": [1, 2]  // minItems: 2
  }]
}
```

---

### shot_dependency_t2i (v4) — 배경 참조 + 죽은 인물 유지

**위치**: `prompts/_base/shot_dependency_t2i/4.202604141200/system.md`

**참조 유형**:
- `exact_background`: 같은 방, 배경 그대로
- `atmosphere_reference`: 다른 방/앵글, 분위기만 참조

**죽은/의식불명 인물 처리 (v4 핵심)**:
- 이 인물은 **환경의 일부** — ignore_elements에 넣지 말 것
- keep_elements에 시각적 묘사 포함
- "Ignore all people" 금지 → 움직이는 인물만 개별 지정

**ignore_elements 규칙**:
- 엔티티 ID 금지 → 보통명사만
- 편집 지시 금지 (Add, Replace, Adjust)
- 죽은/의식불명 인물은 무시 대상 아님

**스키마**:
```json
{
  "dependencies": [{
    "scene_index": 12,
    "shot_index": 2,
    "location_refs": [{
      "scene_index": 12,
      "shot_index": 1,
      "reason": "같은 침실",
      "ref_usage": "exact_background",
      "ignore_elements": "Ignore the standing woman near the curtain.",
      "keep_elements": ["the dead woman slumped against the wall", "blood pool"]
    }]
  }]
}
```

---

### shot_staging — 촬영 연출 (DP)

**위치**: `prompts/_base/shot_staging/5.202604141200/system.md`

**출력**:
- camera_direction: 카메라 위치/앵글/프레이밍 (영어 상세)
- lighting_mood: 조명/색감 (영어 상세)
- perspective: observer/subjective_pov/over_shoulder
- pov_character: POV 인물 (1인칭 시점 시)
- perception_mode: direct/through_device/hallucination/dream/memory/reflection
- character_angles: [{character, angle, body_pose, gaze_target}]
- key_bg_elements: [{element, state, camera_use, orientation}]

**gaze_target 특수값**: dead, severely_injured, unconscious, closed

**프레임 점유 제한**: 비인간 물체 40% 이상 금지

---

### beat_extract — Beat 추출

**위치**: `prompts/_base/beat_extract/{version}/system.md`

**역할**: 씬 내 상태 변화 감지
- 각 beat: title, change_type, before_state, after_state, key_entities
- change_type: arrival, departure, revelation, conflict, death, transformation 등

---

### shot_extract — Shot 추출

**위치**: `prompts/_base/shot_extract/{version}/system.md`

**역할**: beat를 스틸 이미지 단위로 분해
- 순차 처리: 이전 shot 결과 참조하여 중복 방지
- 인물 제약: entity_character_list 기반

---

### character_state_variant — 상태 변형 참조 이미지

**위치**: `prompts/_base/character_state_variant/1.202604101200/system.md`

**템플릿 변수**: {state_type}, {character_name}, {character_description}, {state_description}
- Identity 보존 규칙
- 3:4 포트레이트, 단색 배경

---

### entity 관련 프롬프트

| 모듈 | 위치 | 핵심 |
|------|------|------|
| entity_all | entity_all/ | 인물/배경/소품 리스팅 (shot 기반) |
| entity_extract_v4 | entity_extract_v4/ | 상세 프로필 추출 |
| entity_filter | entity_filter/ | 저빈도 요소 필터링 |
| entity_relation | entity_relation/ | 변형 관계 감지 |
| scene_director | scene_director/ | V/A/H 분류 + primary_location |
| shot_director | shot_director/ | shot별 VE + variant 전환 |

---

## 프롬프트에서 코드로 주입되는 동적 섹션

scene_detail user_prompt에 코드가 주입하는 블록:

1. `[분석 대상 Shot]` — shot description + beat 정보
2. `[앞쪽 연관 Shot]` — shot_dependency 참조
3. `[중요 — 순간 고정]` — 단일 순간만 캡처 지시
4. `[교차 샷 고정 요소]` ★ NEW — scene_consistency fixed_elements (단어 단위 동일 복사 지시)
5. `[사용 가능한 엔티티]` — visible_entities 목록
6. `인물별 아웃룩 선택지` — outlook 매핑
7. `[촬영 감독(DP) 연출 지시]` — shot_staging 결과
8. `[배경 설계 참고]` — set_design 힌트
9. `[인물-카메라 각도 + 시선]` — character_angles
10. `[카메라 포커싱]` + `[조명/색감 판단]` — 자체 판단 지시
11. `[변형 관계 참고/주의]` — variant 처리
12. `[규칙]` — bare ID + outfit + variation 수