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