16 KiB
16 KiB
Design Agent — 진행 상황
현재 상태 요약 (2026-04-01 기준)
| 상태 | 내용 |
|---|---|
| 완료 | Phase 1 |
| 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: 제약 기반 블록 선택 + 글자수 예산 시스템 (설계 확정)
핵심 원칙: "계산 먼저, 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 단계 새 흐름:
- STAGE 1 — MDX 분석 + 레이아웃 매칭 (Type A/B/B'/B'')
- STAGE 2 — Zone 별 텍스트 1차 배치
- STAGE 3 — Zone 별 프레임 매칭 (완벽 / 어정쩡 / 안 됨 분기)
- STAGE 4 — 프레임 검토 + 컨테이너 조정 (5 차 Fallback)
- 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_candidatetoken 추가- 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 반영 |