# Phase H: 스토리라인 설계 기반 파이프라인 전환 — 실행 상세

> "꼭지 추출 → 블록 매칭"에서 "스토리라인 설계 → 목적 기반 배치 → 원본 보존 편집"으로 전환.
> 코드 구조 변경 없음. 프롬프트 3개만 수정. 하류 호환 유지 (topics 구조 동일).
> 원칙: 하드코딩 금지. 원본 텍스트 최대 보존. 회귀 금지.

---

## 문제 진단

### 문제 1: 1단계가 "꼭지 추출"만 함 — 스토리라인 설계 없음

현재 KEI_PROMPT: "본문에서 핵심 꼭지 2~5개를 추출해줘"
- 꼭지가 개별 덩어리로 나옴
- 각 꼭지가 슬라이드 안에서 왜 그 위치에 있어야 하는지 맥락 없음
- 결과: 제목 중복, 빈 블록, 맥락 없는 배치

있어야 하는 것:
```
핵심 메시지: "BIM은 DX의 일부분이다"
스토리 흐름:
  (1) 문제 제기 → (2) 근거/사례 → (3) 핵심 전달 → (4) 용어 정의 → (5) 결론
```

### 문제 2: 3단계 편집자가 텍스트를 과도하게 재작성

현재 EDITOR_PROMPT: "세련된 표현으로 편집한다"
- 원본이 이미 충분히 정리된 텍스트인데 2줄로 압축
- description 슬롯을 비워둠
- 원본 분량 수준에서는 약간의 편집만 필요

### 문제 3: 2단계 팀장이 블록의 "목적"을 모름

현재: 꼭지 제목만 보고 블록 형태 매칭
- "용어 혼용 문제" → callout? quote? 무작위
- 블록의 목적(문제제기? 근거? 정의?)을 모르고 형태만 매칭

---

## H-1: KEI_PROMPT 재설계 — "꼭지 추출" → "스토리라인 설계"

### 현재 상태
```
"본문에서 핵심 꼭지 2~5개를 추출해줘"
→ topics: [{id, title, summary, layer, role, ...}]
```

### 변경
```
"이 콘텐츠로 슬라이드 1장을 만든다면 어떤 스토리로 구성할지 설계해줘"
```

프롬프트에 추가할 지시:
- **핵심 메시지**를 먼저 파악 (이 슬라이드가 전달해야 할 한 줄)
- **스토리 흐름**을 설계 (문제→근거→핵심→정의→결론)
- 각 위치의 **목적(purpose)** 명시 (문제제기/근거사례/핵심전달/용어정의/결론강조)
- 각 위치에 **원본의 어떤 부분**이 가는지 명시
- 원본 텍스트는 최대한 보존. 슬라이드에 맞게 약간만 편집.

출력 형식 (기존 topics 구조 유지 + 필드 추가):
```json
{
  "title": "건설산업 DX의 올바른 이해",
  "core_message": "BIM은 건설산업 DX의 기초 일부분이지 전체가 아니다",
  "total_pages": 1,
  "info_structure": "...",
  "topics": [
    {
      "id": 1,
      "title": "용어 혼용 문제",
      "summary": "DX와 BIM이 혼용되어 사용",
      "purpose": "문제제기",
      "source_hint": "용어의 혼용 섹션 전체",
      "layer": "intro",
      "role": "flow",
      ...
    }
  ]
}
```

### 하류 호환
- topics[] 배열 구조 동일 → 2단계/3단계 파싱 깨지지 않음
- purpose, core_message, source_hint는 새 필드 → `.get()`으로 접근하면 없어도 안전
- 기존 필드(layer, role, emphasis 등) 유지

### 수정 파일
- `src/kei_client.py` — KEI_PROMPT

---

## H-2: EDITOR_PROMPT 수정 — 원본 텍스트 최대 보존

### 현재 상태
```
"세련된 표현으로 편집한다 (원본 그대로가 아님)"
→ 과도한 요약/재작성. description 비움.
```

### 변경
```
"원본 텍스트를 최대한 보존한다.
슬라이드 공간에 맞게 약간만 축약한다.
의미를 바꾸거나 완전히 재작성하지 않는다.
각 블록의 purpose를 보고 해당 목적에 맞는 텍스트를 원본에서 가져온다.
모든 슬롯을 빠짐없이 채운다. 빈 슬롯 금지."
```

### 핵심 변경 포인트
- "세련된 표현으로 편집" → "원본 보존, 약간만 축약"
- "빈 슬롯 금지" 명시
- purpose 필드를 참고하여 "이 위치에 무엇이 들어가야 하는지" 맥락 제공

### 수정 파일
- `src/content_editor.py` — EDITOR_PROMPT

---

## H-3: STEP_B_PROMPT 보강 — purpose 기반 블록 선택 + 출력에 purpose 추가

### 현재 상태
```
"꼭지에 적합한 블록을 선택해줘"
→ 형태만 보고 매칭. 목적 모름.
→ 출력 JSON에 purpose 필드 없음.
```

### 변경 1: purpose 기반 블록 선택 가이드 추가
STEP_B_PROMPT의 "블록 선택 규칙" 섹션 뒤에 추가:

```
## purpose 기반 블록 선택 가이드 (참고, 강제 아님)
- purpose: 문제제기 → callout-warning, quote-big-mark, quote-question 중 선택
- purpose: 근거사례 → quote-left-border (출처 포함), card-text-grid (항목 나열)
- purpose: 핵심전달 → comparison-2col, compare-pill-pair, compare-2col-split
- purpose: 용어정의 → card-text-grid (정의+출처), card-numbered (순서 있으면)
- purpose: 결론강조 → conclusion-accent-bar (footer), banner-gradient
- purpose: 구조시각화 → venn-diagram, layer-diagram (단독 배치)
```

### 변경 2: 출력 JSON에 purpose 필드 추가
정밀 검토에서 발견: H-4에서 편집자에게 purpose를 전달하려면, Step B 출력에 purpose가 있어야 함.

```json
{"blocks": [{"area": "...", "type": "...", "topic_id": 1, "purpose": "문제제기", "reason": "...", ...}]}
```

### 하드코딩 점검
- purpose 가이드는 AI 참고용 추천. 강제 아님. Sonnet이 무시해도 기존과 동일 동작.
- purpose 값은 1단계 Kei가 결정한 것을 2단계 Sonnet이 참조. AI 판단 체인.

### 수정 파일
- `src/design_director.py` — STEP_B_PROMPT (가이드 추가 + 출력 형식에 purpose 추가)

---

## H-4: 3단계 편집자에게 purpose 전달

### 현재 상태
content_editor.py의 `fill_content()`에서 각 블록의 슬롯 정보는 전달하지만,
**이 블록이 왜 여기 있는지 (purpose)** 는 전달하지 않음.

### 변경
블록별 슬롯 요청 생성 시 purpose를 포함:

```python
req_text = (
    f"블록 {i+1} ({block_type}, 영역: {area}, topic_id: {topic_id}):\n"
    f"  목적(purpose): {block.get('purpose', '미지정')}\n"  # 추가
    f"  용도: {block.get('reason', '미지정')}\n"
    ...
)
```

### 수정 파일
- `src/content_editor.py` — `fill_content()` 내 slot_requirements 생성 부분

---

## 수정 파일 총괄

| 파일 | 항목 | 변경 성격 |
|------|------|----------|
| `src/kei_client.py` | H-1 | KEI_PROMPT 재설계 (스토리라인 설계) |
| `src/content_editor.py` | H-2, H-4 | EDITOR_PROMPT 수정 (원본 보존) + purpose 전달 |
| `src/design_director.py` | H-3 | STEP_B_PROMPT에 purpose 기반 블록 선택 가이드 추가 |

코드 구조 변경 없음. 프롬프트만 수정. persona_agent 수정 0건.

---

## 검증 체크리스트

- [ ] H-1: 1단계 출력에 core_message, purpose, source_hint 포함
- [ ] H-1: 기존 topics 구조 유지 (하류 깨지지 않음)
- [ ] H-2: 편집자가 원본 텍스트를 과도하게 축약하지 않음
- [ ] H-2: 모든 슬롯에 텍스트 채워짐 (빈 슬롯 0건)
- [ ] H-3: purpose에 맞는 블록 선택 (문제제기→경고계열, 정의→카드계열)
- [ ] H-4: 편집자가 각 블록의 purpose를 인지하고 적절한 텍스트 배치
- [ ] 전체: 슬라이드에 스토리 흐름이 있음 (문제→근거→핵심→정의→결론)

---

## 정밀 검토 결과

### 발견 사항

| # | 발견 | 대응 |
|---|------|------|
| 1 | H-4가 동작하려면 H-3의 JSON 출력에 purpose 필드 필요 | H-3에 출력 형식 수정 포함 (위에 반영) |
| 2 | "약간만 축약" 시 슬라이드 초과 가능 | 기존 안전망 유지 (4단계 CSS 조정 + 5단계 재검토) |
| 3 | core_message 현재 미활용 | Kei의 사고 과정 기록용. 향후 5단계에서 활용 가능 |

### 충돌/회귀/하드코딩 총괄

| 항목 | 충돌 | 회귀 | 하드코딩 | API | persona 수정 |
|------|:----:|:----:|:-------:|:---:|:----------:|
| H-1 | 없음 | 없음 | 없음 (Kei 사고) | Kei API | 없음 |
| H-2 | 없음 | 없음 | 없음 | Kei API | 없음 |
| H-3 | 없음 | 없음 | 가이드일 뿐 강제 아님 | Sonnet | 없음 |
| H-4 | 없음 | 없음 | 없음 | Kei API | 없음 |

---

## 수정 이력

| 날짜 | 내용 |
|------|------|
| 2026-03-26 | 초안. 스토리라인 설계 기반 전환. 프롬프트 3개 수정. |
| 2026-03-26 | 정밀 검토. H-3 출력 형식에 purpose 추가 필요 발견. 반영. |