Setup RailPose3D harness (Planner/Generator/Evaluator)
Name the project RailPose3D and stand up a multi-agent harness following the Anthropic harness-design blog principles (decomposition, separation of concerns, file-based handoff, sprint contracts, context-reset over compaction). - CLAUDE.md / PLAN.md / PROGRESS.md as the file-based handoff surface; every agent must read PLAN+PROGRESS before acting. - 7 sub-agents under .claude/agents/: plan-architect (Planner), pole-detector-builder, rail-detector-builder, triangulation- builder, data-pipeline-builder (Generators), module-evaluator (Evaluator), dataset-explorer (read-only helper). - 6 skills under .claude/skills/: /start /sprint /eval /progress /handoff /contract. - SessionStart and Stop hooks to inject the PLAN/PROGRESS briefing and remind about PROGRESS.md updates. - docs/plan.md captures the user-approved detailed plan; docs/research.md is the prior tech survey. - .gitignore excludes data/, .usage/, model checkpoints, and local Claude overrides. Tracking: closes #1 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
minsung
114
CLAUDE.md
Normal file
114
CLAUDE.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# CLAUDE.md — RailPose3D
|
||||
|
||||
> **프로젝트 명**: **RailPose3D** — 드론 영상에서 전철주·레일 등 **긴 물체를 검출**하고 SfM 카메라 포즈로 **3D 좌표화**하는 R&D 프로젝트.
|
||||
|
||||
## 0. 모든 에이전트 첫 행동 (필수)
|
||||
|
||||
세션이나 서브에이전트가 시작되면 **반드시** 다음을 먼저 수행한다:
|
||||
|
||||
1. [PLAN.md](PLAN.md) 를 읽는다 — 불변 기준선·sprint 분할·검증 지표.
|
||||
2. [PROGRESS.md](PROGRESS.md) 를 읽는다 — 현재 sprint, 다음 액션, blocker.
|
||||
3. 자신의 역할이 어느 sprint·module 에 속하는지 PROGRESS.md 의 *Current Sprint* 섹션과 대조해 명시한 뒤 작업을 시작한다.
|
||||
|
||||
작업이 끝나면 **반드시** PROGRESS.md 의 Sprint 상태판 + Activity Log 를 갱신한다.
|
||||
|
||||
## 1. Goal (요약)
|
||||
|
||||
- **입력**: 드론 nadir + oblique 영상, 그리고 SfM(COLMAP/Metashape)이 산출한 카메라 포즈와 sparse/dense cloud (사용자 보유).
|
||||
- **출력**: 전철주 base 의 3D point + 레일의 3D polyline (EPSG:5186 GeoJSON / DXF).
|
||||
- **제약**: 라벨 30장만 보유 (zero-shot/transfer/self-training 우선), Windows 환경, 한국 catenary 도메인.
|
||||
|
||||
## 2. Architecture (3-모듈, 불변)
|
||||
|
||||
| Module | 책임 | 채택 |
|
||||
|---|---|---|
|
||||
| **A** Pole keypoint | 전철주 4-keypoint `{base, top, L_arm, R_arm}` | RTMPose-m / ViTPose |
|
||||
| **B** Rail seg | 레일 binary mask → skeleton → polyline | SegFormer-B2 (3-stage transfer) |
|
||||
| **C** 2D→3D | 다중뷰 삼각측량으로 3D 좌표 산출 | DBSCAN + pycolmap + pyceres / PDAL CSF + Open3D + scipy |
|
||||
|
||||
자세한 근거는 [docs/plan.md](docs/plan.md) 참조.
|
||||
|
||||
### 절대 하지 않는 것
|
||||
|
||||
- bbox 기반 detector 로 base 추정 (oblique view 에서 완금이 base 로 오인됨 — 기하 문제)
|
||||
- SfM dense mesh 에서 직접 객체 추출 (가는 물체에서 fragment)
|
||||
- 30장으로 큰 모델 from-scratch 학습
|
||||
- Lane detector(CLRNet 등) 를 nadir 드론에 그대로 적용
|
||||
- BlenderProc 합성 데이터에만 의존
|
||||
|
||||
## 3. Harness 설계 원칙 (Anthropic engineering blog 기반)
|
||||
|
||||
이 프로젝트는 **Planner / Generator / Evaluator** 3-역할 분리 하네스로 운영한다.
|
||||
|
||||
- **Planner = `plan-architect` 에이전트** — sprint 단위로 분해, contract(번호 매긴 성공 조건) 작성.
|
||||
- **Generator = 모듈별 builder 에이전트** — `pole-detector-builder`, `rail-detector-builder`, `triangulation-builder`, `data-pipeline-builder`.
|
||||
- **Evaluator = `module-evaluator` 에이전트** — PCK / mIoU / reprojection error 등 정량 지표로 contract pass/fail 판정.
|
||||
|
||||
원칙:
|
||||
- **Decomposition** — 한 sprint 에 한 모듈·한 feature 만.
|
||||
- **File-based handoff** — 대화 턴이 아니라 PLAN.md / PROGRESS.md / `docs/contracts/*.md` 로 인계.
|
||||
- **Context reset over compaction** — 컨텍스트 압박 시 `/handoff` 로 상태 스냅샷 후 새 세션 시작.
|
||||
- **Evaluator tuning loop** — evaluator 의 판단이 사용자와 어긋나면 evaluator 프롬프트를 갱신.
|
||||
- **Iterative simplification** — 모델 개선 시 하네스 컴포넌트가 여전히 load-bearing 인지 재검증.
|
||||
|
||||
## 4. 운영 워크플로
|
||||
|
||||
```
|
||||
[user] → /start # PLAN+PROGRESS 자동 로드·요약
|
||||
→ /sprint <id> # plan-architect → contract 생성
|
||||
→ builder agent 작업 # generator
|
||||
→ /eval <module> # module-evaluator → pass/fail
|
||||
→ /progress # PROGRESS.md 갱신
|
||||
↳ context 부족 시 /handoff 후 새 세션
|
||||
```
|
||||
|
||||
## 5. 디렉터리 규약
|
||||
|
||||
```
|
||||
detectelectronpole/
|
||||
├── CLAUDE.md ← 이 파일
|
||||
├── PLAN.md ← 불변 기준선
|
||||
├── PROGRESS.md ← 현재 상태 (자주 갱신)
|
||||
├── README.md
|
||||
├── docs/
|
||||
│ ├── plan.md ← 사용자 승인 상세 plan
|
||||
│ ├── research.md
|
||||
│ ├── contracts/ ← sprint contract 파일 (S<n>-contract.md)
|
||||
│ └── handoffs/ ← context 핸드오프 스냅샷
|
||||
├── data/ ← 드론 원본·SfM·라벨 (gitignored)
|
||||
├── configs/ ← MMPose, SegFormer 등 설정
|
||||
├── src/
|
||||
│ ├── detection/ ← 모듈 A, B
|
||||
│ ├── triangulation/ ← 모듈 C
|
||||
│ ├── self_training/
|
||||
│ └── export/ ← GeoJSON/DXF
|
||||
├── pipeline/
|
||||
│ └── run_full.py ← end-to-end orchestrator
|
||||
├── tests/
|
||||
└── .claude/
|
||||
├── agents/ ← 서브에이전트
|
||||
├── skills/ ← /start, /sprint, /eval, /progress, /handoff, /contract
|
||||
├── commands/ ← (legacy mirror, skills 와 동일 내용)
|
||||
└── settings.json ← hooks
|
||||
```
|
||||
|
||||
## 6. 코딩·환경 규약
|
||||
|
||||
- Python 3.11+, `uv` 또는 conda 환경.
|
||||
- 라이브러리: `pycolmap`, `pyceres`, `open3d`, `pdal`, `mmpose`, `transformers`(SegFormer), `albumentations`, `scipy`, `geomdl`, `ezdxf`.
|
||||
- 타입 힌트 필수, `ruff` + `pytest`.
|
||||
- 모든 detection 출력은 **COCO-keypoints** (pole) / **GeoJSON-like polyline** (rail) 통합 포맷으로 직렬화.
|
||||
- 좌표계: 기본 EPSG:5186 (Korea Central Belt 2010), 로컬 frame 인 경우 GCP 3점으로 변환.
|
||||
|
||||
## 7. Memory & Imports
|
||||
|
||||
- 자동 메모리: `~/.claude/projects/d--MYCLAUDE-PROJECT-detectelectronpole/memory/`
|
||||
- 사용자 글로벌 지침: `@~/.claude/CLAUDE.md`
|
||||
|
||||
## 8. 응답 언어
|
||||
|
||||
기본 한국어. 기술 용어·라이브러리·식별자는 영어 그대로. 코드 주석은 영어.
|
||||
|
||||
---
|
||||
|
||||
이 파일을 읽은 에이전트는 **반드시** PLAN.md + PROGRESS.md 로 이어서 진행할 것.
|
||||
Reference in New Issue
Block a user