C.E.L_Slide_test2/IMPROVEMENT-PHASE-Q-FIX.md

Phase Q 수정 계획: 정확한 문제 분석 + 정확한 해법

작성일: 2026-03-30 상태: 분석 완료, 수정 대기 근거: Phase Q 5차 테스트 결과 + Phase P/이전 run 비교 분석

---

1. 문제의 정확한 진단

Phase Q에서 바꿔야 했던 것 vs 실제로 바꾼 것

구분	바꿔야 했던 것	실제로 바꾼 것	결과
블록 선택	FAISS+Opus 환각 → 제약 기반	✅ 제대로 바꿈	블록 선택 개선
글자수 예산	없음 → 사전 계산	✅ 제대로 바꿈	overflow 감소
텍스트 채우기	바꾸면 안 됐음	❌ fill_candidates → fill_content로 교체	텍스트 품질 파괴
overflow 조정	피드백 루프 → 수학적 조정	✅ 글루 모델 추가	작동
품질 게이트	없음 → 비전 모델	✅ 추가	작동

핵심 오류: 텍스트 채우기 방식을 바꿔서는 안 됐다.

Phase P의 텍스트 채우기 (잘 작동함)

fill_candidates(): topic 1개 + 후보 블록 3개 → Kei API 1회 호출
                   ↓
Kei가 topic의 source_data를 보고 블록 슬롯에 맞게 풍부하게 채움
                   ↓
결과: 604자 (DX vs BIM 상세 비교), 사례 2건, 출처 포함

Phase P step3_edited_variants.json 실제 결과:

• topic 2 (사례): 2건 모두 포함, 불릿 상세 (스마트건설방안 + 제7차 기본계획)
• topic 3 (핵심): DX vs BIM 8개 항목 비교, 604자
• topic 4 (용어): 3개 용어 풀 정의 + 출처 (국토교통부, 2020 / IBM, 2011)
• topic 5 (결론): 원문 그대로 ("BIM은 건설산업의 디지털전환(DX)을 수행하는 과정에서...")

Phase Q의 텍스트 채우기 (파괴됨)

fill_content(): 전체 블록 5-6개를 한 번에 → Kei API 1회 호출
                ↓
Kei가 한 번에 5-6개 블록을 처리하느라 각 블록을 축약
                ↓
결과: topic당 30-50자 수준으로 과축약

Phase Q step3_fill_content.json 실제 결과:

• topic 2 (사례): 1건만 (제7차 기본계획 누락)
• topic 3 (핵심): "상위개념" 한 단어 수준 (604자 → ~20자)
• topic 4 (용어): 수식어 삭제, 출처 없음
• topic 5 (결론): 원문 보존 (이건 OK)

왜 이렇게 됐나

fill_content()는 원래 Phase O 이전부터 있던 함수로, 전체 슬라이드의 모든 블록을 한 번에 처리한다. 한 번의 API 호출에 블록 5-6개의 슬롯 정보를 모두 담으니, 각 블록에 할당되는 응답 분량이 자연스럽게 줄어든다.

반면 fill_candidates()는 topic 1개씩 개별 호출이므로, Kei가 해당 topic에 집중하여 풍부한 텍스트를 생성한다.

이건 프롬프트 문제가 아니라 호출 구조 문제.

---

2. 정확한 해법

원칙

Phase Q가 개선한 것:  블록 선택 (FAISS → 제약 기반)     ← 유지
Phase P에서 가져올 것: 텍스트 채우기 (topic별 개별 호출)  ← 복원
합치면:              제약 기반 블록 선택 + topic별 풍부한 텍스트 채우기

수정 대상: pipeline.py의 Step 3

현재 (Phase Q — 잘못된 방식):

# 전체 블록을 한 번에 fill_content() 호출
layout_concept = await fill_content(content, layout_concept, analysis)

수정 (Phase P 방식 복원 + Phase Q 블록 선택 유지):

# topic별로 개별 호출 — Phase P의 fill_candidates() 방식
for topic in topics:
    tid = topic.get("id")
    block = selected_blocks.get(tid)
    if not block:
        continue

    # Phase Q에서 선택된 단일 블록을 리스트로 감싸서 fill_candidates 호출
    await fill_candidates(content, topic, [block], analysis)

변경 파일 + 범위

파일	변경	범위
src/pipeline.py	Step 3에서 fill_content() → topic별 fill_candidates() 호출로 교체	~15줄 교체
src/content_editor.py	fill_candidates()에 Phase Q 글자수 예산(_char_budget) 전달 추가	~5줄 추가
src/content_editor.py	EDITOR_PROMPT 변경 롤백 — Phase P 원본으로 복원	프롬프트 복원

건드리지 않는 것

파일	이유
src/block_selector.py	Phase Q 블록 선택 — 잘 작동하고 있음
src/space_allocator.py	예산 계산 + 글루 모델 — 잘 작동하고 있음
src/kei_client.py	Q-4 블록 선택 + Q-6 품질 게이트 — 잘 작동하고 있음
templates/catalog.yaml	Phase Q 메타데이터 — 잘 작동하고 있음
personas/	Kei persona — 절대 수정 금지

---

3. 구체적 수정 내용

3-A: pipeline.py Step 3 교체

# 현재 (삭제 대상)
layout_concept = await fill_content(content, layout_concept, analysis)

# 수정 (Phase P 방식 복원)
from src.content_editor import fill_candidates

yield {"event": "progress", "data": "3/5 Kei 편집자가 텍스트를 정리 중..."}

for topic in topics:
    tid = topic.get("id")
    block = selected_blocks.get(tid)
    if not block:
        continue

    # fill_candidates는 topic 1개 + 블록 리스트를 받으므로 [block]으로 감쌈
    await fill_candidates(content, topic, [block], analysis)

    logger.info(
        f"[Q Step 3] topic {tid}: {block['type']} → "
        f"data={'있음' if block.get('data') else '없음'}"
    )

3-B: fill_candidates()에 Phase Q 예산 전달

fill_candidates()의 컨테이너 제약 전달 부분에 _char_budget도 포함:

# fill_candidates() 내부 — 이미 _container_height_px 전달하는 부분에 추가
char_budget = block.get("_char_budget", {})
if char_budget:
    section += (
        f"\n  ★ 글자수 예산 (하드 제약):"
        f"\n    총 글자: {char_budget.get('total_chars', '제한 없음')}자"
        f"\n    최대 항목: {char_budget.get('max_items', '제한 없음')}개"
        f"\n    항목당 글자: {char_budget.get('chars_per_item', '제한 없음')}자"
    )

3-C: EDITOR_PROMPT 롤백

Phase Q에서 5번 수정한 EDITOR_PROMPT를 Phase P 원본 기반으로 복원. 단, Phase Q의 핵심 규칙 2개만 추가:

1. "글자수 예산(★) 초과 금지"
2. "source_data가 있으면 그것을 우선 사용"

---

4. 기대 효과

지표	Phase P (20점)	Phase Q 현재	Phase Q 수정 후 (예상)
블록 선택	3종류, 유령 5개	5종류, 유령 0개	5종류, 유령 0개 (유지)
텍스트 품질	풍부 (604자)	축약 (~30자)	풍부 (Phase P 수준 복원)
overflow	213px	0~45px	예산 제약으로 방지
사례 수	2건	1건	2건 (복원)
용어 정의	풀 버전	축약	풀 버전 + 출처 (복원)
의미 왜곡	있음 (순차↔포함)	없음	없음 (유지)
처리 시간	~40분	~6분	~8분 (topic별 호출 추가)

---

5. 교훈

1. 작동하는 것을 바꾸지 마라. Phase P의 텍스트 채우기는 잘 작동했다. Phase Q에서 바꿀 이유가 없었다.
2. 프롬프트 탓을 하기 전에 호출 구조를 확인하라. 5번 프롬프트를 수정했지만, 문제는 "한 번에 6개 블록 요청"이라는 호출 구조였다.
3. 이전 결과물과 비교하라. step3_edited_variants.json(Phase P)과 step3_fill_content.json(Phase Q)을 처음부터 비교했으면 원인을 즉시 찾았을 것이다.
4. 조사 결과를 적용할 때, 기존에 잘 작동하는 부분은 보존하라. "계산 먼저, AI 판단 나중에"는 블록 선택에 적용할 원칙이었지, 텍스트 채우기에 적용할 원칙이 아니었다.