# Pipeline 개선 — 매칭 시스템 통합 (Redesign)

> **작성일**: 2026-04-28
> **목적**: 매칭 시스템 (V1~V4) 테스트 결과를 기존 design_agent pipeline 에 통합. AI 호출을 줄이고 결정론적 매칭 + 정밀한 공간 관리를 결합.
> **상태**: 설계 단계. 실행은 사용자 승인 후 단계적 진행.

---

## 1. 배경 / 문제의식

### 기존 pipeline 의 한계

| 문제 | 현황 |
|---|---|
| AI 호출 과다 | Stage 1A / 1B / 1B-ST / 1.7 / 1.8 / 2 / 4 — 5~6 회 호출 |
| Type A/B/B'/B'' 하드코딩 | 콘텐츠별 전용 코드 분기 (오답노트 #2 위반 우려) |
| 블록 catalog 50+ 개 vs 실제 사용 7.9% | Phase P 결과 — 다양성 부족 |
| 유령 블록 / overflow 출력 | Phase Q 에서 일부 해결 |

### 매칭 시스템 (V1~V4) 테스트 결과

`tests/matching/` 에서 별도 검증한 결과:

| 항목 | 결과 |
|---|---|
| TARGET 정답률 | 3/4 (75%) — Logistic Regression 가중치 학습 + LOOCV 4/4 검증 |
| BM25 / IDF 비교 | 현 방식 우위 (4/4 vs 3/4) |
| V4 slot 축 ablation | Top-1 매칭 7/7 동일 — slot 축 frame 선별 무영향 확인 |
| 발견된 약점 | 8 가지 (`tests/PROGRESS.md` 참조) |

### 통합 필요성

매칭 시스템이 **콘텐츠 분석 / 디자인 추천** 부분을 코드로 대체 가능함을 확인. 단, 1280×720 안 정밀 공간 관리는 매칭 시스템이 다루지 않으므로 기존 pipeline 의 공간 관리 로직 (`space_allocator`, `fit_verifier`, `slide_measurer`) 은 유지 필요.

→ **콘텐츠 분석은 매칭 시스템, 공간 관리는 기존 pipeline** 으로 책임 분리.

---

## 2. 영역 분리 — 3 가지

| 영역 | 무엇을 하나 | 누가 담당 |
|---|---|---|
| **A. 콘텐츠 분석 / 디자인 추천** | "이 MDX 콘텐츠에 어떤 디자인이 어울리나?" | **매칭 시스템 V1~V4 (신규)** |
| **B. 공간 관리 / 사이즈 조정** | "1280×720 안에 어떻게 끼워 넣나? overflow 안 나게?" | **기존 pipeline (유지)** |
| **C. HTML 생성 / 슬롯 채움** | "선택된 디자인에 MDX 텍스트를 어떻게 넣나?" | **기존 + V4 label 분기** |

### 핵심 원칙

- A 는 매칭 시스템으로 완전 대체 (AI 호출 줄임)
- B 는 절대 손대지 않음 (정밀한 공간 관리는 기존 로직이 검증됨)
- C 는 매칭 결과의 label 에 따라 분기 (코드 / AI 1회 / Sonnet 재구성)

---

## 3. 핵심 결정 사항 (확정)

### 3.1 처리 단위

```
MDX 1 파일 = 대목차 1개 = 슬라이드 1장
   └ 중목차들 = 슬라이드 안의 frame 들 (조합)
       └ 소목차들 = 더 작은 단위 frame 또는 슬롯
```

### 3.2 매칭 알고리즘 — 소→중→대 합치기 룰

```
[1단계] 모든 소목차에 V1~V4 매칭 시도
   각 소목차의 best frame 도출

[2단계] 같은 중목차 내 소목차 매칭이 비슷하면 → 중목차로 묶어서 다시 매칭
   더 큰 frame 단위로 합치기 가능한지 확인

[3단계] 중목차들이 비슷하면 → 대목차로 묶어서 매칭
   슬라이드 1장 전체를 1 frame 으로 처리 가능한지 확인

→ 가장 적합한 합치기 단위 + frame 조합 채택
```

### 3.3 레이아웃 프리셋

기존 design_agent 의 4 가지 Type 으로 시작:

| 프리셋 | 조건 | 비고 |
|---|---|---|
| Type A | 참조 자료 (용어 정의 등) 별도 존재 | 기존 그대로 유지 (오답노트 #7) |
| Type B | 본문 흐름만 | 기존 그대로 |
| Type B' | 카드형 + 표 | 기존 그대로 |
| Type B'' | 색상바 + 여백 분리 | 기존 그대로 |

→ 4 개로 시작. 운영하면서 부족하면 추가.

### 3.4 V4 label 분기

매칭 결과의 label 이 후속 작업 비용을 결정:

| label | confidence | 후속 작업 | 비용 |
|---|---|---|---|
| use_as_is | ≥ 0.90 | 슬롯에 텍스트만 매핑 | 자동, AI 0회 |
| light_edit | ≥ 0.75 | AI 가 슬롯 텍스트 다듬기 | AI 1회 |
| restructure | ≥ 0.60 | 가장 유사 frame 참고 + Sonnet 변형 | 사람 + AI |
| reject | < 0.60 | 대안 frame 시도 → 그래도 안 되면 유사 frame 참고 | 사람 + AI |

### 3.5 자유 HTML 생성 금지

→ 항상 frame DB 의 어떤 frame 을 참고하여 생성. Phase R' 식 자유 디자인은 X.

### 3.6 텍스트 원문 보존 원칙 (절대 룰)

> **슬라이드 본문은 preview / 요약 가능하지만, MDX 원문은 popup / detail 에 무손실 보존한다.**

- 슬라이드 본문에 표시되는 것 = 일부 / 핵심 / preview 가능
- 단, 원문이 잘리거나 사라지지 않음 — 항상 팝업 / "자세히 보기" 에 무손실 저장
- "텍스트 압축 / trim / restructure" 같은 처리 금지 (오답노트 #5 준수)
- 안 들어가면 슬라이드를 키우는 게 아니라 → 본문은 preview, 팝업에 원문 보존
- AI 가 텍스트를 "줄여서 채워 넣지" 않는다 — preview 로 가공 후, 원문은 detail 에 보존

### 3.7 팝업 처리 룰

- MDX 에 팝업 콘텐츠 (`<details>`) 가 있으면 별도 보존
- 슬라이드 1장 룰 절대 유지 (2장으로 분리 X)
- 처리: **본문 요약 / 일부만 표시 + "자세히 보기" 클릭 → 팝업으로 전체**
- 전체를 팝업으로 빼는 것 X
- 팝업 콘텐츠도 MDX 원문 무손실 (3.6 원칙 적용)

---

## 4. 위계 + 용어 정리

### 4.1 슬라이드 위계

```
[ 슬라이드 ] 1280 × 720
   │
   ├─ slide-title         ← MDX 대목차 제목 (자동 매핑)
   ├─ slide-divider       (고정)
   │
   ├─ slide-body  ≈ 1200 × 590   ─ ★ 여기에 콘텐츠
   │     │
   │     └─ 레이아웃 (Type A / B / B' / B'')
   │           │
   │           └─ Zone  (top / bottom_l / bottom_r 등)
   │                 │
   │                 └─ 프레임 (Figma 디자인)
   │
   └─ slide-footer        ← MDX 대목차 결론 (자동 매핑)
```

### 4.2 용어

| 용어 | 의미 | 단위 / 위치 |
|---|---|---|
| **슬라이드** | 1280×720 한 장 | 가장 큰 단위 |
| **slide-base** | 배경 + 제목 + 구분선 + 결론 pill (모든 슬라이드 공통 그릇) | `templates/blocks/slide-base.html` 고정 |
| **slide-body** | 본문 가용 영역 (≈ 1200×590) | slide-base 안 |
| **레이아웃 (Layout)** | Type A / B / B' / B'' (4 가지 프리셋) | slide-body 안 |
| **Zone (영역)** | 레이아웃이 결정한 콘텐츠 구역 (top / bottom 등) | 레이아웃 안 |
| **컨테이너 (Container)** | zone 의 px 명세 (코드 레벨 표현) | zone 의 구체화 |
| **프레임 (Frame)** | Figma 디자인 단위 (= 기존 "블록") | zone 안 |

### 4.3 MDX → 슬라이드 매핑

| MDX 위치 | 슬라이드 위치 |
|---|---|
| `# 대목차 제목` | `slide-title` |
| 본문 (`##` / `###` 중·소목차) | `slide-body` 안 — 레이아웃 / zone / 프레임 |
| `# 대목차 결론` (있을 시) | `slide-footer` |
| `<details>` 팝업 콘텐츠 | 슬라이드 위 별도 레이어 |

### 4.4 매칭 시스템 (V1~V4) 의 frame 단위 — 명확화

- 매칭 시스템에서 **frame 32 개를 슬라이드 1장 단위로 검증** 함 (예: Frame 18 = BIM/DX 비교 슬라이드 통째로)
- 새 흐름에서는 **frame = zone 안 디자인 단위**
- → frame DB 라벨링 재검토 필요 (사이즈 분류: "슬라이드 전체 / zone 1 개 / 작은 박스")
- 8.1 항목 (32 frame 사이즈 라벨링) 의 핵심 작업

---

## 5. 새 Pipeline Flow

```
═══════════════════════════════════════════════════════════════
[전처리 — 한 번만, 결과 캐싱]
═══════════════════════════════════════════════════════════════

T-0. Figma frame DB 구축
     · 각 frame 의 키워드 (핵심/세트/연관) 라벨링       ✅ 완료
     · 각 frame 의 구조 (layout, family, relation_type,
                         cardinality, content_affinity,
                         structure_intent, slots,
                         alternative_patterns) 라벨링    ✅ 완료
     · 각 frame 의 사이즈 비율 (전체 / 절반 / 1/3 / 박스)  ✅ 대체 완료 (Zone 적용 분류 — `docs/architecture/FRAME-INTEGRATION-MAP.md` 의 `zone_direct/adapt/extract/reference_only`)
     · 각 frame 의 스타일 / 시각 언어 인벤토리                ✅ 완료 (`docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md`)

T-1. (새 frame 추가 시) 자동 라벨링 룰
     · 새 Figma frame 입력 → V3 의 detect_mdx_v2_profile 로 자동 감지
     · 사람이 검수 후 DB 추가

T-2. 레이아웃 프리셋 정의 (4 개)
     · 각 프리셋의 grid / area 정의
     · 어떤 frame 사이즈 조합에 어울리나 메타 정보

═══════════════════════════════════════════════════════════════
[실행 — MDX 1 파일 처리 = 슬라이드 1 장 생성]
═══════════════════════════════════════════════════════════════

STAGE 1)  MDX 분석 + 레이아웃 매칭                         [코드]
          · MDX 정규화 + 외부 컴포넌트 인라인 (Phase Y)
          · 팝업 콘텐츠 (<details>) 별도 보존
          · 대 / 중 / 소목차 트리 추출
          · 콘텐츠 성격 분석 (V3 의 detect_mdx_v2_profile)
          · 4 가지 레이아웃 (Type A / B / B' / B'') 중 1 개 결정
          · MDX 대목차 제목 → slide-title
          · MDX 대목차 결론 → slide-footer

STAGE 2)  Zone 별 텍스트 1 차 배치                         [코드]
          · 레이아웃이 결정한 zone 들에 콘텐츠 분배
          · 어떤 중 / 소목차가 어떤 zone 에 갈지 결정
          · 컨테이너 (zone 의 px) 계산 — space_allocator.py

STAGE 3)  Zone 별 프레임 매칭 (V1~V4 매칭 시스템)           [코드 + label 분기 AI]
          ┌──────────────────────────────────────────────┐
          │ 각 zone 의 콘텐츠와 Figma 프레임 DB 매칭      │
          │ V1 키워드 → V2 의미 → V3 구조 → V4 종합 판정 │
          │                                                │
          │ 매칭 결과 분기:                                │
          │   ├ 매칭 완벽 (use_as_is)   → 텍스트 업데이트 │
          │   ├ 매칭 어정쩡 (light_edit │
          │   │            / restructure) → 디자인 참고   │
          │   │              재구성 (Sonnet)              │
          │   └ 매칭 안 됨 (reject)    → 디자인 컨셉      │
          │                              바탕 재구성       │
          │                                                │
          │ 자유 디자인 금지 — 항상 프레임 DB 참고        │
          └──────────────────────────────────────────────┘

STAGE 4)  프레임 내용 검토 + 컨테이너 조정                 [코드 + AI fallback]
          · zone 별 검증 (넘침 / 공란 / 적정 / 불균형)
          · 보정:
              ├ 넘침   → 본문 미리보기 + "자세히 보기" 팝업
              │           (MDX 원문 절대 줄이지 않음 — 3.6 원칙)
              ├ 공란   → MDX 팝업 콘텐츠 있으면 일부 끌어옴
              ├ 적정   → 그대로
              └ 불균형 → 레이아웃 자체 부적절 → STAGE 1 회귀
                         (5 차 Fallback — 6 장 참조)

STAGE 5)  HTML 조립 + 검증 + 출력                          [코드 + AI]
          · slide-base.html (배경 + 제목 + 구분선 + 결론 pill)
              + slide-body 안 (레이아웃 + zone + 프레임)
              + slide-title / slide-footer 채움
              + 팝업 레이어
          · Jinja2 렌더링
          · 실측 검증 (Selenium) — 넘침 차단
          · 시각 검증 (Vision — Opus) — 품질 평가
          · final.html 출력
```

---

## 6. 컨테이너 검증 + Fallback 룰 (STAGE 4 상세)

### 6.1 검증 케이스 분류

```
[모든 컨테이너 검증 결과 종합]

케이스 1) 모두 적정
   → 다음 단계 진행

케이스 2) 일부 Overflow + 나머지 적정
   → 본문 요약 + "자세히 보기" 팝업 처리

케이스 3) 일부 Underflow (특정 컨테이너만 공란) + 나머지 정상
   ❗ 레이아웃 잘못 → STAGE 1 회귀 (레이아웃 재선택)

케이스 4) 일부 Overflow + 일부 Underflow 동시
   ❗ 레이아웃 잘못 (불균형) → STAGE 1 회귀 (레이아웃 재선택)

케이스 5) 모두 Underflow + 채울 콘텐츠 없음
   ✅ 공란 허용 (콘텐츠 자체가 적은 슬라이드)
```

### 6.2 5 차 Fallback (불균형 검출 시)

```
[1차] 매칭 → 적합 프리셋 → 검증
   OK → 종료
   불균형 → 2차

[2차] 다른 프리셋 시도 (예: Type B → Type B')
   또는 frame 합치기 단위 변경 (소→중 또는 중→대)
   OK → 종료
   불균형 → 3차

[3차] 매칭 결과 자체 변경 (Top-1 → Top-2 frame)
   OK → 종료
   불균형 → 4차

[4차] AI 콘텐츠 조정 의뢰 (Sonnet 1회)
   현재 매칭된 frame / zone / container 는 유지한 채,
   zone 안 콘텐츠 분량과 슬롯 매핑만 AI 로 조정한다.
     · 긴 텍스트 → 본문 preview + 팝업 원문 분리 제안
     · 슬롯 의미 매핑 미세 조정
     · 불필요한 반복 표현을 preview 에서 정리
     · 원문은 popup / detail 에 무손실 보존
   ⚠️ AI 는 zone 안 콘텐츠만 조정한다.
   ⚠️ 레이아웃 / 프리셋 / 새 frame 결정 / HTML 구조 생성은 코드만 수행한다.
   OK → 종료
   안 되면 → 5차

[5차] 단일 프리셋 강제 (Type A 또는 가장 큰 frame 만 사용)
   나머지 콘텐츠 → "자세히 보기" 팝업
   OK → 종료
   그래도 안 되면 → 사람 개입 알림
```

### 6.3 Fallback 단계별 비율 추정

| 단계 | 종료 비율 (가설) | 비용 |
|---|---|---|
| 1차 | 80%+ | 낮음 (코드만) |
| 2~3차 | 15% | 낮음 (코드만) |
| 4차 (AI) | 4% | 중간 |
| 5차 (단일 + 팝업) | 1% 이하 | 낮음 |
| 사람 개입 | 매우 드물게 | 최후 수단 |

→ 실제 비율은 MDX 데이터로 검증 필요. 일단 가설.

---

## 7. 단계적 진행 계획

### Phase Z-0 — 매칭 시스템 (✅ 완료)

```
✅ V1~V4 매칭 시스템 구축
✅ 32 frame 키워드 + 구조 라벨링
✅ TARGET 3/4 정답
✅ 보고서 (DECK 1~7)
```

### Phase Z-1 사전 작업 — 진행 중

```
✅ 완료 (2026-04-28)
  · Frame Integration Map (32 frame Zone 적용 분류)
    → docs/architecture/FRAME-INTEGRATION-MAP.md
  · Frame Style Inventory (32 frame + 18 token + 6 legacy)
    → docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md

⬜ 미진행 (Phase Z-1 본격 진입 전)
  · catalog / runtime 설계 prep
  · slide-base 검증

⚠️ 미실행 / 의도적으로 보류 (승인 전)
  · 기존 templates/blocks 삭제 / 교체
  · catalog / runtime 구현
  · templates/styles/frame-patterns 신규 파일 생성
  · 새 token (gap_candidate) 추가
```

### Phase Z-1 — 통합 prototype (본격)

```
[목표] MDX 03 (회귀 기준) 으로 매칭 시스템 + 기존 pipeline 통합 검증

작업:
  · Stage 1.7 (블록 선택) 만 V4 로 교체
  · 32 frame ↔ Type B/B'/B'' 매핑 테이블 작성
  · MDX 03 결과 기존과 비교 (회귀 통과)

완료 기준:
  · MDX 03 기존 결과 대비 overflow 없음
  · 텍스트 누락 없음 (MDX 원문 무손실 보존, 3.6 원칙)
  · AI 호출 수 감소 (Stage 1.7 의 Kei 1회 제거)
  · 옵션 플래그 off 시 동일 경로 복귀 (회귀 방지)

리스크: 낮음 (한 곳만 교체)
산출물: 매칭 시스템이 기존 pipeline 안에서 작동 확인
```

### Phase Z-2 — 매칭 + 프리셋 통합

```
[목표] Type A/B/B'/B'' 프리셋과 매칭 결과 연결

작업:
  · 매칭 결과 → 4 프리셋 중 1 개 자동 선택 룰
  · 합치기 룰 (소→중→대) 구현
  · MDX 02, 01 적용 검증

완료 기준:
  · MDX 03 / 02 / 01 모두 매칭 + 프리셋 자동 선택 작동
  · 합치기 룰이 소목차 → 중목차 → 대목차 순서로 작동
  · MDX 원문 무손실 유지 (3.6 원칙)

리스크: 중간
산출물: MDX 03/02/01 모두 매칭 + 프리셋 자동
```

### Phase Z-3 — 컨테이너 검증 + Fallback

```
[목표] 컨테이너 별 검증 + 5 차 Fallback 로직

작업:
  · 불균형 검출 룰 (Overflow / Underflow / 동시)
  · STAGE 4 의 1~5 차 Fallback 단계 구현
  · 팝업 처리 룰 (안 들어가면 자세히 보기)

완료 기준:
  · 컨테이너 별 검증 (Overflow / Underflow / 불균형) 작동
  · Fallback 5 차 단계 작동 (각 단계 독립 검증)
  · 팝업 처리 — preview 본문 + 무손실 팝업

리스크: 중간 ~ 높음
산출물: 안정적 자동 처리
```

### Phase Z-4 — 전체 통합 + 검증

```
[목표] 새 pipeline 으로 모든 MDX 처리 + 회귀 확인

작업:
  · MDX 03 / 02 / 01 회귀
  · Selenium + Vision 검증
  · AI 호출 수 / 처리 시간 측정

완료 기준:
  · MDX 03 / 02 / 01 모두 새 pipeline 통과
  · Vision 품질 평가 합격
  · AI 호출 수 / 처리 시간 기존 대비 감소

산출물: 새 pipeline 완성
```

---

## 8. 검토 / 결정 필요한 항목

### 8.1 32 frame 의 사이즈 라벨링

frame DB 에 "이 frame 은 슬라이드 전체 / 위 절반 / 좌측 1/3 / 작은 박스" 같은 사이즈 분류 필요.

| 옵션 | 방법 |
|---|---|
| (a) 사용자 직접 분류 | 정확하지만 시간 소요 |
| (b) Figma 캔버스 사이즈 자동 추정 | 빠르지만 부정확 가능 |
| (c) 매칭 시스템의 기존 라벨 (layout) 활용 + 보완 | 절충 |

→ **추천 (c)** : 기존 layout 라벨 (compare-rows / table-2col / cards-3col 등) 을 사이즈 라벨에 매핑하는 룰 작성.

### 8.2 프리셋 자동 선택 룰

frame 들의 사이즈 / 개수 → 4 프리셋 중 1 개 선택하는 룰.

예시:
- frame 1 개 + 사이즈 = 슬라이드 전체 → Type A 또는 Type B 단일
- frame 2 개 + 사이즈 = 위/아래 절반 → Type B (상단 + 하단)
- frame 2 개 + 사이즈 = 좌/우 절반 → Type A (사이드바)

### 8.3 합치기 룰 종료 조건

소→중→대 합치기 룰에서 어디까지 합칠지 결정:
- 소목차 매칭 결과가 "비슷" 하다는 기준은?
- 같은 frame_id ? 같은 layout family ? V4 axes 일부 일치 ?

### 8.4 슬롯 매핑 — 코드 + AI 하이브리드 비율

- 어디까지 코드 휴리스틱? (제목 → title 같은 명확한 것)
- 어디부터 AI? (의미 매핑 / 사이즈 조정 / 텍스트 다듬기)

---

## 9. 회귀 방지 / 안전 원칙

### 9.1 기존 작동 코드 보존

- **Type A 코드** (오답노트 #7) — 절대 건드리지 않음
- **공간 관리 로직** (`space_allocator`, `fit_verifier`, `slide_measurer`) — 그대로 유지
- **Phase Y 진행 중 작업** — MDX 외부 컴포넌트 처리 그대로

### 9.2 회귀 검증

- 단계마다 **MDX 03 (회귀 기준)** 결과 기존과 비교
- 변경 전 / 변경 후 다음 항목 측정:
  - 최종 HTML 의 시각 결과 (스크린샷 비교)
  - AI 호출 수
  - 처리 시간
  - overflow 발생 여부

### 9.3 옵션 플래그 도입

```
USE_MATCHING_SYSTEM = False  # 기본값
```

- 새 기능은 플래그로 도입
- 문제 발생 시 즉시 기존 경로로 fallback
- 안정화 후 기본값 True

### 9.4 핵심 원칙 (오답노트.md 준수)

- **거짓말 금지** — 못 하면 못 한다고 명시
- **하드코딩 금지** — 결과물 고치지 말고 프로세스 고침
- **검증 없이 넘어가지 마라** — 단계마다 실측 + 회귀
- **텍스트 원문 무손실 보존** — 슬라이드 본문은 preview / 일부만 표시 가능, MDX 원문은 팝업 / detail 에 무손실 보존 (3.6 원칙)
- **프로세스 만들어라** — 매번 사고하여 판단 (AI 든 코드든)

---

## 10. 참고 문서

### 우선순위 — 충돌 시 어느 문서가 최신인가

**매칭 시스템 관련**:
- ✅ 최신 기준 = `tests/PIPELINE.md` (V1~V4 통합 정리)
- ⚠️ `tests/matching/CURRENT_STATUS.md` 등 옛 문서는 **과거 기록 (참조 X)**
- 옛 문서에 "V2/V3/V4 미완료" 로 적혀 있어도 무시. 실제는 모두 완료.

**design_agent 전체**:
- ✅ 최신 기준 = `PIPELINE.md` + 이 문서 (`IMPROVEMENT-REDESIGN.md`)
- ⚠️ `ARCHITECTURE_OVERVIEW.md` 는 **deprecated** (2026-03-27 스냅샷, Type A/B 분기 등 미반영)

### 매칭 시스템 (V1~V4)

| 문서 | 위치 |
|---|---|
| 매칭 시스템 V1~V4 통합 정리 | `tests/PIPELINE.md` |
| 매칭 시스템 진행 / 약점 | `tests/PROGRESS.md` |
| 매칭 시스템 단계별 계획 | `tests/PLAN.md` |
| 매칭 시스템 코드 + 결과 + 보고서 | `tests/pipeline/` |
| 매칭 시스템 원본 (보존) | `tests/matching/` |

### 기존 design_agent

| 문서 | 위치 |
|---|---|
| 현재 pipeline 흐름 | `PIPELINE.md` |
| 전체 Phase 이력 | `PROGRESS.md` |
| 단계별 계획 | `PLAN.md` |
| 절대 원칙 | `오답노트.md` |
| 프로젝트 규칙 | `CLAUDE.md` |
| README | `README.md` |

### 보고서 (임원 보고용)

| 문서 | 위치 |
|---|---|
| DECK 1~7 (TARGET / Holdout / 방법 / DB / 키워드) | `tests/pipeline/reports/DECK_*.html` |

---

## 11. 리스크 + 대응 방안

설계안에서 실행계획으로 넘어갈 때 고려해야 할 리스크.

| # | 리스크 | 대응 방안 |
|---|---|---|
| 1 | **V4 가 디자인 적합성은 보지만 공간 적합성은 보지 않음** | 기존 공간 관리 (B 영역, `space_allocator` / `fit_verifier`) 그대로 유지. STAGE 4 컨테이너 검증으로 보완. V4 confidence 와 별개로 컨테이너 단위 overflow / underflow 측정 |
| 2 | **slot 의미 매핑 부재** (BIM → col_a_label 같은 매핑 없음) | STAGE 3 (zone 별 프레임 매칭) 의 슬롯 매핑에 AI 1회 호출 (Sonnet). 또는 frame DB 에 매핑 룰 사전 정의. 매칭 시스템의 slot 축 ablation 결과 — 이 영역은 별도 작업 필요 |
| 3 | **32 frame DB 의 사이즈 라벨 부족** | 8.1 항목 결정 후 라벨링 작업 (사용자 직접 또는 매칭 시스템의 layout 라벨 활용). Phase Z-1 시작 전 완료 필요 |
| 4 | **기존 Type B'/B'' 하드코딩 관성 재발 위험** | 4 프리셋 안에서만 조합. 새 콘텐츠별 전용 코드 절대 금지 (오답노트 #2). 새 변형 필요 시 — 코드 분기 추가 X, frame DB 또는 프리셋 추가로 해결 |
| 5 | **보고서용 매칭 성능 ≠ 실제 렌더 품질** | TARGET 3/4 정답률은 매칭 단독 성능. 실제 슬라이드 품질은 Phase Z-1 ~ Z-4 단계마다 MDX 03 실 렌더 + Vision 평가 회귀 |
| 6 | **MDX 분석 키워드 사전의 부정확성** (V3) | Hybrid 룰 — 코드 자동 + Kei fallback (신뢰도 낮을 때). 또는 추후 LLM 분석으로 교체 (`tests/PROGRESS.md` 의 Phase E.1, E.2) |
| 7 | **합치기 룰 (소→중→대) 무한 재시도 위험** | Fallback 5 차로 명확히 종료 (STAGE 4). 각 단계 최대 1 회 시도. 5 차 후엔 사람 개입 알림 |
| 8 | **매칭 시스템의 02-2.2 매칭 실패 사례** | 매칭 시스템 자체 약점 (`tests/PROGRESS.md` 약점 #1). Phase Z-1 진행 전 frame 14 의 anchor_sets 재라벨링 필요 (사전 작업) |

---

## 다음 단계

1. **이 문서 검토** — 사용자 + 협업자
2. **검토 사항 (7장) 결정** — 4 가지 항목
3. **리스크 대응 (11장) 사전 작업** — 32 frame 사이즈 라벨링 + frame 14 재라벨링
4. **Phase Z-1 시작** — 통합 prototype
5. **단계별 회귀 검증** — MDX 03 기준