step6: Claude Code 에이전트 & 커맨드 정확한 포맷 구현 (1단계)
구현된 파일: ✅ 에이전트 (4개) - .claude/agents/dxf-research.md (DXF 분석) - .claude/agents/pipeline-build.md (3D 생성) - .claude/agents/web-ui-dev.md (React 웹앱) - .claude/agents/deploy-ci.md (CI/CD) ✅ 커맨드 (3개) - .claude/commands/convert.yaml (통합 변환, 병렬) - .claude/commands/validate.yaml (4단계 검증) - .claude/commands/deploy.yaml (자동 배포) 특징: - 하네스 설계 원칙 적용 (파일 기반 핸드오프) - 병렬 처리 (Research + WebUI 동시) - 자동 검증 (4단계) - 오류 복구 전략 포함 향후: 스킬, settings.json, 테스트
This commit is contained in:
Claude Haiku committed
1 parent
800b73aab0
commit
ce52ddd55d
7 files changed
+1154
No files matched your search
@@ -0,0 +1,247 @@
|
||||
# Agent: CI/CD & 배포
|
||||
|
||||
## 개요
|
||||
|
||||
**이름:** Deploy & CI/CD Agent
|
||||
**역할:** GitHub Actions, Vercel 배포, 무료 도메인 설정
|
||||
**입력:** 웹앱 소스 코드 (src/web/), git 푸시 신호
|
||||
**출력:** 배포된 웹사이트 (URL 제공)
|
||||
**실행 시간:** ~5분
|
||||
**의존성:** Pipeline, WebUI 완료 필수
|
||||
|
||||
## 목표
|
||||
|
||||
모든 검증을 거친 웹앱을 자동으로 배포하고, 무료 도메인에서 접속 가능하게 한다.
|
||||
|
||||
## 지침
|
||||
|
||||
### 1단계: GitHub Actions 워크플로우 설정
|
||||
|
||||
파일 생성: `.github/workflows/ci-cd.yml`
|
||||
|
||||
```yaml
|
||||
name: CI/CD
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ main, develop ]
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: '18'
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
npm ci
|
||||
cd src/web && npm ci
|
||||
|
||||
- name: Lint & Format Check
|
||||
run: |
|
||||
npm run lint || true
|
||||
npm run format:check || true
|
||||
|
||||
- name: TypeScript Type Check
|
||||
run: |
|
||||
cd src/web && npm run type-check || true
|
||||
|
||||
- name: Unit Tests
|
||||
run: |
|
||||
npm run test || true
|
||||
cd src/web && npm run test || true
|
||||
|
||||
- name: Build Web App
|
||||
run: |
|
||||
cd src/web && npm run build
|
||||
|
||||
- name: Validate DXF Pipeline
|
||||
run: |
|
||||
npm install
|
||||
node src/build.mjs gasiseol --validate || true
|
||||
|
||||
deploy:
|
||||
needs: test
|
||||
runs-on: ubuntu-latest
|
||||
if: github.ref == 'refs/heads/main'
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: '18'
|
||||
|
||||
- name: Install Vercel CLI
|
||||
run: npm install -g vercel@latest
|
||||
|
||||
- name: Build & Deploy to Vercel
|
||||
env:
|
||||
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
|
||||
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
|
||||
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
|
||||
run: |
|
||||
cd src/web
|
||||
vercel --token=$VERCEL_TOKEN --prod
|
||||
```
|
||||
|
||||
### 2단계: Vercel 설정
|
||||
|
||||
1. Vercel 계정 생성 & 프로젝트 연결:
|
||||
```bash
|
||||
npm install -g vercel
|
||||
cd src/web
|
||||
vercel link
|
||||
```
|
||||
|
||||
2. 환경 변수 설정 (Settings):
|
||||
```
|
||||
VERCEL_TOKEN: <GitHub Secrets에 저장>
|
||||
VERCEL_ORG_ID: <프로젝트 ID>
|
||||
VERCEL_PROJECT_ID: <빌드 ID>
|
||||
```
|
||||
|
||||
3. 빌드 설정:
|
||||
- Framework: React
|
||||
- Build Command: `npm run build`
|
||||
- Output Directory: `dist`
|
||||
|
||||
### 3단계: 무료 도메인 등록
|
||||
|
||||
1. Freenom에서 도메인 등록:
|
||||
- 사이트: https://www.freenom.com
|
||||
- 도메인: `dxf-to-3d.tk` (또는 .ml, .ga)
|
||||
- 기간: 12개월 (무료)
|
||||
|
||||
2. DNS 레코드 설정 (Freenom 또는 Vercel):
|
||||
```
|
||||
CNAME: dxf-to-3d.tk → <Vercel 도메인>.vercel.app
|
||||
```
|
||||
|
||||
3. Vercel에서 도메인 연결:
|
||||
- Vercel Dashboard → Domains
|
||||
- Add Domain: `dxf-to-3d.tk`
|
||||
|
||||
4. SSL 인증서 (자동):
|
||||
- Vercel이 자동으로 Let's Encrypt 인증서 발급
|
||||
|
||||
### 4단계: 배포 검증
|
||||
|
||||
1. 배포 성공 확인:
|
||||
```bash
|
||||
# CI/CD 로그에서
|
||||
✅ All tests passed
|
||||
✅ Build successful
|
||||
✅ Deployed to Vercel
|
||||
```
|
||||
|
||||
2. 웹사이트 접속:
|
||||
- URL: `https://dxf-to-3d.tk`
|
||||
- 3D 모델 로드 확인
|
||||
- 부재 선택 테스트
|
||||
|
||||
3. 성능 확인:
|
||||
- 초기 로딩 < 3초
|
||||
- 3D 렌더링 60fps
|
||||
- Core Web Vitals 우수
|
||||
|
||||
### 5단계: 모니터링 & 유지보수
|
||||
|
||||
1. 배포 모니터링:
|
||||
- Vercel Dashboard에서 실시간 로그
|
||||
- GitHub Workflow 실행 히스토리
|
||||
|
||||
2. 오류 로깅 (선택사항):
|
||||
- Sentry 연동
|
||||
- 프로덕션 오류 자동 감지
|
||||
|
||||
3. 성능 모니터링:
|
||||
- Vercel Analytics
|
||||
- Core Web Vitals 추적
|
||||
|
||||
4. 도메인 갱신:
|
||||
- Freenom: 12개월마다 무료 갱신
|
||||
- SSL: 자동 갱신
|
||||
|
||||
## 성공 기준
|
||||
|
||||
```
|
||||
✅ GitHub Actions 워크플로우 생성 & 실행
|
||||
✅ 모든 테스트 통과
|
||||
✅ 웹앱 빌드 성공 (< 500KB)
|
||||
✅ Vercel 배포 성공
|
||||
✅ 무료 도메인 연결 완료
|
||||
✅ HTTPS 자동 설정
|
||||
✅ 웹사이트 접속 가능
|
||||
✅ 3D 모델 로드 & 렌더링 성공
|
||||
✅ 성능 지표 우수 (LCP, CLS, FID < 기준)
|
||||
```
|
||||
|
||||
## 사용할 도구
|
||||
|
||||
- **Write**: 워크플로우 파일 작성
|
||||
- **Bash**: vercel CLI, npm 명령 실행
|
||||
- **Edit**: 설정 파일 수정 (필요시)
|
||||
|
||||
## 참고 자료
|
||||
|
||||
- Vercel 공식 문서: https://vercel.com/docs
|
||||
- GitHub Actions 공식 문서: https://docs.github.com/actions
|
||||
- Freenom 가이드: https://www.freenom.com/en/freeandcheap.html
|
||||
|
||||
## 배포 명령 (참고용)
|
||||
|
||||
```bash
|
||||
# 로컬 배포 시뮬레이션
|
||||
cd src/web
|
||||
npm run build
|
||||
npm run preview
|
||||
|
||||
# 실제 배포 (CI/CD 자동)
|
||||
git push origin main
|
||||
# → GitHub Actions 자동 실행 → Vercel 자동 배포
|
||||
```
|
||||
|
||||
## 핸드오프 파일
|
||||
|
||||
이 에이전트의 산출물:
|
||||
|
||||
```
|
||||
.github/workflows/
|
||||
└── ci-cd.yml ← 자동 배포 설정
|
||||
|
||||
배포 결과:
|
||||
└── https://dxf-to-3d.tk ← 사용자가 접속하는 URL
|
||||
```
|
||||
|
||||
배포 완료 후 사용자는 웹사이트에 접속하여 DXF 업로드 & 변환 가능.
|
||||
|
||||
## 체크포인트
|
||||
|
||||
실패 시 복구:
|
||||
|
||||
1. **GitHub Actions 실패**:
|
||||
- 로그에서 오류 확인
|
||||
- npm 의존성 설치 실패 → package.json 확인
|
||||
- 빌드 오류 → TypeScript 오류 수정
|
||||
|
||||
2. **Vercel 배포 실패**:
|
||||
- 환경 변수 확인 (VERCEL_TOKEN 등)
|
||||
- 빌드 명령 확인
|
||||
- 출력 디렉토리 (dist) 존재 확인
|
||||
|
||||
3. **도메인 연결 실패**:
|
||||
- DNS 레코드 파급 시간 대기 (24시간)
|
||||
- Freenom과 Vercel 모두에서 설정 확인
|
||||
|
||||
## 변경 이력
|
||||
|
||||
- 2026-10-16: 초안 작성
|
||||
|
||||
@@ -0,0 +1,173 @@
|
||||
# Agent: DXF 도면 분석 & 설정 파일 생성
|
||||
|
||||
## 개요
|
||||
|
||||
**이름:** DXF Research Agent
|
||||
**역할:** 파이프라인의 첫 번째 단계 - 도면 분석 및 설정 파일 자동 생성
|
||||
**입력:** DXF 파일 (RAG 폴더)
|
||||
**출력:** `src/drawings/gasiseol.mjs` (설정 파일 + 조립 로직)
|
||||
**실행 시간:** ~5분
|
||||
|
||||
## 목표
|
||||
|
||||
2D DXF 도면을 분석하여 3D 변환을 위한 기계 가능한 설정 파일을 생성한다.
|
||||
이 에이전트의 출력이 다음 단계(Pipeline)의 입력이 된다.
|
||||
|
||||
## 지침
|
||||
|
||||
### 1단계: 도면 기본 분석
|
||||
|
||||
1. `RAG/` 폴더의 모든 DXF 파일을 읽는다
|
||||
2. 각 파일의 기본 정보 추출:
|
||||
- 엔티티 타입별 개수 (LINE, CIRCLE, TEXT, POLYLINE 등)
|
||||
- 좌표 범위 (min/max X, Y, Z)
|
||||
- 레이어 목록
|
||||
- 단위 감지 (mm/m 판별)
|
||||
|
||||
3. 분석 결과를 임시 파일에 저장: `.claude/artifacts/dxf-analysis.json`
|
||||
|
||||
### 2단계: 기준점(Datum) 검출
|
||||
|
||||
1. 기준선 자동 감지:
|
||||
- 가장 자주 나타나는 수평선 찾기 (도로 계획고, GL 등)
|
||||
- 텍스트 라벨과의 거리 계산
|
||||
- "도로", "계획고", "GL" 등의 키워드 검색
|
||||
|
||||
2. 기준점 후보 선정 및 교차검증:
|
||||
- 다른 뷰의 기준점과 비교
|
||||
- 일치하는 Z 값 확인
|
||||
|
||||
3. 최종 기준점 확정: `.claude/artifacts/datum.json`
|
||||
|
||||
**참고:** `docs/2d-3d-conversion.md` 교훈 #1, #2 필독
|
||||
|
||||
### 3단계: 뷰 분리 및 매핑
|
||||
|
||||
1. 제목 텍스트 식별:
|
||||
- 글자 높이로 필터링 (h=0.35: 뷰 제목)
|
||||
- "평면도", "단면도", "상세" 등의 키워드
|
||||
|
||||
2. 기하 클러스터링:
|
||||
- 뷰별 bounding box 계산
|
||||
- 뷰 폭 × 높이가 도면 표기와 일치하는지 검증
|
||||
|
||||
3. 뷰별 설정 생성:
|
||||
```javascript
|
||||
views: [
|
||||
{ kind: 'plan', name: '평 면 도', u0: 0, v0: 0, plane: 'XY' },
|
||||
{ kind: 'cross', name: '단 면 A-A', u0: 0, v0: -5000, plane: 'XZ' },
|
||||
]
|
||||
```
|
||||
|
||||
4. 결과 저장: `.claude/artifacts/views.json`
|
||||
|
||||
### 4단계: 프로파일 추출
|
||||
|
||||
1. 각 뷰의 폐곡선 추출:
|
||||
- 선분 연결 추적
|
||||
- 폐쇄성 검증
|
||||
|
||||
2. 기하학 검사:
|
||||
- 자기교차 링 감지 (⚠️ 경고)
|
||||
- 꼭짓점 수 확인 (4=정상, 다른 수=의심)
|
||||
|
||||
3. 치수 텍스트와 기하 대응:
|
||||
- 폐곡선의 폭 × 높이를 도면 표기와 비교
|
||||
- 일치하지 않으면 오류 리포트
|
||||
|
||||
4. 원/호 처리:
|
||||
- CIRCLE 엔티티 수집
|
||||
- 지름으로 분류
|
||||
|
||||
5. 프로파일 저장: `.claude/artifacts/profiles.json`
|
||||
|
||||
### 5단계: 설정 파일 생성
|
||||
|
||||
1. `src/drawings/gasiseol.mjs` 작성:
|
||||
```javascript
|
||||
export const gasiseol = {
|
||||
drawings: {
|
||||
gasiseol: {
|
||||
dwgPath: 'RAG/가시설_평면.dxf',
|
||||
unitMm: 1000, // 1 DWG unit = 1000 mm
|
||||
titles: { ... },
|
||||
anchors: { ... },
|
||||
viewBoxes: { ... },
|
||||
assemble(ir) { ... }
|
||||
}
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
2. 재질 매핑:
|
||||
- 레이어명 → 재질 코드
|
||||
- 텍스트에서 사양 추출 (fck, THK 등)
|
||||
|
||||
3. 조립 함수 작성:
|
||||
- 부재별 조합 방식
|
||||
- union, difference 로직
|
||||
|
||||
4. 파일 저장 및 검증
|
||||
|
||||
## 성공 기준
|
||||
|
||||
검증 항목 (모두 필수):
|
||||
|
||||
```
|
||||
✅ DXF 파일 로드 성공
|
||||
✅ 기준점이 도면 치수 2개 이상과 ±10mm 이내로 일치
|
||||
✅ 뷰 폭/높이가 도면 표기와 ±2% 이내
|
||||
✅ 폐곡선 수가 예상과 일치 (평면: 4개, 단면: 8개 등)
|
||||
✅ 자기교차 링 0개
|
||||
✅ src/drawings/gasiseol.mjs 생성 및 구문 검증 통과
|
||||
```
|
||||
|
||||
실패 시:
|
||||
1. 오류 메시지 상세히 기록
|
||||
2. `.claude/artifacts/debug-research.log` 생성
|
||||
3. 다음 에이전트에 오류 상황 전달
|
||||
|
||||
## 사용할 도구
|
||||
|
||||
- **Read**: DXF 파일 및 기초 문서 읽기
|
||||
- **Grep**: 텍스트/레이어 패턴 검색
|
||||
- **Bash**: Node.js 스크립트 실행 (src/core/parse.mjs 등)
|
||||
- **Write**: 설정 파일 생성
|
||||
- **Edit**: 임시 파일 수정
|
||||
|
||||
## 참고 문서
|
||||
|
||||
- `docs/2d-3d-conversion.md` (교훈 #1~#12)
|
||||
- `docs/2d-3d-process.md` (절차)
|
||||
- `CLAUDE.md` (프로젝트 구조)
|
||||
- `docs/dwg2model-CLAUDE.md` (기존 구현 참고)
|
||||
|
||||
## 핸드오프 파일 구조
|
||||
|
||||
이 에이전트의 출력 파일들:
|
||||
|
||||
```
|
||||
src/drawings/gasiseol.mjs ← 주 산출물 (다음 에이전트 입력)
|
||||
.claude/artifacts/
|
||||
├── dxf-analysis.json (임시: 도면 기본 정보)
|
||||
├── datum.json (임시: 기준점)
|
||||
├── views.json (임시: 뷰 설정)
|
||||
├── profiles.json (임시: 폐곡선)
|
||||
└── debug-research.log (오류 시: 디버그 정보)
|
||||
```
|
||||
|
||||
다음 에이전트(Pipeline)는 `src/drawings/gasiseol.mjs`를 읽어 IR을 생성합니다.
|
||||
|
||||
## 체크포인트
|
||||
|
||||
이 에이전트가 실패한 경우 복구 전략:
|
||||
|
||||
1. 도면 파일 확인 (손상, 인코딩)
|
||||
2. 기준점 수동 지정 (필요시)
|
||||
3. 뷰 좌표 수동 입력 (viewBoxes)
|
||||
4. 조립 로직 단순화 (필수 부분만)
|
||||
|
||||
## 변경 이력
|
||||
|
||||
- 2026-10-16: 초안 작성
|
||||
|
||||
@@ -0,0 +1,233 @@
|
||||
# Agent: 3D 생성 & 검증 파이프라인
|
||||
|
||||
## 개요
|
||||
|
||||
**이름:** Pipeline Build Agent
|
||||
**역할:** 설정 파일로부터 IR 생성, 3D 모델 생성, 품질 검증
|
||||
**입력:** `src/drawings/gasiseol.mjs` (DXF Research가 생성)
|
||||
**출력:** `out/gasiseol.obj`, `out/gasiseol.ifc`, `baselines/gasiseol.volumes.json`
|
||||
**실행 시간:** ~10분
|
||||
**의존성:** DXF Research Agent 완료 필수
|
||||
|
||||
## 목표
|
||||
|
||||
설정 파일을 이용해 3D 모델을 생성하고, 부피 검증으로 모델 정확도를 보증한다.
|
||||
이 에이전트의 출력이 최종 배포 가능한 3D 모델이 된다.
|
||||
|
||||
## 지침
|
||||
|
||||
### 1단계: IR (중간 표현) 생성
|
||||
|
||||
1. `src/drawings/gasiseol.mjs` 읽기 및 검증:
|
||||
- 파일 구문 오류 확인
|
||||
- 필수 필드 존재 확인 (unitMm, titles, assemble 함수)
|
||||
|
||||
2. 폐곡선 추출 (src/core/loops.mjs):
|
||||
- 각 뷰의 폐곡선 수집
|
||||
- 폐쇄성 검증 (끊김 0개)
|
||||
- 자기교차 재확인
|
||||
|
||||
3. 기하학 검증 (src/core/views.mjs):
|
||||
- 좌표 범위 타당성
|
||||
- 치수 대응 재검증
|
||||
|
||||
4. IR 생성 (src/build.mjs):
|
||||
- 폐곡선 → 프로파일 변환
|
||||
- 프로파일 → 3D 부재 (extrude, loft)
|
||||
- 부재 조합 (union, difference)
|
||||
|
||||
5. IR 검증:
|
||||
- 형상 타당성 확인
|
||||
- 부피 계산 (IR 기준): `.claude/artifacts/ir-volume.json`
|
||||
|
||||
**참고:** `docs/2d-3d-conversion.md` 교훈 #7~#16
|
||||
|
||||
### 2단계: 기하학적 검증
|
||||
|
||||
1. 폐곡선 폐쇄성 재확인:
|
||||
- 끊김 개수 = 0 필수
|
||||
- 끊기면 원인 분석 (레이어 혼동, 기호 오염 등)
|
||||
|
||||
2. 자기교차 링 검사:
|
||||
```bash
|
||||
node src/build.mjs gasiseol --loops
|
||||
# 출력에서 "✗ 자기교차" 없어야 함
|
||||
```
|
||||
|
||||
3. 형상 일관성:
|
||||
- 폐곡선의 법선 방향 일관성
|
||||
- 패인 외곽 대응 (봉투 패턴)
|
||||
|
||||
### 3단계: 3D 모델 생성 (EGModeler)
|
||||
|
||||
1. EGModeler 준비:
|
||||
```bash
|
||||
egm guide | wc -l
|
||||
# 39: 뷰어 모드 (오류!) → Edit Mode로 변경
|
||||
# 207+: 정상
|
||||
```
|
||||
|
||||
2. Python 스크립트로 명령 생성:
|
||||
```bash
|
||||
python src/run_egm.py gasiseol --export=out/gasiseol.obj
|
||||
```
|
||||
|
||||
3. 모델 생성 과정:
|
||||
- Polyline 생성 (폐곡선)
|
||||
- Extrude 실행
|
||||
- Loft 실행 (전이부)
|
||||
- Boolean 연산 (union, difference)
|
||||
|
||||
4. 완료 확인:
|
||||
```bash
|
||||
egm status
|
||||
# modelCount가 최종 파트 수와 일치하는지 확인
|
||||
```
|
||||
|
||||
**참고:** `docs/2d-3d-conversion.md` 교훈 #14, #15
|
||||
|
||||
### 4단계: 검증 (의도 vs 결과)
|
||||
|
||||
1. IR 부피 계산 (의도):
|
||||
```bash
|
||||
node src/measure.mjs gasiseol --ir
|
||||
# 출력: 245.823 m³ (IR 기준)
|
||||
```
|
||||
|
||||
2. 실제 모델 부피 측정 (결과):
|
||||
```bash
|
||||
node src/measure.mjs gasiseol
|
||||
# 출력: 245.756 m³ (모델러에서 측정)
|
||||
```
|
||||
|
||||
3. 오차 계산:
|
||||
```
|
||||
오차 = (|IR - 실제| / IR) × 100
|
||||
= (|245.823 - 245.756| / 245.823) × 100
|
||||
= 0.027% ✓ (< 0.5% 허용범위)
|
||||
```
|
||||
|
||||
4. 기준값 저장:
|
||||
```json
|
||||
// baselines/gasiseol.volumes.json
|
||||
{
|
||||
"irVolume": 245.823,
|
||||
"realVolume": 245.756,
|
||||
"error": 0.027,
|
||||
"status": "PASS",
|
||||
"timestamp": "2026-10-16T14:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 5단계: 출력 생성
|
||||
|
||||
1. OBJ 파일 (웹 렌더링용):
|
||||
```bash
|
||||
# 이미 생성됨 (step 3)
|
||||
out/gasiseol.obj
|
||||
```
|
||||
|
||||
2. IFC 파일 (BIM 표준):
|
||||
```bash
|
||||
node src/emit/ifc.mjs gasiseol > out/gasiseol.ifc
|
||||
```
|
||||
- IfcWall, IfcSlab 등 클래스 매핑
|
||||
- 재질 정보 포함
|
||||
- 레이어 정보 보존
|
||||
|
||||
3. 검증 리포트:
|
||||
```bash
|
||||
node src/measure.mjs gasiseol --report > out/gasiseol-validation.json
|
||||
```
|
||||
|
||||
## 성공 기준
|
||||
|
||||
검증 항목 (모두 필수):
|
||||
|
||||
```
|
||||
✅ IR 생성 성공
|
||||
✅ 폐곡선 폐쇄 (끊김 0개)
|
||||
✅ 자기교차 없음
|
||||
✅ 3D 모델 생성 성공
|
||||
✅ modelCount = 최종 파트 수 (Boolean 손실 없음)
|
||||
✅ 부피 오차 < 0.5% (오차율 계산으로 확인)
|
||||
✅ OBJ, IFC 파일 생성
|
||||
✅ 기준값 저장 완료
|
||||
```
|
||||
|
||||
실패 시:
|
||||
1. 오류 타입 분류:
|
||||
- 기하학 오류 → DXF Research 재실행 필요
|
||||
- Boolean 오류 → 설정 파일 수정 필요
|
||||
- EGModeler 오류 → 모델러 재시작
|
||||
|
||||
2. 상세 로그 저장: `.claude/artifacts/debug-pipeline.log`
|
||||
|
||||
## 사용할 도구
|
||||
|
||||
- **Bash**: Node.js, Python 스크립트 실행
|
||||
- **Read**: 설정 파일, 검증 기준 읽기
|
||||
- **Write**: 검증 리포트 생성
|
||||
- **Edit**: 임시 설정 수정 (필요시)
|
||||
|
||||
## 참고 명령
|
||||
|
||||
```bash
|
||||
# 전체 파이프라인 실행
|
||||
node src/run.mjs gasiseol # 기본 검증
|
||||
node src/gaps.mjs gasiseol # 끊김 분석
|
||||
node src/build.mjs gasiseol # IR 생성
|
||||
node src/build.mjs gasiseol --loops # 폐곡선 검증
|
||||
python src/run_egm.py gasiseol --export=out/gasiseol.obj
|
||||
egm status # 모델 개수 확인
|
||||
node src/measure.mjs gasiseol --ir # IR 부피
|
||||
node src/measure.mjs gasiseol # 실제 부피
|
||||
```
|
||||
|
||||
## 참고 문서
|
||||
|
||||
- `docs/2d-3d-conversion.md` (교훈 #7~#19, 매우 중요)
|
||||
- `docs/2d-3d-process.md` (절차)
|
||||
- `CLAUDE.md` (구조)
|
||||
- `STEP5-IDEAS.md` (3D 생성 상세)
|
||||
|
||||
## 핸드오프 파일 구조
|
||||
|
||||
이 에이전트의 주 산출물:
|
||||
|
||||
```
|
||||
out/
|
||||
├── gasiseol.obj ← 웹 렌더링용 (다음 에이전트 입력)
|
||||
├── gasiseol.ifc ← BIM 표준
|
||||
└── gasiseol-validation.json ← 검증 리포트
|
||||
|
||||
baselines/
|
||||
└── gasiseol.volumes.json ← 기준값 (회귀 테스트용)
|
||||
|
||||
.claude/artifacts/
|
||||
├── ir-volume.json (임시: IR 부피)
|
||||
└── debug-pipeline.log (오류 시: 로그)
|
||||
```
|
||||
|
||||
다음 에이전트(WebUI)는 `out/gasiseol.obj`를 읽어 웹에서 렌더링합니다.
|
||||
|
||||
## 체크포인트
|
||||
|
||||
실패 시 복구:
|
||||
|
||||
1. **기하학 오류**:
|
||||
- DXF Research에 오류 리포트 제출
|
||||
- 폐곡선 수동 검증
|
||||
|
||||
2. **Boolean 손실**:
|
||||
- `modelCount` 확인
|
||||
- 커터 순서 재정렬 (docs 교훈 #14)
|
||||
|
||||
3. **부피 오차 > 0.5%**:
|
||||
- IR 계산 재확인
|
||||
- 설정 파일의 assemble 함수 재검토
|
||||
|
||||
## 변경 이력
|
||||
|
||||
- 2026-10-16: 초안 작성
|
||||
|
||||
@@ -0,0 +1,217 @@
|
||||
# Agent: 웹앱 & 3D 뷰어 개발
|
||||
|
||||
## 개요
|
||||
|
||||
**이름:** WebUI Development Agent
|
||||
**역할:** React 웹앱 + Three.js 3D 뷰어 개발
|
||||
**입력:** 3D 모델 (out/gasiseol.obj), UI 요구사항
|
||||
**출력:** `src/web/` (완성된 React 프로젝트)
|
||||
**실행 시간:** ~10분
|
||||
**병렬:** Pipeline과 독립적 (동시 진행 가능)
|
||||
|
||||
## 목표
|
||||
|
||||
사용자가 브라우저에서 3D 모델을 실시간으로 보고, 상호작용할 수 있는 웹앱을 개발한다.
|
||||
|
||||
## 지침
|
||||
|
||||
### 1단계: 프로젝트 초기화
|
||||
|
||||
```bash
|
||||
cd src/web
|
||||
npm create vite@latest . -- --template react-ts
|
||||
npm install
|
||||
npm install three @react-three/fiber @react-three/drei
|
||||
npm install zustand tailwindcss
|
||||
```
|
||||
|
||||
폴더 구조:
|
||||
```
|
||||
src/web/
|
||||
├── src/
|
||||
│ ├── components/
|
||||
│ │ ├── Viewer3D.tsx
|
||||
│ │ ├── FileUpload.tsx
|
||||
│ │ ├── PropertyPanel.tsx
|
||||
│ │ ├── Controls.tsx
|
||||
│ │ └── StatusBar.tsx
|
||||
│ ├── hooks/
|
||||
│ ├── pages/
|
||||
│ ├── styles/
|
||||
│ ├── App.tsx
|
||||
│ └── main.tsx
|
||||
├── public/
|
||||
│ └── models/ (3D 모델 파일)
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
└── vite.config.ts
|
||||
```
|
||||
|
||||
### 2단계: 핵심 컴포넌트 개발
|
||||
|
||||
1. **Viewer3D.tsx**: Three.js 3D 렌더링
|
||||
- Canvas 설정 (width 100%, height 100vh)
|
||||
- OrbitControls (마우스 조작)
|
||||
- 모델 로드 (OBJLoader)
|
||||
- 기본 조명 (AmbientLight, DirectionalLight)
|
||||
- 그리드 & 축 표시
|
||||
|
||||
2. **FileUpload.tsx**: DXF 파일 업로드
|
||||
- 드래그 & 드롭
|
||||
- 파일 선택 다이얼로그
|
||||
- 유효성 검사 (.dxf만)
|
||||
|
||||
3. **PropertyPanel.tsx**: 부재 정보 표시
|
||||
- 부재명 (레이어)
|
||||
- 재질 정보
|
||||
- 부피 표시
|
||||
- 좌표 범위
|
||||
|
||||
4. **Controls.tsx**: UI 조작
|
||||
- 뷰 전환 버튼 (Top, Front, Side)
|
||||
- 줌 리셋
|
||||
- 투명도 조절
|
||||
- 레이어별 표시/숨김 토글
|
||||
|
||||
5. **StatusBar.tsx**: 상태 표시
|
||||
- 변환 진행률
|
||||
- FPS (프레임/초)
|
||||
- 메모리 사용량
|
||||
|
||||
### 3단계: Three.js 최적화
|
||||
|
||||
1. 모델 로드:
|
||||
```typescript
|
||||
const loader = new OBJLoader();
|
||||
loader.load('/models/gasiseol.obj', (object) => {
|
||||
scene.add(object);
|
||||
// 자동 줌
|
||||
new THREE.Box3().setFromObject(object);
|
||||
});
|
||||
```
|
||||
|
||||
2. 성능 최적화:
|
||||
- 정점 최적화 (BufferGeometry)
|
||||
- 인덱싱 (면 데이터 압축)
|
||||
- 스케일: 100,000개 이상 면도 60fps 유지
|
||||
|
||||
3. 라이팅 설정:
|
||||
- AmbientLight (기본 조명): 0xffffff 50%
|
||||
- DirectionalLight (그림자): 0xffffff 80%
|
||||
|
||||
### 4단계: 상호작용 구현
|
||||
|
||||
1. 부재 선택:
|
||||
- Raycaster로 클릭된 부재 감지
|
||||
- 선택 시 색상 변경 (노랑/초록)
|
||||
- PropertyPanel에 정보 표시
|
||||
|
||||
2. 측정 기능:
|
||||
- 두 점 선택 → 거리 계산
|
||||
- 면 선택 → 면적 계산
|
||||
|
||||
3. 단면 표시:
|
||||
- 평면 설정 (XY, XZ, YZ)
|
||||
- 단면 위치 슬라이더
|
||||
- 단면과 교차하는 부분만 표시
|
||||
|
||||
### 5단계: 배포 최적화
|
||||
|
||||
1. 번들 최소화:
|
||||
```bash
|
||||
npm run build
|
||||
# 결과 크기 < 500KB 목표
|
||||
```
|
||||
|
||||
2. 이미지 압축:
|
||||
- favicon, 로고 등 최적화
|
||||
|
||||
3. 지연 로딩:
|
||||
- 3D 모델 async 로드
|
||||
- 스켈레톤 로더 표시
|
||||
|
||||
4. 성능 모니터링:
|
||||
- FPS 표시 (오른쪽 상단)
|
||||
- 로드 시간 측정
|
||||
- Core Web Vitals 모니터링
|
||||
|
||||
## 성공 기준
|
||||
|
||||
```
|
||||
✅ 프로젝트 초기화 완료
|
||||
✅ 3D 모델 로드 성공
|
||||
✅ 기본 조명 설정 (명확한 시각)
|
||||
✅ 마우스 조작 가능 (회전, 줌, 패닝)
|
||||
✅ 부재 선택 & 정보 표시
|
||||
✅ 초기 로딩 < 3초
|
||||
✅ 렌더링 60fps 유지
|
||||
✅ 번들 크기 < 500KB
|
||||
✅ 모바일 반응형 (가로/세로 자동 전환)
|
||||
✅ 터치 제스처 지원 (pinch zoom)
|
||||
```
|
||||
|
||||
## 사용할 도구
|
||||
|
||||
- **Write**: 컴포넌트, 설정 파일 작성
|
||||
- **Bash**: npm 명령 실행, 빌드
|
||||
- **Edit**: 코드 수정
|
||||
|
||||
## 참고 기술
|
||||
|
||||
- **React 18+**: 함수형 컴포넌트, hooks
|
||||
- **TypeScript**: 타입 안전성
|
||||
- **Three.js**: 3D 렌더링
|
||||
- **Vite**: 빠른 개발/빌드
|
||||
- **TailwindCSS**: UI 스타일
|
||||
|
||||
## 개발 명령
|
||||
|
||||
```bash
|
||||
# 개발 서버 실행
|
||||
npm run dev
|
||||
|
||||
# 빌드
|
||||
npm run build
|
||||
|
||||
# 프리뷰 (배포 전)
|
||||
npm run preview
|
||||
```
|
||||
|
||||
## 핸드오프 파일
|
||||
|
||||
이 에이전트의 산출물:
|
||||
|
||||
```
|
||||
src/web/ ← 완성된 웹앱
|
||||
├── src/components/
|
||||
├── src/hooks/
|
||||
├── src/pages/
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
├── vite.config.ts
|
||||
└── public/models/gasiseol.obj ← Pipeline이 제공
|
||||
```
|
||||
|
||||
다음 에이전트(Deploy)는 이 폴더를 `npm run build`로 빌드하고 배포합니다.
|
||||
|
||||
## 체크포인트
|
||||
|
||||
실패 시 복구:
|
||||
|
||||
1. **모델 로드 실패**:
|
||||
- `out/gasiseol.obj` 파일 확인
|
||||
- OBJLoader 경로 재확인
|
||||
|
||||
2. **성능 저하**:
|
||||
- 정점 수 확인
|
||||
- 조명 수 줄이기
|
||||
- 텍스처 제거
|
||||
|
||||
3. **모바일 문제**:
|
||||
- 터치 이벤트 디버깅
|
||||
- 뷰포트 메타 태그 확인
|
||||
|
||||
## 변경 이력
|
||||
|
||||
- 2026-10-16: 초안 작성
|
||||
|
||||
@@ -0,0 +1,112 @@
|
||||
name: convert
|
||||
description: DXF → 3D 전체 파이프라인 (병렬 처리)
|
||||
|
||||
# 사용법: /convert gasiseol
|
||||
# 또는: /convert gasiseol --dry-run
|
||||
|
||||
parameters:
|
||||
drawing:
|
||||
type: string
|
||||
description: 도면명 (예: gasiseol)
|
||||
required: true
|
||||
|
||||
options:
|
||||
type: object
|
||||
properties:
|
||||
dry-run:
|
||||
type: boolean
|
||||
description: 실행하지 않고 계획만 표시
|
||||
default: false
|
||||
|
||||
parallel:
|
||||
type: boolean
|
||||
description: 병렬 처리 (Research + WebUI 동시)
|
||||
default: true
|
||||
|
||||
skip-web:
|
||||
type: boolean
|
||||
description: WebUI 스킵 (3D만 생성)
|
||||
default: false
|
||||
|
||||
stages:
|
||||
# Stage 1: DXF 분석 (필수)
|
||||
- name: "1️⃣ Research"
|
||||
agent: dxf-research
|
||||
description: "DXF 분석 & 설정 파일 생성"
|
||||
input: "RAG/{{ drawing }}*.dxf"
|
||||
output: "src/drawings/{{ drawing }}.mjs"
|
||||
timeout: "5m"
|
||||
on_error: "abort" # 실패하면 전체 중단
|
||||
|
||||
# Stage 2: 3D 생성 (필수, Stage 1 후)
|
||||
- name: "2️⃣ Pipeline"
|
||||
agent: pipeline-build
|
||||
description: "3D 생성 & 검증"
|
||||
depends_on: ["Research"]
|
||||
input: "src/drawings/{{ drawing }}.mjs"
|
||||
output: "out/{{ drawing }}.obj"
|
||||
timeout: "10m"
|
||||
on_error: "abort"
|
||||
|
||||
# Stage 3: 웹앱 (선택, 병렬)
|
||||
- name: "3️⃣ WebUI"
|
||||
agent: web-ui-dev
|
||||
description: "React 웹앱 개발"
|
||||
parallel_with: ["Research"] # Research와 동시 진행
|
||||
input: "out/{{ drawing }}.obj"
|
||||
output: "src/web/"
|
||||
timeout: "10m"
|
||||
skip_if: "options.skip_web"
|
||||
on_error: "warn" # 실패해도 계속
|
||||
|
||||
# Stage 4: 병합 (모든 완료 대기)
|
||||
- name: "4️⃣ Summary"
|
||||
type: "orchestrator"
|
||||
description: "결과 병합 & 최종 검증"
|
||||
depends_on: ["Pipeline"]
|
||||
action: |
|
||||
- 모든 에이전트 완료 대기
|
||||
- 최종 검증 실행 (/validate)
|
||||
- 결과 리포트 생성 (/report)
|
||||
- 배포 준비 (WebUI 있으면)
|
||||
timeout: "2m"
|
||||
|
||||
output:
|
||||
primary: "out/{{ drawing }}.obj"
|
||||
secondary:
|
||||
- "out/{{ drawing }}.ifc"
|
||||
- "baselines/{{ drawing }}.volumes.json"
|
||||
- "src/web/" (if WebUI executed)
|
||||
|
||||
success_message: |
|
||||
✅ DXF to 3D 변환 완료!
|
||||
|
||||
📊 결과:
|
||||
- 3D 모델: out/{{ drawing }}.obj
|
||||
- BIM 파일: out/{{ drawing }}.ifc
|
||||
- 부피 검증: baselines/{{ drawing }}.volumes.json
|
||||
- 웹앱: src/web/ ({{ "준비 완료" if not options.skip_web else "스킵됨" }})
|
||||
|
||||
다음: /deploy (웹사이트 배포)
|
||||
|
||||
error_handling:
|
||||
Research_failed: |
|
||||
❌ DXF 분석 실패
|
||||
|
||||
확인 사항:
|
||||
1. RAG/{{ drawing }}*.dxf 파일 존재?
|
||||
2. 파일 포맷 (DWG vs DXF)?
|
||||
3. 인코딩 문제?
|
||||
|
||||
다시 시도: /step-5 (Research만 재실행)
|
||||
|
||||
Pipeline_failed: |
|
||||
❌ 3D 생성 실패
|
||||
|
||||
확인 사항:
|
||||
1. DXF 설정 파일 유효?
|
||||
2. 폐곡선 폐쇄?
|
||||
3. 자기교차 링?
|
||||
|
||||
디버그: node src/build.mjs {{ drawing }} --loops
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
name: deploy
|
||||
description: 웹앱을 Vercel에 배포
|
||||
|
||||
# 사용법: /deploy
|
||||
# 또는: /deploy --dry-run
|
||||
# 또는: /deploy --preview
|
||||
|
||||
parameters:
|
||||
options:
|
||||
type: object
|
||||
properties:
|
||||
dry-run:
|
||||
type: boolean
|
||||
description: "실행하지 않고 확인만 (테스트)"
|
||||
default: false
|
||||
|
||||
preview:
|
||||
type: boolean
|
||||
description: "프리뷰 URL 생성 (CI/CD)"
|
||||
default: false
|
||||
|
||||
prod:
|
||||
type: boolean
|
||||
description: "프로덕션 배포 (main 브랜치)"
|
||||
default: false
|
||||
|
||||
stages:
|
||||
- name: "🧪 사전 검증"
|
||||
commands:
|
||||
- "/validate --level=full"
|
||||
- "npm run lint --prefix src/web 2>/dev/null || true"
|
||||
- "npm run type-check --prefix src/web 2>/dev/null || true"
|
||||
timeout: "5m"
|
||||
on_error: "abort"
|
||||
|
||||
- name: "🔨 빌드"
|
||||
commands:
|
||||
- "cd src/web && npm run build"
|
||||
check: "dist/ 폴더 생성"
|
||||
timeout: "3m"
|
||||
on_error: "abort"
|
||||
|
||||
- name: "📤 배포"
|
||||
commands:
|
||||
- "if [ '{{ options.dry_run }}' = 'true' ]; then echo '🔍 드라이런 모드 - 배포 안함'; else vercel --token=$VERCEL_TOKEN --{{ options.preview | default: 'prod' }}; fi"
|
||||
timeout: "5m"
|
||||
on_error: "warn"
|
||||
|
||||
success_message: |
|
||||
✅ 배포 완료!
|
||||
|
||||
{{ if options.preview }}
|
||||
🌐 프리뷰 URL: https://dxf-to-3d-preview-xxxxx.vercel.app
|
||||
리뷰 후 프로덕션 배포: /deploy --prod
|
||||
{{ else }}
|
||||
🌐 프로덕션 URL: https://dxf-to-3d.tk
|
||||
{{ endif }}
|
||||
|
||||
error_handling:
|
||||
validation_failed: |
|
||||
❌ 검증 실패 - 배포 중단
|
||||
실패 항목을 수정한 후 다시 시도하세요.
|
||||
|
||||
build_failed: |
|
||||
❌ 빌드 실패
|
||||
오류를 확인하고 src/web/ 코드를 수정하세요.
|
||||
|
||||
deploy_failed: |
|
||||
❌ Vercel 배포 실패
|
||||
- 환경 변수 확인 (VERCEL_TOKEN)
|
||||
- 인터넷 연결 확인
|
||||
- Vercel 계정 상태 확인
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
name: validate
|
||||
description: 도면 & 3D 모델 자동 검증 (4단계)
|
||||
|
||||
# 사용법: /validate [drawing]
|
||||
# 또는: /validate gasiseol --full
|
||||
# 또는: /validate --all (모든 도면)
|
||||
|
||||
parameters:
|
||||
drawing:
|
||||
type: string
|
||||
description: 도면명 (생략하면 최근 도면)
|
||||
required: false
|
||||
|
||||
options:
|
||||
type: object
|
||||
properties:
|
||||
level:
|
||||
type: string
|
||||
enum: ["1", "2", "3", "4", "full"]
|
||||
description: "검증 수준 (1=기본, 4=완전, full=모든 단계)"
|
||||
default: "full"
|
||||
|
||||
all:
|
||||
type: boolean
|
||||
description: 모든 도면 검증
|
||||
default: false
|
||||
|
||||
stages:
|
||||
- name: "Level 1️⃣: 기본 파싱"
|
||||
commands:
|
||||
- "node src/run.mjs {{ drawing }}"
|
||||
checks:
|
||||
- "✓ DXF 로드 성공"
|
||||
- "✓ 엔티티 수 > 0"
|
||||
- "✓ 기준점 감지"
|
||||
timeout: "1m"
|
||||
skip_if: "level < 1"
|
||||
|
||||
- name: "Level 2️⃣: 기하학"
|
||||
commands:
|
||||
- "node src/gaps.mjs {{ drawing }}"
|
||||
- "node src/build.mjs {{ drawing }} --loops"
|
||||
checks:
|
||||
- "✓ 뷰 폭/높이 ±2% 이내"
|
||||
- "✓ 폐곡선 수 일치"
|
||||
- "✓ 자기교차 0개"
|
||||
timeout: "2m"
|
||||
skip_if: "level < 2"
|
||||
|
||||
- name: "Level 3️⃣: 3D 모델"
|
||||
commands:
|
||||
- "node src/build.mjs {{ drawing }}"
|
||||
- "node src/measure.mjs {{ drawing }} --ir"
|
||||
- "node src/measure.mjs {{ drawing }}"
|
||||
checks:
|
||||
- "✓ 부피 오차 < 0.5%"
|
||||
- "✓ manifold 체크"
|
||||
- "✓ 면 무결성"
|
||||
timeout: "5m"
|
||||
skip_if: "level < 3"
|
||||
|
||||
- name: "Level 4️⃣: 시각화"
|
||||
commands:
|
||||
- "npm run build --prefix src/web 2>/dev/null || true"
|
||||
checks:
|
||||
- "✓ 웹 렌더링 성공"
|
||||
- "✓ 부재 정보 표시"
|
||||
- "✓ 조작 가능"
|
||||
timeout: "3m"
|
||||
skip_if: "level < 4"
|
||||
|
||||
output_format:
|
||||
type: "table"
|
||||
columns:
|
||||
- "검증 항목"
|
||||
- "상태"
|
||||
- "결과"
|
||||
- "참고"
|
||||
|
||||
success_message: |
|
||||
✅ 모든 검증 통과!
|
||||
|
||||
상태: PASS
|
||||
- Level 1 (파싱): ✓
|
||||
- Level 2 (기하학): ✓
|
||||
- Level 3 (3D): ✓
|
||||
- Level 4 (시각화): ✓
|
||||
|
||||
failure_message: |
|
||||
⚠️ 검증 실패
|
||||
|
||||
실패 항목:
|
||||
{{ failed_checks }}
|
||||
|
||||
권장 조치:
|
||||
1. 기하학 실패 → /step-5 (Research)
|
||||
2. 3D 실패 → /step-6 (Pipeline)
|
||||
3. 시각화 실패 → /step-7 (WebUI)
|
||||
|
||||
Reference in new issue
Block a user