diff --git a/CLAUDE.md b/CLAUDE.md index 6899924..807394e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,10 +12,89 @@ --- -## 아키텍처 (Phase Q 파이프라인) +## 위계 + 용어 (Phase Z 정리, 2026-04-28) + +> 매칭 시스템 (V1~V4) 통합 설계 시 정리. 상세는 [`IMPROVEMENT-REDESIGN.md`](IMPROVEMENT-REDESIGN.md) 4 장 참조. +> +> Phase Z 사전 작업 — Frame Zone 적용 분류 [`docs/architecture/FRAME-INTEGRATION-MAP.md`](docs/architecture/FRAME-INTEGRATION-MAP.md), Frame / Style / Token 인벤토리 [`docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md`](docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md). + +### 슬라이드 위계 + +``` +[ slide ] 1280×720 (전체 슬라이드) + │ + ├─ slide-title ← MDX 대목차 제목 (자동 매핑) + ├─ slide-divider (고정) + │ + ├─ slide-body ≈ 1200×590 (콘텐츠 영역 — `templates/blocks/slide-base.html`) + │ │ + │ └─ 레이아웃 (8-preset layout vocabulary; legacy hint = Type A/B/B'/B'') + │ │ + │ └─ Zone (top / bottom_l / bottom_r 등) + │ │ + │ └─ 프레임 (Figma 디자인 단위) + │ + └─ slide-footer ← MDX 대목차 결론 (자동 매핑) +``` + +### 용어 + +| 용어 | 의미 | +|---|---| +| **슬라이드** | 1280×720 한 장 | +| **slide-base** | 모든 슬라이드 공통 그릇 (배경 + 제목 + 구분선 + 결론 pill) — `templates/blocks/slide-base.html` | +| **slide-body** | 본문 가용 영역 (≈ 1200×590) | +| **레이아웃 (Layout)** | 8-preset layout vocabulary — slide-body 안 zone 분배 형태 (legacy hint = Type A/B/B'/B'') | +| **Zone (영역)** | 레이아웃이 결정한 콘텐츠 구역 | +| **Internal Region** | Zone 안의 placement / planning unit (Layer A) — content_object 를 배치하는 내부 영역 (SPEC v1 §2) | +| **컨테이너 (Container)** | zone 의 px 명세 (코드 레벨) | +| **프레임 (Frame)** | Figma 디자인 단위 (= 기존 "블록") — zone 안 | +| **Frame Slot** | Frame 안의 declared placement slot (Layer B) — frame contract 가 선언하는 콘텐츠 placement target (SPEC v1 §3) | +| **Layer A** | composition planning 의 zone-내 layer — content_object 를 Internal Region 으로 배치하는 단위 (SPEC v1 §1~§2) | +| **Layer B** | frame contract 기반 frame-내 layer — 콘텐츠 매핑 대상인 Frame Slot 구조를 선언하는 단위 (SPEC v1 §3) | + +### MDX → 슬라이드 매핑 + +| MDX 위치 | 슬라이드 위치 | +|---|---| +| `# 대목차 제목` | `slide-title` | +| 본문 (`##` / `###`) | `slide-body` 안 (레이아웃 + zone + 프레임) | +| `# 대목차 결론` | `slide-footer` | +| `
` 팝업 | 슬라이드 위 별도 레이어 | + +Layer A planning telemetry is active in trace-only mode; render path activation remains the next axis. + +--- + +## 아키텍처 — Phase Z 흐름 (5 단계) + +> 상세는 [`IMPROVEMENT-REDESIGN.md`](IMPROVEMENT-REDESIGN.md) 5 장 참조. + +``` +STAGE 1) MDX 분석 + 레이아웃 매칭 (8-preset layout vocabulary; legacy = Type A/B/B'/B'') +STAGE 2) Zone 별 텍스트 1차 배치 +STAGE 3) Zone 별 프레임 매칭 (V1~V4; B4 frame_selection evidence integration pending) + ├ 매칭 완벽 → 텍스트 업데이트 + ├ 매칭 어정쩡 → 디자인 참고 재구성 + └ 매칭 안 됨 → 디자인 컨셉 바탕 재구성 +STAGE 4) 프레임 검토 + 컨테이너 조정 (5 차 Fallback) +STAGE 5) HTML 조립 + 검증 + 출력 +``` + +핵심 원칙 : +- **MDX 1 파일 = 슬라이드 1 장** (절대 분할 X) +- **텍스트 원문 무손실 보존** (본문 미리보기 + 팝업 원문) +- **자유 디자인 금지** (항상 Figma 프레임 DB 참고) +- **불일치 시 레이아웃 회귀** (콘텐츠 줄이지 않고 그릇 변경) + +--- + +## 아키텍처 (Phase Q 파이프라인 — 기존) > Phase P(다후보 렌더링 비교) 실행 결과 20/100점. 업계 조사(Beautiful.ai, Napkin.ai, VASCAR 등) 기반으로 Phase Q에서 재설계. > 핵심 전환: "계산 먼저, AI 판단 나중에, 렌더링은 검증만" +> +> ⚠️ Phase Z (매칭 시스템 통합) 진행 후 이 섹션의 일부는 새 흐름으로 대체될 예정. ``` [1단계] Kei 실장 (Opus) — AI 사고 @@ -65,30 +144,48 @@ reference 꼭지 있음 → sidebar-right 나머지 → single-column ``` -### 역할 분리 (Phase R') +### 역할 분리 (Phase Z) + +> ⚠️ Phase R' 의 역할 분리 (AI 가 HTML 구조 직접 생성) 는 **Phase Z 에서 폐기**. 아래는 Phase Z 기준. | 역할 | 담당 | 방식 | 하는 일 | 하지 않는 일 | |------|------|------|---------|------------| -| Kei 실장 | Opus (Kei API) | AI | 꼭지 추출, 비중 판단, relation_type + expression_hint 부여, 최종 검수 | HTML 생성, 레이아웃 계산 | -| 컨테이너 계산 | 코드 | 결정론적 | Kei 비중 → 역할별 컨테이너 px 확정 | AI 판단 불필요 | -| 프리셋 선택 | 코드 | 규칙 | 실장의 role에 따라 프리셋 자동 선택 | AI 판단 불필요 | -| **HTML 생성** | **AI (Kei API)** | **AI** | **콘텐츠 전달 의도에 맞는 HTML 구조를 직접 생성. 블록 CSS를 참고하되 구조는 AI가 결정.** | 블록 "선택" 안 함. 슬롯 "채우기" 안 함. | -| 검증 | 코드 + AI | Selenium + 비전 모델 | overflow 측정, 시각 품질 평가 | | +| Kei 실장 | Opus (Kei API) | AI | MDX 본문 분석 보조, 최종 검수 | HTML 생성, 레이아웃 계산 | +| 레이아웃 결정 | 코드 | 룰 매칭 | MDX 콘텐츠 → 8-preset layout vocabulary 기반 slide/zone topology 선택 (legacy hint = Type A/B/B'/B'') | — | +| 컨테이너 계산 | 코드 | 결정론적 | zone 별 px 확정 (`space_allocator`) | — | +| 프레임 매칭 | 코드 (V1~V4; B4 frame_selection evidence integration pending) | 결정론적 | zone ↔ Figma 프레임 매칭 | — | +| **콘텐츠 매핑** | **코드 + AI** | **하이브리드** | **zone 안 콘텐츠 / 텍스트를 프레임 슬롯에 배치 / 다듬기 / 변형** | **HTML 구조 생성 X** | +| HTML 조립 | 코드 (Jinja2) | 결정론적 | `slide-base` + 프레임 + 슬롯 콘텐츠 합쳐서 final.html | AI 호출 X | +| 검증 | 코드 + AI | Selenium + Vision | overflow 측정, 시각 품질 평가 | — | -### HTML 생성 원칙 (Phase R') +### HTML 생성 원칙 (Phase Z) ``` -블록이 구조를 결정 (P=Q=R, 실패) → 콘텐츠가 구조를 결정 (R', 접근 C) +블록이 구조를 결정 (P=Q=R, 실패) +콘텐츠가 구조를 결정 (R', 폐기 — AI 가 HTML 직접 생성하면 회귀 가능성 큼) +→ slide-base + 프레임 DB 가 구조를 결정, AI 는 zone 안 콘텐츠만 (Phase Z) ``` -- AI가 콘텐츠 전달 의도(expression_hint)에 맞는 HTML 구조를 직접 생성 -- 기존 38개 블록의 CSS(색상, 폰트, 배경, radius)를 **스타일 참고**로 활용 -- 블록을 **"선택"하지 않음**. topic 합침/분리, 포함 관계, 핵심 메시지 분리 가능 -- 디자인 토큰(CSS 변수)으로 품질 제약 + Selenium 측정 + 비전 모델 검증 +**Phase Z 의 핵심 원칙**: +- **HTML 구조** = `slide-base.html` + 코드 (Jinja2) 가 결정 (절대 AI 가 생성 X) +- **AI 의 역할** = zone 안 콘텐츠 매핑 / 텍스트 다듬기 / 디자인 변형 (콘텐츠 단위) +- **프레임 DB 참고 필수** — 자유 디자인 금지 +- **MDX 원문 무손실 보존** (본문 preview, 팝업에 원문) + +⚠️ **Phase R' 회귀 방지**: AI 한테 "HTML 구조 만들어줘" 같은 호출 절대 X. AI 호출은 zone 안 콘텐츠 단위로만. --- -## 핵심 프로세스 +## 핵심 프로세스 (구 Phase Q 기준 — Phase Z 에서 대체됨) + +> ⚠️ **아래 흐름은 구 Phase Q 기준의 5 단계 (Kei 실장 → 디자인 팀장 → 텍스트 편집자 → 디자인 실무자 → 재검토). Phase Z 에서 대체됨.** +> +> **신규 흐름은 위 "아키텍처 — Phase Z 흐름 (5 단계)" 섹션 또는 [IMPROVEMENT-REDESIGN.md](IMPROVEMENT-REDESIGN.md) 5 장 따름.** +> +> ⚠️ **특히 Phase Z 와 충돌하므로 무시할 것**: +> - "페이지 분리" → Phase Z: MDX 1 파일 = 슬라이드 1 장 (절대 분할 X) +> - "텍스트 압축 / 요약" → Phase Z: MDX 원문 무손실 보존 (본문 preview, 팝업 원문) +> - "AI 5 단계" → Phase Z: AI 호출은 zone 안 콘텐츠 단위로만 (HTML 구조 / 레이아웃 / 프리셋 결정 X) ``` 사용자 콘텐츠 입력 (텍스트/MDX 붙여넣기 또는 파일 업로드)