From 1c65255f04f1f218de85180b36d763d7dd06692f Mon Sep 17 00:00:00 2001 From: kyeongmin Date: Thu, 26 Mar 2026 09:29:50 +0900 Subject: [PATCH] =?UTF-8?q?Phase=20I=20=EA=B3=84=ED=9A=8D=20=EC=88=98?= =?UTF-8?q?=EB=A6=BD:=20=EC=A0=84=EC=88=98=20=EC=A0=95=ED=95=A9=EC=84=B1?= =?UTF-8?q?=20=EB=B3=B5=EA=B5=AC=20+=2010=EA=B0=80=EC=A7=80=20=EB=9F=B0?= =?UTF-8?q?=ED=83=80=EC=9E=84=20=EB=AC=B8=EC=A0=9C=20=ED=95=B4=EA=B2=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 전수 검토 결과 발견: - 실제 블록 38개 (문서 46개 표기 → 8개 미존재) - STEP_B_PROMPT가 미존재 블록 3개를 적극 추천 (프롬프트 자기모순) - catalog.yaml not_for에서 미존재 블록 참조 - 슬롯 의미 미전달 → 편집자가 source/rows/cards 채우지 못함 13개 항목 3패턴 분류: A. 프롬프트 자기모순 해소 (I-1~I-3) B. 슬롯 의미 전달 (I-4~I-5) C. 코드 안전망 확장 (I-6~I-9) D. 문서 동기화 (I-10~I-13) Co-Authored-By: Claude Opus 4.6 (1M context) --- IMPROVEMENT-PHASE-I.md | 308 +++++++++++++++++++++++++++++++++++++++++ IMPROVEMENT.md | 28 ++++ 2 files changed, 336 insertions(+) create mode 100644 IMPROVEMENT-PHASE-I.md diff --git a/IMPROVEMENT-PHASE-I.md b/IMPROVEMENT-PHASE-I.md new file mode 100644 index 0000000..d861606 --- /dev/null +++ b/IMPROVEMENT-PHASE-I.md @@ -0,0 +1,308 @@ +# Phase I: 전수 정합성 복구 + 10가지 런타임 문제 해결 — 실행 상세 + +> 전수 검토에서 발견된 프롬프트 자기모순, 문서-코드 불일치, 코드 안전망 부족을 해결. +> 원칙: 하드코딩 금지. 범용 해결. 회귀 금지. persona_agent 수정 0건. + +--- + +## 문제 진단 총괄 + +### 전수 검토에서 발견된 근본 원인 + +**실제 블록 수: 38개** (문서는 46개로 표기) +삭제된 8개: card-text-grid, quote-left-border, conclusion-accent-bar, details-block, layer-diagram, timeline-vertical, timeline-horizontal, pyramid-hierarchy + +이 8개가 삭제되었지만 프롬프트, catalog, INDEX.md, README.md에 여전히 참조되고 있음. +→ AI가 존재하지 않는 블록을 선택 → 부적절한 강제 교체 → 빈 블록, 잘못된 배치 + +--- + +## 패턴 A: 프롬프트 자기모순 (문제 2, 7) + +### I-1: STEP_B_PROMPT purpose 가이드에서 미존재 블록 제거 + +**현재 문제:** +```python +# design_director.py 264~271행 +"- 근거사례 → quote-left-border, card-text-grid" ← 둘 다 미존재! +"- 용어정의 → card-text-grid" ← 미존재! +"- 구조시각화 → venn-diagram, layer-diagram" ← layer-diagram 미존재! +``` + +허용 목록에는 없는데 purpose 가이드에서 적극 추천 → **프롬프트 자기모순** → Sonnet이 미존재 블록 선택 + +**수정:** +``` +- 근거사례 → quote-big-mark (출처 포함), card-icon-desc (항목 나열) +- 용어정의 → card-icon-desc (정의+출처), card-numbered (순서 있으면) +- 구조시각화 → venn-diagram (단독 배치) +``` + +**수정 파일:** src/design_director.py (STEP_B_PROMPT) + +--- + +### I-2: catalog.yaml의 not_for/when에서 미존재 블록 참조 제거 + +**현재 문제:** +- circle-gradient not_for: "topic-header" → 실제 이름은 topic-left-right/topic-center/topic-numbered +- circle-gradient not_for: "conclusion-accent-bar" → 미존재. 실제는 banner-gradient +- process-horizontal not_for: "timeline" → 미존재. 실제 없음 (삭제됨) + +**수정:** catalog.yaml 전체에서 미존재 블록 참조를 실존 블록으로 교체 + +**수정 파일:** templates/catalog.yaml + +--- + +### I-3: 미등록 블록 교체를 purpose 기반으로 변경 + +**현재 문제:** +```python +# design_director.py 574행 +block["type"] = "callout-solution" # 모든 미등록 블록을 일괄 교체 +``` + +결론 꼭지의 미등록 블록도 callout-solution으로 교체 → 의미적으로 부적절 + +**수정:** purpose 기반 교체 맵 +```python +PURPOSE_FALLBACK = { + "문제제기": "callout-warning", + "근거사례": "quote-big-mark", + "핵심전달": "comparison-2col", + "용어정의": "card-icon-desc", + "결론강조": "banner-gradient", + "구조시각화": "card-icon-desc", +} +# 미등록 블록 거부 시: block의 purpose를 보고 적절한 대체 블록 선택 +fallback_type = PURPOSE_FALLBACK.get(block.get("purpose", ""), "callout-solution") +``` + +**수정 파일:** src/design_director.py + +--- + +## 패턴 B: 슬롯 의미 정보 미전달 (문제 3, 5, 9, 10) + +### I-4: BLOCK_SLOTS에 slot_desc 추가 + +**현재 문제:** +편집자가 슬롯 이름만 받고 의미를 모름: +- source에 출처가 아닌 꼭지 제목을 넣음 (문제 3) +- text/sub_text 순서를 뒤집음 (문제 5) +- rows[][] 배열 구조를 채우지 못함 (문제 9) +- cards[] 배열 구조를 채우지 못함 (문제 10) + +**수정:** BLOCK_SLOTS에 slot_desc 필드 추가 +```python +"quote-big-mark": { + "required": ["quote_text"], + "optional": ["source"], + "slot_desc": { + "quote_text": "인용할 본문 텍스트", + "source": "출처 (예: 국토교통부, 2024). 꼭지 제목이 아님!", + }, +}, +"banner-gradient": { + "required": ["text"], + "optional": ["sub_text"], + "slot_desc": { + "text": "핵심 결론 한 줄 (굵은 대형 텍스트. 가장 중요한 메시지)", + "sub_text": "부연 설명 (작은 보조 텍스트. text보다 덜 중요)", + }, +}, +"compare-2col-split": { + "required": ["left_title", "right_title", "rows"], + "optional": [], + "slot_desc": { + "left_title": "왼쪽 열 헤더", + "right_title": "오른쪽 열 헤더", + "rows": "비교 행 배열. 각 행: {criteria: '비교 기준', left: '왼쪽 내용', right: '오른쪽 내용'}. 최소 3행.", + }, +}, +``` + +**수정 범위:** 38개 블록 모두에 slot_desc 추가 (가장 큰 작업) + +### I-5: 편집자 프롬프트에 slot_desc 전달 + +**현재:** content_editor.py 87~88행 +```python +f" 필수 슬롯: {slots.get('required', [])}\n" +f" 선택 슬롯: {slots.get('optional', [])}" +``` + +**수정:** +```python +f" 필수 슬롯: {slots.get('required', [])}\n" +f" 선택 슬롯: {slots.get('optional', [])}\n" +# slot_desc가 있으면 각 슬롯의 의미 전달 +slot_desc = slots.get("slot_desc", {}) +if slot_desc: + desc_lines = [f" {k}: {v}" for k, v in slot_desc.items()] + req_text += "\n 슬롯 설명:\n" + "\n".join(desc_lines) +``` + +**수정 파일:** src/content_editor.py, src/design_director.py (BLOCK_SLOTS) + +--- + +## 패턴 C: 코드 안전망 부족 (문제 1, 4, 6, 8) + +### I-6: 제목 유사도 검증 (문제 1) + +**현재:** 프롬프트에 "달라야 한다"고 지시했지만 코드 검증 없음 + +**수정:** pipeline.py 또는 design_director.py에서 `analysis["title"]`과 `analysis["topics"][0]["title"]` 비교 +```python +from difflib import SequenceMatcher +title = analysis.get("title", "") +first_topic_title = analysis.get("topics", [{}])[0].get("title", "") +similarity = SequenceMatcher(None, title, first_topic_title).ratio() +if similarity > 0.7: + # 첫 꼭지 제목을 purpose 기반으로 변경 + first_topic = analysis["topics"][0] + purpose = first_topic.get("purpose", "문제제기") + first_topic["title"] = f"{purpose}: {first_topic.get('summary', '')[:30]}" + logger.warning(f"[제목 중복 교정] 유사도 {similarity:.0%} → 첫 꼭지 제목 변경") +``` + +**수정 파일:** src/pipeline.py + +### I-7: compare-pill-pair 단독 사용 금지 (문제 4) + +**현재:** compare-pill-pair가 비교 내용 없이 라벨만 표시 + +**수정:** _validate_height_budget() 안에서 compare-pill-pair가 해당 zone에서 유일한 "비교" 블록이면 경고 +```python +# compare-pill-pair는 비교 테이블의 헤더로만 사용 +# 같은 zone에 compare-2col-split, compare-3col-badge, comparison-2col이 없으면 부적절 +COMPARISON_BLOCKS = {"compare-2col-split", "compare-3col-badge", "comparison-2col"} +for area, area_blocks in zone_blocks.items(): + types = {b.get("type") for b in area_blocks} + if "compare-pill-pair" in types and not types & COMPARISON_BLOCKS: + # pill-pair를 comparison-2col로 교체 + for block in area_blocks: + if block.get("type") == "compare-pill-pair": + block["type"] = "comparison-2col" + logger.warning(f"[pill-pair 단독 금지] compare-pill-pair → comparison-2col") +``` + +**수정 파일:** src/design_director.py + +### I-8: 대형 테이블 → detail_target 자동 설정 (문제 6) + +**현재:** 원본의 12행 비교표가 detail_target으로 잡히지 않음 + +**수정:** pipeline.py에서 1단계-B 완료 후 +```python +for table in analysis.get("tables", []): + if table.get("rows", 0) >= 5 and not table.get("fits_single_page", True): + for topic in analysis.get("topics", []): + if topic.get("id") == table.get("topic_id"): + if not topic.get("detail_target"): + topic["detail_target"] = True + logger.info(f"대형 테이블 → detail_target 자동: topic {topic['id']}") +``` + +**수정 파일:** src/pipeline.py + +### I-9: DOWNGRADE_MAP 확장 + 다단계 교체 (문제 8) + +**현재:** body 높이 600px > 490px인데 medium 블록 교체 대상 없음 + +**수정:** +1. medium → compact 교체 맵 추가 +2. 교체 임계치 `>= 250` → `>= 150`으로 낮춤 +3. 1회 교체 후에도 초과이면 다음 블록도 교체 (현재는 break) + +```python +DOWNGRADE_MAP = { + # 기존 large/xlarge → medium/compact + "venn-diagram": "card-icon-desc", + "card-step-vertical": "card-numbered", + ... + # 추가: medium → compact + "quote-big-mark": "divider-text", + "comparison-2col": "compare-pill-pair", # 주의: I-7 규칙과 함께 적용 + "process-horizontal": "flow-arrow-horizontal", + "dark-bullet-list": "highlight-strip", + "card-icon-desc": "highlight-strip", +} +``` + +**수정 파일:** src/design_director.py + +--- + +## 문서 동기화 + +### I-10: INDEX.md 동기화 (38개 실제 현황) + +미존재 8개 블록 항목 제거: card-text-grid, quote-left-border, conclusion-accent-bar, details-block, layer-diagram, timeline-vertical, timeline-horizontal, pyramid-hierarchy + +**수정 파일:** templates/blocks/INDEX.md + +### I-11: README.md 동기화 + +- "46개 + _legacy 13개" → "38개" +- Sonnet fallback 표기 제거 (Phase G에서 제거됨) +- 블록 트리 구조에서 미존재 블록 제거 +- 각 카테고리 개수 수정: cards 9, visuals 6, emphasis 10 + +**수정 파일:** README.md + +### I-12: BLOCK_SLOTS 주석 수정 + +- "visuals/ (10개)" → "visuals/ (6개)" +- "emphasis/ (12개)" → "emphasis/ (10개)" + +**수정 파일:** src/design_director.py (주석만) + +### I-13: 데드 코드 정리 + +- `_call_anthropic_direct()` 함수 제거 (kei_client.py) — G-2에서 호출 제거했지만 함수 자체는 잔존 + +**수정 파일:** src/kei_client.py + +--- + +## 수정 파일 총괄 + +| 파일 | 항목 | 변경 성격 | +|------|------|----------| +| `src/design_director.py` | I-1, I-3, I-7, I-9, I-12 | purpose 가이드 교체 + 교체 맵 개선 + pill-pair 검증 + DOWNGRADE 확장 + 주석 | +| `src/design_director.py` (BLOCK_SLOTS) | I-4 | 38개 블록에 slot_desc 추가 | +| `src/content_editor.py` | I-5 | 편집자에게 slot_desc 전달 | +| `src/pipeline.py` | I-6, I-8 | 제목 유사도 + detail_target 자동 | +| `src/kei_client.py` | I-13 | 데드 코드 제거 | +| `templates/catalog.yaml` | I-2 | not_for 미존재 블록 참조 교체 | +| `templates/blocks/INDEX.md` | I-10 | 미존재 블록 제거 | +| `README.md` | I-11 | 블록 수 + fallback + 트리 구조 동기화 | + +--- + +## 검증 체크리스트 + +- [ ] I-1: STEP_B_PROMPT의 purpose 가이드에 미존재 블록 0건 +- [ ] I-2: catalog.yaml의 not_for/when에 미존재 블록 참조 0건 +- [ ] I-3: 미등록 블록 교체가 purpose 기반으로 동작 +- [ ] I-4: BLOCK_SLOTS 38개 블록 모두에 slot_desc 존재 +- [ ] I-5: 편집자 프롬프트에 슬롯 설명 포함 +- [ ] I-6: 제목 유사도 70% 이상 시 자동 교정 +- [ ] I-7: compare-pill-pair 단독 사용 시 comparison-2col로 교체 +- [ ] I-8: 5행 이상 테이블 → detail_target 자동 true +- [ ] I-9: body 높이 초과 시 medium 블록도 교체 가능 +- [ ] I-10: INDEX.md에 미존재 블록 0건 +- [ ] I-11: README.md 블록 수 38개, Sonnet fallback 표기 없음 +- [ ] I-12: BLOCK_SLOTS 주석이 실제 개수와 일치 +- [ ] I-13: _call_anthropic_direct() 함수 없음 + +--- + +## 수정 이력 + +| 날짜 | 내용 | +|------|------| +| 2026-03-26 | 초안. 전수 정합성 검토 기반 13개 항목. 3패턴(프롬프트 모순 + 슬롯 의미 + 코드 안전망) 분류. | diff --git a/IMPROVEMENT.md b/IMPROVEMENT.md index be5c831..7aeece0 100644 --- a/IMPROVEMENT.md +++ b/IMPROVEMENT.md @@ -328,6 +328,34 @@ CLAUDE.md 요구사항 전수검토 결과 발견된 미구현/부분구현/위 --- +## Phase I: 전수 정합성 복구 + 10가지 런타임 문제 해결 (13개) + +> **실행 상세:** [IMPROVEMENT-PHASE-I.md](IMPROVEMENT-PHASE-I.md) +> 전수 검토에서 발견된 프롬프트 자기모순 + 슬롯 의미 미전달 + 코드 안전망 부족 해결. + +### 패턴 A: 프롬프트 자기모순 (I-1~I-3) — 최우선 +- I-1: STEP_B_PROMPT에서 미존재 블록 3개(quote-left-border, card-text-grid, layer-diagram) → 실존 블록으로 교체 +- I-2: catalog.yaml not_for에서 미존재 블록 참조 → 실존 블록으로 교체 +- I-3: 미등록 블록 교체를 callout-solution 일괄 → purpose 기반 교체 맵 + +### 패턴 B: 슬롯 의미 미전달 (I-4~I-5) +- I-4: BLOCK_SLOTS 38개 블록에 slot_desc 추가 (각 슬롯의 의미/예시/구조) +- I-5: 편집자 프롬프트에 slot_desc 전달 + +### 패턴 C: 코드 안전망 (I-6~I-9) +- I-6: 제목 유사도 검증 (70% 이상 → 자동 교정) +- I-7: compare-pill-pair 단독 사용 금지 (비교 테이블 없으면 comparison-2col로 교체) +- I-8: 대형 테이블(5행+) → detail_target 자동 설정 +- I-9: DOWNGRADE_MAP 확장 (medium → compact) + 다단계 교체 + +### 문서 동기화 (I-10~I-13) +- I-10: INDEX.md 미존재 블록 제거 (46→38) +- I-11: README.md 동기화 (블록 수, Sonnet fallback 제거) +- I-12: BLOCK_SLOTS 주석 수정 +- I-13: 데드 코드(_call_anthropic_direct) 제거 + +--- + ## Phase별 의존 관계 ```