# 2026-04-07 이슈 #2 — .claude/ 에이전트·커맨드·스킬·훅 셋업

- **이슈**: kimminsung/recordingtest#2
- **소요 시간**: ~15분
- **Context 사용량**: ~95k tokens

## 작업 내용

Claude Code 공식 포맷 조사(claude-code-guide 에이전트) 후, recordingtest 운영에 필요한 커스터마이즈를 `.claude/` 하위에 생성.

### Subagents — `.claude/agents/*.md`
- **sut-explorer** — EG-BIM Modeler 정적 분석(플러그인/Json/어셈블리). SUT 실행 금지.
- **diff-triager** — 회귀 실패 분류(real bug / intentional / normalization gap / env drift / flaky).
- **scenario-author** — 자연어 → 시나리오 YAML 생성.

### Slash commands — `.claude/commands/*.md`
- **/sut-probe** — sut-explorer 위임, 카탈로그 생성.
- **/regress** — 회귀 실행 + 실패 자동 triage.
- **/approve** — received → approved 승격, 사유 강제.
- **/handoff** — PROGRESS/PLAN/history 3종 세트 갱신.
- **/progress** — PROGRESS.md/PLAN.md 요약 출력.

### Skills — `.claude/skills/<name>/SKILL.md`
- **golden-file-normalizer** — 정규화 규칙 카테고리/원칙/저작 가이드.
- **flaui-cookbook** — FlaUI 런칭/대기/엘리먼트 캡처/3D 뷰포트 폴백/함정.

### Hooks — `.claude/settings.json` + `.claude/hooks/*.sh`
- **SessionStart** → `session-start-progress.sh`: PROGRESS.md/PLAN.md 자동 주입.
- **PreToolUse(Bash)** → `guard-sut-launch.sh`: EG-BIM Modeler.exe 실행 경고.
- **PreToolUse(Edit|Write)** → `guard-sut-folder.sh`: SUT 폴더 수정 차단(exit 2).
- **Stop** → `stop-handoff-reminder.sh`: 오늘 history 파일/PROGRESS/PLAN 누락 시 /handoff 권장.

## 원칙

- 포맷은 claude-code-guide 조사 결과를 따름(frontmatter: name/description/allowed-tools/tools/model).
- SUT 폴더는 **read-only** — 훅으로 강제.
- 실제 모듈(src/*)은 아직 미생성 — /regress 등은 건드릴 파일이 없으면 early-exit.

## 산출물

```
.claude/
├── agents/
│   ├── sut-explorer.md
│   ├── diff-triager.md
│   └── scenario-author.md
├── commands/
│   ├── sut-probe.md
│   ├── regress.md
│   ├── approve.md
│   ├── handoff.md
│   └── progress.md
├── skills/
│   ├── golden-file-normalizer/SKILL.md
│   └── flaui-cookbook/SKILL.md
├── hooks/
│   ├── session-start-progress.sh
│   ├── guard-sut-launch.sh
│   ├── guard-sut-folder.sh
│   └── stop-handoff-reminder.sh
└── settings.json  (hooks 섹션 추가)
```

## 다음 단계

- PROGRESS.md / PLAN.md 실제 파일 작성 (셋업 단계에서)
- src/ 모듈 scaffold
- 훅 bash 스크립트 실제 동작 검증