_Geulbeot/04. design_agent/IMPROVEMENT-PHASE-A.md

Phase A: 슬라이드 품질 핵심 — 실행 상세

"프레임에 내용이 안 보인다"의 직접 원인 해결. 8개 항목. 원칙: 하드코딩 금지. 모든 판단은 AI 사고. 회귀 금지.

---

실행 순서

[독립] A-6 (cover→contain), A-7 (table-layout: fixed)
  → A-8 (container query, A-7 후)
  → A-1 (Sonnet 디자인 조정 — 가장 큰 작업)
  → A-2 (HTML 전달), A-3 (shrink), A-4 (rewrite) — 병렬 가능
  → A-5 (overflow 재검토, A-1 완료 후)

---

A-6: object-fit: cover → contain ✅ 완료

현재 상태

• image-row-2col.html:30 — object-fit: cover;
• image-grid-2x2.html:31 — object-fit: cover;
• cover는 이미지를 crop → CLAUDE.md "이미지를 crop하지 않는다" 위반

작업

두 파일에서 cover → contain 변경 (CSS 1줄씩)

충돌/회귀

• 충돌: 없음. CSS 속성값만 변경
• 회귀: 없음. CLAUDE.md 원칙 복구
• 부작용: contain은 이미지 주변에 빈 공간(letterbox) 가능 → background: var(--color-bg-subtle) 추가로 자연스럽게 처리

수정 파일

• templates/blocks/media/image-row-2col.html
• templates/blocks/media/image-grid-2x2.html

구현 결과

• image-row-2col.html:29~31 — object-fit: contain; height: 100%; background: var(--color-bg-subtle, #f8fafc);
  • cover → contain, 높이 하드코딩(354px) → 100%(부모 기준), letterbox 배경색 추가
• image-grid-2x2.html:29~31 — 동일 패턴 적용 (200px 하드코딩도 함께 제거)

---

A-7: table-layout: fixed ✅ 완료

현재 상태

• compare-3col-badge.html에 table-layout 미지정
• 열 너비가 내용 길이에 따라 불안정하게 변동

작업

.ct-table {
    table-layout: fixed;
    width: 100%;  /* fixed는 width 필수 */
}

충돌/회귀

• 충돌: 없음. 기존 테이블 스타일에 속성 추가만
• 회귀: 없음. fixed는 열 너비를 균등하게 고정 — 더 안정적

수정 파일

• templates/blocks/tables/compare-3col-badge.html

구현 결과

• .block-table-figma table에 table-layout: fixed; 추가 (기존 width: 100%는 이미 있었음)

---

A-8: container query 폰트 스케일링 ✅ 완료

현재 상태

• 표 셀 폰트 크기 고정 → 좁은 공간(sidebar 35%)에서 텍스트 잘림/넘침
• @container 규칙 없음

작업

.block-compare-table {
    container-type: inline-size;
}

@container (max-width: 40rem) {
    .ct-cell, .ct-header {
        font-size: var(--font-caption);  /* 0.8rem */
    }
}
@container (max-width: 25rem) {
    .ct-cell, .ct-header {
        font-size: var(--font-small);  /* 0.7rem */
    }
}

하드코딩 점검

• 40rem, 25rem은 font-size 기반 상대값 (px 고정이 아님)
• var(--font-caption), var(--font-small)은 디자인 토큰 → 하드코딩 아님

충돌/회귀

• 충돌: 없음. 신규 CSS 규칙 추가
• 회귀: 없음. @container 미지원 브라우저에서는 무시 → 기존과 동일
• 의존성: A-7 (table-layout: fixed) 먼저 적용해야 열 너비가 안정적

수정 파일

• templates/blocks/tables/compare-3col-badge.html

구현 결과

• .block-table-figma에 container-type: inline-size; 추가
• @container (max-width: 40rem) — 테이블/헤더/셀 폰트 축소 + 패딩 축소
• @container (max-width: 25rem) — 추가 축소 + badge 패딩 축소
• 추가: tr:hover 제거 (Phase C-2 선행 처리 — CLAUDE.md "호버 효과 금지")

---

A-1: 4단계 Sonnet 디자인 조정 ✅ 완료

현재 상태

• pipeline.py:73에서 render_slide(layout_concept) 직접 호출
• 텍스트 양에 맞는 디자인 조정 과정이 없음 → 텍스트 넘침/빈공간 원인
• CLAUDE.md: "디자인 실무자 (Sonnet + Jinja2 + CSS) — 텍스트에 맞게 폰트/여백/박스 조정"

API 선택

• Sonnet (CLAUDE.md "4단계: Anthropic API (Sonnet)")
• 디자인 실무자는 Kei가 아님 — Sonnet이 맞음

핵심 아이디어: CSS 변수 cascade

블록 템플릿 20개가 이미 CSS 변수(var(--font-body), var(--spacing-inner) 등)를 187회 사용 중. area div에서 CSS 변수를 override하면 템플릿 수정 없이 모든 블록이 자동 조정됨.

<!-- 예시: Sonnet이 body area의 폰트를 줄이기로 결정 -->
<div class="area-body" style="--font-body: 0.85rem; --spacing-inner: 10px;">
    {{ block.html }}  <!-- 내부 블록들이 자동으로 작은 폰트/여백 적용 -->
</div>

파이프라인 흐름 변경

기존:
  3단계 fill_content → 4단계 render_slide → 5단계 review

변경:
  3단계 fill_content → [신규] _adjust_design → 4단계 render_slide → 5단계 review

신규 함수: _adjust_design()

위치: pipeline.py

입력: layout_concept (data 채워진 상태)

처리:

1. 코드가 각 area별 블록 수, 텍스트 총량(글자 수), zone budget_px를 계산
2. Sonnet에게 전달: area별 정보 + 사용 가능한 CSS 변수 목록
3. Sonnet이 area별 CSS 변수 override를 결정하여 JSON 반환
4. layout_concept에 area_styles 저장

Sonnet 프롬프트 구성:

당신은 디자인 실무자이다. 편집자가 정리한 텍스트가 각 영역에 잘 들어가도록 CSS를 조정한다.

## 원칙
- 텍스트를 자르지 않는다. 디자인이 텍스트에 맞춘다.
- 빈 공간을 방치하지 않는다.
- 조정 가능한 CSS 변수: --font-body, --font-subtitle, --font-caption, --spacing-inner, --spacing-block, --spacing-small

## 각 영역 현황
- body (예산 490px, 너비 65%): 3개 블록, 총 820자
  - quote-question: 120자
  - topic-header: 200자
  - comparison-table: 500자
- sidebar (예산 490px, 너비 35%): 2개 블록, 총 400자
  - card-image: 250자
  - card-image: 150자
- footer (예산 60px): 1개 블록, 80자

## 출력 (JSON만)
{"area_styles": {"body": "--font-body: 0.85rem; --spacing-inner: 10px;", "sidebar": "", "footer": ""}}

Sonnet 출력 파싱:

• area_styles dict 추출
• 각 area별 CSS 문자열 → layout_concept 페이지에 저장

실패 시: area_styles가 빈 dict → style="" → 기존과 동일하게 렌더링 (안전)

renderer.py 변경

render_multi_page() 192~197행:

기존:

pages_rendered.append({
    "grid_areas": page.get("grid_areas", "'main'"),
    ...
    "blocks": blocks_grouped,
    "page_number": page_idx + 1,
})

변경:

# area_styles를 각 grouped block에 주입
area_styles = page.get("area_styles", {})
for grouped_block in blocks_grouped:
    grouped_block["style_override"] = area_styles.get(grouped_block["area"], "")

pages_rendered.append({
    "grid_areas": page.get("grid_areas", "'main'"),
    ...
    "blocks": blocks_grouped,
    "page_number": page_idx + 1,
})

slide-base.html 변경

45행:

기존:

<div class="area-{{ block.area }}">

변경:

<div class="area-{{ block.area }}" style="{{ block.style_override | default('') }}">

하드코딩 점검

• CSS 조정값: Sonnet이 결정 → AI 판단 ✅
• CSS 변수 목록: 프롬프트에 "조정 가능한 변수" 안내 → 가이드일 뿐 강제 아님 ✅
• area별 글자 수: 코드가 계산 → 객관적 수치 ✅
• 하드코딩 없음 ✅

충돌/회귀

• pipeline.py: render_slide() 전에 삽입. 기존 흐름 안 건드림 ✅
• renderer.py: blocks_grouped에 style_override 키 추가. 기존 키 영향 없음 ✅
• slide-base.html: style 속성 추가. area_styles 없으면 빈 문자열 → 기존 동일 ✅
• 템플릿 수정: 불필요 (CSS 변수 cascade로 자동 적용) ✅
• 회귀: 없음. 실패 시 기존과 동일 동작 ✅

수정 파일

• src/pipeline.py — _adjust_design() 신규 함수 + generate_slide()에 호출 추가
• src/renderer.py — render_multi_page()에서 area_styles 주입
• templates/slide-base.html — area div에 style_override 적용

구현 결과

• pipeline.py _adjust_design() 신규 함수 (약 80행):
  • 각 area별 block_count, total_chars, budget_px, width_pct, block_types 자동 집계 (코드)
  • Sonnet(디자인 실무자)에게 area별 현황 전달 → CSS 변수 override를 JSON으로 반환받음
  • 출력: page["area_styles"] = {"body": "--font-body: 0.85rem; ...", "sidebar": "", ...}
  • 실패 시: area_styles = {} → style="" → 기존과 동일 렌더링 (안전)
• pipeline.py generate_slide() 72행: _adjust_design() 호출 삽입 (render_slide 직전)
• renderer.py render_multi_page() 192~196행: area_styles를 grouped block의 style_override에 주입
• slide-base.html 45행: <div class="area-{{ block.area }}" style="{{ block.style_override | default('') }}">
• CSS 변수 cascade 방식: 블록 템플릿 수정 불필요 — 이미 var(--font-body) 등 187회 사용 중이므로 area div에서 override하면 자동 적용

---

A-2: 5단계 HTML을 프롬프트에 전달 ✅ 완료

현재 상태

• pipeline.py:103 _review_balance(html, ...) — html 파라미터 있지만 141~146행 프롬프트에서 미사용
• 블록별 데이터 길이만 전달 → 시각적 균형 판단 불가

작업

_review_balance() 프롬프트에 html 전문 포함

user_prompt = (
    f"## 1차 조립 HTML\n{html}\n\n"
    f"## 블록별 데이터 양\n" + "\n".join(block_summary) + ...
)

하드코딩 점검

• html 전문 전달 (임의 잘라내기 없음) ✅
• Sonnet 200K context → 전문 전달 가능 ✅

충돌/회귀

• 프롬프트 텍스트만 변경. 파싱/함수 시그니처 동일 ✅
• 회귀: 없음 ✅

수정 파일

• src/pipeline.py — _review_balance() 프롬프트 부분

구현 결과

• _review_balance() user_prompt에 f"## 1차 조립 HTML\n{html}\n\n" 추가 — html 전문 전달
• 시스템 프롬프트에 "5. HTML 구조: 블록이 영역 안에 잘 배치되었는지" 점검 항목 추가
• 출력 형식에 target_ratio 필드 추가 (A-3과 연동)

---

A-3: 5단계 shrink action + 기존 expand 하드코딩 수정 ✅ 완료

현재 상태

• shrink: 조건에 없어서 무시됨
• expand: char_guide * 1.5 하드코딩 (pipeline.py:186)
• CLAUDE.md: "모든 판단은 사고로. 하드코딩 없음"

작업

1) 5단계 프롬프트 출력 형식 변경

기존:

{"adjustments": [{"block_area": "...", "action": "expand|shrink|rewrite", "detail": "..."}]}

변경:

{"adjustments": [{"block_area": "...", "action": "expand|shrink|rewrite", "target_ratio": 1.4, "detail": "..."}]}

→ Sonnet(디자인 팀장)이 얼마나 조정할지를 target_ratio로 결정

2) _apply_adjustments() 코드 변경

for adj in adjustments:
    area = adj.get("block_area", "")
    action = adj.get("action", "")
    ratio = adj.get("target_ratio")
    detail = adj.get("detail", "")

    for page in layout_concept.get("pages", []):
        for block in page.get("blocks", []):
            if block.get("area") == area:
                if action == "expand" and ratio:
                    for key in block.get("char_guide", {}):
                        block["char_guide"][key] = int(block["char_guide"][key] * ratio)
                elif action == "shrink" and ratio:
                    for key in block.get("char_guide", {}):
                        block["char_guide"][key] = int(block["char_guide"][key] * ratio)
                logger.info(f"조정: {area} → {action} ×{ratio} ({detail})")

→ ratio가 없으면(Sonnet 누락) 조정 안 함 (무동작이 안전) → expand/shrink 모두 Sonnet이 결정한 ratio 사용

하드코딩 점검

• ratio: Sonnet이 결정 ✅ (기존 1.5 하드코딩 제거)
• ratio 없을 때 기본값: 적용 안 함 (하드코딩 기본값 없음) ✅

충돌/회귀

• 기존 expand * 1.5 제거 → 기존 하드코딩을 수정하는 것이므로 회귀 아님, 개선임
• 5단계 프롬프트 출력 형식 변경 → _parse_json() 파싱에 영향 없음 (JSON 구조)
• Sonnet이 target_ratio를 안 넣으면 → 조정 안 함 → 기존보다 보수적 (안전)

수정 파일

• src/pipeline.py — _review_balance() 프롬프트 + _apply_adjustments() 코드

구현 결과

• _apply_adjustments() 전면 재작성:
  • ratio = adj.get("target_ratio") — Sonnet이 결정한 비율 추출
  • action == "expand" and ratio → char_guide[key] * ratio
  • action == "shrink" and ratio → char_guide[key] * ratio
  • ratio 없으면(Sonnet 누락) 조정 안 함 → 안전
  • 기존 * 1.5 하드코딩 완전 제거
• _review_balance() 프롬프트에 action별 target_ratio 설명 추가

---

A-4: 5단계 rewrite action ✅ 완료

현재 상태

• rewrite가 expand와 같은 조건(action in ("expand", "rewrite"))에 들어가지만
• if action == "expand" 안에만 실제 로직 → rewrite는 로그만 찍고 끝 (no-op)

작업

A-3에서 변경한 코드에 rewrite 분기 추가:

elif action == "rewrite":
    if "data" in block:
        del block["data"]
    block["reason"] = f"재작성: {detail}"
    logger.info(f"조정: {area} → rewrite ({detail})")

• data 삭제 → fill_content() 재호출(192행) 시 재매칭

하드코딩 점검

• 없음 ✅

충돌/회귀

• 기존 no-op → 실제 동작으로 변경 (개선, 회귀 아님)
• fill_content 재호출 시 topic_id 매칭으로 다른 블록도 재편집될 수 있음 → 기존 expand도 동일 동작
• 회귀: 없음 ✅

수정 파일

• src/pipeline.py — _apply_adjustments() (A-3과 같은 함수)

구현 결과

• _apply_adjustments()에 elif action == "rewrite" 분기 추가
• data 삭제 (del block["data"]) → fill_content 재호출 시 topic_id로 재매칭
• block["reason"] 업데이트 → 편집자에게 재작성 방향 전달

---

A-5: overflow 정책 재검토 ✅ 완료

현재 상태

• base.css:16 .slide { overflow: hidden } — 프레임 경계
• base.css:74 .slide > div { overflow: hidden } — BF-8에서 추가한 area별 안전망

작업

/* base.css:74 변경 */
.slide > div {
    overflow: visible;  /* hidden → visible: A-1이 사전 조정하므로 잘림 방지 불필요 */
    min-height: 0;
    min-width: 0;
}

.slide { overflow: hidden }(16행)은 유지 — 프레임 바깥은 잘려야 함

하드코딩 점검

• 없음 ✅

충돌/회귀

• BF-8에서 추가한 .slide > div { overflow: hidden } 제거 → BF-8과 방향 다름
• 그러나 BF-8의 overflow: hidden은 "텍스트를 자르지 않는다" 원칙과 충돌하는 임시 조치였음
• A-1(Sonnet 디자인 조정)이 넘침을 사전 방지 → 안전망 불필요
• 반드시 A-1 완료 후 적용

수정 파일

• static/base.css

구현 결과

• base.css .slide > div — overflow: hidden → overflow: visible
• 주석 추가: "A-1(Sonnet 디자인 조정)이 텍스트 양에 맞게 CSS를 사전 조정하므로, area 레벨에서는 overflow: visible로 텍스트 잘림을 방지한다."
• .slide { overflow: hidden }(16행)은 유지 — 프레임 경계 보호

---

수정 파일 총괄

파일	항목	변경 성격
templates/blocks/media/image-row-2col.html	A-6	CSS 1줄 변경
templates/blocks/media/image-grid-2x2.html	A-6	CSS 1줄 변경
templates/blocks/tables/compare-3col-badge.html	A-7, A-8	CSS 추가
src/pipeline.py	A-1, A-2, A-3, A-4	신규 함수 + 기존 함수 수정
src/renderer.py	A-1	area_styles 주입 (3줄)
templates/slide-base.html	A-1	style 속성 추가 (1줄)
static/base.css	A-5	overflow 변경 (1줄)

---

검증 체크리스트

• A-6: image-row, image-grid에서 이미지가 crop 안 됨
• A-7: 테이블 열 너비가 내용과 무관하게 균등
• A-8: sidebar(35%)에 표가 들어가면 폰트 자동 축소
• A-1: Sonnet이 area별 CSS 변수 override 출력 → 렌더링에 반영
• A-1: _adjust_design 실패 시 기존과 동일하게 렌더링 (안전)
• A-2: 5단계 Sonnet이 HTML 구조를 보고 균형 판단
• A-3: shrink 시 Sonnet이 결정한 ratio로 char_guide 축소
• A-3: 기존 expand 1.5 하드코딩 제거됨
• A-4: rewrite 시 해당 블록 data 삭제 후 재편집
• A-5: area div에서 텍스트 잘림 없음

---

수정 이력

날짜	내용
2026-03-25	초안. 하드코딩 제거 반영 (A-2 html 전문, A-3 target_ratio, A-8 상대값).
2026-03-25	Phase A 전체 구현 완료. 검증 통과.

구현 완료 확인

항목	검증 결과
A-1	_adjust_design() 함수 존재, pipeline에서 호출, renderer에서 area_styles 주입, slide-base에서 style_override 적용
A-2	_review_balance() 프롬프트에 html 전문 포함, target_ratio 출력 형식 추가
A-3	shrink action 구현 + expand 하드코딩(×1.5) 제거 → Sonnet target_ratio 기반
A-4	rewrite action 구현 — data 삭제 + reason 업데이트 + fill_content 재호출
A-5	.slide > div { overflow: visible } — 프레임(.slide)은 hidden 유지
A-6	image-row, image-grid: cover → contain + 높이 하드코딩 제거
A-7	table-layout: fixed + width: 100%
A-8	container-type: inline-size + @container (40rem, 25rem)
추가	compare-3col-badge tr:hover 제거 (Phase C-2 선행 처리)