Set up AI dev environment for recordingtest (#2)

- CLAUDE.md with collaboration rules and Planner/Generator/Evaluator cycle - .claude/ agents, commands, skills, hooks per Claude Code conventions - Sprint Contracts for sut-prober, normalizer, recorder, player, diff-reporter - SUT catalog (EG-BIM Modeler, 187 plugins) and .gitignore excluding SUT tree - PROGRESS.md / PLAN.md as shared agent handoff state - Solution scaffold targeting sut-prober PoC Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-07 13:57:20 +09:00
parent a48a8a2d1d
commit 7ffbb1f757
47 changed files with 1886 additions and 11 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,169 @@
+# CLAUDE.md — recordingtest
+
+이 파일은 Claude Code가 본 저장소에서 작업할 때 항상 읽는 프로젝트 운영 지침이다.
+
+## 0. 세션 시작 시 필독 (모든 에이전트)
+
+여러 에이전트가 작업을 분담하므로, **세션을 시작하는 모든 에이전트는 가장 먼저 다음 두 파일을 읽는다:**
+
+1. [PROGRESS.md](PROGRESS.md) — 지금까지 *무엇이 끝났는가*. 모듈별 진행 상태, 최근 완료 작업, 현재 차단 이슈.
+2. [PLAN.md](PLAN.md) — 앞으로 *무엇을 해야 하는가*. 모듈별 To-Do, 담당 에이전트, 우선순위, 의존 관계.
+
+읽고 나서 자신이 맡을 작업을 PLAN.md에서 고르고, 시작 시 PROGRESS.md에 "in progress"로 표시한다. 작업이 끝나면:
+- PROGRESS.md 의 해당 항목을 "done"으로 옮기고 날짜·결과·산출물 경로 기록
+- PLAN.md 의 완료 항목 제거 또는 다음 단계로 갱신
+- `docs/history/YYYY-MM-DD_{작업명}.md` 히스토리 파일 작성 (소요 시간·Context 사용량 필수)
+
+**원칙:** PROGRESS.md와 PLAN.md는 *에이전트 간 공유 메모리*다. 자기 머릿속에만 두지 말고 반드시 파일에 반영해야 다음 에이전트가 이어받을 수 있다. 충돌 시 최신 커밋 기준으로 머지하고, 모호하면 사용자에게 질문한다.
+
+## 0.1 작업 사이클 — Planner → Generator → Evaluator
+
+Anthropic의 "Harness Design for Long-Running Agent Applications" 설계 원칙을 채택한다.
+핵심: **생성자와 평가자를 같은 에이전트가 겸하지 않는다**. 자기 작업을 과대평가하는 편향을 피하기 위해서다.
+
+모든 비자명한(non-trivial) 모듈/기능 작업은 다음 3단계를 거친다:
+
+1. **Planner (`/contract <name>`)** — 사용자의 요청을 Sprint Contract로 변환.
+   - 산출물: `docs/contracts/<name>.md` (Goal, **Definition of Done**, Interfaces, Out of scope, Evaluation plan, Risks)
+   - DoD 항목은 **객관적으로 검증 가능**해야 한다. "잘 동작한다"는 금지.
+   - `PLAN.md`에 해당 항목 추가.
+
+2. **Generator** — Sprint Contract를 계약으로 삼고 실제 구현. 일반 세션 또는 전용 구현 에이전트가 수행.
+   - 계약을 읽고 DoD 항목만 충족시키는 데 집중.
+   - 스코프 이탈 금지. 범위 변경이 필요하면 planner를 다시 호출.
+
+3. **Evaluator (`/evaluate <name>`)** — 독립된 `evaluator` 서브에이전트가 계약 기준으로 채점.
+   - 산출물: `docs/contracts/<name>.evaluation.md` (verdict + evidence table)
+   - **fail**이면 PROGRESS.md에 done으로 옮기지 않는다. Generator가 재작업.
+   - **pass**여야만 호출자가 PROGRESS.md를 갱신한다.
+
+### 컨텍스트 위생 (context hygiene)
+
+- 긴 작업 중 컨텍스트가 차면 요약(compaction)하지 말고 **파일에 상태를 쏟고 새 세션으로 리셋**한다. PROGRESS.md/PLAN.md/Sprint Contract가 그 인계 창구다.
+- Stop hook이 핸드오프 누락을 경고한다. 무시하지 말 것.
+- 모델/하네스가 진화하므로 `.claude/` 비계는 주기적으로 감사·축소한다 (PLAN.md에 "scaffolding review" 상시 항목 유지).
+
+## 1. 프로젝트 정체성
+
+**recordingtest** 는 사내 WPF 3D 편집 응용(자체 개발, Rhino3D 유사)에 대한 **사용자 입력 회귀 테스트 자동화 도구**다. 도구 자체이지 SUT가 아니다.
+
+### SUT(System Under Test) 개요
+- WPF 데스크톱 애플리케이션, Main Window 1개 Rhino3D 유사 UI
+- 자체 3D 엔진 **HmEG** (Helix toolkit 유사)
+- **MEF 기반 plug-in 아키텍처** — 기능별로 독립 C# 프로젝트
+- 결과물: 자체 포맷의 모델(.hmeg)/프로젝트 저장 파일
+
+## 2. 핵심 전략 — Golden-file 회귀
+
+> 수동 테스트 입력을 레코딩 → 리플레이 → 결과 저장 파일을 베이스라인과 diff.
+
+ApprovalTests 패턴과 동형. SUT 코드 변경 협조를 최소화하기 위한 의도적 선택.
+
+```
+[수동 테스트] → 입력 레코드 + 결과 파일 A (baseline)
+[회귀 시점]   → 입력 리플레이 → 결과 파일 B → normalize → diff(A, B)
+```
+
+**우선순위:**
+- 1순위: recorder, player, 정규화(normalizer), diff-reporter
+- 2순위: engine-bridge (엔진 상태 sidecar JSON 덤프)
+- 후순위: viewport-verifier (픽셀/이미지 비교) — golden-file로 못 잡는 케이스 보강용
+
+## 3. 아키텍처 구성요소(예정)
+
+| 모듈 | 책임 |
+|------|------|
+| `sut-prober` | 대상 앱 실행, UIA 트리·MEF plugin 목록 덤프 |
+| `recorder` | 입력 캡처(키/마우스/포커스) + element path + offset 동시 저장 |
+| `player` | 시나리오 재생, 비동기 작업 동기화 |
+| `normalizer` | 저장 파일 정규화(타임스탬프/GUID/경로/부동소수점/순서) |
+| `diff-reporter` | baseline vs received diff, 갈라진 지점 시각화 |
+| `engine-bridge` | HmEG 내부 상태(카메라/선택/씬그래프) sidecar JSON 노출 |
+| `test-runner` | 시나리오 묶음 실행, 리포트 |
+| `viewport-verifier` | (후순위) 3D 스크린샷 SSIM 비교 |
+
+각 모듈은 독립 PoC → 통합 순서로 진행한다.
+
+## 4. 기술 스택 가이드
+
+- **언어**: C# / .NET (SUT와 동일 생태계, in-process probe 가능)
+- **UI 자동화**: **FlaUI** 1순위 (UIA 기반, .NET 네이티브). WinAppDriver/Appium은 fallback.
+- **저수준 입력**: Win32 SetWindowsHookEx (low-level mouse/keyboard) — element 매칭과 hybrid
+- **시나리오 포맷**: JSON 또는 YAML (git diff 친화적). 바이너리 금지.
+- **베이스라인 파일**: `*.approved.{ext}` / `*.received.{ext}` 명명 규칙
+- **이미지/큰 베이스라인**: Git LFS
+
+## 5. 반드시 지킬 설계 원칙
+
+1. **결정성(Determinism) 우선** — 비결정적 요소(시각·랜덤·경로·GUID·부동소수점·컬렉션 순서)는 정규화 파이프라인을 통과해야 한다. 새 필드 추가 시 정규화 규칙 동시 등록.
+2. **Element-aware 입력 캡처** — 좌표만 저장 금지. 항상 UIA element path + 상대 offset을 같이 기록해 해상도/DPI/창크기 변화에 견디게 한다.
+3. **타이밍 동기화** — 고정 sleep 금지. UIA 이벤트, property 변경, plugin 로드 완료 신호를 대기한다.
+4. **Dispatcher marshaling** — SUT 내부 probe/hook 코드는 반드시 WPF UI thread 위에서 동작.
+5. **체크포인트** — 한 시나리오 안에서 여러 번 저장→비교 가능해야 한다(이분 탐색용).
+6. **실패 아티팩트 풀세트** — 실패 시 스크린샷, UIA 트리 덤프, 엔진 상태 sidecar, 입력 로그, diff를 한 폴더에 동시 저장.
+7. **SUT 침습 최소화** — AutomationPeer/probe 부착이 필요하면 별도 어셈블리로 격리하고 SUT 팀과 합의 후 진행.
+8. **민감정보 마스킹** — 레코딩에 비밀번호/토큰 포함 금지.
+
+## 6. 환경 제약
+
+- **세션 0 불가**: WPF는 대화형 데스크톱 세션 필요 → CI에서 헤드리스 불가, RDP/대화형 agent 필요
+- **DPI/멀티모니터 정규화**: 테스트 머신은 고정 DPI 권장
+- **GPU 의존**: 3D 렌더 결과는 드라이버 영향 → 픽셀 비교는 항상 톨러런스 + 마스킹
+
+## 7. 작업 흐름 규칙
+
+### 히스토리 기록 (필수)
+모든 작업 완료 시 `docs/history/YYYY-MM-DD_{작업명}.md` 작성. 필수 항목:
+- **소요 시간**
+- **Context 사용량**
+- 관련 이슈 (#N)
+
+누락 시 저장이 차단된다.
+
+### 저장소
+- Origin: https://gitea.hmac.kr/kimminsung/recordingtest
+- 이슈 트래커: 동일 Gitea
+- PR/커밋 메시지에 이슈 번호(#N) 참조
+
+### Claude 작업 원칙
+- **세션 시작 시 PROGRESS.md / PLAN.md 먼저 읽기** (§0 참조)
+- 코드 변경 전 관련 파일 read 필수
+- 테스트 자동화 도구 자체의 회귀를 위해 본 저장소 코드도 단위 테스트 보유 권장
+- 의존성 추가는 사전에 사용자 확인
+- 메모리 시스템(`~/.claude/projects/.../memory/`)에 프로젝트 진행 상태/전략 결정 보존
+- 작업 종료 시 PROGRESS.md / PLAN.md 업데이트 + 히스토리 파일 작성 (3종 세트)
+
+## 8. 디렉터리 구조 (예정 — 셋업 시 확정)
+
+```
+recordingtest/
+├── src/
+│   ├── Recordingtest.Recorder/
+│   ├── Recordingtest.Player/
+│   ├── Recordingtest.Normalizer/
+│   ├── Recordingtest.DiffReporter/
+│   ├── Recordingtest.EngineBridge/
+│   ├── Recordingtest.SutProber/
+│   └── Recordingtest.Runner/
+├── tests/
+├── scenarios/                # 시나리오 JSON/YAML
+├── baselines/                # *.approved.* (LFS 후보)
+├── docs/
+│   ├── history/              # 작업 히스토리
+│   ├── contracts/            # Sprint Contracts + evaluations
+│   └── sut-catalog/          # sut-explorer 산출물
+├── PROGRESS.md
+├── PLAN.md
+└── CLAUDE.md
+```
+
+## 9. 비목표 (Out of Scope)
+
+- SUT 자체의 기능 변경/버그 수정
+- 일반 웹/모바일 자동화
+- 부하·성능 테스트
+- 단위 테스트 프레임워크 대체
+
+## 10. 결정 로그 위치
+
+주요 기술 결정과 그 근거는 `docs/history/`와 Claude 메모리(`project_recordingtest_*`)에 분산 저장된다. 새 결정 시 반드시 둘 다 갱신한다.