← 홈 / reference

Hermes ppi-bug-tracer

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

Hermes ppi-bug-tracer: 입력: 구성 파일, 주요 처리 단계: 증상별 탐색 진입점, 결과: 설정 변경 이력 흐름
동작 흐름 요약
  1. 입력: 구성 파일
  2. 주요 처리 단계: 증상별 탐색 진입점
  3. 결과: 설정 변경 이력
문서 읽는 법 · 활용 가이드식

이 문서는 이렇게 읽으면 됩니다

Hermes ppi-bug-tracer — PPI 버그 재현 경로 분석 에이전트의 핵심을 활용 가이드식으로 먼저 안내합니다. 기술적 결론과 원문 근거는 아래 본문에 보존되어 있습니다.

핵심 흐름 펼쳐 보기
  1. 어떤 상황에서 이 문서를 쓰는지 확인합니다.
  2. 절차와 판단 기준을 순서대로 적용합니다.
  3. 기대 산출물과 운영 체크리스트로 결과를 확인합니다.
  • 역할
  • 구성 파일
  • 사용법

PPI 버그·이슈를 입력받아 코드를 직접 탐색하고 재현 경로를 단계별로 파악하는 로컬 LLM 에이전트. Claude Code와 별개로 운영되며 오프라인 환경에서 PPI 프로젝트를 이해하는 전용 에이전트입니다.

에이전트Hermes Agent (로컬 LLM 실행환경)
모델qwen3.6:latest via Ollama (http://127.0.0.1:11434/v1)
설정 파일~/.hermes/config.yaml
역할 정의~/.hermes/SOUL.md
스킬~/.hermes/skills/ppi-bug-tracer/SKILL.md
작업 디렉토리/Users/maru/git-projects/ppi
작성일2026-06-22

역할

PPI 프로젝트에서 발생한 버그·이슈 내용을 전달하면 코드를 직접 열고 흐름을 추적하여 재현 경로를 파악해주는 에이전트입니다. 추측 대신 실제 파일을 읽고 근거를 제시합니다.

버그 / 이슈
증상·로그·에러
→
Hermes
ppi-bug-tracer
→
재현 경로
의심 파일·라인
철칙: 코드를 읽기 전에 재현 경로를 추측하지 않는다. 파일을 열고 hook → manager → socket 이벤트 흐름을 따라가며 근거를 확인한 뒤 답변한다.

구성 파일

~/.hermes/SOUL.md — 에이전트 정체성

Hermes가 매 메시지마다 로드하는 시스템 프롬프트. 재시작 없이 즉시 반영됩니다.

~/.hermes/skills/ppi-bug-tracer/SKILL.md — 분석 워크플로우

/ppi-bug-tracer 명령으로 호출하는 구조화된 4단계 분석 스킬입니다.

Phase 1 — 증상 수집
어떤 화면·역할(게스트/호스트)에서 발생했는지, 에러 메시지·로그 유무, 재현 조건 파악
Phase 2 — 코드 탐색
증상에 따라 apps/web/app/guest/ 또는 apps/web/app/main/meet/[roomId]/부터 hook → manager → socket 이벤트 순으로 파일을 직접 열고 추적
Phase 3 — 재현 경로 제시
전제 조건 / 재현 단계(번호 목록) / 예상 결과 / 실제 결과 형식으로 출력
Phase 4 — 원인 가설
의심 파일과 라인 번호, 코드 기반 원인 설명, 추가 확인 사항 제시

~/.hermes/config.yaml — 모델 및 환경 설정

model.defaultqwen3.6:latest
model.providercustom
model.base_urlhttp://127.0.0.1:11434/v1
model.api_modechat_completions
terminal.cwd/Users/maru/git-projects/ppi

사용법

기본 — 버그 내용 바로 붙여넣기

SOUL.md가 항상 로드되므로 버그 내용만 전달해도 분석을 시작합니다.

[버그 내용 / VOC / 로그 붙여넣기]

스킬 명시 호출 — 4단계 구조 강제

/ppi-bug-tracer를 먼저 입력하고 Enter → 스킬 로드 확인 후 버그 내용을 전달합니다. 스킬 호출과 버그 내용을 한 줄에 붙이면 "File name too long" 에러가 발생합니다. 

# 1단계: 스킬 호출
/ppi-bug-tracer

# 2단계: (스킬 로드 확인 후) 버그 내용 붙여넣기
제목: [버그 제목]
증상: [어떤 화면에서, 어떤 역할이, 무엇을 봄]
재현 조건: [항상 / 특정 상황]
로그/에러: [콘솔 에러, 세션 ID, LogRocket 링크]
TIP: 이미 ROOT CAUSE가 확정된 버그 리포트는 던지지 않아도 됩니다. 아직 원인이 불명확한 새 버그에 활용하세요.

증상별 탐색 진입점

게스트(아동) 화면 apps/web/app/guest/ → 관련 hook → use-session-manager → socket 이벤트
호스트(치료사) 화면 apps/web/app/main/meet/[roomId]/ → 관련 section → socket 이벤트
WebRTC / 미디어 use-media-manager → /api/ice-servers/ → WebRTC 연결 흐름
Socket 이벤트 apps/socket/server.js → 이벤트 핸들러 → web 클라이언트
핑퐁이 / OpenAI use-session-manager → apps/web/lib/openai.ts → Realtime API

Hermes 기동 및 재시작

# gateway 재시작 (config.yaml 변경 반영)
hermes gateway restart

# Hermes CLI 실행
hermes
SOUL.md는 재시작 없이 매 메시지마다 자동으로 로드됩니다. config.yaml 변경(모델·cwd 등)은 hermes gateway restart가 필요합니다.

베스트 프랙티스

✅ 좋은 예 — 증상 + 역할 + 조건이 명확한 경우

제목: 체크아웃 단계에서 아바타 전환 시 이전 아바타가 잠깐 렌더됨

증상: 태양(taeyang_v2) 아바타가 talking으로 전환될 때 지우(jiwoo_v2) talking 영상이
      약 1~2초 나타났다 사라짐. 게스트(아동) 측에서만 발생, 호스트는 정상.

재현 조건: 한 회기 안에서 지우↔태양 두 아바타를 번갈아 사용한 경우.
           아바타 단일 사용 회기는 미발생.

로그: [CHILD] MEET_VIDEO loadstart avatar_jiwoo_v2_talking_0.mp4
      (avatarId=taeyang_v2 상태에서)
세션 ID: 6-019eda46-...-119c8629e417 (LogRocket, ppi-prod, 2026-06-18)

❌ 나쁜 예 — 증상만 있고 컨텍스트가 없는 경우

아바타가 이상해요
역할(게스트/호스트), 재현 조건, 로그가 없으면 Hermes가 Phase 1(증상 수집)에서 추가 질문을 해야 하므로 분석이 느려집니다.

✅ 좋은 예 — 에러 로그를 그대로 붙이는 경우

제목: 게스트 입장 후 WebRTC 연결이 안 됨

증상: 호스트가 입장 승인 후 게스트 화면이 계속 "연결 중..." 상태로 멈춤.
      호스트는 게스트 영상이 보이지 않음.

에러 (게스트 콘솔):
  RTCPeerConnection failed
  ICEConnectionState: failed
  Error: 0 candidate pairs

재현 조건: 사내 Wi-Fi에서는 정상, 특정 학교 네트워크에서 발생.
환경: Linux x86_64 / Chrome 124

✅ 좋은 예 — "항상 발생"이 아닌 타이밍 이슈

제목: 핑퐁이가 대답 중에 다음 activity 스텝으로 넘어가면 응답이 잘림

증상: 핑퐁이가 말하는 도중 호스트가 다음 스텝으로 넘기면
      핑퐁이 음성이 즉시 끊기고 게스트 화면에 빈 영상이 잠깐 표시됨.
      이후 새 스텝은 정상 동작.

재현 조건: 핑퐁이 응답 시작 후 2초 이내에 스텝 전환 시 높은 확률로 발생.
환경: 게스트 Chrome / 호스트 Chrome (재현율 ~70%)

정보가 없을 때 Hermes에게 먼저 물어보기

로그나 에러 메시지 없이 VOC만 있는 경우, 아래처럼 전달하면 Hermes가 Phase 1 질문을 통해 필요한 정보를 요청합니다.

/ppi-bug-tracer

(다음 메시지에서 VOC 내용만 붙여넣기)
"수업 중에 핑퐁이 목소리가 안 들려요" — 강OO 학부모 피드백, 2026-06-20

설정 변경 이력