C.E.L_Slide_test2/CLAUDE.md

# Design Agent — 콘텐츠 시각 구조화 슬라이드 생성기

## 프로젝트 목적

텍스트/MDX 콘텐츠를 **가로 슬라이드(1페이지 또는 다중 페이지)**로 시각 구조화하는 독립 에이전트.
콘텐츠의 의미를 분석하여 적합한 레이아웃 블록을 선택하고, 핵심만 추출하여 깔끔한 HTML/CSS로 렌더링한다.

**핵심 원칙:**
- 전체 페이지를 하나의 고정 템플릿으로 찍어내는 것이 아니라, 콘텐츠를 분석 → 각 덩어리별로 적합한 레이아웃 블록 선택 → 조합하여 배치
- 기획자(편집자)가 정리한 텍스트가 기준. **디자인이 텍스트에 맞춘다** (텍스트가 디자인에 맞추는 것이 아님)
- **모든 판단은 실장/팀장/편집자의 사고. 하드코딩 없음**

---

## 아키텍처 (5단계 파이프라인)

```
[1단계] Kei 실장 (Sonnet) — AI 사고
    꼭지 추출 → 레이어 수준 → 강조 판단 → 배치 방향
    ↓
[2단계] 디자인 팀장 (Sonnet) — AI 사고
    블록 매핑 + 공간 배분 + 글자 수 가이드 → 편집자에게 전달
    ↓
[3단계] Kei 텍스트 편집자 (Sonnet) — AI 사고
    글자 수 가이드 참고하되 내용 의미 우선. 도메인 용어 보존하며 편집
    ↓
[4단계] 디자인 실무자 (Sonnet + Jinja2 + CSS) — AI + 코드
    편집자가 정리한 텍스트에 맞게 디자인 조정 + HTML 조립
    ↓
[5단계] 디자인 팀장 (Sonnet) — AI 사고
    전체 균형 재검토 → 공간 재배분 → 2차 조정 지시
```

### 역할 분리

| 역할 | 담당 | 방식 | 하는 일 | 하지 않는 일 |
|------|------|------|---------|------------|
| Kei 실장 | Sonnet | AI | 꼭지 추출, 레이어 판단, 강조 판단, 배치 방향, 이미지/표/상세 판단 | 디자인, 텍스트 편집 |
| 디자인 팀장 | Sonnet | AI | catalog에서 블록 선택, 공간 배분, 겹침 방지, 글자 수 가이드, 전체 재검토 | 텍스트 정리, 콘텐츠 의미 판단 |
| 텍스트 편집자 | Sonnet | AI | 도메인 용어 보존하며 편집, 출처 보존, 표 내용 편집 | 레이아웃 결정, 디자인 판단 |
| 디자인 실무자 | Sonnet + 코드 | AI + 코드 | 텍스트에 맞게 디자인 조정, HTML/CSS 조립, 이미지 크기 조정, 표 스케일링 | 콘텐츠 의미 판단 |

---

## 핵심 프로세스

```
사용자 콘텐츠 입력 (텍스트/MDX 붙여넣기 또는 파일 업로드)
    ↓
[1단계] Kei 실장 — 꼭지 추출 + 분석

    꼭지 추출:
    - 본문에서 핵심 꼭지 추출 (2~5개)
    - 1페이지 적정 꼭지 수: 5개

    페이지 분리 판단:
    - 중요도가 5개를 넘고 레이어도 동등하면 → 2페이지로 분리
    - 내용과 의미 기반으로 자연스러운 분할 (2/3, 3/4, 4/3, 5/2 등)
    - 5개인데 내용이 많으면 → 꼭지 레이어를 보고 세부 내용은 자세히보기로

    각 꼭지 분석:
    - 레이어 수준 (도입/핵심/보조/결론)
    - 강조 판단 (어떤 꼭지를 눈에 띄게 할 것인가)
    - 배치 방향 (세로로 긴 꼭지, 가로 나열 꼭지)

    이미지 판단:
    - 몇 개인지, 어떤 꼭지에 속하는지
    - 핵심인지(도표/차트) 보조인지(참고 문서 표지)
    - 텍스트가 포함된 이미지인지 (너무 축소하면 안 됨)

    표 판단:
    - 행/열 규모
    - 전체 표시 가능한지, 요약 필요한지

    상세 콘텐츠 판단:
    - 너무 구체적/세부적인 내용은 "자세히보기" 대상
    ↓
[2단계] 디자인 팀장 — 레이아웃 설계

    블록 매핑:
    - catalog 메뉴판에서 각 꼭지에 적합한 블록 선택
    - 꼭지의 성격을 보고 판단 (출처 있으면 example-card, 정의면 card-grid 등)

    이미지 배치:
    - 원본 이미지 크기 확인 (Pillow Image.open().size)
    - 가로/세로 비율에 따라 영역 결정
      (가로형이면 전체 너비, 세로형이면 텍스트 옆)
    - 텍스트 포함 도표는 너무 작게 하면 안 됨
    - 이미지는 원본 그대로 사용, 크기만 조절

    표 배치:
    - 행×열 규모 보고 공간 안에 들어가는지 판단
    - 안 들어가면 실장에게 요약 요청 또는 2페이지 분리

    자세히보기 설계:
    - 상세 콘텐츠는 <details>/<summary> 영역으로 설계

    공간 배분:
    - 전체 공간에서 영역별 비율 결정
    - 꼭지끼리 겹치지 않도록 grid-template 설계
    - 각 블록의 대략적 글자 수 가이드

    페이지 판단:
    - 안 들어가면 2페이지로 분리
    ↓
[3단계] Kei 텍스트 편집자 — 텍스트 정리

    - 팀장의 글자 수 가이드 참고하되, 내용 의미가 우선
    - 전체 컨텍스트와 핵심 용어 유지
    - 도메인 전문가로서 세련된 표현으로 편집
    - 출처 보존, 개조식 작성, 날조 금지
    - 결과 글자 수가 가이드와 다를 수 있음 (의미 > 글자 수)
    - 표 내용도 편집 (핵심 행/열 선택, 요약 등)
    - 자세히보기 대상은 요약 버전 + 상세 버전 둘 다 작성
    ↓
[4단계] 디자인 실무자 — 디자인 조정 + HTML 조립

    텍스트 맞춤:
    - 편집자가 정리한 텍스트 양에 맞게 디자인 조정
    - 텍스트가 가이드보다 길면 → 폰트/여백/박스를 조정 (텍스트를 자르지 않음)
    - 빈 공간 방치 안 함 (박스 줄이거나 공간 활용)

    이미지 처리:
    - object-fit: contain (비율 유지, 잘리지 않게)
    - 팀장이 정한 영역 크기에 맞춤

    표 처리:
    - table-layout: fixed + container query 폰트 스케일링
    - 행/열 수에 따라 셀 크기 자동 조정

    자세히보기:
    - <details>/<summary>로 접기/펼치기
    - 인쇄 시 자동 펼침 (JavaScript)

    HTML 조립:
    - Jinja2 템플릿 렌더링
    - 다중 페이지 시 page-break 처리
    ↓
[5단계] 디자인 팀장 — 전체 재검토

    균형 점검:
    - 1차 조립 결과의 전체 균형 확인
    - 블록별 채움 비율 (텍스트 양 vs 공간)
    - 블록 간 균형 (한쪽만 빽빽하고 다른 쪽 비어있지 않은지)

    이미지/표 점검:
    - 이미지 크기가 적절한지 (너무 작아서 안 보이지 않는지)
    - 표가 읽을 수 있는 크기인지

    조정:
    - 필요 시 공간 재배분 → 실무자에게 2차 조정 지시
    - 좌우 불균형, 어색한 빈 공간 해소
    - 최종 HTML 출력
    ↓
미리보기 → HTML 다운로드
```

**핵심 원칙:**
- 디자인 팀장은 레이아웃 + 공간 배분. 텍스트를 건드리지 않는다.
- 텍스트 편집자가 정리한 텍스트가 기준. 디자인이 텍스트에 맞춘다.
- 실무자는 텍스트를 자르지 않고, 디자인을 조정한다.
- 이미지는 원본 그대로 사용, 크기만 조절.
- 표는 표로 유지, 공간 안 되면 요약하거나 페이지 분리.
- 상세 내용은 `<details>`로 접기/펼치기.
- 1차 조립 후 팀장이 전체 균형을 재검토하여 2차 조정.
- **모든 기준은 하드코딩 없이 실장/팀장/편집자의 사고로 판단.**

---

## 콘텐츠 유형 분류 기준

실장이 콘텐츠를 분석하여 아래 유형으로 분류한다.
**이 분류는 하드코딩이 아니라, 실장이 매번 사고하여 판단한다.**

| 텍스트 패턴 | 유형 | 적합한 블록 |
|------------|------|-----------|
| "A vs B", 장단점, 차이점 | 비교 | 2단 병렬 / 비교 테이블 |
| "1단계 → 2단계 → 3단계" | 프로세스 | 플로우차트 / 단계 카드 |
| "X는 Y를 포함한다", 상위-하위 | 구성/관계 | 벤 다이어그램 / 트리 |
| 수치, KPI, 통계 | 핵심 지표 | 큰 숫자 + 보조 텍스트 |
| 용어 정의, 개념 설명 | 정의 | 카드 3열 / 아이콘 카드 |
| 기능/특성 나열 | 목록 | 아이콘 리스트 / 카드 그리드 |
| 연도별 사건, 로드맵 | 시간 순서 | 타임라인 (가로/세로) |
| 핵심 메시지, 결론 | 강조 | 결론 바 / 인용 블록 |
| 문제 상황, 경고 | 문제 제기 | 경고 박스 / 강조 인용 |
| 이미지 + 텍스트 | 이미지 참조 | 전체너비 / 사이드 / 썸네일 |
| 다항목 데이터 | 표 | 비교 테이블 |
| 세부/구체적 내용 | 자세히보기 | `<details>/<summary>` |

---

## 블록 타입 정의

각 블록은 독립적인 CSS 컴포넌트로, 슬롯(교체 가능한 위치)을 가진다.

### 1. 비교 블록 (comparison)
- 2단 병렬 레이아웃
- 슬롯: 좌측 제목/내용, 우측 제목/내용
- 용도: A vs B, 장단점, Before/After

### 2. 카드 그리드 (card-grid)
- 2~4열 카드 배열
- 슬롯: 카드별 아이콘/제목/설명/출처
- 용도: 용어 정의, 개념 설명, 기능 나열

### 3. 관계도 (relationship)
- 벤 다이어그램 또는 트리 구조
- 슬롯: 중심 요소, 하위 요소들, 관계 설명
- 용도: 상위-하위 관계, 포함 관계, 기술 융합

### 4. 프로세스 (process)
- 가로 또는 세로 단계 흐름
- 슬롯: 단계별 번호/제목/설명
- 용도: 절차, 워크플로우, 파이프라인

### 5. 타임라인 (timeline)
- 시간 축 기반 배치
- 슬롯: 날짜/제목/설명
- 용도: 연혁, 로드맵, 일정

### 6. 핵심 지표 (big-number)
- 큰 숫자 + 보조 텍스트
- 슬롯: 숫자, 단위, 설명
- 용도: KPI, 통계, 성과 수치

### 7. 강조 인용 (quote-block)
- 배경색 + 좌측 라인 + 인용 텍스트
- 슬롯: 인용 텍스트, 출처
- 용도: 문제 제기, 핵심 메시지, 정의

### 8. 결론 바 (conclusion-bar)
- 하단 전체 폭 강조 영역
- 슬롯: 핵심 한 줄
- 용도: 슬라이드 결론, 요약 메시지

### 9. 비교 테이블 (comparison-table)
- 테이블 형식의 다항목 비교
- 슬롯: 행/열 헤더, 셀 내용
- 용도: 다차원 비교, 기능 매트릭스

### 10. 이미지 블록 (image-block)
- 이미지 + 캡션
- 3가지 변형: 전체너비(image-full), 텍스트옆(image-side), 썸네일(image-thumb)
- 슬롯: 이미지 경로, 캡션 텍스트, 이미지 크기 정보
- 용도: 도표, 다이어그램, 근거 자료, 문서 참조
- CSS: object-fit: contain (비율 유지, 잘리지 않음)

---

## 이미지 처리 원칙

- 원본 이미지를 **그대로 사용** (crop/재구성은 극히 예외)
- 팀장이 슬라이드 구조에 맞게 **크기만 조절** (가로/세로 비율 유지)
- 이미지 크기 읽기: Pillow `Image.open().size` (헤더만 읽음, 전체 로드 안 함)
- 가로형(ratio > 1.2) → 전체 너비 배치
- 세로형(ratio < 0.8) → 텍스트 옆 배치
- 텍스트 포함 도표 → 너무 작게 축소하면 안 됨
- CSS: `object-fit: contain` (전체 보이게, 비율 유지)

## 표 처리 원칙

- 표는 **표로 유지** (다른 형태로 전환하지 않음)
- 공간에 안 들어가면: 요약하거나 페이지 분리
- CSS: `table-layout: fixed` + container query 폰트 스케일링
- 표 내용 편집은 Kei 텍스트 편집자가 담당

## 자세히보기 (상세 콘텐츠) 원칙

- HTML 네이티브 `<details>/<summary>` 사용 (JavaScript 불필요)
- 슬라이드 표면: 요약/핵심만 표시
- 펼치면: 전체 상세 내용 표시
- 인쇄 시: JavaScript 6줄로 자동 펼침
- 정보 밀도는 실장/팀장이 사고로 판단 (하드코딩 기준 없음)

---

## 페이지 구성 원칙

### 레이아웃 배치 규칙
- CSS Grid 기반 (`grid-template-areas`)
- 가로 슬라이드 비율: 16:9 (1280×720)
- 1페이지 적정 꼭지 수: 5개
- 정보 계층: 위 → 아래 (문제 제기 → 분석 → 결론)
- 여백: 블록 간 최소 20px, 페이지 패딩 40px

### 페이지 분리 기준
- 꼭지 5개 이하 + 내용 적절 → 1페이지
- 꼭지 5개 + 내용 많음 → 1페이지 + 일부 자세히보기
- 꼭지 5개 초과 + 레이어 동등 → 2페이지 (의미 기반 분할)
- 분할 비율: 2/3, 3/4, 4/3, 5/2 등 내용에 따라

### 블록 조합 예시

```
┌─────────────────────────────────────────────┐
│ [강조 인용] 문제 제기                         │
├──────────────────┬──────────────────────────┤
│ [사례 카드 2열]   │ [카드 그리드 3열]         │
│ 정책 사례         │ 용어 정의                │
├──────────────────┴──────────────────────────┤
│ [관계도] 벤 다이어그램                        │
├─────────────────────────────────────────────┤
│ [결론 바] 핵심 한 줄                         │
└─────────────────────────────────────────────┘
```

---

## 글자 수 추정 (타이포그래피 기반)

한글은 글자 너비가 거의 일정하므로, 블록 크기에서 글자 수를 계산할 수 있다.
**이 계산은 팀장의 글자 수 가이드를 보조하는 참고 도구이지, 하드코딩 기준이 아니다.**

```
계산식:
  한 줄 글자 수 = 블록 너비(px) ÷ (폰트 크기(px) × 0.97)
  줄 수 = 블록 높이(px) ÷ (폰트 크기(px) × 줄간격)
  총 글자 수 = 한 줄 글자 수 × 줄 수 × 안전 계수(0.85)
```

Pretendard 폰트 크기별 참고값 (1회 측정, 상수 저장):

| 폰트 크기 | 한글 글자 너비 | 줄간격 1.6 기준 줄 높이 |
|----------|-------------|---------------------|
| 12px | ~11.6px | 19.2px |
| 16px | ~15.5px | 25.6px |
| 20px | ~19.4px | 32.0px |
| 24px | ~23.3px | 38.4px |

---

## 디자인 원칙 (절대 규칙)

### DO (해야 하는 것)
- 여백을 충분히 확보한다 (여백 > 장식)
- 색상은 최대 3개 (메인 1개 + 포인트 1개 + 중성 1개)
- 폰트 크기 체계를 일관되게 유지 (제목/소제목/본문/캡션 4단계)
- 흑백 기조 + 포인트 컬러 최소 사용
- 정보 계층을 시각적으로 명확히 표현

### DON'T (하지 않는 것)
- 그라데이션 배경 금지
- CSS 애니메이션/트랜지션 금지
- 호버 효과 금지
- 그림자(box-shadow) 최소화 (1개 레벨만)
- 다크 테마 금지 (요청하지 않는 한)
- 둥근 모서리 과다 사용 금지 (border-radius 최대 8px)
- 텍스트를 자르지 않는다 (디자인이 텍스트에 맞춘다)

---

## 디자인 토큰

```css
:root {
    /* 색상 */
    --color-primary: #1e293b;
    --color-accent: #2563eb;
    --color-neutral: #64748b;
    --color-bg: #ffffff;
    --color-bg-subtle: #f8fafc;
    --color-border: #e2e8f0;
    --color-danger: #dc2626;

    /* 폰트 크기 */
    --font-title: 2rem;
    --font-subtitle: 1.25rem;
    --font-body: 0.95rem;
    --font-caption: 0.8rem;

    /* 여백 */
    --spacing-page: 40px;
    --spacing-block: 20px;
    --spacing-inner: 16px;

    /* 기타 */
    --radius: 6px;
    --border-width: 1px;
    --accent-border: 3px;
}
```

---

## Kei API 연동

### 호출 포인트
| 단계 | API | 용도 |
|------|-----|------|
| 1단계 꼭지 추출 | Anthropic API (Sonnet) | 꼭지 추출 + 레이어 + 강조 + 배치 + 이미지/표/상세 판단 |
| 2단계 레이아웃 설계 | Anthropic API (Sonnet) | 블록 매핑 + 공간 배분 + 글자 수 가이드 |
| 3단계 텍스트 정리 | Anthropic API (Sonnet) | 의미 보존 편집 + 표 편집 + 자세히보기 작성 |
| 4단계 디자인 조정 + 조립 | Anthropic API (Sonnet) + Jinja2/CSS | 텍스트에 맞게 디자인 조정 + HTML 생성 |
| 5단계 재검토 | Anthropic API (Sonnet) | 균형 점검 + 2차 조정 |

### 독립 실행 가능
- Kei API 없이 Anthropic API 직접 호출로 동작
- Kei API 연결 시 1단계에서 Kei RAG 지식 활용 가능

---

## 교본 (레퍼런스) 관리

### catalog.yaml
- 디자인 팀장의 "메뉴판"
- 각 블록의 id, 시각 설명, 언제 쓰는지(when), 슬롯 목록
- Figma에서 디자인 추출 → 템플릿 변환 → catalog에 등록
- **Figma 작업 완료 후 연동 예정**

### 저장 위치
```
design_agent/
├── templates/
│   ├── catalog.yaml          ← AI용 블록 메뉴판 (Figma 작업 후)
│   ├── slide-base.html       ← 슬라이드 베이스
│   └── blocks/               ← 블록 템플릿
├── samples/                  ← 완성 슬라이드 샘플
└── docs/                     ← 조사 자료
```

---

## 기술 스택

| 역할 | 도구 | 비고 |
|------|------|------|
| 서버 | FastAPI + uvicorn | 포트 8001 |
| 템플릿 | Jinja2 | 블록 조합 |
| 렌더링 | CSS Grid + 디자인 토큰 | 16:9 고정 |
| 폰트 | Pretendard Variable | word-break: keep-all |
| AI | Anthropic API (Sonnet) | 5단계 모두 |
| 이미지 크기 | Pillow Image.open().size | 헤더만 읽음 |
| 자세히보기 | `<details>/<summary>` | HTML 내장 |
| 출력 | HTML 다운로드 | |

---

## 향후 연결 가능성

```
현재: 독립 개발 + 테스트
    ↓
검증 후 선택지:
    A) Kei 본체에 합치기 (대화 안에서 "슬라이드로 정리해줘")
    B) 글벗에 붙이기 (문서 자동화 → 시각화 단계)
    C) 둘 다
```

---

## 금지 사항

1. Kei Persona Agent 코드를 수정하지 않는다
2. 디자인 판단을 하드코딩하지 않는다 (AI가 사고한다)
3. 전체 페이지를 하나의 고정 템플릿으로 만들지 않는다 (블록 조합 방식)
4. 텍스트를 자르지 않는다 (디자인이 텍스트에 맞춘다)
5. 이미지를 crop하지 않는다 (크기만 조절)
6. 그라데이션, 애니메이션, 다크 테마를 기본으로 사용하지 않는다