docs + V4 catalog + samples + Phase Q legacy 보존
전체 26 files (20 추가 + 6 수정), 10507 insertions. Phase Z 문서 : - docs/architecture/PHASE-Z-CHANGE-LOG.md (신설) — axis-by-axis 의사결정 history (newest-on-top). Step 7-A 부터 6 entry 박힘 + 2026-05-08 / 2026-05-08 #2 (compat 매트릭스 폐기 / 6-B 폐기 / F14 표현 정정 / label gate policy 분리). - docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md (수정) — Step 5/6/9 Gap note append (구조 무변, append-only). 6-B 폐기 사실 + Refinement F. - docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md (수정) — snapshot date 2026-05-08 갱신. §3 핵심 missing item 5 (Step 5/6/9 boundary axis breakdown + 폐기 기록). §6 한 줄 갱신 — 다음 axis 후보 A~F. Project root docs : - PLAN.md / PROGRESS.md / README.md (수정) — 토큰 체계 / 폴더 구조 / 설계 문서 / 역할 분리 반영. - IMPROVEMENT-REDESIGN.md (신설) — Phase Z 설계 핵심 문서. - PROCESS_OVERVIEW.html (신설) — 파이프라인 개요 시각. - docs/tasks/* (신설) — Phase Z task 문서. V4 catalog (Phase Z runtime 필수 의존성) : - tests/matching/v4_full32_result.yaml (신설, 4888 줄) — V4 매칭 결과 32 frame × 10 MDX section. lookup_v4_match() / lookup_v4_candidates() 가 본 파일 read. Phase Z runtime 이 *없으면 즉시 abort* — clone 후 즉시 동작 가능 보장. Samples : - samples/mdx_batch/04.mdx (신설) — MDX04 기본 sample. - samples/mdx/04. DX 지연 요인.mdx (신설) — MDX04 원본. Phase Q legacy 보존 (별 axis "Phase Q audit & salvage" 영역) : - src/block_matcher_tfidf.py / catalog_blocks.py / frame_extractor.py / pipeline_v2.py — Phase Q (옛 파이프라인) src 신규 untracked 파일들. Phase Z runtime 와 의존성 0. Phase Q audit axis 에서 검토 예정. - scripts/eval_block_matcher.py / fetch_all_frame_screenshots.py / match_17_units_my_matcher.py / match_mdx_strict.py / match_mdx_to_frames_tfidf.py / ocr_augment_texts.py / run_pipeline_v2.py / previews/ — Phase Q 작업 시 사용한 옛 script. 같이 보존. - run_mdx03_pipeline.py (수정) — Phase Q 진입점 (no flag) + Phase Z 진입점 (--phase-z2 flag) 동시 wrapper. Phase Z 만 사용 시 `python -m src.phase_z2_pipeline samples/mdx_batch/03.mdx <run_id>` 직접 호출. 비-scope : - tests/matching/ (v4_full32_result.yaml 외 ~63MB) — V4 진화 history / reports / DECK / ATTACH. Phase Q audit axis 에서 검토. - tests/pipeline/ (~15MB) — pipeline data. Phase Q audit 영역. - templates/catalog/blocks.yaml — 옛 block catalog. Phase Q audit. - templates/phase_z2/frames/ — 옛 frame partial 위치. Phase Q audit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
578
IMPROVEMENT-REDESIGN.md
Normal file
578
IMPROVEMENT-REDESIGN.md
Normal file
@@ -0,0 +1,578 @@
|
||||
# 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 기준
|
||||
Reference in New Issue
Block a user