kyeongmin
02e2ae0afb
INTEGRATION-AUDIT-01 (#50) §10.4 / §10.5 housekeeping carry-over. F-4: annotate 14 remaining legacy Phase R'/Q sample-text hits across 10 src/ files with inline marker `# [legacy Phase R'/Q example -- INTEGRATION-AUDIT-01 §10.4]`. Comment-only. No string-literal / regex / sample dict value mutated. fit_verifier.py L612 marker keeps Phase Z partial-live import graph (FitAnalysis / RoleFit / redistribute / salvage) byte-precise. F-5: docs-only addendum -- §10.5.1 in INTEGRATION-AUDIT-01-REPORT.md + tests/CLAUDE.md fixture convention note. No root tests/fixtures/ dir created; existing tests/phase_z2/fixtures/ convention preserved. Documents test-only sample-reference allowance vs src/** runtime prohibition. Out of scope: Phase Z source 11 hits (phase_z2_content_extractor / failure_router / mapper / retry), production behavior change, #19 work. Verified: pytest -q tests/phase_z2/ = 157 PASS. git diff +210/-0 (35 src/docs lines + 175 new tests/CLAUDE.md). No behavioral delta. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
176 lines
7.4 KiB
Markdown
176 lines
7.4 KiB
Markdown
# 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)
|