# 이미지 제작 토큰 최적화 방안 스펙 (v2.0 — 퀄리티 보존판)

**작성일**: 2026-03-29
**최종 수정**: 2026-03-29 (task-1267.1 퀄리티 재검토 반영)
**작성자**: 오딘 (dev2-team, 원본) → 헤르메스 (dev1-team, v2.0 통합)
**관련 작업**: task-1263.1, task-1265.1 (로키 재검토), task-1267.1 (퀄리티 집대성)
**목표**: 이미지 5장 제작+QC 토큰 사용량 50-65% 절감 (퀄리티 보존 전제)

---

## 핵심 원칙

1. **퀄리티 최우선** — 절감률보다 결과물 품질이 우선
2. **GREEN → YELLOW → RED 순서** — 퀄리티 안전한 것부터 적용
3. **안전장치 없이 적용 금지** — YELLOW 방안은 반드시 명시된 보호 장치와 함께 적용
4. **실측 후 확대** — Wave 1 효과를 측정한 후 Wave 2 진행

---

## 절감률 기준 (로키 보정값 + 퀄리티 안전 기준)

- Wave 1 (GREEN): 15-22% 절감, 퀄리티 위험 제로
- Wave 1+2 (GREEN+YELLOW 핵심): 35-50% 절감
- Wave 1+2+3 (검증 완료): 45-60% 절감
- 전체: 50-65% 절감

**주의**: 원본 스펙의 "70% 이상" 목표는 과대추정. 50-65%로 하향 조정.

---

## Wave 1: 즉시 적용 (1-2일) — GREEN 전량

### W1-1. 선택적 노하우 로딩 (난이도: Easy, 절감: 2-3%)

**변경 대상**: `prompts/image_workflow.py` → `build_phase_minus1_prompt`

**퀄리티 영향**: (+) 향상 — 불필요한 컨텍스트 제거로 모델 집중도 상승

**구현 방법**:
Phase -1 프롬프트에 위임 라운드별 조건 분기 추가:
```
## 노하우 프리로딩 (선택적)
- 1차 위임 (카피 Phase): knowhow-marketing.md + design-qc-knowhow.md만 읽으세요
- 2차 위임 (디자인 Phase): knowhow-design.md + design-qc-knowhow.md만 읽으세요
- 3차 위임 (최종 검증): 3개 파일 모두 읽으세요
```

**Phase-노하우 매핑 테이블**:
- 1차 위임 (Phase -1~2): marketing + QC knowhow (~3.4K tok)
- 2차 위임 (Phase 2.5~3.5): design + QC knowhow (~4.4K tok → 보정: 6.0KB design + 5.1KB QC)
- 3차 위임 (Phase 4~5): 전체 3파일 (~5.4K tok → 보정값, 원본 4.7K에서 상향)

### W1-2. dispatch.py 이중 적재 해결 (난이도: Easy, 절감: 3-5%)

**변경 대상**: `/home/jay/workspace/dispatch.py` → `build_workflow_overview_prompt` 관련 로직
(경로 정정: 원본의 `prompts/dispatch.py`는 오류, 실제 경로는 루트 레벨)

**퀄리티 영향**: (+) 향상 — QC 기준 이중 적재로 인한 모델 혼동 제거

**구현 방법**:
1. `build_workflow_overview_prompt()`에서 `_build_category_a_section`, `_build_category_b_section`, `_build_fail_categories_section`, `_build_escalation_section` 호출 제거
2. 대신 안내 문구 추가:
```
## QC 기준 안내
QC 기준(A카테고리, B카테고리, FAIL 기준, 에스컬레이션)은 각 Phase 프롬프트에서 로딩됩니다.
여기서는 워크플로우 흐름과 Phase 순서에 집중하세요.
```

### W1-3. 에스컬레이션 섹션 중복 제거 (난이도: Easy, 절감: 2-4%)

**변경 대상**: `prompts/image_workflow.py` 내 7개 함수

**퀄리티 영향**: (0) 중립 — 에스컬레이션 규칙은 참조용

**구현 방법**:
1. 에스컬레이션 규칙을 별도 파일로 추출:
   - 경로: `memory/specs/escalation-rules.md`
   - 내용: 현재 `_build_escalation_section()` 반환값
2. 7개 함수에서 `_build_escalation_section()` 호출을 파일 참조로 교체:
```python
# Before:
f"{_build_escalation_section()}\n"

# After:
f"## 에스컬레이션 규칙\n"
f"- 참조: {{WORKSPACE_ROOT}}/memory/specs/escalation-rules.md\n"
```

**영향 함수** (로키 검증 결과, 정정됨):
- `build_phase0_prompt` (Phase 0)
- `build_phase1_prompt` (Phase 1)
- `build_phase2_prompt` (Phase 2)
- `build_phase3_prompt` (Phase 3)
- `build_phase3_5_prompt` (Phase 3.5)
- `build_phase4_prompt` (Phase 4)
- `build_workflow_overview_prompt` (overview) → W1-2에서 이미 제거

### W1-4. Sub-agent 결과 구조화 (난이도: Easy, 절감: 10-15%)

**변경 대상**: `prompts/DIRECT-WORKFLOW.md`, `prompts/team_prompts.py`

**퀄리티 영향**: (+) 향상 — 구조화된 결과로 팀장 판단 정확도 상승, context rot 방지

**구현 방법**:
DIRECT-WORKFLOW.md에 규칙 추가:
```
## 서브에이전트 결과 크기 제한 (필수)
Task tool로 팀원을 호출할 때:
1. 결과 요약을 500자(약 200토큰) 이내로 제한
2. 상세 내용은 파일에 저장하도록 지시 (memory/cache/{task_id}-{역할}-result.md)
3. 요약 필수 포함: 성공/실패 상태, FAIL 항목 수와 코드, 다음 단계 필요 행동
4. "FAIL 존재 시 반드시 FAIL 코드와 사유를 요약에 포함" (누락 금지)
```

---

## Wave 2: 조건부 적용 (3-7일) — YELLOW 핵심

### W2-1. /compact 강제 삽입 (난이도: Easy, 절감: 10-15%)

**변경 대상**: `prompts/image_workflow.py`

**퀄리티 영향**: 조건부 — 적용 위치가 핵심

**구현 방법**:
Phase 완료 프롬프트에 아래 지시 추가:
```
## 세션 관리 (필수)
- Phase 완료 후, 다음 Phase 진입 전 /compact 실행
- ⚠️ QC 사이클 진행 중(Phase 1.5, 3.5 내부)에서는 /compact 금지
- 컨텍스트 70% 이상이면 즉시 /compact (단, 사이클 중이면 사이클 완료 후)
- /compact 전 반드시 체크포인트 저장: memory/checkpoints/{task_id}.md
```

**적용 위치**: `build_phase2_prompt` (Phase 2 완료 후), `build_phase3_prompt` (Phase 3 완료 후), `build_phase4_prompt` (Phase 4 완료 후)
**적용 제외**: `build_phase1_5_prompt`, `build_phase3_5_prompt` (사이클 내부)

**퀄리티 보호 장치**:
- compact 금지 구간: Phase 1.5, 3.5 사이클 내부
- compact 허용 구간: Phase 간 전환점만
- 체크포인트 필수 저장
- 서브에이전트 내에서는 적용 불가 (메인 세션 수준만)

### W2-2. 저해상도 QC 이미지 (난이도: Easy, 절감: 25-40%)

**변경 대상**: 이미지 QC 파이프라인 (새 유틸리티 스크립트)

**퀄리티 영향**: 조건부 — 해상도와 대상 카테고리가 핵심

**구현 방법**:
1. 유틸리티 스크립트 생성: `teams/shared/qc-resize.py`
```python
from PIL import Image

def create_qc_thumbnail(input_path: str, output_path: str, size: int = 540):
    """QC용 썸네일 생성. 최소 540x540."""
    img = Image.open(input_path)
    img.thumbnail((size, size), Image.LANCZOS)
    img.save(output_path, quality=95)
```

2. Phase 3.5/4 프롬프트에 조건 추가:
```
## QC 이미지 해상도 최적화
- B카테고리(디자인 품질) 시각 평가: 540x540 QC 이미지 사용 가능
  - QC 이미지 경로: memory/cache/{task_id}-qc-thumb-{N}.png
- A카테고리(기술 검증): 반드시 1080x1080 원본 사용 (해상도 민감)
- Phase 4 최종 검증: 반드시 1080x1080 원본 사용
```

**퀄리티 보호 장치**:
- 최소 해상도: 540x540 (360 사용 금지)
- A카테고리: 원본 필수 (기술 검증은 해상도 민감)
- Phase 4 최종 검증: 원본 필수
- B카테고리만 저해상도 허용

### W2-3. 노하우 요약 캐시 (난이도: Easy, 절감: 3-5%)

**변경 대상**: `prompts/image_workflow.py` → `build_phase_minus1_prompt`

**퀄리티 영향**: 조건부 — 요약 품질이 핵심

**구현 방법**:
Phase -1 프롬프트 말미에 캐시 지시 추가:
```
## 노하우 요약 캐시 (2/3차 위임 효율화)
1차 위임에서 노하우를 읽은 후:
1. 핵심 요약을 memory/cache/knowhow-summary-{task_id}.md에 저장
2. 필수 포함 섹션:
   - 핵심 규칙 (5개 이내)
   - 예외 및 조건부 규칙 (전부 포함, 누락 금지)
   - 수치 기준 (px, 비율 등 정확한 숫자)
3. 2/3차 위임에서는 캐시가 존재하면 캐시만 읽기
4. 캐시에 없는 내용이 필요하면 원본 파일 참조
```

**퀄리티 보호 장치**:
- 예외 규칙 전용 섹션 필수 포함
- "불확실하면 원본 참조" 원칙
- 수치 기준 정확성 검증

### W2-4. Delta QC — 이미지 단위만 (난이도: Medium, 절감: 15-25%)

**변경 대상**: `prompts/image_workflow.py` → Phase 1.5, 3.5

**퀄리티 영향**: 조건부 — delta 범위가 핵심

**구현 방법**:
1. QC 결과 저장:
   - 경로: `memory/cache/{task_id}-qc-cycle{N}.json`
   - 내용: 이미지별 PASS/FAIL + 항목별 점수

2. 사이클 2/3 프롬프트:
```
## 차분 QC (이전 사이클 참조)
- 이전 사이클 결과: memory/cache/{task_id}-qc-cycle{N-1}.json
- PASS 이미지: 재검수 불필요 (이전 점수 유지)
- FAIL 이미지만 재검수 (전 항목 재채점)
- ⚠️ 주의: 항목 단위 delta는 금지. FAIL 이미지는 전 항목을 다시 평가
- ⚠️ 구조적 변경 시 전체 재채점: 텍스트 길이 변경, 레이아웃 이동, 요소 추가/삭제
```

**퀄리티 보호 장치**:
- 이미지 단위 delta만 허용 (항목 단위 금지)
- FAIL 이미지는 전 항목 재채점
- 구조적 변경 시 전체 재채점 규칙

---

## Wave 3: 검증 후 적용 (1-3주)

### W3-1. QC 기준 외부 파일화 (난이도: Easy, 절감: 3-7%)

**전제**: A/B 테스트 실시 — 인라인 vs 외부파일 → 실제 토큰 비교

**변경 대상**: `prompts/image_workflow.py`

**구현 방법**:
1. `memory/specs/qc-criteria-compact.md` 생성 (A+B+FAIL 기준 통합)
2. 각 Phase에서 인라인 → 파일 참조 교체

**영향 함수** (로키 정정 반영):
- `build_phase2_prompt` (A+B+FAIL 섹션)
- `build_phase3_5_prompt` (A 섹션)
- `build_phase4_prompt` (A+B+FAIL 섹션)
(원본의 `build_phase0_5_prompt`, `build_phase1_5_prompt`는 QC 섹션 없음 — 수정 대상에서 제거)

**퀄리티 보호 장치**: 프롬프트에 "QC 기준 파일을 반드시 Read하고, Read 결과를 인용하여 채점하라" 명시

### W3-2. Playwright 기반 A카테고리 자동 QC (난이도: Medium-Hard, 절감: 20-35%)

**전제**: 2주 병행 검증 → 일치율 95%+ 확인

**변경 대상**: 새 파일 `teams/shared/auto-qc.py` + `prompts/image_workflow.py`

**구현 방법**: 원본 스펙 B-1과 동일하되:
- 난이도 상향: Easy-Medium → Medium-Hard (로키 보정)
- 1단계: HTML 기반 이미지만 대상 (PNG는 수동 유지)
- 병행 검증 기간 2주 필수

**퀄리티 보호 장치**:
- 병행 검증: 자동 QC + 수동 QC 동시 실행 → 불일치 건 분석
- 일치율 95%+ 달성 후에만 자동만 적용
- 자동 QC 결과 JSON 로깅 (사후 감사 가능)

### W3-3. 이미지 배치 QC (난이도: Medium, 절감: 8-12%)

**구현 방법**: 원본 방안6과 동일하되 배치 크기 2장 제한

**퀄리티 보호 장치**: 배치 크기 2장, 항목별 체크리스트 강제

---

## Wave 4: 전제조건 충족 후 (1개월+) — RED

### W4-1. Phase 통합 — 위임 라운드 축소 (난이도: Hard, 절감: 15-25%)

**전제조건** (3개 모두 충족 필수):
1. W2-1 (/compact) 적용 및 효과 검증 완료
2. W2-2 (저해상도 QC 이미지) 적용 및 효과 검증 완료
3. W3-2 (Playwright 자동 QC) 적용 및 일치율 95%+ 확인

**구현 방법**: 원본 C-1과 동일
- 3회 위임 → 2회로 축소
- 1차: Phase -1~2, 2차: Phase 2.5~5

### W4-2. 모델 계층 최적화 (비용 절감, 토큰 수 동일)

**전제조건**: A카테고리 벤치마크 20건 → Haiku vs Sonnet 일치율 90%+ 확인

**구현 방법**:
- A카테고리(기술 QC): Haiku 모델 사용
- B카테고리(디자인 평가): Sonnet 고정
- 모델 분기 로직을 Phase 프롬프트에 추가

---

## 구현 체크리스트

### Wave 1 (즉시)
- [ ] W1-1: Phase -1 프롬프트에 위임 라운드별 노하우 선택 조건 추가
- [ ] W1-2: build_workflow_overview_prompt에서 QC 기준 상세 제거
- [ ] W1-3: escalation-rules.md 생성 + 7개 함수에서 파일 참조 교체
- [ ] W1-4: DIRECT-WORKFLOW.md에 서브에이전트 결과 크기 제한 규칙 추가

### Wave 2 (조건부)
- [ ] W2-1: Phase 간 전환 프롬프트에 /compact 지시 추가 (사이클 내 금지 명시)
- [ ] W2-2: qc-resize.py 생성 + Phase 3.5/4 프롬프트에 저해상도 조건 추가
- [ ] W2-3: Phase -1 프롬프트에 노하우 캐시 로직 추가
- [ ] W2-4: Phase 1.5/3.5 프롬프트에 이미지 단위 delta QC 추가

### Wave 3 (검증 후)
- [ ] W3-1: A/B 테스트 실시 → 결과 기반 외부 파일화 여부 결정
- [ ] W3-2: auto-qc.py 개발 + 2주 병행 검증
- [ ] W3-3: 배치 QC 프롬프트 수정

### Wave 4 (전제조건 후)
- [ ] W4-1: 위임 라운드 축소 설계 (전제조건 3개 충족 확인)
- [ ] W4-2: Haiku 벤치마크 20건 실시 → 결과 기반 적용 여부 결정

---

## 측정 방안

### 토큰 사용량 추적 (원본 유지)
task-timer.py에 추가 가능한 필드:
- `estimated_input_tokens`: 입력 토큰 추정값
- `estimated_output_tokens`: 출력 토큰 추정값
- `compact_count`: /compact 실행 횟수
- `image_read_count`: 이미지 Read 횟수

### 비교 기준
- 현재 기준: task-1259.1 (1시간 19분, 토큰 소진)
- 목표: 동일 작업(5장 이미지 제작+QC)을 토큰 소진 없이 완료
- KPI: 작업 완료율 (현재 0% → 목표 100%), 소요 시간, 토큰 사용량

### Wave별 효과 측정
- Wave 1 적용 후 첫 이미지 제작에서 토큰 사용량 측정
- Wave 1 기준선 대비 Wave 2 효과 측정
- 각 Wave 완료 시 보고서에 실측값 기록

---

## 리스크 및 완화

**리스크 1: /compact로 중요 컨텍스트 손실**
- 완화: QC 사이클 내 compact 금지 + 체크포인트 필수 저장
- 심각도: Medium → Low (보호 장치 적용 시)

**리스크 2: 저해상도 QC에서 미세 품질 문제 미발견**
- 완화: A카테고리/최종검증은 원본 필수, B카테고리만 저해상도
- 심각도: Medium → Low (보호 장치 적용 시)

**리스크 3: Playwright 자동 QC의 False PASS**
- 완화: 2주 병행 검증 + 95% 일치율 게이트
- 심각도: High → Low (병행 검증 기간 동안)

**리스크 4: Phase 통합 시 context rot**
- 완화: RED 분류, 전제조건 3개 충족 후에만 진행
- 심각도: High → Low (전제조건 게이트)

**리스크 5: 노하우 요약 캐시의 예외 규칙 누락**
- 완화: 예외 규칙 전용 섹션 필수 + "불확실하면 원본" 원칙
- 심각도: Medium → Low (보호 장치 적용 시)