C.E.L_Slide_test2/PROGRESS.md

Design Agent — 진행 상황

현재 상태 요약 (2026-04-01 기준)

상태	내용
완료	Phase 15 기반, AQ 개선, R(실패), S(설계), T 전체 완료
Phase T 결과	11 Step 완료 (T-0~T-10). 통합 테스트 31/31 통과. 신규 5파일, 수정 4파일+yaml
다음	실제 MDX + Kei API + Sonnet API로 end-to-end 실행. Phase ZZ는 파이프라인 안정화 이후

---

✅ 완성된 것

파이프라인 핵심

• 5단계 파이프라인 작동 (1A→1B→컨테이너계산→A-2→블록스펙→3→4→측정→5)
• Kei API 무한 재시도 (모든 Kei 호출. fallback 없음. 제한 없음)
• Step B(Sonnet 블록 매핑) 제거 — Kei(A-2) + 코드(Phase O)로 대체
• 죽은 코드 전면 정리 (STEP_B_PROMPT, _fallback_layout, PURPOSE_FALLBACK, DOWNGRADE_MAP, _downgrade_fallback, _apply_defaults, manual_classify)

블록/카탈로그

• 블록 라이브러리 38개 (6 카테고리)
• catalog.yaml 개선 완료 (when/not_for/purpose_fit)
• FAISS 인덱스 재빌드 완료 (bge-m3, 38블록)
• topic_id/id 양쪽 체크 버그 수정

레이아웃

• 프리셋 자동 선택 (sidebar-right, two-column, hero-detail, single-column)
• Kei 비중 시스템 (page_structure weight — 콘텐츠마다 동적)
• Phase O 컨테이너 스펙 계산 (calculate_container_specs)
• Phase O 블록 스펙 확정 (finalize_block_specs)
• 비중 기반 grid row 컨테이너 (renderer.py)

측정/검수

• Phase L Selenium 렌더링 측정 (scrollHeight/clientHeight)
• Phase N-4 스크린샷 캡처 (slide.screenshot_as_base64)
• Stage 5 Opus 멀티모달 검수

인프라

• 중간 산출물 추적 (data/runs/{timestamp}/)
• 실행 리포트 생성 (scripts/generate_run_report.py)
• SSE 스트리밍 유틸 (sse_utils.py)
• 이미지 크기 측정 + base64 삽입 (image_utils.py)

버그 수정 완료

• BF-1~BF-10: 전부 수정 완료 (SSE 파싱, Jinja2 변수, 한글, body 겹침, 제목, topic_id, 예산, grid, catalog 캐시)

---

✅ Phase P 실행 완료 + 결과 분석 (2026-03-27~28)

실행 결과

• 실행 데이터: data/runs/1774599277829/
• 최종 슬라이드 품질: 20/100점

발견된 근본 문제 5가지

#	근본 원인	증상
R1	FAISS 텍스트 임베딩이 시각 블록을 매칭하지 못함	"hierarchy" 관계인데 venn 대신 comparison-2col 선택
R2	Opus 추천에 catalog 검증 없음	존재하지 않는 블록 5개 환각 (arrow-flow, hierarchy-tree 등)
R3	overflow 해소 실패 시 출력 차단 없음	배경 117px에 330px 콘텐츠 → 겹침 상태로 출력
R4	블록 중복 사용 제한 없음	5개 topic에 3종류 블록만 사용 (38개 중 7.9%)
R5	공간 배분이 일방향	배경 20%에 topic 2개 강제 → card-numbered(205px)가 컨테이너(117px)에 안 맞음

Phase P 접근법의 구조적 한계

• 3후보 × 5topics = 15번 렌더링 + 15번 AI 호출 → ~40분 소요
• 15개 중 10개 폐기 (작업의 2/3 낭비)
• 업계 조사 결과, 다후보 렌더링 비교 방식은 어떤 상용/오픈소스 도구도 사용하지 않음
• 블록 유형 선택은 렌더링 전에 결정할 수 있는 문제 (콘텐츠 relation_type 기반)

업계 조사 결과 (2026-03-28)

접근법	대표 사례	핵심 원리
제약 기반 레이아웃 엔진	Beautiful.ai	AI는 콘텐츠만, 레이아웃은 규칙 엔진이 결정론적으로
템플릿 검색 + AI 커스터마이징	Canva	벡터 검색으로 템플릿 매칭, AI가 텍스트/색상만 교체
NLP 관계 유형 → 시각화 매핑	Napkin.ai	계층/비교/프로세스 감지 → 다이어그램 유형 자동 선택
시각적 자기교정	VASCAR (2024)	생성→렌더링→비전 모델 평가→개선, 훈련 불필요
참조 기반 학습	PPTAgent (EMNLP 2025)	기존 프레젠테이션에서 디자인 패턴 귀납적 학습

업계 합의: AI가 레이아웃을 직접 결정하면 안 된다. AI는 콘텐츠만, 레이아웃은 제약 엔진이 담당.

---

📋 Phase Q: 제약 기반 블록 선택 + 글자수 예산 시스템 (설계 확정)

상세: IMPROVEMENT-PHASE-Q.md

핵심 원칙: "계산 먼저, AI 판단 나중에, 렌더링은 검증만"

실행 스텝

스텝	내용	유형	파일	의존성	상태
Q-1	catalog.yaml 메타데이터 보강 (min_height_px, relation_types, category, min/max_items)	데이터	templates/catalog.yaml	✅ 완료
Q-2	relation_type → 블록 카테고리 결정론적 매핑 엔진	신규	src/block_selector.py	✅ 완료
Q-3	글자수 예산 계산 엔진	추가	src/space_allocator.py	✅ 완료
Q-4	Kei 블록 선택 프롬프트 재설계 (필터링된 2-3개만 제시)	수정	src/kei_client.py	✅ 완료
Q-5	pipeline.py 재구성 (Phase P 15-render → Phase Q 단일 경로)	수정	src/pipeline.py	✅ 완료
Q-6	비전 모델 품질 게이트 (VASCAR식)	신규	src/kei_client.py	✅ 완료
Q-7	overflow 수학적 조정 (LaTeX 글루 모델)	추가	src/space_allocator.py	✅ 완료
Q-8	출력 차단 정책 + P0 재시도 제한 (30회/300초)	추가	src/pipeline.py	✅ 완료

기대 효과

지표	Phase P	Phase Q 목표
슬라이드 품질	20/100	70-80/100
처리 시간	~40분	~8-12분
API 호출	~25회	~8회
유령 블록	5건 발생	불가능
overflow 출력	허용	차단

---

Phase 이력

Phase	내용	상태	비고
1~3	기반 구축 + 블록 템플릿 + AI 파이프라인	완료
4	UI + 출력	완료
5	블록 라이브러리 확장 (38개)	완료
A~D	슬라이드 품질 핵심	완료	일부 Phase O로 대체
G	Kei API 통신 정상화	완료
H	스토리라인 설계 기반 전환	완료
I	전수 정합성 복구 (14건)	완료
J	블록 선택 권한 재정의	완료	Step B 제거로 일부 무력화
K	purpose 기반 시각적 위계	완료
K-1	중간 산출물 저장	완료
L	Selenium 렌더링 측정	완료
M	Kei 비중 시스템	완료	Phase O로 교체
N	4대 핵심 문제 해결	완료
O	컨테이너 기반 레이아웃	완료	코드 + 미해결 3건 해결 + Step B 제거
P	다후보 렌더링 비교 선택	완료	실행됨. 결과 20/100점 → Phase Q로 방향 전환
Q	제약 기반 블록 선택 + 글자수 예산	코드 완료	Q-1~Q-8 구현 + fill_candidates 복원. 블록 선택 개선 확인
R	하이브리드 블록 시스템 (variant 추가)	실패	기존 블록 선택 구조 위에 패치만 추가. P=Q=R 동일 구조.
R'	접근 C: 블록 CSS 참고 + AI 구조 결정	설계	방향만 확정. Kei API HTML 생성 실패 확인.
S	검증 기반 확정 — Claude HTML 생성 + 검증된 프롬프트 규칙	설계 확정	영역별 검증 합격. Claude Sonnet 확정.
T	폰트 위계 + 파이프라인 기반 정비 + 디자인 레퍼런스	완료	11 Step 완료. 통합 테스트 31/31 통과.

---

❌ Phase R 실패 기록

Phase R은 접근 C로 가기로 합의했으나, 구현에서 기존 블록 선택 시스템 위에 variant 패치만 추가. P = Q = R: 세 개 다 "블록 선택 → 슬롯 채우기" 근본 구조가 동일. 결과물 34점. C_reference.png(70점) 수준에 전혀 도달 못함.

근본 원인: 기존 코드(block_selector, catalog, fill_candidates)를 유지하면서 최소 변경으로 해결하려는 관성.

---

📋 Phase R': 접근 C — 블록 CSS 참고 + AI 구조 결정 (설계 확정)

⚠️ Legacy — Phase Z 로 대체됨 (2026-04-28)

Phase R' 의 "AI 가 HTML 구조를 직접 생성" 흐름은 Phase Z 에서 다음과 같이 변경됨:

• HTML 구조 = slide-base.html + 코드 (Jinja2) 가 결정 (AI 가 생성하지 않음)
• AI 의 역할 = zone 안의 콘텐츠 / 텍스트 매핑 / 텍스트 다듬기 / 디자인 변형만
• 자유 디자인 금지 — 항상 Figma 프레임 DB 참고

아래 R' 설계 내용은 히스토리 / 참고용. 실제 구현은 IMPROVEMENT-REDESIGN.md 의 5 단계 흐름 따름.

상세: IMPROVEMENT-PHASE-R-PRIME.md

핵심 전환

P=Q=R (실패):  블록이 구조를 결정 → 콘텐츠를 슬롯에 채움
R' (접근 C):   콘텐츠가 구조를 결정 → 블록 CSS를 참고하여 HTML 생성

프로세스 변경

⚠️ 아래 표는 폐기된 Phase R' 기록이며 신규 구현 지시가 아니다. 새 구현은 IMPROVEMENT-REDESIGN.md 의 Phase Z 5 단계 흐름 따름.

단계	현재 (P=Q=R)	R' (접근 C)
1단계 Kei 분석	유지	유지
1.5단계 컨셉 구체화	유지	유지
컨테이너 계산	유지	유지
프리셋 선택	유지	유지
2단계	block_selector → 블록 선택	제거 → html_generator가 AI HTML 생성
3단계	fill_candidates → 슬롯 채우기	제거 → html_generator에 통합
4단계 렌더링	render_slide (블록 템플릿)	render_slide_from_html (AI HTML 삽입)
검증	Selenium + 비전 모델	유지

실행 스텝

스텝	내용	파일	상태
R'-1	디자인 토큰 + 블록 CSS 패턴을 프롬프트용 텍스트로 추출	신규 src/design_tokens.py	대기
R'-2	few-shot 예시 슬라이드 정리	data/examples/	대기
R'-3	AI HTML 생성 함수 구현	신규 src/html_generator.py	대기
R'-4	pipeline.py 2-3단계 교체 (블록 선택+채우기 → html_generator)	src/pipeline.py	대기
R'-5	렌더러에 AI HTML 삽입 함수 추가	src/renderer.py	대기
R'-6	HTML 정화 + 토큰 위반 검증	신규 src/html_validator.py	대기
R'-7	테스트 (2개 콘텐츠)	scripts/test_phase_r_prime.py	대기

회귀 방지 — 호출하면 안 되는 함수

• select_block_candidates() — 블록 선택 회귀
• fill_candidates() / fill_content() — 슬롯 채우기 회귀
• select_block_for_topics() — 블록 선택 AI 회귀
• finalize_block_specs() — 블록 스펙 회귀

합격 기준

C_reference.png와 동일 수준의 결과를 자동으로 생성:

• topic 합침 가능
• 포함 관계 시각화 가능
• 핵심 메시지 별도 강조 가능
• 원본 텍스트 보존 (자유도 15-20)
• 720px overflow 없음

---

Phase R' 이후 방향

• 디자인 참조 DB 구축 → 성공한 슬라이드를 few-shot으로 축적
• Playwright 마이그레이션 → 더 빠른 측정 + PDF 내보내기

---

Phase Z: 매칭 시스템 통합 설계 (2026-04-28)

배경

별도 검증한 매칭 시스템 (V1~V4) 을 기존 design_agent pipeline 에 통합하기 위한 설계.

매칭 시스템 (tests/matching/) 검증 결과:

• V1 키워드 매칭 (Logistic Regression 가중치, TARGET 4/4 LOOCV 검증)
• V2 의미 매칭 (ko-sroberta cosine)
• V3 구조 매칭 (layout / content_affinity / structure_intent)
• V4 종합 판정 (5축 + 라벨)
• TARGET 정답률 3/4 (75%), BM25 / IDF 보다 우위
• V4 slot 축 ablation: Top-1 매칭 7/7 동일 (slot 축 frame 선별 무영향)

설계 결정 사항

위계 + 용어 정리 :

[ slide ] 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 대목차 결론

5 단계 새 흐름:

1. STAGE 1 — MDX 분석 + 레이아웃 매칭 (Type A/B/B'/B'')
2. STAGE 2 — Zone 별 텍스트 1차 배치
3. STAGE 3 — Zone 별 프레임 매칭 (완벽 / 어정쩡 / 안 됨 분기)
4. STAGE 4 — 프레임 검토 + 컨테이너 조정 (5 차 Fallback)
5. STAGE 5 — HTML 조립 + 검증 + 출력

핵심 원칙:

• MDX 1 파일 = 대목차 1 개 = 슬라이드 1 장
• 텍스트 원문 무손실 보존 (본문 미리보기 + 팝업 원문)
• 자유 디자인 금지 (항상 Figma 프레임 DB 참고)
• 불일치 시 레이아웃 회귀 (콘텐츠 줄이지 않고 그릇 변경)

산출물 (이번 세션)

파일	용도
IMPROVEMENT-REDESIGN.md	매칭 시스템 통합 설계 문서 (전체 명세)
PROCESS_OVERVIEW.html	임원 보고용 A4 2 페이지 (프로세스 + 구조도)
tests/PIPELINE.md	V1~V4 통합 정리 + frame 단위 명확화
tests/pipeline/	매칭 시스템 코드 + 결과 + 보고서 (분류 복사본)

다음 단계 (구현)

IMPROVEMENT-REDESIGN.md 의 단계적 진행 계획 참조.

• Phase Z-1: 통합 prototype (MDX 03 회귀 통과)
• Phase Z-2: 매칭 + 프리셋 통합
• Phase Z-3: 컨테이너 검증 + Fallback
• Phase Z-4: 전체 통합 + 검증

발견된 약점 (8가지) — Phase Z 진행 시 대응

IMPROVEMENT-REDESIGN.md 11 장 (리스크) + tests/PROGRESS.md 약점 표 참조.

핵심 :

• 02-2.2 매칭 실패 (Frame 14 anchor 재라벨링 필요)
• 32 frame DB 사이즈 라벨링 부족 (zone 단위 vs 슬라이드 단위)
• slot 의미 매핑 부재
• V3 콘텐츠 성격 분류 부정확 (키워드 사전 한계)

---

Phase Z-1 사전 작업 진행 (2026-04-28)

Phase Z-1 자체는 진행 중. 본 entry 는 사전 작업 중 Frame / Style Inventory 완료 만 기록.

✅ 완료 — Frame / Style Inventory (사전 작업 일부)

산출	위치	내용
Frame Integration Map	docs/architecture/FRAME-INTEGRATION-MAP.md	32 frame Zone 적용 분류 (zone_direct / zone_adapt / zone_extract / reference_only). row 21~28 Figma ID 정정. 1171281171 부록 처리
Frame Style Inventory	docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md	32 frame (변환 14 + 미변환 18) + Token 18 행 (covered 7 / gap 5 / hierarchy 3 / hold 3) + Legacy 6 행

⬜ 다음 — Phase Z-2 본격 (catalog / runtime 설계)

• Phase Z-1 의 catalog / runtime 설계 prep 부분 (slide-base 검증 등) 은 미진행
• Phase Z-2 본격 (매칭 + 4 프리셋 통합) 도 미진행

⚠️ 미실행 / 의도적으로 보류

• 기존 templates/blocks/ 삭제 / 교체 실행
• catalog / runtime 구현
• templates/styles/frame-patterns/ 신규 파일 생성
• templates/styles/tokens/ 의 gap_candidate token 추가
• legacy structures 6 파일 삭제

→ 모두 승인 전 보류. Frame / Style Inventory 는 추출 / 검증 단계이고, 실제 변경은 별도 승인 단계.

---

프로젝트 구조

항목	파일	상태
프로젝트 규칙	CLAUDE.md	Phase Z 반영 (2026-04-28)
개선 계획 (이전)	IMPROVEMENT.md	Phase R' 반영
개선 계획 (신규)	IMPROVEMENT-REDESIGN.md	Phase Z 매칭 시스템 통합 (2026-04-28)
임원 보고용	PROCESS_OVERVIEW.html	Phase Z 흐름 반영
진행 추적	PROGRESS.md	이 파일 (2026-04-28 갱신)
전체 감사	CLEANUP-AUDIT.md	유효/무력화 분류 완료
Phase별 상세	IMPROVEMENT-PHASE-{A~R'}.md	각 Phase 기록
Phase R 실패 기록	IMPROVEMENT-PHASE-R.md	블록 선택 위에 variant 패치 — 실패
Phase R' 설계	IMPROVEMENT-PHASE-R-PRIME.md	접근 C 기반 재설계
매칭 시스템 (별도 검증)	tests/PIPELINE.md + tests/pipeline/	V1~V4 검증 완료 (2026-04-27)
README	README.md	Phase Z 반영