⚙️ Claude Code · Skill + 서브에이전트 ✅ 구현 완료 · /repro-path

재현 경로 파악 에이전트 설계

마지막 업데이트 2026-07-22

"아동070 1회기 / 아동 세션 접속 / 진행자 측에 아동 소리 안 들림" 같은 단발 증상 신고를, 동일 증상이 재현되는 단계별 경로 + 근거 타임라인으로 자동 환원하는 반복 재사용 에이전트. LogRocket(아동·진행자) · Grafana ppi-socket 미디어 로그를 실시간으로 교차 조사하고, 재현 가설을 반증으로 검증해 확신이 설 때까지 스스로 반복한다.

★ 한눈에

플랫폼
Claude Code (LogRocket MCP 기연결 · Grafana Loki API 직접 조회 · 축적 절차 재활용)

형태
Skill 1개 /repro-path + 서브에이전트 4종 (병렬 조사 3 + 반증 1)

입력
아동명 · 회기 · 증상 한 문장 (선택: 날짜/시간 · 진행자 .mov)

출력
단계별 재현 시나리오 + 근거 타임라인 + roomId 매칭 근거 + 확신도

자료 접근
실시간 — LogRocket MCP + Grafana Loki query_range API

.mov 영상
보조 증거 — 사람이 검토할 체크포인트 타임코드만 산출 (에이전트 직접 분석 X)

1 왜 Claude Code인가

후보 4종을 이 작업의 실제 요구(실시간 MCP/API 접근 · 반복 자산화 · ppi 축적 절차 재활용)로 평가.

기준	Claude Code	Hermes	Codex	openclaw
LogRocket MCP 실시간	✅ 기연결	△ 직접 연동	△ 직접 구축	△ 직접 구축
Grafana Loki API	✅ Bash/WebFetch	✅	✅	✅
재사용 자산화	✅ Skill/서브에이전트 정형화	△ 프롬프트 템플릿	△	△
목표 완료까지 자율 루프	✅ 반증 루프	✅ 강점	✅	✅
ppi 축적 절차/메모리 재활용	✅ 다수 보유	❌	❌	❌

결론 — Claude Code. Hermes·openclaw·Codex 모두 자율성은 충분하지만 "도구 연결 + ppi 진단 절차"를 처음부터 붙여야 한다. 이 작업 가치의 대부분은 바로 그 부분에 있고, Claude Code는 ① LogRocket MCP가 이미 붙어있고 ② roomId 양방향 매칭·monitor 새로고침 회귀 같은 검증된 절차가 메모리/문서로 축적돼 있어 그대로 스킬에 주입할 수 있다. Hermes/openclaw는 범용 자율 에이전트라 이 강점이 없다.

2 구성 형태 — Skill + 서브에이전트

단일 슬래시 커맨드(자율 반복 약함)나 Workflow 스크립트(토큰↑·유연성↓)보다, 대화형으로 중간 개입 가능하면서 병렬 팬아웃과 반증 루프를 모두 담는 Skill + 서브에이전트가 최적. 메인 스킬이 오케스트레이터, 조사·검증은 서브에이전트가 격리 실행한다.

서브에이전트	역할	도구	반환
child-session	날짜+아동명으로 아동 LogRocket 세션 검색 → roomId 추출 → 타임라인 추출	LogRocket MCP	표준 타임라인 + roomId + 세션 링크
host-session	같은 roomId의 진행자 세션 매칭 → 타임라인 추출 + 매칭 근거	LogRocket MCP	표준 타임라인 + 매칭 근거 + 링크
grafana-media	roomId로 ppi-socket 미디어 서버 로그 조회 (mediasoup producer/consumer·transport·relay·join 패턴)	Grafana Loki `query_range`	표준 타임라인 (서버 관점)
refuter	수립된 재현 가설을 로그로 반증 시도 (반례/대안 설명/인과 일관성)	위 산출물 일체	가설별 생존/기각 판정 + 근거

3 6단계 파이프라인

인테이크 & 증상 라우팅
필수: 아동명·회기·증상 한 문장. 선택: 날짜/시간·.mov 경로. 증상을 도메인으로 분류하고 관련 known-issue 메모리/문서를 로드해 조사 초점을 좁힌다. (라우팅표 §4)

▼

자료 수집 팬아웃 병렬 서브에이전트 3
child-session / host-session / grafana-media 를 동시 가동. 각자 표준 타임라인 스키마(§5)로 반환 → 형식이 통일돼 다음 단계에서 바로 병합 가능.

▼

교차 정렬 (correlation)
roomId 매칭 근거 확정(아동·진행자·서버 일치) → 3개 타임라인을 단일 시간축(UTC 정규화)으로 병합 → 증상 발생 추정 시점 T* 식별 및 전후 인과 후보 구간 마킹.

▼

재현 가설 수립
"전제조건 + 조작/이벤트 순서 → 증상" 형태의 후보 가설 N개. 각 가설에 전제(기기·네트워크·타이밍·조작 순서·서버 상태)를 명시.

▼

반증 검증 루프 refuter — 핵심 (§6)
가설마다 다관점 반증 시도. 수렴하면 확정, 못 깨면 부족한 자료/관점을 식별해 Stage 1로 추가 라운드. 확신 임계치 도달까지 반복.

▼

산출
단계별 재현 시나리오 + 병합 근거 타임라인 + roomId 매칭 근거 + 미해결/추가검증 항목 + .mov 확인 체크포인트 타임코드. 슬랙 붙여넣기용 요약, 선택적으로 ppi-docs HTML 저장.

4 증상 → 도메인 라우팅표

인테이크 단계에서 증상을 매핑해 조사 초점과 참고할 known-issue를 결정한다. (성장하는 표)

증상	조사 초점	참고 known-issue
한쪽만 안 들림 (오디오 미수신)	relay 경로 · mediasoup producer/consumer 생성·교체 · transport RTT	호스트 음성 relay 경로
영상 끊김	카메라 인코딩 부하 · 기기 주사율 · 동시부하(STT/오버레이)	고주사율 노트북 60Hz 가이드 · 저사양 기기 분류
자동전환 안 됨 / 스텝 회귀	guest 소켓 아웃바운드 지연 · 진행자 모니터 새로고침 stale push	`monitor-refresh-stale-step-regression`
입장/재입장 실패	validate-lesson (TOO_EARLY · REENTRY_EXPIRED · 예약 수업 없음)	LogRocket 이슈 조회 베스트프랙티스
STT 이상 (전사 누락/중복/환각)	stt_dedup · hallucination · waitForSttResponse 모드 전환	stt-expert 영역

전 증상 공통: roomId 기준 아동·진행자 양방향 매칭 후 양쪽 + 서버 로그를 시간축 비교 (LogRocket 베스트프랙티스).

5 입출력 스키마

표준 타임라인 항목 (서브에이전트 공통 반환)

{
  "ts": "2026-06-15T06:04:54.123Z",   // UTC 정규화
  "actor": "guest" | "host" | "server",
  "event": "guest-step-update / producer-replace / validate-lesson:TOO_EARLY ...",
  "detail": "사람이 읽을 한 줄 설명",
  "evidence": "LogRocket 링크 또는 Loki logline"
}

최종 산출물 구조

재현 시나리오 — 전제조건 → 단계별 조작/이벤트 순서 → 기대 증상 → 재현 확신도
근거 타임라인 — 병합된 표준 타임라인 (ts·actor·event·근거링크)
roomId 매칭 근거 — 아동/진행자 세션 링크 + 매칭 판단 근거
미해결 · 추가 검증 필요 — 부족한 자료, 사람이 확인할 .mov 체크포인트 타임코드
슬랙 붙여넣기용 요약

6 반증 검증 루프 — "끝까지 진행" 메커니즘

재현 경로가 확신 임계치에 도달할 때까지 스스로 반복하는 것이 이 에이전트의 핵심.

각 가설을 refuter 다관점(① 인과 일관성 ② 반례 이벤트 ③ 대안 설명)으로 깨본다.
생존 가설이 1개로 수렴 + 다수 관점 통과 → 확정 → Stage 5 산출.
미수렴(전부 기각 / 복수 생존 / 자료 부족) → 부족한 자료·관점을 식별 → Stage 1 추가 조사 라운드.

가드: 최대 라운드 한도(기본 3). 한도 도달·자료 부족으로 막히면 임의 단정 대신 "확정에 필요한 추가 자료"(예: .mov 특정 구간, 다른 회기 세션, 추가 Loki 쿼리)를 명시하고 사람에게 질문한다.

7 재사용 자산 파일 구성

.claude/skills/repro-path/
├─ SKILL.md            # 트리거 키워드·6단계 절차·루프 가드·출력 스키마
├─ routing.md          # 증상→도메인 라우팅표 + known-issue 메모리 링크
├─ schema.md           # 표준 타임라인 / 재현 시나리오 템플릿
└─ agents/
   ├─ child-session.md  # 아동 세션 조사 프롬프트
   ├─ host-session.md   # 진행자 세션 매칭 프롬프트
   ├─ grafana-media.md  # ppi-socket Loki 조사 프롬프트
   └─ refuter.md        # 반증 검증 프롬프트

트리거 키워드(예시): "재현 경로", "repro-path", "안 들림", "재현 안 됨", "어떻게 하면 재현돼", "[아동명] [회기] 이슈". 기존 메모리 logrocket-issue-lookup-workflow · monitor-refresh-stale-step-regression 를 절차로 직접 인용.

8 구축 단계 (구현 플랜)

SKILL.md 골격 — description(트리거 키워드 포함) + 6단계 절차 + 루프 가드 작성
routing.md — 증상→도메인 라우팅표 작성, 기존 메모리/문서 매핑 연결
schema.md — 표준 타임라인 JSON + 재현 시나리오 마크다운 템플릿 정의
서브에이전트 프롬프트 4종 — child / host / grafana / refuter, 각자 표준 스키마로 반환하도록 명시
드라이런 검증 — 아동070 1회기 "진행자 측 아동 소리 안 들림" 케이스로 전 단계 실행, 산출물 점검
ppi-docs 등록 — 운영 매뉴얼/사용법 정리 후 reference에 등록

검증 기준: 아동070 1회기 케이스에서 ① roomId 양방향 매칭 성공 ② 3개 타임라인 병합 ③ 재현 가설이 반증 루프를 통과해 1개로 수렴 ④ 단계별 재현 시나리오 + 근거 타임라인 산출.

9 사용 예시

스킬 파일은 ppi 레포 .claude/skills/repro-path/에 구현됨. 인테이크에 아동명·회기·증상 한 문장만 있으면 시작한다. (날짜/시간·.mov는 선택)

기본 호출

/repro-path 아동070 1회기 / 진행자 측에 아동 소리 안 들림

또는 트리거 키워드로 자연어 호출: "아동070 1회기에서 진행자 쪽에 아동 소리가 안 들렸대. 재현 경로 파악해줘."

예시 1 — 정보가 충분할 때 (권장)

/repro-path
아동: 아동070 / 회기: 1회기
증상: 아동 세션 접속 후 진행자 측에 아동 소리가 안 들림
시점: 2026-06-15 오후 (대략)
진행자 녹화: ~/Downloads/kimjaein-1회기.mov

에이전트 동작:

증상 라우팅 → "한쪽만 안 들림" → 조사 초점: relay 경로 · mediasoup producer/consumer · transport RTT
병렬 팬아웃 — child-session(아동 세션→roomId 추출) / host-session(같은 roomId 진행자 매칭) / grafana-media({service="ppi-socket"} |= "<roomId>")
roomId 교차정렬 → 증상 발생 시점 T* 식별
재현 가설 수립 → refuter로 반증 → 1개로 수렴할 때까지 반복
산출 — 단계별 재현 시나리오 + 근거 타임라인 + roomId 매칭 근거 + .mov 체크포인트 타임코드

예시 2 — 다른 증상 도메인

/repro-path 아동124 3회기 / 자동전환이 안 되고 이전 활동으로 돌아감

→ 라우팅이 monitor 새로고침 stale 회귀 패턴을 참조해, guest 소켓 아웃바운드 지연 + 진행자 새로고침 stale push 가설을 우선 검증.

/repro-path 아동216 2회기 / 입장이 안 됨, "예약된 수업 없음" 떴다고 함

→ validate-lesson 도메인(TOO_EARLY · REENTRY_EXPIRED · 예약 없음)으로 라우팅.

예시 3 — 최소 입력 (대화형 보완)

/repro-path 아동070 소리 안 들림

→ 회기·시점이 없으면 딱 필요한 것만 되묻는다: "몇 회기인가요? 대략 날짜/시간 알려주시면 세션 검색이 정확해집니다."

산출물 형태 (요약 예시)

■ 재현 시나리오 (확신도: 중)
  전제: 아동 기기 네트워크 약함 + 입장 직후 카메라 producer 생성
  1) 아동 입장 → audio producer 생성
  2) T*=06:04:54 transport RTT 급등 구간에서 consumer 생성 누락
  3) → 진행자 측 아동 audio consume 실패 = "안 들림"

■ 근거 타임라인 (병합)
  06:04:50 guest  produce(audio)        [LogRocket 링크]
  06:04:54 server consumer create 실패   [Loki logline]
  06:05:01 host   no remote audio track  [LogRocket 링크]

■ roomId 매칭 근거: id-011…_42 (아동/진행자 세션 링크)
■ 추가 검증 필요: .mov 06:05 구간 — 진행자 화면 음소거 표시 여부
■ [슬랙 붙여넣기용 요약] …

Claude Code · Skill + 서브에이전트 오케스트레이션 · ppi 재현 경로 파악 에이전트 (/repro-path 구현 완료)