# CLAUDE.md — DXF to 3D Web App 프로젝트 가이드 > **이것은 AI 에이전트를 위한 프로젝트 지침서입니다.** > 이 파일을 먼저 읽고 작업을 시작하세요. --- ## 프로젝트 개요 ### 목표 2D DXF 도면(가시설 일반도)을 분석하여 3D 모델로 변환하고, 웹상에서 실시간으로 검토할 수 있는 웹앱을 만든다. ### 최종 산출물 ``` 사용자 → 웹사이트 (무료 도메인) ↓ DXF 업로드 & 자동 변환 ↓ 3D 모델 실시간 시각화 ↓ 부재 정보 조회, 측정, 다운로드 ``` ### 핵심 요구사항 - ✅ **Git 관리**: 모든 작업 과정 기록 - ✅ **무료 배포**: Vercel + 커스텀 도메인 - ✅ **품질**: Haiku 4.5 모델임에도 우수한 결과물 - ✅ **단계별 검증**: 각 단계 전에 작업 리마인드 + 진행 확인 --- ## 프로젝트 구조 ``` D:\Obsidian Vault\999ETC\261016_HW_DwfTo3D\ │ ├── docs/ # 기초 자료 (읽기 전용) │ ├── roadmap.md # 진행 상황 & 우선순위 │ ├── 2d-3d-conversion.md # 19개 교훈 (매우 중요!) │ ├── 2d-3d-process.md # 절차 문서 │ ├── methodology.html # 방법론 상세 │ └── dwg2model-CLAUDE.md # 기존 프로젝트 가이드 │ ├── RAG/ # 대상 DXF 파일 │ ├── 가시설_평면.dxf # 평면도 │ ├── 가시설_단면.dxf # 단면도 │ └── 가시설_상세1~4.dxf # 상세도 │ ├── src/ # 소스 코드 (구현 예정) │ ├── drawings/ │ │ ├── index.mjs # 모든 도면의 중앙 진입점 │ │ └── gasiseol.mjs # 가시설 도면 설정 & 조립 로직 │ │ │ ├── core/ # 도면 고유값 없음 (절대 건드리지 말 것) │ │ ├── parse.mjs # DXF 파싱 │ │ ├── views.mjs # 뷰 분리 │ │ ├── loops.mjs # 폐곡선 추출 │ │ └── datum.mjs # 기준점 검출 │ │ │ ├── build/ # IR 생성 (도면 독립) │ │ ├── assemble.mjs # 부재 조립 │ │ └── validate.mjs # 검증 │ │ │ ├── emit/ # 3D 출력 (도면 독립) │ │ ├── egm.mjs # EGModeler 명령 생성 │ │ └── ifc.mjs # IFC 출력 │ │ │ ├── web/ # React 웹앱 (새로) │ │ ├── components/ │ │ │ ├── Viewer3D.tsx # Three.js 뷰어 │ │ │ ├── FileUpload.tsx # DXF 업로드 │ │ │ ├── PropertyPanel.tsx # 부재 정보 │ │ │ └── Controls.tsx # 조작 UI │ │ ├── pages/ │ │ │ ├── index.tsx # 메인 페이지 │ │ │ └── api/convert.ts # 변환 API │ │ ├── styles/ │ │ ├── App.tsx │ │ └── main.tsx │ │ │ ├── run.mjs # 도면 검증 (기존) │ ├── build.mjs # IR 생성 (기존) │ ├── measure.mjs # 부피 측정 (기존) │ └── paths.mjs # 경로 관리 (한 곳) │ ├── .claude/ # 에이전트 설정 (단계 6에서) │ ├── agents/ │ │ ├── research.md │ │ ├── pipeline.md │ │ ├── webui.md │ │ └── deploy.md │ ├── commands/ │ ├── skills/ │ └── hooks/ │ ├── PROGRESS.md # 진행 상황 추적 (매 세션 업데이트) ├── PLAN.md # 상세 계획 및 에이전트 역할 분담 ├── CONSIDERATIONS.md # 고려사항 (단계 2 결과) ├── CLAUDE.md # 이 파일 │ └── .gitignore # git 설정 node_modules/ dist/ *.obj *.log ``` --- ## 개발 워크플로우 ### 0️⃣ 세션 시작 전 ``` 1. PROGRESS.md 읽기 ← 진행 상황 파악 2. PLAN.md 읽기 ← 다음 작업 확인 3. 메모리 로드 ← 이전 세션 컨텍스트 ``` ### 1️⃣ 각 단계 시작 시 ``` 리마인드 (작업 내용 명시화) ├─ 이 단계에서 할 것 ├─ 예상 결과물 └─ 성공 기준 진행 확인 (사용자 승인) └─ "다음으로 진행해도 될까요?" → 대기 작업 수행 (git 커밋 포함) └─ 의미 있는 커밋 메시지 검증 (문제 없는지 확인) └─ 자동 테스트 또는 수동 검사 완료 리포트 (PROGRESS.md 업데이트) └─ 결과물 요약 & 다음 단계 예고 ``` ### 2️⃣ Git 커밋 원칙 ``` 좋은 예시: step2: CONSIDERATIONS.md 작성 - 고려사항 8개 영역 정리 step3: CLAUDE.md 작성 - 프로젝트 구조 & 워크플로우 정의 나쁜 예시: ❌ update (너무 모호) ❌ fix bugs (어떤 버그?) ❌ step1-draft (완료 전 중간 저장) ``` --- ## 핵심 원칙 (반드시 지킬 것) ### 🚫 절대 어기면 안 되는 경계 ``` src/core/* · src/build/* → 도면 고유값 금지 (= 설정파일로 분리) src/drawings/*.mjs → 레이어명, 좌표, 단위 모두 여기 src/web/* → 웹앱만 담당 (도면 파싱 X) src/emit/* → 3D 도구 사정만 (도면값 X) ``` **위반하면**: 두 번째 도면(다른 가시설)을 할 때 파이프라인이 아니라 복사본이 생긴다. ### 📊 검증 체크리스트 (필수) #### 도면 검증 - [ ] 기준점이 도면 치수 2개 이상과 일치 - [ ] 뷰 폭·높이가 도면 표기와 ±2% 이내 - [ ] 폐곡선 수가 예상과 일치 - [ ] 자기교차 링 없음 (`--loops` 확인) #### 3D 모델 검증 - [ ] 부피 오차 < 0.5% (IR vs 실제) - [ ] manifold 체크 (닫힌 면) - [ ] 렌더링 성공 (Three.js) - [ ] 부재 정보 표시 가능 #### 배포 검증 - [ ] 웹앱 로딩 < 3초 - [ ] 3D 렌더링 60fps - [ ] 모바일 반응형 확인 - [ ] 도메인 접속 가능 --- ## 에이전트 역할 (단계 5에서 상세 정의) | 에이전트 | 담당 영역 | 도구 | |---------|---------|------| | **Research** | 가시설 도면 분석, 설정 파일 작성 | DXF 파싱, 기하학 분석 | | **Pipeline** | dwg2model 통합, 테스트 자동화 | 빌드, 검증, 측정 | | **WebUI** | React 컴포넌트, Three.js 통합 | 개발 서버, 빌드 | | **Deploy** | CI/CD, Vercel 배포, 도메인 설정 | GitHub Actions, npm | --- ## 빠른 참조 ### 자주 실행하는 명령 ```bash # 도면 검증 (Node.js 필요) node src/run.mjs 가시설 # 3D 생성 (Python & egm CLI 필요) python src/run_egm.py 가시설 --export=out/gasiseol.obj # 부피 측정 node src/measure.mjs 가시설 --ir # 웹앱 개발 서버 (나중) cd src/web && npm run dev # 배포 (CI/CD 자동) git push ``` ### 주요 문서 (필독) | 문서 | 언제 읽을까 | |------|-----------| | [`docs/2d-3d-conversion.md`](docs/2d-3d-conversion.md) | **새 도면 추가 전 필수** (19개 함정) | | [`docs/2d-3d-process.md`](docs/2d-3d-process.md) | 절차 확인 시 | | [`docs/roadmap.md`](docs/roadmap.md) | 우선순위 확인 시 | | [`CONSIDERATIONS.md`](CONSIDERATIONS.md) | 고려사항 확인 시 | | [`PLAN.md`](PLAN.md) | 에이전트 분담 시 | | [`PROGRESS.md`](PROGRESS.md) | 진행 상황 업데이트 시 | --- ## 품질 기준 ### 코드 스타일 ``` - 주석은 "왜"를 적는다. "무엇"은 코드가 말한다. - 조용히 틀리느니 예외를 던진다 - 좌표·치수는 mm 정수로 (egm에 넘기기 전에만 m로 변환) - 가정하지 마라. 검증하고 단정해라 ``` ### 테스트 ``` - 도면 검증: 자동화 (--loops, --ir, measure.mjs) - 웹앱: 단위 테스트 + E2E 테스트 - 배포: 리뷰 URL에서 수동 테스트 후 병합 ``` ### 문서 ``` - 코드와 문서를 따로 유지 (업데이트가 다르다) - 변경사항은 PROGRESS.md에 즉시 기록 - 함정/해결책은 이 파일에 추가 ``` --- ## 트러블슈팅 ### "도면 로드가 실패했어요" → `docs/2d-3d-conversion.md` 교훈 #1~#6 확인 ### "폐곡선이 4개가 아니에요" → `docs/2d-3d-conversion.md` 교훈 #12, #18 (자기교차 검사) ### "부피가 IR과 맞지 않아요" → `src/measure.mjs --ir` 로 의도(IR) vs 결과(모델러) 분리 ### "웹앱이 느려요" → 모델 정점 수 확인, LOD 적용, 번들 최적화 ### "배포 실패" → GitHub Actions 로그 확인, 환경 변수 설정 검사 --- ## 변경 이력 | 버전 | 날짜 | 내용 | |------|------|------| | 1.0 | 2026-10-16 | 초안 작성 (단계 3) | --- ## 라이선스 이 프로젝트는 [`docs/dwg2model-CLAUDE.md`](docs/dwg2model-CLAUDE.md)를 상속받는다. 특히 `vendor/acadrust-dwg/` 의 **MPL-2.0** 라이선스를 준수해야 한다.