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>
2026-04-28 08:32:05 +09:00
parent 39df31f3e4
commit 417f880a87
23 changed files with 1202 additions and 0 deletions
--- a/.claude/skills/contract/SKILL.md
+++ b/.claude/skills/contract/SKILL.md
@@ -0,0 +1,18 @@
+---
+name: contract
+description: 특정 sprint의 contract 파일만 새로 작성하거나 갱신. plan-architect 에이전트에 위임. /sprint와 달리 PROGRESS.md 의 sprint 상태는 변경하지 않음(planning-only).
+argument-hint: <sprint-id e.g. S4>
+allowed-tools: Read, Write, Glob, Agent
+---
+
+대상 sprint: `$ARGUMENTS`
+
+1. `PLAN.md` 의 sprint 분할표에 `$ARGUMENTS` 가 있는지 확인.
+2. 기존 `docs/contracts/$ARGUMENTS-contract.md` 가 있으면 사용자에게 덮어쓸지 묻는다.
+3. **`plan-architect`** Agent 도구로 호출:
+   ```
+   Sprint $ARGUMENTS 의 contract 만 docs/contracts/$ARGUMENTS-contract.md 에
+   작성/갱신하라. PROGRESS.md sprint 상태판은 건드리지 말고, contract 링크만
+   해당 행의 Contract 칸에 갱신하라.
+   ```
+4. 결과 (생성/갱신된 contract 경로) 보고.
--- a/.claude/skills/eval/SKILL.md
+++ b/.claude/skills/eval/SKILL.md
@@ -0,0 +1,22 @@
+---
+name: eval
+description: RailPose3D 모듈 평가. module-evaluator 에이전트에 위임해 sprint contract의 성공 조건을 정량 측정. argument로 sprint id 또는 module letter (A|B|C) 를 받는다.
+argument-hint: <sprint-id|module-letter>
+allowed-tools: Read, Glob, Agent
+---
+
+평가 대상: `$ARGUMENTS`
+
+1. 입력이 sprint id (S0~S8) 면 해당 sprint 의 contract 파일을 평가 대상으로 한다.
+2. 입력이 module letter (A|B|C) 면 PROGRESS.md 에서 해당 모듈의 가장 최근 in-progress 또는 막 완료된 sprint 의 contract 를 평가 대상으로 한다.
+3. **`module-evaluator` 서브에이전트** 를 Agent 도구로 호출한다. 프롬프트:
+
+   ```
+   대상 sprint: <확정한 sprint id>
+   contract: docs/contracts/<id>-contract.md
+
+   각 success criterion 을 측정하고 contract 파일과 PROGRESS.md 를 갱신하라.
+   ```
+
+4. evaluator 결과를 사용자에게 요약 (passed criteria 수 / 전체, fail 사유) 으로 보여준다.
+5. fail 시 → 어떤 builder 를 재호출할지 권장. pass 시 → 다음 sprint 진입 권장.
--- a/.claude/skills/handoff/SKILL.md
+++ b/.claude/skills/handoff/SKILL.md
@@ -0,0 +1,41 @@
+---
+name: handoff
+description: RailPose3D context-reset 핸드오프 스냅샷 생성. 컨텍스트 윈도우 압박 또는 세션 종료 직전에 호출. docs/handoffs/YYYYMMDD-HHMM.md 에 현재 sprint·열린 의문·미완 작업·다음 행동을 기록해 새 세션이 파일 한 개만 읽고 이어갈 수 있게 한다.
+argument-hint: [optional summary]
+allowed-tools: Read, Write, Bash
+---
+
+선택 메모: `$ARGUMENTS`
+
+1. `PLAN.md`, `PROGRESS.md`, 현재 in-progress sprint 의 contract 파일을 읽는다.
+2. 현재 시각으로 파일명 결정: `docs/handoffs/<YYYYMMDD-HHMM>.md` (Bash `date +%Y%m%d-%H%M` 사용).
+3. 다음 템플릿으로 핸드오프 파일 작성:
+
+   ```markdown
+   # Handoff — <timestamp>
+
+   ## 한 줄 요약
+   <현재 sprint, 마지막에 한 일, 다음 한 줄>
+
+   ## 진행 중 sprint
+   - id, contract 경로, 현재 상태
+   - 끝낸 criterion 번호 / 남은 번호
+   - 마지막 측정 수치 (있으면)
+
+   ## 열린 의문 / blocker
+   - …
+
+   ## 다음 세션이 가장 먼저 할 일
+   1. /start
+   2. <구체적 다음 호출>
+   3. …
+
+   ## 환경 메모
+   - 활성 conda env, GPU 가용성, 현재 데이터셋 위치 등 (알면 기록)
+
+   ## 사용자 메모
+   $ARGUMENTS
+   ```
+
+4. PROGRESS.md Activity Log 에 "handoff written: <파일명>" 한 줄 append.
+5. 사용자에게 파일 경로를 보여주고 "다음 세션 첫 명령은 `/start` 후 이 핸드오프 파일을 읽도록 하세요" 안내.
--- a/.claude/skills/progress/SKILL.md
+++ b/.claude/skills/progress/SKILL.md
@@ -0,0 +1,23 @@
+---
+name: progress
+description: RailPose3D PROGRESS.md를 갱신. 현재 sprint 상태 변경, Activity Log 한 줄 추가, 다음 액션 갱신. 인자 없이 실행하면 현재 상태와 갱신 후보를 제안.
+argument-hint: [optional note]
+allowed-tools: Read, Edit, Write
+---
+
+요청 메시지: `$ARGUMENTS` (없으면 현재 상태 점검)
+
+1. `PROGRESS.md` 를 읽는다.
+2. 인자가 있으면 Activity Log 에 한 줄 추가:
+   ```
+   | <오늘 날짜 YYYY-MM-DD> | <에이전트/사용자 이름> | $ARGUMENTS | <결과 요약> |
+   ```
+3. PLAN.md 의 sprint 표와 PROGRESS.md 의 sprint 상태판을 비교해 누락/불일치를 찾는다.
+4. 사용자에게 다음을 묻는다 (한 번에 한 sprint 씩):
+   - 현재 in-progress sprint 가 완료되었나?
+   - 새 sprint 로 진입할 준비가 되었나?
+   - blocker 가 해결되었나?
+5. 응답에 따라 PROGRESS.md 를 Edit 으로 갱신.
+6. 갱신 후 `Last updated` 날짜를 오늘로 변경.
+
+**규칙**: PLAN.md 는 절대 수정하지 않는다. PLAN.md 변경이 필요하면 사용자에게 명시 승인을 요구.
--- a/.claude/skills/sprint/SKILL.md
+++ b/.claude/skills/sprint/SKILL.md
@@ -0,0 +1,24 @@
+---
+name: sprint
+description: RailPose3D 새 sprint를 시작한다. plan-architect 에이전트에 위임해 contract 파일을 생성하고 PROGRESS.md를 갱신. argument로 sprint id (S0~S8) 를 받는다.
+argument-hint: <sprint-id e.g. S2>
+allowed-tools: Read, Write, Edit, Glob, Agent
+---
+
+요청된 sprint id: `$ARGUMENTS`
+
+다음 절차를 수행한다.
+
+1. `PLAN.md` 의 Sprint 분할표에서 해당 id 행이 존재하는지 확인한다. 없으면 사용자에게 알리고 멈춘다.
+2. `PROGRESS.md` 를 읽고 의존성 sprint 가 완료되었는지(✅) 확인한다. 미완 의존성 발견 시 경고하고 진행 여부를 사용자에게 묻는다.
+3. **`plan-architect` 서브에이전트** 를 Agent 도구로 호출한다. 프롬프트는:
+
+   ```
+   Sprint $ARGUMENTS 의 contract 파일을 docs/contracts/$ARGUMENTS-contract.md 에
+   작성하라. PLAN.md 의 해당 sprint 행과 검증 기준 섹션을 근거로 번호 매긴
+   testable success criteria 를 작성하고, verification method 와 required
+   artifacts 를 명시하라. 작업 후 PROGRESS.md 의 sprint 행을 갱신하라.
+   ```
+
+4. plan-architect 가 보고한 contract 파일 경로와 갱신된 PROGRESS.md 항목을 사용자에게 보여준다.
+5. 다음 단계 권장 (어떤 builder 를 호출할지) 을 한 줄 출력한다.
--- a/.claude/skills/start/SKILL.md
+++ b/.claude/skills/start/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: start
+description: RailPose3D 세션 진입점. PLAN.md와 PROGRESS.md를 읽어 현재 sprint·다음 액션·blocker를 한 화면 요약으로 보여준다. 새 세션이나 복귀 직후 항상 가장 먼저 실행한다.
+allowed-tools: Read, Glob
+---
+
+당신은 지금 RailPose3D 프로젝트 세션을 시작했다. 다음 절차를 그대로 수행한다.
+
+1. `CLAUDE.md`, `PLAN.md`, `PROGRESS.md` 를 차례로 읽는다.
+2. 다음 형식으로 한 화면 브리핑을 출력한다 (섹션 헤더 한국어 유지):
+
+```
+# RailPose3D — 현재 상태
+
+## 현재 sprint
+<PROGRESS.md 의 Current Sprint 섹션 그대로>
+
+## Sprint 보드 (요약)
+| Sprint | 상태 |
+| --- | --- |
+| ...PLAN.md + PROGRESS.md 머지... |
+
+## 다음 액션
+<PROGRESS.md 의 Next Action 그대로>
+
+## Blockers
+<PROGRESS.md 의 Blockers 그대로 (없으면 "(없음)")>
+
+## 권장 다음 호출
+- /sprint <id>      ← 현재 sprint 시작 시
+- /contract <id>    ← contract 만 새로 만들 때
+- <builder-name>    ← in-progress sprint 의 generator 직접 호출
+- /eval <module>    ← builder 작업 직후
+- /progress         ← 작업 끝나고 PROGRESS 갱신
+```
+
+3. 사용자 입력을 기다린다. 자의적으로 작업을 시작하지 않는다.