C.E.L_Slide_test2/tests/CLAUDE.md

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

이 파일은 Claude (AI) 가 tests/ 디렉토리에서 작업할 때 참고하는 컨텍스트입니다. 프로젝트 루트의 ../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 — 분석 보고서

자주 쓰는 명령어

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)