# PLAN.md — 상세 계획 및 에이전트 역할 > **PROGRESS.md의 예정 항목을 상세히 풀어 쓴 것입니다.** > 각 단계 시작 전에 여기서 자신의 역할을 확인하세요. --- ## 전체 일정 (단계 4~9) ``` 단계 4 → 단계 5 → 단계 6 → 단계 7 → 단계 8 → 단계 9 ↓ ↓ ↓ ↓ ↓ ↓ 계획 아이디어 구현 보강 병렬화 모델확정 2일 2일 3일 1일 2일 1일 (총 ~12일) ``` --- ## 단계 4: PROGRESS.md & PLAN.md 작성 ✅ (완료) ### 목표 - PROGRESS.md: 진행 상황 추적용 (에이전트가 매 세션 읽기) - PLAN.md: 상세 계획 및 에이전트 역할 (이 파일) ### 완료 기준 - [ ] PROGRESS.md 작성 (2026-10-16) - [ ] PLAN.md 작성 (지금) - [ ] 메모리에 저장 ### 산출물 - `PROGRESS.md`: 현재 상태, 완료 단계, 예정 항목 - `PLAN.md`: 상세 계획 (이 파일) --- ## 단계 5: 에이전트/커맨드/스킬 아이디어 제안 ### 목표 Claude Code의 에이전트, 커맨드, 스킬, 훅 구조를 이해하고, 이 프로젝트에 필요한 것들을 제안한다. ### 작업 항목 #### 5.1 에이전트 설계 ``` 4개 에이전트 (병렬 처리 가능): [Agent-Research] 목적: 가시설 도면 분석 & 설정 파일 작성 담당: DXF 파싱, 좌표 검증, 기하학 분석 주요 스킬: Grep (도면 패턴 찾기), 계산 입력: 원본 DXF 파일 출력: src/drawings/gasiseol.mjs (설정 파일) [Agent-Pipeline] 목적: dwg2model 파이프라인 최적화 & 테스트 담당: 빌드, 검증, 부피 측정 주요 커맨드: node src/run.mjs, node src/build.mjs, node src/measure.mjs 입력: 설정 파일 (src/drawings/gasiseol.mjs) 출력: IR (중간 표현), 검증 리포트 [Agent-WebUI] 목적: React 웹앱 & Three.js 통합 담당: UI 컴포넌트, 3D 뷰어, API 주요 기술: React, Three.js, TypeScript 입력: 3D 모델 (OBJ/IFC) 출력: 웹앱 (src/web/) [Agent-Deploy] 목적: CI/CD, 배포, 도메인 설정 담당: GitHub Actions, Vercel, 도메인 주요 도구: git, npm, gh CLI 입력: 웹앱 소스 코드 출력: 배포된 웹사이트 + 무료 도메인 ``` #### 5.2 커맨드 설계 ``` 프로젝트 특화 커맨드 (구현 예정): /step-X 단계별 워크플로우 실행 /validate 도면 & 3D 모델 자동 검증 /convert DXF → 3D 한 번에 (3개 에이전트 병렬) /deploy 웹앱 배포 (CI/CD 자동) /report 진행 상황 & 검증 결과 리포트 ``` #### 5.3 스킬 설계 ``` 프로젝트 특화 스킬: /dxf-analyze 입력: DXF 파일 출력: 도면 분석 리포트 (좌표 범위, 레이어, 엔티티 수) /3d-validate 입력: OBJ 또는 IFC 파일 출력: 검증 리포트 (manifold, 부피, 면 수) /web-dev 입력: 3D 모델 출력: 웹앱 로컬 서버 실행 /ci-setup 입력: 저장소 설정 출력: GitHub Actions 워크플로우 파일 ``` #### 5.4 훅 설계 ``` 자동 실행 훅 (settings.json): [git commit 후] 훅: 자동 검증 → node src/measure.mjs <도면> 실행 → 부피 변화 감지 → 문제 시 경고 [PROGRESS.md 수정 후] 훅: 상태 반영 → 다음 세션에 알림 [배포 전] 훅: 모든 테스트 통과 확인 → npm run test → npm run lint → node src/build.mjs --validate ``` ### 완료 기준 - [ ] 4개 에이전트 정의 (이름, 목적, 담당, 입출력) - [ ] 5개 커맨드 아이디어 제안 - [ ] 3개 스킬 아이디어 제안 - [ ] 4개 훅 아이디어 제안 - [ ] 사용자 승인 받기 ### 산출물 - 텍스트 문서 또는 이 파일 확장 ### 의존성 - 단계 4 완료 후 --- ## 단계 6: Claude Code 구조 조사 및 정확한 포맷 구현 ### 목표 Claude Code의 공식 에이전트, 커맨드, 스킬, 훅 포맷을 학습하고, 단계 5의 아이디어를 정확한 포맷으로 구현한다. ### 작업 항목 #### 6.1 Claude Code 구조 조사 ``` 학습 대상: - .claude/agents/*.md 포맷 (에이전트 정의) - .claude/commands/*.yaml 포맷 (커맨드) - .claude/skills/*.yaml 포맷 (스킬) - settings.json hooks 포맷 (자동 실행) 공식 문서: - /help claude-code - /help agents - https://claude.com/claude-code (설명) ``` #### 6.2 정확한 포맷으로 구현 ``` 폴더 구조: D:\Obsidian Vault\999ETC\261016_HW_DwfTo3D\.claude\ ├── agents/ │ ├── dxf-research.md [Agent-Research] │ ├── pipeline-build.md [Agent-Pipeline] │ ├── web-ui-dev.md [Agent-WebUI] │ └── deploy-ci.md [Agent-Deploy] │ ├── commands/ │ ├── step.yaml (/step-X) │ ├── validate.yaml (/validate) │ ├── convert.yaml (/convert) │ └── deploy.yaml (/deploy) │ ├── skills/ │ ├── dxf-analyze.yaml (/dxf-analyze) │ ├── 3d-validate.yaml (/3d-validate) │ └── web-dev.yaml (/web-dev) │ └── settings.json └── hooks: [자동 실행 규칙] ``` #### 6.3 각 파일의 내용 ``` agents/dxf-research.md: - name: 도면 분석 & 설정 파일 - description: DXF 파일 파싱, 좌표 검증, 설정 파일 작성 - tools: [Read, Edit, Write, Grep, Bash] - instructions: [...상세 지침...] commands/convert.yaml: - name: convert - description: DXF → 3D 변환 (병렬 처리) - agents: - dxf-research (stage 1) - pipeline-build (stage 2) - web-ui-dev (stage 3) - sequential: false (병렬 실행) skills/dxf-analyze.yaml: - 트리거: /dxf-analyze <파일> - 실행: Agent-Research 호출 - 결과: 도면 분석 리포트 ``` ### 완료 기준 - [ ] .claude/ 폴더 구조 생성 - [ ] 4개 에이전트 정의 파일 작성 - [ ] 4개 커맨드 파일 작성 - [ ] 3개 스킬 파일 작성 - [ ] settings.json 훅 설정 - [ ] 모든 파일 git 커밋 ### 산출물 ``` .claude/ 폴더 완성 ├── agents/ (4개 파일) ├── commands/ (4개 파일) ├── skills/ (3개 파일) └── settings.json (훅 포함) ``` ### 의존성 - 단계 5 완료 + 아이디어 승인 후 - Claude Code 공식 문서 학습 필요 --- ## 단계 7: 추가 하네스 및 보강 ### 목표 Anthropic 엔지니어링 블로그의 "harness-design-long-running-apps" 자료를 읽고, 장기 실행 앱 설계를 프로젝트에 적용한다. ### 작업 항목 #### 7.1 하네스 개념 학습 ``` 읽을 자료: https://www.anthropic.com/engineering/harness-design-long-running-apps 학습 항목: - 에이전트 상태 관리 - 장기 실행 작업의 진행률 추적 - 오류 복구 전략 - 단계별 검증 포인트 ``` #### 7.2 프로젝트에 적용 ``` 개선 사항: 1. 에이전트 체크포인트 - 각 에이전트의 중간 결과 저장 - 실패 시 재개 가능 2. 진행 상황 실시간 추적 - PROGRESS.md 자동 업데이트 - 웹 대시보드 (옵션) 3. 롤백 가능성 - git 커밋 포인트 명확 - 문제 시 이전 버전 복구 4. 재시도 로직 - 네트워크 오류 시 재시도 - 지수 백오프 ``` #### 7.3 CLAUDE.md 업데이트 ``` 추가 내용: - 에이전트 체크포인트 정의 - 오류 복구 절차 - 진행 상황 모니터링 - 롤백 가이드 ``` ### 완료 기준 - [ ] 하네스 설계 개념 문서 작성 - [ ] 프로젝트 구조 다이어그램 (상태 관리) - [ ] CLAUDE.md 보강 - [ ] 에이전트에 체크포인트 로직 추가 ### 산출물 - 보강된 CLAUDE.md - 하네스 설계 다이어그램 - 각 에이전트의 체크포인트 정의 ### 의존성 - 단계 6 완료 후 --- ## 단계 8: 동적 에이전트 + 병렬화 워크플로우 구현 ### 목표 복합 작업을 여러 에이전트가 병렬로 처리하는 워크플로우를 구현한다. 안정성을 유지하면서 속도를 높인다. ### 작업 항목 #### 8.1 병렬 처리 구조 ``` 사용자 입력 ↓ Orchestrator 에이전트 ├─→ [Agent-Research] │ (DXF 분석, 설정 파일) │ ├─→ [Agent-Pipeline] │ (빌드, 검증) │ (Research 완료 대기) │ └─→ [Agent-WebUI] (UI 개발) (Pipeline 완료 대기) 병렬화 규칙: - Research와 WebUI: 병렬 가능 - Pipeline: Research 완료 후 시작 - 최종 병합: 모든 에이전트 완료 대기 ``` #### 8.2 워크플로우 정의 (코드 또는 설정) ``` example: convert.yaml stages: stage1: agents: - dxf-research parallel: false stage2: agents: - pipeline-build depends_on: stage1 parallel: false stage3: agents: - web-ui-dev parallel: true (stage1과 동시) stage4: agents: - orchestrator (병합) depends_on: [stage2, stage3] ``` #### 8.3 안정성 보장 ``` 체크포인트 전략: - 각 stage 시작 전: 상태 저장 - 각 stage 완료 후: 결과 검증 - 실패 시: 해당 stage부터 재시작 타임아웃: - Research: 5분 - Pipeline: 10분 - WebUI: 10분 - 전체: 30분 에러 처리: - 중단 불가: Research + WebUI (서로 독립) - 중단 가능: Pipeline 실패 → 전체 실패 ``` #### 8.4 모니터링 대시보드 (옵션) ``` 실시간 추적: ├─ 각 에이전트 진행률 ├─ 현재 병목 지점 ├─ 예상 완료 시간 └─ 오류 알림 구현: - 웹 UI (React) - 또는 CLI 대시보드 ``` ### 완료 기준 - [ ] 워크플로우 YAML 정의 - [ ] Orchestrator 에이전트 구현 - [ ] 병렬 실행 테스트 (2회 이상) - [ ] 오류 복구 테스트 - [ ] 모니터링 (CLI 또는 웹) ### 산출물 - .claude/commands/convert.yaml (병렬 워크플로우) - Orchestrator 에이전트 구현 - 워크플로우 다이어그램 - 테스트 리포트 ### 의존성 - 단계 7 완료 후 --- ## 단계 9: 모델 선택 확정 ### 목표 Haiku 4.5로 작업한 결과를 평가하고, 필요시 더 강력한 모델로 전환할지 결정한다. ### 작업 항목 #### 9.1 성능 평가 ``` 평가 항목: - 코드 품질 (정확성, 버그) - 개발 속도 (각 단계별 소요 시간) - 결과물 품질 (웹앱 기능성, 3D 정확도) - 비용 (Haiku 비용 vs 상위 모델) 기준: ✅ Haiku 충분: 모든 항목 80점 이상 △ 개선 필요: 1~2개 항목 60~80점 ❌ Haiku 부족: 2개 이상 항목 60점 미만 ``` #### 9.2 대안 평가 ``` 모델 선택지: 현재: Claude Haiku 4.5 - 비용: 저 (토큰당 0.80/3.2) - 속도: 매우 빠름 - 추론: 기본적 작업 우수 대안 1: Claude Sonnet 5 - 비용: 중 (3/15) - 속도: 빠름 - 추론: 복잡한 구조 이해 우수 대안 2: Claude Opus 5 - 비용: 높음 (15/60) - 속도: 느림 - 추론: 최고 수준 ``` #### 9.3 의사결정 ``` 선택 기준: Haiku 유지: ✓ 결과물 품질 만족 ✓ 개발 일정 충족 ✓ 비용 절감 (목표) → Sonnet 전환: ✗ 정확도 부족 (3D 모델 오류) ✗ 개발 지연 (단계별 시간 초과) ✗ 특정 기술 이해 미흡 → Opus 전환: ✗ Sonnet도 부족한 경우만 ✗ 비용 대폭 증가 ``` ### 완료 기준 - [ ] 1단계별 소요 시간 기록 - [ ] 코드 품질 평가 (린트, 테스트) - [ ] 3D 모델 정확도 검증 - [ ] 웹앱 기능 평가 - [ ] 최종 모델 결정 ### 산출물 - 평가 리포트 (성능 지표) - 모델 선택 의사결정 문서 ### 의존성 - 단계 8 완료 + 전체 구현 완료 후 --- ## 크리티컬 패스 ``` 단계 5 (아이디어) ↓ 단계 4 (계획) → 단계 6 (구현) → 단계 7 (보강) ↓ ↓ 단계 8 (병렬화) ↓ 단계 9 (평가) 병목: - 단계 5→6: 포맷 학습 (1일) - 단계 6→7: 구조 확정 (1일) - 단계 8: 병렬 안정성 (2일) ``` --- ## 리스크 및 완화책 | 단계 | 리스크 | 완화책 | |------|--------|--------| | 5 | 아이디어 과다 | 핵심만 4개 에이전트로 제한 | | 6 | 포맷 불일치 | 공식 문서 읽고 예제 확인 | | 7 | 복잡도 증가 | 단계별 검증점 명확 | | 8 | 병렬 관리 어려움 | Orchestrator 패턴 활용 | | 9 | 모델 전환 비용 | 초기 평가 명확 기준 설정 | --- ## 변경 이력 | 버전 | 날짜 | 내용 | |------|------|------| | 1.0 | 2026-10-16 | 초안 (단계 4) |