detectelectronpole/CLAUDE.md

CLAUDE.md — RailPose3D

프로젝트 명: RailPose3D — 드론 영상에서 전철주·레일 등 긴 물체를 검출하고 SfM 카메라 포즈로 3D 좌표화하는 R&D 프로젝트.

0. 모든 에이전트 첫 행동 (필수)

세션이나 서브에이전트가 시작되면 반드시 다음을 먼저 수행한다:

1. PLAN.md 를 읽는다 — 불변 기준선·sprint 분할·검증 지표.
2. 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 참조.

절대 하지 않는 것

• 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 로 이어서 진행할 것.