← 홈 / reference

Hermes ppi-bug-tracer

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

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

설정 변경 이력