V-04. CLAUDE.md-AutoCAD DWG 도면에서 Revit 3D 모델 자동 생성하기

CLAUDE.md — Claude Code 세션 규칙

이 파일은 Claude Code가 매 세션 시작 시 반드시 읽는 프로젝트 규칙 파일입니다. 작업 전 전체를 읽고, 아래 규칙을 항상 따르세요.

---

프로젝트 한 줄 요약

AutoCAD DWG 층별 평면도 → IFC 자동 변환 파이프라인 (Python)

---

필수 선행 작업 (매 세션 시작 시)

# 1. 현재 진행 상황 확인
cat PLAN.md

# 2. 최근 변경 파일 확인
git log --oneline -10

# 3. 테스트 상태 확인
pytest tests/ -q --tb=no 2>/dev/null || echo "테스트 없음"

작업 시작 전 반드시 PLAN.md의 현재 Phase와 체크박스를 확인하고, 어느 단계를 작업하는지 먼저 사용자에게 말하세요.

---

폴더 구조 및 파일 역할

dwg-to-revit/
  ├── src/
  │   ├── parser/
  │   │   └── dwg_parser.py       # ezdxf로 DWG 로드, 엔티티 추출
  │   ├── preprocessor/
  │   │   └── cleaner.py          # 중복 제거, 끝점 스냅, 노이즈 제거
  │   ├── classifier/
  │   │   ├── layer_classifier.py # 레이어명 기반 요소 분류
  │   │   ├── geometry_classifier.py # 형상 기반 요소 분류
  │   │   └── ai_classifier.py    # Claude API 기반 분류 (3차)
  │   ├── modeler/
  │   │   ├── wall_modeler.py     # 벽 두께/중심선/연결점
  │   │   ├── opening_modeler.py  # 문/창 개구부 처리
  │   │   └── floor_assembler.py  # 층간 조립
  │   ├── ifc_writer/
  │   │   └── ifc_builder.py      # ifcopenshell IFC 파일 생성
  │   └── reporter/
  │       └── report_builder.py   # HTML 리포트 생성
  ├── tests/                      # pytest 테스트
  ├── input/                      # DWG 입력 파일 (git ignore)
  ├── output/                     # 변환 결과 (git ignore)
  ├── config.yaml                 # 프로젝트 설정
  ├── requirements.txt
  ├── PRD.md                      # 제품 요구사항
  ├── PLAN.md                     # 실행계획 (체크박스)
  └── CLAUDE.md                   # 이 파일

---

코딩 컨벤션

Python 스타일

• Python 3.10+ 문법 사용 (match-case, union type hints 허용)
• 타입 힌트 필수: def parse(path: str) -> list[Entity]:
• 함수 하나는 하나의 역할만
• 함수 길이 50줄 초과 시 분리 검토
• 모든 공개 함수에 docstring 작성

# 좋은 예
def snap_endpoints(entities: list[Entity], tolerance: float = 1.0) -> list[Entity]:
    """끝점이 tolerance(mm) 이내인 엔티티를 스냅하여 반환."""
    ...

# 나쁜 예
def process(data):
    # 뭘 하는지 모름
    ...

에러 처리

• 파일 관련 오류는 반드시 try/except로 처리
• 예외 무시 금지: except Exception: pass 사용 금지
• 오류는 로깅 후 상위로 전파하거나 명시적으로 처리

# 좋은 예
try:
    doc = ezdxf.readfile(path)
except ezdxf.DXFStructureError as e:
    logger.error(f"DWG 파싱 실패: {path} — {e}")
    raise

로깅

• print() 사용 금지 — logging 모듈 사용
• 레벨: DEBUG(상세), INFO(진행), WARNING(경고), ERROR(실패)

import logging
logger = logging.getLogger(__name__)

logger.info(f"파싱 시작: {path}")
logger.warning(f"미분류 엔티티: layer={layer}, type={etype}")

좌표 처리

• 모든 좌표는 mm 단위 기준
• 부동소수점 비교 시 허용 오차 명시
• numpy array 사용 시 float64 명시

# 좋은 예
SNAP_TOLERANCE = 1.0  # mm
if abs(pt1.x - pt2.x) < SNAP_TOLERANCE:
    ...

# 나쁜 예
if pt1.x == pt2.x:  # 부동소수점 직접 비교 금지
    ...

---

절대 하지 말 것 (DON'T)

파일/데이터

• ❌ input/ 폴더의 DWG 파일을 수정하거나 삭제하지 말 것
• ❌ output/ 폴더를 git에 커밋하지 말 것
• ❌ .env 파일을 읽거나 출력하지 말 것 (API 키 노출 금지)
• ❌ 실제 DWG 파일 없이 파서 코드를 "있는 척" 완성하지 말 것

코드

• ❌ except Exception: pass — 예외 무시 금지
• ❌ print() — logging 사용
• ❌ 하드코딩 경로 (/Users/name/...) — config 또는 인자로 받을 것
• ❌ Claude API를 1차 분류에 사용 (비용 낭비) — 레이어/형상 분류 먼저
• ❌ 테스트 없이 modeler/ifc_writer 구현 완료 선언

아키텍처

• ❌ 모듈 간 순환 import 생성
• ❌ src/ 외부에 비즈니스 로직 작성
• ❌ 단일 함수에 파싱 + 분류 + IFC 출력 혼합

---

작업 완료 기준

각 Phase 완료 시 아래를 반드시 수행:

1. PLAN.md 체크박스 업데이트 — 완료 항목을 ⬜ → ✅ 변경
2. 테스트 실행 — pytest tests/ -v
3. git commit — 커밋 메시지 형식: [Phase N] 내용 요약

# 커밋 메시지 예시
git commit -m "[Phase 2] DWG 파서 구현 - 엔티티 추출 및 블록 분해"
git commit -m "[Phase 3] 전처리 - 끝점 스냅 및 중복 제거"

---

의존성 설치

pip install ezdxf shapely numpy anthropic ifcopenshell click jinja2 pytest

또는

pip install -r requirements.txt

---

자주 쓰는 명령어

# 단일 DWG 파싱 테스트
python -m src.parser.dwg_parser input/1F.dwg

# 전체 파이프라인 실행
python main.py --config config.yaml

# 특정 Phase 테스트만 실행
pytest tests/test_parser.py -v
pytest tests/test_classifier.py -v

# IFC 검증
python -c "import ifcopenshell; f=ifcopenshell.open('output/model.ifc'); print(f.schema)"

---

Claude API 사용 지침

• 모델: claude-sonnet-4-20250514
• 사용 시점: 레이어/형상 분류 모두 실패한 경우에만
• 프롬프트에 포함할 정보: 레이어명, 엔티티 타입, 좌표 범위, 인접 레이어명
• 응답 형식: JSON ({"type": "wall", "confidence": 0.85})
• 비용 절약: 동일 레이어명은 캐싱하여 반복 호출 방지

# 캐싱 예시
_cache: dict[str, ClassifyResult] = {}

def classify_with_ai(layer: str, etype: str) -> ClassifyResult:
    key = f"{layer}:{etype}"
    if key in _cache:
        return _cache[key]
    result = call_claude_api(layer, etype)
    _cache[key] = result
    return result

---

알려진 한계 및 주의사항

상황 현재 처리 비고

단선 도면	기본 두께 200mm 적용	config에서 변경 가능
층고 정보 없음	config.yaml 수동 입력 필요	단면도 파싱은 미구현
곡선 벽	미지원 (직선으로 근사)	Phase 10 이후 검토
MEP 요소	미분류 처리 후 리포트에 기록	범위 외
DWG R14 이하	미지원	ezdxf 제한
한글 레이어명	지원 (UTF-8 인코딩)	EUC-KR DWG 주의

---

마지막 업데이트: 프로젝트 초기화