마지막 업데이트 2026-07-22
이 문서는 PPI 프로젝트에서 발생한 버그, 성능 문제, 배포 실패, WebRTC 이상 현상처럼 원인 분석과 해결이 필요한 요청을 AI에게 정확하게 전달하는 방법을 정리한 안내서입니다.
핵심은 “무엇이 문제인지”보다 “어떤 결과를 원하는지”를 함께 전달하는 것입니다.
무엇이 안 되는지, 어느 화면에서 발생하는지 적습니다.
guest / host / socket / web / 배포 / 인프라 중 어디 문제인지 명시합니다.
정상이라면 어떻게 보여야 하는지 설명합니다.
현재 어떤 문제가 보이는지, 에러 메시지가 있으면 함께 적습니다.
어떤 순서로 하면 문제를 볼 수 있는지 적습니다.
무엇이 되면 해결로 판단할 수 있는지 알려줍니다.
[페이지/기능]에서 [증상]이 발생한다.
기대 동작은 [기대]이고 실제 동작은 [실제]다.
재현 방법은 [1, 2, 3]이다.
원인 분석 후 [수정/검증/대안]까지 해줘.guest 아바타 영상이 idle/talking 전환 때 다른 아바타로 바뀌는 문제가 있어. RMS 입모양 수정 기능과 관련이 있는지도 같이 분석해줘.
핑퐁이 음성이 호스트에게 전달되지 않아. socket 이벤트 흐름과 media relay 경로를 확인해서 원인을 찾아줘.
meet 페이지에서 화면 공유 시작 후 잠깐 뒤 끊겨. 원인 분석 후 typecheck/lint까지 검증해줘.
dev 배포는 성공했는데 /api/health만 정상이고 화면은 비어 있어. 서버와 브라우저 양쪽 로그를 기준으로 원인을 찾아줘.
“guest 입장 후 대화 시작 시 이전 아바타 영상이 보인다. avatar resource 매핑과 RMS 기능의 관련 여부를 포함해 원인 분석하고 수정해줘.”
“아바타가 이상해요. 좀 봐주세요.”
정보가 부족해도 시작은 가능하지만, 위 항목이 많을수록 더 정확하고 빠르게 해결할 수 있습니다.