Claude Haiku
363c2a2a25
- CLAUDE.md: 프로젝트 전체 가이드 및 워크플로우 정의 - CONSIDERATIONS.md: 8개 영역 고려사항 분석 (기술, 품질, 배포, UX) - PROGRESS.md: 진행 상황 추적 및 체크리스트 - PLAN.md: 단계 5~9 상세 계획 및 에이전트 역할 정의 - 메모리: 프로젝트 정보 저장 다음: 단계 5 (에이전트/커맨드/스킬/훅 아이디어 제안)
290 lines
9.0 KiB
Markdown
290 lines
9.0 KiB
Markdown
# 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** 라이선스를 준수해야 한다.
|
|
|