# task-1664.1 완료 보고서: 블로그 이미지 품질 개선

## SCQA

**S**: 블로그 이미지 생성 파이프라인(image_router.py + satori_cli.js)이 구축되어 infographic, process_flow, comparison_table, checklist 4종 레이아웃을 지원한다.

**C**: 5개 이미지 중 3개가 "infographic 및 satori 모두 실패" 에러를 반환하고, 성공한 이미지도 폰트 크기가 작고(24px/14px), 줄바꿈이 부적절하며, 디자인 일관성이 부족하다. Claude CLI HTML→PNG 경로의 프롬프트 품질 기준이 낮고, 생성 후 품질 검증 단계가 없어 저품질 이미지가 그대로 전달된다.

**Q**: 프롬프트 품질 기준 강화와 자동 QA 검증 도입으로 이미지 생성 성공률과 품질을 개선할 수 있는가?

**A**: 3가지 개선을 적용했다: (1) `_prompt_to_html` 디자인 토큰 강화 — 폰트 32px/24px/18px, word-break: keep-all, WCAG AA 대비(4.5:1), padding 40px, line-height 1.7, (2) `_validate_image_quality` 함수 신설 — 파일 크기 10KB+, 이미지 너비 600px+, 빈 이미지(stddev<5) 감지, (3) `_generate_infographic`에 품질 검증 통합. pytest 101건 전체 통과, satori 4종 레이아웃 통합 테스트 100% 성공(175-195KB 이미지 생성 확인).

## 근본 원인 분석

### satori_cli.js 4종 레이아웃
- 직접 실행 테스트 결과: 4종 모두 정상 동작 (infographic 190KB, process_flow 191KB, comparison_table 195KB, checklist 188KB)
- Node.js v24.14.0 호환성 문제 없음
- Python subprocess 호출 경로도 정상 동작 확인

### 실패 원인
- Claude CLI HTML→PNG 경로: 첫 시도에서 빈 응답 반환 빈도 높음 (3회 재시도로 대응 중)
- 품질 미달 이미지가 검증 없이 전달되어 사용자에게 저품질 경험 제공
- 프롬프트 디자인 토큰이 블로그 이미지에 부적합한 수준 (제목 24px, 본문 14px)

## 작업 내용

### 1. `_prompt_to_html` 디자인 토큰 강화
- 폰트: 제목 24px→32px, 소제목 18px→24px, 본문 14px→18px
- 레이아웃: padding 32px→40px, gap 16px→24px
- 한글: word-break: keep-all 추가, line-height 1.7 추가
- 접근성: WCAG AA 색상 대비 4.5:1 기준 명시
- 안전장치: "폰트 32px/18px 미만 금지" 경고문 추가

### 2. `_validate_image_quality` 함수 신설
- 파일 크기 검증: 최소 10KB (빈/손상 이미지 차단)
- 이미지 너비 검증: 최소 600px (PIL 사용 시)
- 빈 이미지 감지: RGB 표준편차 < 5이면 단색으로 판정 (PIL 사용 시)
- PIL 미설치 시: 파일 크기만 검증 (graceful degradation)

### 3. `_generate_infographic` 품질 검증 통합
- HTML 렌더링 성공 후 `_validate_image_quality` 자동 실행
- 검증 실패 시 False 반환 → fallback 체인(satori)으로 자동 전환

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **worktree에 커밋되지 않은 infographic 기능 누락** — 원본 workspace의 uncommitted 변경을 worktree에 복사 후 개선 적용
   - 상세: image_router.py에 INFOGRAPHIC enum, 라우팅, fallback 체인이 uncommitted 상태였음
2. **테스트에서 PIL 로컬 import mock 실패** — `image_router.Image` 모듈레벨 patch 대신 실제 PIL 이미지 생성으로 테스트
   - 상세: test_image_router.py:1048 — PIL로 800x600 랜덤 컬러 이미지 생성하여 검증
3. **PIL 생성 이미지 크기 미달(2.7KB < 10KB)** — 랜덤 픽셀 이미지로 변경하여 충분한 파일 크기(>10KB) 확보
   - 상세: test_image_router.py:1053 — random.randint 픽셀로 노이즈 이미지 생성

### 범위 외 미해결 (1건)
1. **Claude CLI 인증/rate limit으로 인한 간헐적 실패** — 범위 외 사유: Claude CLI 인프라 이슈. 기존 3회 재시도 로직이 대응 중이며, 실패 시 satori fallback이 동작함

## 테스트 결과

- pytest 101건 전체 통과 (5.03s)
- satori 4종 레이아웃 직접 실행: 4/4 성공
- Python image_router 통한 satori 호출: 4/4 성공 + 품질 검증 통과
- 생성 이미지 크기: 175-195KB (최소 10KB 기준 대비 충분)

## 산출물

- `/home/jay/workspace/.worktrees/task-1664.1-dev2/tools/ai-image-gen/image_router.py`
- `/home/jay/workspace/.worktrees/task-1664.1-dev2/tools/ai-image-gen/test_image_router.py`

## 머지 판단
- **머지 필요**: Yes
- **브랜치**: task/task-1664.1-dev2
- **워크트리 경로**: /home/jay/workspace/.worktrees/task-1664.1-dev2
- **머지 의견**: pytest 101건 전체 통과, 기존 테스트 회귀 없음, satori 4종 통합 테스트 100% 성공. 단, main에 uncommitted infographic 기능이 있어 머지 전 main의 변경사항을 먼저 커밋하거나 rebase 필요.

## 모델 사용 기록
- 팀원: 토르(백엔드) / 작업: image_router.py 품질 개선 / 모델: sonnet
- 팀원: 헤임달(테스터) / 작업: 테스트 작성 / 모델: sonnet
- 팀장: 오딘 / 작업: 분석, 검증, 통합, 보고서 / 모델: opus

## 셀프 QC 체크리스트
- [x] 1. 영향 파일: image_router.py, test_image_router.py (2개)
- [x] 2. 엣지 케이스: 빈 파일, 0KB 이미지, PIL 미설치, 존재하지 않는 파일 — 모두 테스트됨
- [x] 3. 작업 지시와 정확히 일치: 프롬프트 품질 강화, QA 검증 추가, satori 안정화 확인
- [x] 4. 에러 처리: PIL ImportError graceful degradation, 파일 부재 처리
- [x] 5. 테스트 커버리지: 15건 신규 추가, 총 101건 전체 통과
- [x] 6. 발견 이슈 모두 해결: 3건 자체 해결, 1건 범위 외 명시
- [x] 7. 코드 아키텍처: 기존 패턴(함수 분리, logging, docstring) 유지
- [x] 8. 인터페이스 변경: `_validate_image_quality` 신규 함수 추가 (기존 API 변경 없음)
- [x] 9. HTML→PNG: 해당 없음 (이미지 생성은 런타임에 수행)
- [x] 10. CLAUDE.md: 수정 없음

## 세션 통계
- 총 도구 호출: 19회

### 수정 파일 목록
- /home/jay/workspace/.worktrees/task-1664.1-dev2/tools/ai-image-gen/test_image_router.py: 7회 (Edit)
- bash_cmd: 6회 (Bash)
- /home/jay/workspace/.worktrees/task-1664.1-dev2/tools/ai-image-gen/image_router.py: 3회 (Edit)
- /home/jay/workspace/memory/reports/task-1664.1.md: 1회 (Write)
- /home/jay/workspace/memory/specs/design-qc-knowhow.md: 1회 (Edit)
- /home/jay/workspace/memory/tasks/task-1664.1.md: 1회 (dispatch)

### 도구 사용 현황
- Edit: 11회
- Bash: 6회
- Write: 1회
- dispatch: 1회