From 889183878d546bc5e1d100d7703eb41c29607939 Mon Sep 17 00:00:00 2001 From: Claude Haiku Date: Mon, 19 Oct 2026 08:44:20 +0900 Subject: [PATCH] =?UTF-8?q?step7:=20=ED=95=98=EB=84=A4=EC=8A=A4=20?= =?UTF-8?q?=EC=84=A4=EA=B3=84=20=EC=95=84=ED=82=A4=ED=85=8D=EC=B2=98=20?= =?UTF-8?q?=EB=B3=B4=EA=B0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 추가 내용: ✅ CLAUDE.md 보강 - 하네스 설계 원칙 (Anthropic 기반) - Tractable Chunks (작업 분해) - Structured Artifacts (파일 기반 핸드오프) - 체크포인트 시스템 - 오류 복구 절차 - 상태 관리 아키텍처 ✅ HARNESS-DESIGN.md (신규, 상세 문서) - 의존성 그래프 (시각화) - 병렬 실행 전략 - 체크포인트 지점 & 저장 방식 - 4가지 오류 시나리오 & 복구 - PROGRESS.md 상태 머신 - 모니터링 & 알림 - 베스트 프랙티스 특징: - 자동 오류 복구 (부분 재실행) - 4단계 검증 (다층 방어) - 체크포인트 기반 상태 추적 - 파일 기반 에이전트 통신 (신뢰성) 다음: 단계 8 (실제 워크플로우 테스트) --- CLAUDE.md | 123 +++++++++++++ HARNESS-DESIGN.md | 437 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 560 insertions(+) create mode 100644 HARNESS-DESIGN.md diff --git a/CLAUDE.md b/CLAUDE.md index 5e983c4..7dfec2d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -282,6 +282,129 @@ git push --- +--- + +## 🏗️ 하네스 설계 아키텍처 (단계 7) + +### 핵심 원칙 + +Anthropic의 "harness-design-long-running-apps" 설계를 적용: + +#### 1. Tractable Chunks (관리 가능한 단위) +``` +복잡한 작업 분해 → 각 에이전트가 한 가지만 담당 + +/convert gasiseol +├─ Stage 1: Research (도면 분석) +├─ Stage 2: Pipeline (3D 생성) +├─ Stage 3: WebUI (앱 개발, 병렬) +└─ Stage 4: Summary (병합 & 검증) +``` + +#### 2. Structured Artifacts (파일 기반 핸드오프) +``` +에이전트 간 통신 = JSON/JS 파일 (스키마 명시) + +Research 생성 → src/drawings/gasiseol.mjs +Pipeline 생성 → out/gasiseol.obj +Validation → baselines/gasiseol.volumes.json + +각 파일 = 명확한 계약 → 에이전트가 신뢰할 수 있음 +``` + +#### 3. 체크포인트 기반 복구 +``` +각 에이전트 완료 후: .claude/artifacts/ 에 스냅샷 저장 +실패 시: 마지막 성공 지점에서 재개 + +예: Pipeline 실패 → Research 결과는 유지 → Pipeline만 재실행 +``` + +#### 4. 3-에이전트 검증 +``` +Generator (생성) ← Research, Pipeline, WebUI +Evaluator (검증) ← /validate 커맨드 +Reporter (보고) ← PROGRESS.md, /report +``` + +### 에이전트 의존성 + +``` + DXF 파일 + ↓ + [Research] ← 기준점 검출, 설정 파일 생성 + ↓ + gasiseol.mjs + ↓ + [Pipeline] ← 3D 생성, 부피 검증 + ↓ + gasiseol.obj + ↓ + [WebUI] (병렬 가능) ← 웹앱 개발 + [Deploy] ← CI/CD 배포 +``` + +**병렬**: Research ↔ WebUI (독립적) +**순차**: Research → Pipeline → Deploy + +### 상태 관리 + +``` +PROGRESS.md + ├─ 현재 단계 + ├─ 완료된 작업 + ├─ 진행 중인 작업 + └─ 다음 예정 + +.claude/artifacts/ + ├─ gasiseol-checkpoint-1.json (Research 완료) + ├─ gasiseol-checkpoint-2.json (Pipeline 완료) + └─ debug-*.log (오류 시) + +baselines/ + └─ gasiseol.volumes.json (기준값, 회귀 테스트) +``` + +### 오류 복구 절차 + +``` +1️⃣ 오류 감지 + /validate 실패 → 어느 에이전트 문제? + +2️⃣ 원인 파악 + - 기하학 오류 → Research 재실행 + - Boolean 오류 → Pipeline 재실행 + - 렌더링 오류 → WebUI 재실행 + +3️⃣ 해당 에이전트만 재개 + 마지막 체크포인트에서 시작 + 이전 단계의 파일은 유지 + +4️⃣ 재검증 + /validate --level=full + +5️⃣ 진행 상황 업데이트 + PROGRESS.md 수정 +``` + +### 품질 계층 (다층 방어) + +``` +Layer 1: 파일 존재 확인 + └─ 각 에이전트 출력 파일 존재? + +Layer 2: 스키마 검증 + └─ JSON/JS 구조 올바름? + +Layer 3: 기능 검증 + └─ 기하학? 부피? 렌더링? + +Layer 4: 회귀 검증 + └─ 기준값과 비교 (오차 < 0.5%) +``` + +--- + ## 라이선스 이 프로젝트는 [`docs/dwg2model-CLAUDE.md`](docs/dwg2model-CLAUDE.md)를 상속받는다. diff --git a/HARNESS-DESIGN.md b/HARNESS-DESIGN.md new file mode 100644 index 0000000..0a44054 --- /dev/null +++ b/HARNESS-DESIGN.md @@ -0,0 +1,437 @@ +# 하네스 설계 상세 문서 (단계 7) + +> Anthropic 엔지니어링 블로그 "harness-design-long-running-apps" 기반 +> DXF to 3D 프로젝트의 구체적인 구현 + +--- + +## 목차 + +1. [아키텍처 개요](#아키텍처-개요) +2. [에이전트 의존성](#에이전트-의존성) +3. [체크포인트 시스템](#체크포인트-시스템) +4. [오류 복구](#오류-복구) +5. [상태 관리](#상태-관리) +6. [모니터링](#모니터링) + +--- + +## 아키텍처 개요 + +### 설계 원칙 + +``` +복잡한 작업 (DXF → 웹앱) + ↓ +단위별 분해 (4개 에이전트) + ↓ +파일 기반 핸드오프 (JSON/JS/OBJ) + ↓ +자동 검증 (4단계) + ↓ +오류 시 부분 복구 (체크포인트) +``` + +### 왜 이 설계인가? + +| 설계 요소 | 문제 해결 | +|---------|---------| +| Tractable Chunks | 큰 작업이 한 에이전트를 압도하는 것 방지 | +| Structured Artifacts | 에이전트 간 통신의 신뢰성 보장 | +| 체크포인트 | 실패 후 처음부터 다시 시작하는 낭비 방지 | +| 다층 검증 | 조용히 틀리는 오류 조기 발견 | + +--- + +## 에이전트 의존성 + +### 의존성 그래프 + +``` +입력 레이어: + RAG/가시설_*.dxf (7개 파일) + ↓ +처리 레이어 1 (병렬 가능): + ┌───────────────────┬────────────────┐ + ↓ ↓ +[Research Agent] [WebUI Agent] +도면 분석 웹앱 개발 +설정 파일 생성 (독립적) + ↓ +src/drawings/gasiseol.mjs + ↓ +처리 레이어 2 (순차): +[Pipeline Agent] + 3D 생성 + 부피 검증 + ↓ +out/gasiseol.obj, out/gasiseol.ifc + ↓ +검증 레이어: +[Validator] + 4단계 검증 + 기준값 저장 + ↓ +baselines/gasiseol.volumes.json + ↓ +출력 레이어: +[Deploy Agent] + 웹 빌드 + Vercel 배포 + ↓ +https://dxf-to-3d.tk +``` + +### 병렬 실행 전략 + +``` +Timeline (최악의 경우): + +Sequential (순차): + Research (5분) → Pipeline (10분) → Deploy (5분) = 20분 + +Parallel (병렬, 이상적): + Research (5분) ──┐ + WebUI (10분) ────┼→ Pipeline (10분) → Deploy (5분) = 25분 + (여전히 더 빠름: 25 < 30) + +실제 구현: + 1. Research + WebUI 동시 시작 + 2. Research 완료 대기 + 3. Pipeline 시작 + 4. WebUI 완료 (이미 끝남) + 5. Deploy 시작 +``` + +### 의존성 테이블 + +| 에이전트 | 입력 파일 | 출력 파일 | 선행 요구 | +|---------|---------|---------|---------| +| Research | RAG/*.dxf | src/drawings/gasiseol.mjs | 없음 | +| Pipeline | src/drawings/gasiseol.mjs | out/gasiseol.obj | Research ✓ | +| WebUI | out/gasiseol.obj | src/web/ | 없음 (선택) | +| Deploy | src/web/, out/gasiseol.obj | https://dxf-to-3d.tk | Pipeline ✓ | +| Validator | 모든 파일 | baselines/gasiseol.volumes.json | Pipeline ✓ | + +--- + +## 체크포인트 시스템 + +### 체크포인트 지점 + +각 에이전트 완료 후 자동 저장: + +``` +1️⃣ Research 완료 + └─ 저장: .claude/artifacts/gasiseol-cp-1-research.json + 내용: { + timestamp: "2026-10-19T14:30:00Z", + agent: "research", + output: "src/drawings/gasiseol.mjs", + status: "success|fail", + error: "..." (if fail) + } + +2️⃣ Pipeline 완료 + └─ 저장: .claude/artifacts/gasiseol-cp-2-pipeline.json + 내용: { + timestamp: "2026-10-19T14:45:00Z", + agent: "pipeline", + output: "out/gasiseol.obj", + volumes: { irVolume, realVolume, error }, + status: "success|fail" + } + +3️⃣ WebUI 완료 + └─ 저장: .claude/artifacts/gasiseol-cp-3-webui.json + +4️⃣ Deploy 완료 + └─ 저장: .claude/artifacts/gasiseol-cp-4-deploy.json + 내용: { + url: "https://dxf-to-3d.tk", + timestamp: "...", + status: "success|fail" + } +``` + +### 체크포인트 저장 방식 + +```bash +# Research 완료 후 +cat > .claude/artifacts/gasiseol-cp-1.json << 'EOF' +{ + "stage": 1, + "agent": "research", + "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)", + "output_file": "src/drawings/gasiseol.mjs", + "status": "success", + "md5": "$(md5sum src/drawings/gasiseol.mjs | cut -d' ' -f1)" +} +EOF +``` + +--- + +## 오류 복구 + +### 복구 전략 + +#### Scenario 1: Research 실패 + +``` +상황: DXF 분석 오류 +영향: 설정 파일 미생성 + +복구: + 1. 오류 로그 분석 (.claude/artifacts/debug-research.log) + 2. DXF 파일 검증 + 3. Research 재실행 + 4. 기준점 수동 지정 (필요시) + 5. /validate --level=2 (기하학만 검증) + +비용: 5분 +영향 받음: 나머지 모든 단계 (차단) +``` + +#### Scenario 2: Pipeline 실패 + +``` +상황: 부피 오차 > 0.5% +영향: 3D 모델 부정확 + +복구: + 1. IR 부피 vs 실제 부피 비교 + 2. Boolean 손실 확인 (modelCount) + 3. assemble() 함수 재검토 + 4. Research 결과 파일 유지 (체크포인트 사용) + 5. Pipeline만 재실행 + +비용: 10분 +영향 받음: Deploy (차단) +``` + +#### Scenario 3: WebUI 실패 + +``` +상황: React 빌드 오류 +영향: 웹앱 미생성 + +복구: + 1. TypeScript 오류 확인 + 2. 의존성 설치 재시도 (npm ci) + 3. WebUI만 재실행 + 4. Research, Pipeline은 유지 + +비용: 10분 +영향 받음: Deploy (차단) +``` + +#### Scenario 4: Deploy 실패 + +``` +상황: Vercel 배포 오류 +영향: 웹사이트 미업데이트 + +복구: + 1. GitHub Actions 로그 확인 + 2. 환경 변수 검증 + 3. Deploy만 재실행 + 4. 나머지는 모두 유지 + +비용: 5분 +영향 받음: 사용자 (임시) +``` + +### 복구 검사목록 + +각 에이전트 재실행 후: + +``` +☐ 출력 파일 존재? +☐ 파일 크기 > 0? +☐ 스키마 유효? +☐ /validate 통과? +☐ 기준값 변경 없음? (회귀) +☐ PROGRESS.md 업데이트? +``` + +--- + +## 상태 관리 + +### PROGRESS.md 상태 머신 + +``` +┌─────────────────────────────────────────┐ +│ Idle │ +└─────────────────┬───────────────────────┘ + ↓ /convert gasiseol + ┌─────────────────────┐ + │ Stage 1: Research │ + └─────────┬───────────┘ + ↓ (Research 완료) + ┌─────────────────────┐ + ┌───┤ Stage 2: Pipeline │◄──┐ (실패 시 루프) + │ └─────────┬───────────┘ │ + │ ↓ │ + │ (Pipeline 통과) │ + │ ↓ │ + └──────────────────────────────┘ + (재실행) + + ↓ (성공) + ┌─────────────────────┐ + ┌───┤ Stage 3: WebUI+Dep │◄──┐ + │ └─────────┬───────────┘ │ + │ ↓ │ + │ (배포 완료) │ + │ ↓ │ + └──────────────────────────────┘ +``` + +### PROGRESS.md 작성 규칙 + +```markdown +## 현재 상태 + +### ✅ 완료 +- [x] Research + - 기준점 검출: OK + - 뷰 분리: OK + - 설정 파일: src/drawings/gasiseol.mjs + +### 🔄 진행 중 +- [ ] Pipeline + - 3D 생성: 진행 중... + - 부피 검증: 대기 중 + +### ⏳ 예정 +- [ ] WebUI +- [ ] Deploy + +### ⚠️ 오류 (있으면) +- [ ] Pipeline 부피 오차 > 0.5% + 해결: assemble() 함수 재검토 필요 +``` + +--- + +## 모니터링 + +### 자동 모니터링 훅 + +#### post-commit 훅 (매 커밋 후) + +```bash +# 대상 파일 변경 감지 +if git diff --cached --name-only | grep -qE "src/drawings/|RAG/"; then + + # 자동 검증 + node src/build.mjs gasiseol --validate + + if [ $? -ne 0 ]; then + # 오류 시 경고 + echo "⚠️ DXF 설정 오류 감지" + echo "상세: node src/build.mjs gasiseol --loops" + fi +fi +``` + +#### pre-deploy 훅 (배포 전) + +```bash +# 모든 검증 통과 확인 +/validate --level=full + +# 실패 시 배포 중단 +if [ $? -ne 0 ]; then + echo "❌ 배포 취소: 검증 실패" + exit 1 +fi +``` + +### 수동 모니터링 + +```bash +# 현재 상태 확인 +/report + +# 상세 검증 +/validate --level=full + +# 성능 분석 +/web-dev --analyze + +# 부피 회귀 테스트 +node src/measure.mjs gasiseol --ir --compare-baseline +``` + +--- + +## 실행 흐름 예시 + +### 성공 경로 (Happy Path) + +``` +1. /convert gasiseol + ├─ Research: ✅ (2분) + ├─ Pipeline: ✅ (8분) + ├─ WebUI: ✅ (병렬 동안) + └─ Deploy: ✅ (4분) + + 총 소요: ~15분 + 결과: https://dxf-to-3d.tk ✅ +``` + +### 오류 + 복구 경로 + +``` +1. /convert gasiseol + ├─ Research: ✅ + ├─ Pipeline: ❌ (부피 오차 1.2%) + │ └─ 체크포인트: .claude/artifacts/gasiseol-cp-1.json + │ └─ 원인: assemble() 함수 오류 + │ + └─ 복구: + 1. assemble() 함수 수정 + 2. Pipeline 재실행 + 3. /validate --level=3 (3D 검증만) + 4. ✅ 부피 오차 0.3% + 5. Deploy 진행 + + 추가 소요: ~10분 + 총: ~25분 +``` + +--- + +## 베스트 프랙티스 + +### ✅ 해야 할 것 + +``` +✓ 매 에이전트 완료 후 체크포인트 저장 +✓ 오류 시 즉시 원인 파악 +✓ PROGRESS.md 상태 유지 +✓ 부분 실패 시 해당 에이전트만 재실행 +✓ 기준값과 항상 비교 (회귀 방지) +✓ 성공/실패 모두 로그 기록 +``` + +### ❌ 하면 안 되는 것 + +``` +✗ 오류 무시하고 다음 단계 진행 +✗ 중간 파일 직접 수정 (에이전트가 신뢰할 수 없음) +✗ 체크포인트 없이 전체 재실행 +✗ 기준값 무시 (오차율 승인 없이) +✗ 에이전트 간 상태 공유 (파일 기반만 사용) +✗ 로그 미기록 (추적 불가) +``` + +--- + +## 변경 이력 + +- 2026-10-19: 초안 작성 (단계 7) +