# CLAUDE.md — PoleDetect2D

> **프로젝트 명**: **PoleDetect2D** — 드론 영상에서 **라멘구조 전철주(portal-frame catenary pole)** 를 2D로 검출하는 R&D 프로젝트.
> (구 프로젝트명: RailPose3D. 2026-04-28 범위 축소: 레일 제거, 3D 제거, 라멘구조 전철주 2D 검출에 집중.)

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

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

1. [PLAN.md](PLAN.md) 를 읽는다 — 불변 기준선·sprint 분할·검증 지표.
2. [PROGRESS.md](PROGRESS.md) 를 읽는다 — 현재 sprint, 다음 액션, blocker.
3. 자신의 역할이 어느 sprint 에 속하는지 PROGRESS.md 의 *Current Sprint* 섹션과 대조해 명시한 뒤 작업을 시작한다.

작업이 끝나면 **반드시** PROGRESS.md 의 Sprint 상태판 + Activity Log 를 갱신한다.

## 1. Goal (요약)

- **입력**: 드론 nadir + oblique 영상.
- **출력**: 라멘구조 전철주의 4-keypoint 픽셀 좌표 `{foot_L, foot_R, head_L, head_R}` + 신뢰도.
- **제약**: 라벨 30장만 보유 (zero-shot/transfer/self-training 우선), Windows 환경, 한국 catenary 도메인.
- **범위 밖**: 레일 검출, 3D 좌표 추출, GeoJSON/DXF export.

## 2. Architecture (단일 모듈)

| Module | 책임 | 채택 |
|---|---|---|
| **A** Pole keypoint | 라멘구조 4-keypoint `{foot_L, foot_R, head_L, head_R}` | RTMPose-m / ViTPose |

- **foot_L / foot_R**: 왼쪽/오른쪽 기둥 하단 (지면 접점)
- **head_L / head_R**: 왼쪽/오른쪽 기둥 상단 (가로 보 연결점)

자세한 근거는 [docs/plan.md](docs/plan.md) 참조.

### 절대 하지 않는 것

- bbox 기반 detector 로 foot 추정 (oblique view 에서 가로 보가 foot 으로 오인됨 — 기하 문제)
- 30장으로 큰 모델 from-scratch 학습
- BlenderProc 합성 데이터에만 의존
- 레일 검출 코드 추가 (범위 밖)
- 3D 삼각측량 코드 추가 (범위 밖)

## 3. Harness 설계 원칙 (Anthropic engineering blog 기반)

이 프로젝트는 **Planner / Generator / Evaluator** 3-역할 분리 하네스로 운영한다.

- **Planner = `plan-architect` 에이전트** — sprint 단위로 분해, contract(번호 매긴 성공 조건) 작성.
- **Generator = `pole-detector-builder`, `data-pipeline-builder`** — 검출 모델, 데이터 파이프라인, self-training 구현.
- **Evaluator = `module-evaluator` 에이전트** — PCK@5px 로 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 A               # module-evaluator → PCK 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/                    ← 드론 원본·라벨 (gitignored)
├── configs/                 ← MMPose 설정
├── src/
│   ├── detection/           ← Module A (pole keypoint)
│   └── self_training/       ← SfM-consistent pseudo-label loop
├── pipeline/
│   └── run_detect.py        ← detection orchestrator
├── tests/
└── .claude/
    ├── agents/              ← 서브에이전트
    ├── skills/              ← /start, /sprint, /eval, /progress, /handoff, /contract
    └── settings.json        ← hooks
```

## 6. 코딩·환경 규약

- Python 3.11+, `uv` 또는 conda 환경.
- 라이브러리: `mmpose`, `albumentations`, `opencv-python`, `numpy`, `scipy`.
- 타입 힌트 필수, `ruff` + `pytest`.
- 모든 detection 출력은 **COCO-keypoints** 포맷 (pole).
- SfM 카메라 포즈는 self-training pseudo-label 생성 용도로만 사용 (3D 출력 없음).

## 7. Memory & Imports

- 자동 메모리: `~/.claude/projects/d--MYCLAUDE-PROJECT-detectelectronpole/memory/`
- 사용자 글로벌 지침: `@~/.claude/CLAUDE.md`

## 8. 응답 언어

기본 한국어. 기술 용어·라이브러리·식별자는 영어 그대로. 코드 주석은 영어.

---

이 파일을 읽은 에이전트는 **반드시** PLAN.md + PROGRESS.md 로 이어서 진행할 것.