# CLAUDE.md — 매칭 시스템 작업 컨텍스트

이 파일은 Claude (AI) 가 `tests/` 디렉토리에서 작업할 때 참고하는 컨텍스트입니다.
프로젝트 루트의 [../CLAUDE.md](../CLAUDE.md) 와 함께 사용.

## 작업 디렉토리

- 메인 작업 디렉토리: `tests/matching/`
- 데이터 / 보고서 파일도 같은 위치
- 실행 시 항상 `tests/matching/` 에서 (스크립트 내부 상대 경로 의존)

## 시스템 개요

MDX 콘텐츠 ↔ Figma Frame 32 개를 매칭하는 4 단계 파이프라인 (V1~V4).
상세는 `README.md` / `PLAN.md` / `PROGRESS.md` 참조.

## 절대 규칙

### 1. 하드코딩 금지 (사용자 강조 사항)
- 결과물을 직접 고치지 말고 **프로세스/코드를 고쳐라**
- 임의 데이터 삽입 금지 (예: DECK 04 의 "제목·A 라벨·B 라벨·행 데이터" placeholder 사용 금지)
- 모든 표시값은 실제 코드 결과 (yaml / 함수 출력) 에서 가져와야 함

### 2. 사용자 직접 수정 보존
- 사용자가 HTML 파일을 직접 편집한 경우 **반드시 pipeline 코드에 반영** 후 재생성
- 코드만 고치고 재실행하면 사용자 수정이 사라짐
- 변경 시: 사용자 수정 8 개 모두 코드에 반영 → 재실행

### 3. 정직한 코드 동작 표시
- 임원 보고용 deck 라도 **코드의 한계를 솔직히 표시**
- 예: "MDX 자동 분석 결과 — 정책/요구사항 (사람이 보면 행렬형 비교)" 같은 표기
- "이 축은 사실 frame 매칭에 영향 없음" 같은 ablation 결과는 임원용에는 빼지만, 내부 문서 (PROGRESS.md) 에는 명시

### 4. 임원 보고용 톤
- 영문 enum 코드 (`policy_requirements`) 직접 노출 금지 — 한글 (정책/요구사항) 우선
- 매칭 키워드는 5~10 개 + "등 N 개" 로 축약
- 디자인: 그라데이션 / 화려한 카드 금지. 단순 표 + 흑백 + 강조 색 1~2 가지
- 정의 / 부연 설명 최소화 (def 는 한 줄, 길게 풀어 쓰지 말 것)

## 명명 규칙

### 파이프라인 스크립트
```
pipeline_<숫자>_<이름>.py
```
- 01~07: 입력 추출 + 전처리 + 키워드
- 08: V2 (semantic) / V3 (structure r2~r5) / V4 (template_fit, r1/r2)
- 09: V2 진단
- 10: Holdout 라벨링 / 평가
- 11: templates_v1 감사
- 12: templates_v2 생성 (r1, r2, r3, final, final_r2, promote_frame13)
- 13: meeting docs / samples
- 14: single sample
- 15: bm25 / idf / logistic regression 비교
- 16: deck 페이지 생성 (DECK 1~7)
- 17: V4 full32 (32 frame 전체 평가)
- 18: V4 slot 축 ablation

### 결과 파일
```
<단계>_<설명>_result.yaml
```
- `mdx_matching_result.yaml` — V1
- `v2_semantic_rerank_result.yaml` — V2
- `v3_structure_rerank_r5_result.yaml` — V3 (최종 r5)
- `v4_full32_result.yaml` — V4 (32 frame 전체)
- `structure_ontology_v2_final_r2.yaml` — Frame 32 DB

### 보고서
```
DECK_<번호>_<이름>.html — 임원 보고용 A4 페이지
ATTACH_<번호>_<이름>.html — 부속 자료
<NAME>_REPORT.html / .md — 분석 보고서
```

## 자주 쓰는 명령어

```bash
cd tests/matching/

# 매칭 시스템 전체 재실행
python pipeline_06_2_mdx_matching.py
python pipeline_08_v2_semantic_rerank.py
python pipeline_08_v3_r5_structure_rerank.py
python pipeline_17_v4_full32.py

# 보고서 재생성
python pipeline_16_deck_4pages.py    # DECK 1~7

# Ablation / 검증
python pipeline_15_logistic_regression.py
python pipeline_18_slot_axis_ablation.py
```

## 파이프라인 핵심 가중치

### V1 키워드 매칭 (Logistic Regression 학습)
```
matching_score = 0.414 × 핵심 + 0.320 × 세트 + 0.265 × 연관
```

### V3 구조 매칭
```
total = 0.40 × 레이아웃 일치 + 0.35 × 콘텐츠 성격 + 0.25 × 시각 의도
```

### V4 종합 판정
```
confidence = 0.25 × anchor + 0.20 × cardinality + 0.20 × relation
           + 0.15 × slot + 0.20 × content − penalty

라벨 임계값:
  ≥ 0.90 → use_as_is (그대로 사용)
  ≥ 0.75 → light_edit (가벼운 편집)
  ≥ 0.60 → restructure (구조 재배치)
  < 0.60 → reject (사용 불가)
```

## 데이터 소스

| 데이터 | 위치 | 용도 |
|---|---|---|
| Figma 텍스트 | `figma_to_html_agent/blocks/*/texts.md` | 32 frame 텍스트 추출 |
| BEPS 마스터 | (별도 위치) | 키워드 보강용 |
| MDX 검증 구간 | (`pipeline_01_extract_nodes.py` 의 `MDX_SECTIONS`) | 정답 매칭 검증 |
| Frame 이미지 | `data/figma_previews/<프레임번호>.png` | DECK 시각화 |

## 테스트 픽스처 컨벤션 (F-5, INTEGRATION-AUDIT-01 §10.5.1)

테스트 데이터 / 샘플 참조의 정식 위치 규약. `tests/` 안에서만 적용되고 `src/**` 프로덕션 경로에는 적용되지 않음.

| 경로 | 상태 | 용도 | 비고 |
|---|---|---|---|
| `tests/phase_z2/fixtures/` | **존재 (정식)** | Phase Z 회귀 YAML 픽스처 | `test_fixtures_loader.py` 가 로드. 서브디렉토리 : `build_layout_css/`, `retry_gate/`. |
| `tests/fixtures/` (루트) | **없음 (현재 미생성)** | 비-Phase-Z / 비-YAML 픽스처 미래 후보 | 샘플 인벤토리가 `tests/phase_z2/test_*.py` 인라인으로 감당 못 할 때만 별도 이슈로 신설. |
| `samples/mdx_batch/**` , `samples/mdx/**` | 존재 | 통합 스모크 입력 | `tests/**` 에서만 참조 가능. `src/**` 런타임 경로 하드코딩 금지. |

규칙 :

- 테스트 코드에서는 `samples/mdx_batch/02.mdx` 같은 샘플 MDX 를 직접 참조해도 됨 (예 : `tests/phase_z2/test_pz2_vu_integration.py`). `src/**` 런타임 입력은 절대 샘플 파일명 / 콘텐츠를 핀하지 말 것.
- 새 YAML 회귀 픽스처는 `tests/phase_z2/fixtures/` 아래 새 서브디렉토리로 추가. 루트 `tests/fixtures/` 신설은 금지 (별도 이슈 필요).
- `src/**` 안에 등장하는 "BIM" / "건설산업 DX" / "재구성" 같은 sample-like 리터럴은 INTEGRATION-AUDIT-01 §10.4 (F-4) 에서 의도된 docstring / glossary / 예시 dict 로 분류 완료. annotation marker 가 붙어 있으면 의도된 example. 새 sample 리터럴을 `src/**` 에 도입하지 말 것.
- 본 컨벤션의 anchor 정의는 `docs/architecture/INTEGRATION-AUDIT-01-REPORT.md` §10.5.1. 변경 시 anchor 부터 갱신.

## 자주 헷갈리는 것

### 영문 enum vs 한글 매핑
- 코드 / yaml: 영문 enum (`comparative_matrix`, `cycle_interrelation`)
- 보고서 표시: 한글 (`행렬형 비교`, `순환/상호 관계`)
- DECK 05 의 키워드 사전 표는 양쪽 다 표시 (사용자 매칭 가능)

### 항목수 vs 슬롯 후보 개수
- **동일** — `item_count = len(slot_candidates)` (표 / subsections / bullets 어떤 형태든)
- V4 의 cardinality 축과 slot.within 부분은 **같은 신호의 중복 가중** (ablation 으로 확인)

### V3 vs V4 구조 점수
- V3 = layout family + content_affinity + structure_intent (3 축)
- V4 = anchor + cardinality + relation + slot + content (5 축)
- **다른 모델**. V3 점수와 V4 confidence 는 별도 계산

## 사용자가 강조한 피드백

- "코드로 돌린 결과물이지 임의 데이터 아님" — 모든 표시 정직
- "임원 보고용이야" — 부정적 부연 / 디테일 산식 빼기
- "한가지만 해" — 한 번에 한 가지만 변경
- "모든 변경은 pipeline 코드에 반영" — HTML 직접 수정은 일시적

## 진행 중 발견된 약점

`PROGRESS.md` 의 "발견된 약점" 표 참조. 8 개 모두 Phase E 작업 대상.

가장 시급:
1. **02-2.2 매칭 실패** (E.5)
2. **MDX 분석 LLM 화** (E.1, E.2)
3. **슬롯 의미 매핑** (E.3, E.4)