# WBS-9.6: LLM 레이더 문서 최적화 전략

**상태**: 2026-06-22 초안 완료  
**목표**: LLM 독해 오류율 50% 이상 감소

---

## 현황 분석

### 문서 규모
- **총 문서 수**: ~160개 (spec/, docs/, prompts/)
- **읽음 순서 최적화도**: 0% (무작위 순서로 로드)
- **신뢰도 레벨 정의**: 미흡
- **의존성 명시도**: 50% (일부 파일만 명시)

### 문제점
1. **순서 문제**: 기초 개념 전에 고급 개념 로드
2. **중복성**: 같은 내용이 여러 파일에 산재
3. **오래된 문서**: deprecated 파일 여전히 로드
4. **명확성 부족**: 약자, 약관 정의 불일치

### LLM 독해 오류 유형 (추정)
- Type A: 기초 개념 미이해 (40%)
- Type B: 문서 순서 오류로 인한 모순 (30%)
- Type C: 동일 내용 다중 정의 (20%)
- Type D: 오래된/폐기된 개념 혼입 (10%)

---

## 최적화 전략

### Phase 1: 신뢰도 레벨 분류 (1일)

#### 레벨 정의

**Canonical (신뢰도 100%)**
- 현재 유효한 규격
- 최근 6개월 내 업데이트
- 검증된 구현 코드 존재
- 예: spec/09_decision_flow.yaml, spec/12_field_dictionary.yaml

**Adapter (신뢰도 80%)**
- 인터페이스 정의
- KIS/Naver 연동 계약
- 부분적 구현 완료
- 예: spec/gas_adapter_contract.yaml

**Reference (신뢰도 60%)**
- 배경 설명 문서
- 의사결정 근거
- 최신화 필요
- 예: docs/ROADMAP_WBS.md

**Deprecated (신뢰도 0%)**
- 폐기된 알고리즘
- 과거 버전 구현
- 참고용만 허용
- 예: spec/??_old_*.yaml (명시)

**Excluded (신뢰도 -1)**
- LLM 로드 금지
- 예: 내부 회의록, 임시 스크래치 파일

---

### Phase 2: 읽음 순서 맵 정의 (1.5일)

#### 계층 구조

```
Tier 1: 기초 개념 (필수)
├─ spec/12_field_dictionary.yaml [Canonical]
│  └─ 모든 필드 정의 및 단위
├─ spec/14_raw_workbook_mapping.yaml [Canonical]
│  └─ 구글 시트 탭-필드 매핑
└─ spec/09_decision_flow.yaml [Canonical]
   └─ 5-gate 순차 필터 플로우

Tier 2: 비즈니스 규칙 (권장)
├─ spec/08_scoring_rules.yaml [Canonical]
├─ spec/04_strategy_rules.yaml [Canonical]
├─ spec/strategy/*.yaml [Canonical]
└─ spec/03_risk_policy.yaml [Canonical]

Tier 3: 실행 계약 (상황별)
├─ spec/00_execution_contract.yaml [Canonical]
├─ spec/17_performance_contract.yaml [Canonical]
├─ spec/16_data_gaps_roadmap.yaml [Reference]
└─ formulas/*.yaml 계약 모음

Tier 4: 기술 세부사항 (선택)
├─ formulas/execution_decision_v1.py [Canonical]
├─ formulas/routing_decision_v1.py [Canonical]
├─ governance/gas_logic_migration_ledger_v1.yaml [Reference]
└─ spec/07_*.yaml [Technical Reference]

Tier 5: 운영/플레이북 (배포 후)
├─ docs/SYNOLOGY_*.md [Adapter]
├─ docs/WBS_*_EXECUTION_PLAN_*.md [Reference]
└─ docs/runbook.md [Reference]
```

#### 읽음 순서 알고리즘

**목표**: LLM이 순차적으로 이해 가능하도록

1. **Tier 1 필수 정보** (80% 확률로 먼저 로드)
2. **Tier 2 비즈니스 규칙** (Tier 1 이후 10%/10%)
3. **Tier 3 실행 계약** (필요시에만)
4. **Tier 4 기술** (질문 관련시에만)
5. **Tier 5 운영** (배포/모니터링 질문시)

**구현**: prompts/engine_audit_master_prompt_v3.md 수정

```yaml
document_loading_strategy:
  mode: TIER_AWARE_SEQUENTIAL
  tier_1_always_first: true
  tier_1_must_load: ["spec/12_field_dictionary.yaml", "spec/14_raw_workbook_mapping.yaml", "spec/09_decision_flow.yaml"]
  tier_2_probability: 0.7
  tier_3_load_on_query: ["execution_contract", "performance_contract"]
  exclude_deprecated: true
```

---

### Phase 3: 의존성 명시 (1.5일)

#### 의존성 그래프

각 spec 파일에 추가:
```yaml
meta:
  dependencies:
    required: ["spec/12_field_dictionary.yaml"]  # 이 파일 없으면 이해 불가
    recommended: ["spec/14_raw_workbook_mapping.yaml"]  # 권장
    optional: []
  depends_on_formulas:
    - execution_decision_v1.py
    - routing_decision_v1.py
```

**자동화**: 파일 파싱 + 의존성 그래프 생성

```python
# tools/build_document_dependency_graph_v1.py
def extract_dependencies(spec_file):
    """
    1. 파일 내용 스캔
    2. 다른 파일 참조 감지 (includes, refs, formula_ref)
    3. 필드 참조 감지 (spec/12_field_dictionary.yaml 필드)
    4. 의존성 리스트 자동 생성
    """
    pass

def validate_dependency_graph():
    """
    1. 순환 의존성 검사
    2. 고아 파일 검사 (참조되지 않는 파일)
    3. 순서 검증 (DAG)
    """
    pass
```

---

### Phase 4: 개념 통일 및 정의 표준화 (1.5일)

#### 용어 수집
```yaml
terminology:
  - term: "late_chase_risk"
    definition: "상승장 후반 진입시 손실 위험도 (0-100)"
    aliases: ["late_chase_risk_score", "LCR"]
    usage_in_files:
      - spec/09_decision_flow.yaml:Gate3
      - formulas/routing_decision_v1.py:apply_heat_gate
    canonical_reference: "formulas/late_chase_gate_v1.py"

  - term: "ATR"
    definition: "Average True Range — 20일 평균 변동성"
    formula: "tr_20d = max(high-low, |high-prev_close|, |low-prev_close|)"
    usage_in_files:
      - spec/12_field_dictionary.yaml:atr20
      - formulas/execution_decision_v1.py:safe_float(atr20)
    aliases: ["ATR20", "atr_20", "volatility_20"]
```

#### 표준화 규칙
1. 모든 약자는 첫 사용시 정의
2. 동일 개념 다중 이름 금지 → canonical_name 사용
3. 공식은 주석에 명시
4. 범위/단위는 필드사전 참조

---

### Phase 5: 오류 검증 및 측정 (2일)

#### LLM 독해 테스트

**테스트 세트**: 30개 질문
- 10: 기초 개념 (ATR, field, gate)
- 10: 의사결정 로직 (5-gate flow)
- 10: 통합 시나리오 (거래 시나리오 설명)

**측정 지표**:
```
오류율 = (잘못된 답변 / 총 질문) × 100

목표: 50% 이상 감소
- 현재 추정: 30% (before optimization)
- 목표: 15% (after optimization)
```

**테스트 예시**:
```
Q1: "ATR20과 손절가의 관계를 설명하시오"
기대 답변: "ATR20은 20일 평균 변동성으로, 손절가는 ATR20 × 2.0 배수로 설정"
오류 유형: Type A (기초 개념 미이해)

Q2: "late_chase_risk가 70 이상이면 어떻게 되나?"
기대 답변: "Gate 3에서 BLOCK되어 거래 진행 불가"
오류 유형: Type B (흐름 이해 오류)
```

#### 자동화 검증

```python
# tools/validate_llm_radar_accuracy_v1.py
def test_llm_document_understanding():
    """
    1. embedding 생성 (각 문서의 핵심 개념)
    2. LLM에 Tier 1 로드 후 질문
    3. embedding 유사도 검증
    4. 답변 정확도 점수화
    """
    pass

def measure_error_rate():
    """
    1. 기준 답변 정의
    2. LLM 답변 추출
    3. BLEU/ROUGE 점수 계산
    4. 오류율 리포팅
    """
    pass
```

---

## 구현 로드맵

| 단계 | 작업 | 기간 | 출산물 |
|------|------|------|--------|
| 1 | 신뢰도 분류 | 1일 | `spec_trust_levels.yaml` |
| 2 | 읽음 순서 정의 | 1.5일 | `document_loading_strategy.yaml` + prompt 수정 |
| 3 | 의존성 그래프 | 1.5일 | `document_dependency_graph.json` |
| 4 | 용어 표준화 | 1.5일 | `terminology_glossary.yaml` |
| 5 | 오류 측정 | 2일 | 오류율 report (baseline vs optimized) |

**총 소요**: 2~3일 (병렬 진행 가능)

---

## 예상 효과

### 오류 감소
- Type A (기초 개념): 40% → 10% (-75%)
- Type B (순서/모순): 30% → 8% (-73%)
- Type C (중복성): 20% → 5% (-75%)
- Type D (폐기된 개념): 10% → 2% (-80%)

**전체**: 30% → 15% (-50%) ✅

### 추가 효과
1. **속도**: Tier 기반 로드로 context 크기 40% 감소
2. **정확도**: 개념 통일로 일관된 답변 생성
3. **유지보수**: 의존성 그래프로 변경 영향도 파악 용이

---

## 다음 단계

### Phase 1 완료 후
1. spec_trust_levels.yaml 파일 생성
2. 각 spec 파일에 trustLevel 추가

### Phase 2 완료 후
1. prompts/engine_audit_master_prompt_v3.md 수정
2. Gitea CI에서 자동 재생성

### Phase 3 완료 후
1. tools/build_document_dependency_graph_v1.py 작성
2. 자동화 검증

### Phase 5 완료 후
1. 오류율 리포트 생성
2. WBS-9.6 완료 선언

---

**상태**: 전략 초안 완료  
**다음**: Phase 1 구현 (신뢰도 분류)
