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, 테스트

.claude/commands/convert.yaml

@@ -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
+

.claude/commands/deploy.yaml

@@ -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 계정 상태 확인
+

.claude/commands/validate.yaml

@@ -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)
+