버그 리포트 예시: 좋은 리포트와 나쁜 리포트 비교
실제 같은 버그 리포트 예시 네 가지를 약한 리포트와 개선한 리포트로 나란히 보여 드리고, 바로 처리되는 리포트의 조건도 설명해요.
좋은 버그 리포트 예시에는 언제나 같은 요소가 들어 있어요. 구체적인 제목, 환경, 알려진 시작점부터 번호를 붙인 재현 단계, 정확한 에러 메시지가 담긴 기대 결과와 실제 결과, 발생 빈도, 그리고 증거예요. 아래에는 실제 있을 법한 버그 네 가지를 각각 두 번씩 써 두었어요. 처음에는 흔히 리포트되는 방식으로, 다음에는 개발자가 질문 하나 없이 바로 작업할 수 있게 다시 쓴 방식으로요.
예시는 가장 흔한 버그 유형을 다뤄요. 아무 말 없이 실패하는 흐름, 특정 기기에서만 생기는 레이아웃 문제, 잘못된 데이터, 그리고 간헐적인 에러예요. 빈 양식이 필요하다면 버그 리포트 템플릿을 복사하세요. 각 항목이 왜 필요한지는 버그 리포트 작성법에서 확인할 수 있어요.
예시 1: 아무 말 없이 실패하는 흐름
사용자가 비밀번호를 재설정했는데 이메일이 오지 않아요.
약한 버전
제목: 비밀번호 재설정 고장
비밀번호 재설정이 안 돼요. 여러 번 해 봤어요. 최대한 빨리 고쳐 주세요.
이 리포트는 개발자에게 거의 아무것도 알려 주지 않아요. 어떤 계정인가요? 어떤 환경인가요? 양식에 에러가 표시됐나요, 아니면 성공했다고 나왔나요? "여러 번 해 봤어요"는 뭔가를 암시하지만 그게 무엇인지는 알 수 없어요. 그리고 영향에 대한 설명 없는 "최대한 빨리"는 우선순위를 정하는 데 아무 도움이 되지 않아요.
좋은 버전
제목: Google 로그인으로 만든 계정에는 비밀번호 재설정 이메일이 발송되지 않음
환경
- URL: https://app.example.com/forgot-password
- Chrome 154, macOS 26
- 계정: [email protected] ("Continue with Google"로 생성)
- 시각: 2026-11-10 09:12 UTC
재현 단계
1. 로그아웃한 상태에서 /forgot-password로 이동한다.
2. [email protected]을 입력하고 "Send reset link"를 클릭한다.
기대 결과
몇 분 안에 재설정 이메일이 도착한다.
실제 결과
페이지에 "Check your inbox"가 표시된다. 이메일은 오지 않는다(30분 기다림,
스팸함 확인함). 네트워크: POST /api/auth/reset이 200을 반환했고 본문은
{"sent": false, "reason": "no_password_identity"}.
발생 빈도
Google로 만든 계정에서는 항상 발생(3/3). 이메일/비밀번호 계정
([email protected])에서는 정상 동작.
심각도
Major: Google로 가입한 사용자는 비밀번호를 설정할 수 없다.
왜 효과적인가
리포터는 두 종류의 계정을 비교해서 패턴을 찾았어요. Google 로그인으로 만든 계정만 영향을 받는다는 거죠. 이 비교 하나로 원인이 "이메일이 고장 났다"에서 코드의 특정 분기로 좁혀져요. 또 Network 패널을 열어 응답 본문을 복사했는데, 페이지는 성공했다고 하면서 서버는 아무것도 보내지 않았다는 걸 알고 있다는 사실이 드러나요. 이 불일치는 따로 적어 둘 만한 두 번째 버그예요. 정확한 시각이 있으면 팀이 이메일 서비스 제공업체의 로그를 확인할 수 있어요. 네트워크 요청을 한 번도 본 적이 없다면 Chrome에서 네트워크 트래픽을 캡처하는 방법 가이드를 참고하세요.
예시 2: 특정 기기에서만 생기는 레이아웃 버그
작은 휴대폰 화면에서 배너가 사용자가 눌러야 할 버튼을 가려요.
약한 버전
제목: 모바일에서 저장 클릭 안 됨
제 휴대폰에서 저장 버튼이 안 돼요.
"안 돼요"는 버튼이 아무 반응이 없다는 뜻일 수도, 에러가 난다는 뜻일 수도, 버튼에 손이 닿지 않는다는 뜻일 수도 있어요. "제 휴대폰"은 수천 가지 기기와 브라우저 중 무엇이든 될 수 있고요. 큰 휴대폰으로 테스트하는 개발자는 아마 아무 문제도 보지 못하고 티켓을 닫을 거예요.
좋은 버전
제목: 작은 화면에서 프로필 페이지의 Save 버튼을 쿠키 배너가 가림
환경
- URL: https://app.example.com/settings/profile
- iPhone SE(3세대)의 Safari, iOS 26, 세로 모드
- 뷰포트 약 375 x 667
- iPhone 15 Pro나 데스크톱에서는 재현되지 않음
재현 단계
1. 비공개 탭에서 URL을 연다(쿠키 배너가 나타나도록).
2. [email protected]으로 로그인한다.
3. 프로필 양식 맨 아래로 스크롤한다.
기대 결과
Save 버튼이 쿠키 배너 위에 보이고 탭할 수 있다.
실제 결과
쿠키 배너(고정 위치, 높이 약 180px)가 Save 버튼을 가린다.
버튼이 있어야 할 곳을 탭하면 배너의 "Settings" 링크가 열린다.
배너를 닫으면 Save를 누를 수 있다.
임시 해결 방법
먼저 쿠키 배너를 수락하거나 닫는다.
첨부 파일
- 스크린샷: profile-save-hidden-iphone-se.png (배너를 빨간색으로 표시)
왜 효과적인가
레이아웃 버그는 화면 크기에 따라 달라지기 때문에, 정확한 기기, 화면 방향, 뷰포트가 핵심 정보예요. 리포터는 다른 기기에서도 테스트해서 문제가 생기지 않는 곳을 적어 두었고, 덕분에 개발자는 작은 화면용 스타일을 살펴봐야 한다는 걸 알 수 있어요. 비공개 탭 단계는 배너가 확실히 나타나게 해서 개발자가 같은 화면을 보게 해 줘요. 임시 해결 방법은 지원팀이 지금 당장 사용자에게 무엇을 안내해야 할지 알려 주고, 팀이 스스로 판단할 수 있는 방식으로 긴급도를 낮춰 줘요.
예시 3: 잘못된 데이터
대시보드의 합계가 내보낸 숫자와 맞지 않아요.
약한 버전
제목: 숫자가 틀림
대시보드의 매출이 틀려요. 내보내기에서는 다르게 나와요.
어느 쪽이 맞는지는 모르겠지만 둘 중 하나는 고장 났어요.
리포터는 실제 문제를 발견했지만, "숫자가 틀림"이라고만 하면 개발자는 어떤 숫자가, 어느 기간에, 얼마나 다른지부터 찾아 헤매야 해요. 데이터 버그에는 정확한 값이 필요해요. 차이의 크기 자체가 단서인 경우가 많거든요.
좋은 버전
제목: 10월 대시보드 매출이 CSV 내보내기보다 $1,240 적음
환경
- URL: https://app.example.com/reports/revenue?period=2026-10
- 워크스페이스: Acme Demo (ID 4821), 시간대 America/Los_Angeles로 설정
- Chrome 154, Windows 11
재현 단계
1. Reports, Revenue 순으로 연다.
2. 2026년 10월을 선택한다.
3. 카드에 표시된 합계를 확인한다.
4. "Export CSV"를 클릭하고 Amount 열을 합산한다.
기대 결과
대시보드 합계와 CSV 합계가 일치한다.
실제 결과
대시보드: $48,310.00. CSV 합계: $49,550.00. 차이: $1,240.00.
차이는 로스앤젤레스 시간 기준 10월 31일 17:00 이후에 들어온
주문 세 건(ID 99812, 99815, 99820)의 금액과 같다.
발생 빈도
10월은 항상 발생. 9월 합계는 일치한다.
메모 (추측)
대시보드는 UTC 날짜로, 내보내기는 워크스페이스 시간대로
묶는 것 같다.
왜 효과적인가
이 리포트는 두 숫자, 그 차이, 그리고 차이를 만든 주문까지 알려 줘요. 마지막 단계에 리포터는 몇 분을 썼지만, 개발자는 훨씬 긴 시간을 아끼게 돼요. 시간대에 대한 추측은 추측이라고 분명히 표시해서 관찰한 사실과 구분했어요. 9월은 일치한다고 적은 덕분에, 버그가 리포트 전체가 아니라 특정 데이터와 관련 있다는 게 드러나요.
예시 4: 간헐적인 에러
업로드가 가끔 실패하는데, 아무도 이유를 몰라요.
약한 버전
제목: 업로드가 가끔 실패함
가끔 업로드가 에러와 함께 실패해요. 랜덤하게 일어나요.
"랜덤하게"는 보통 "아직 아무도 이유를 찾지 못했다"는 뜻이에요. 에러 메시지도, 파일 정보도, 횟수도 없으면 조사할 거리가 하나도 없어요.
좋은 버전
제목: 10MB가 넘는 파일을 업로드하면 "Upload failed (413)"로 실패함
환경
- URL: https://app.example.com/projects/218/files
- Chrome 154와 Firefox 158, Windows 11, 사무실 네트워크
재현 단계
1. 프로젝트를 열고 Files 탭으로 이동한다.
2. "Upload"를 클릭하고 10MB보다 큰 PDF를 선택한다
(테스트한 크기: 10.4MB, 12MB, 25MB).
기대 결과
파일이 업로드되고 목록에 나타난다.
실제 결과
진행 표시줄이 약 90퍼센트까지 차오른 뒤 "Upload failed (413)"가 표시된다.
네트워크: POST /api/files가 413 Request Entity Too Large를 반환했고,
응답 본문은 JSON이 아니라 HTML 에러 페이지다.
콘솔: Uncaught (in promise) SyntaxError: Unexpected token '<'
발생 빈도
10MB가 넘는 파일은 항상 발생(6/6). 9MB 미만 파일은 발생하지 않음(0/8).
첨부 파일
- 실패한 업로드의 화면 녹화(40초)
- 한 번의 시도를 담은 정리된 HAR 파일
왜 효과적인가
"랜덤"이던 버그는 알고 보니 파일 크기에 따라 달라졌고, 리포터는 기준선 양쪽의 횟수로 그것을 증명했어요. 413 상태 코드와 HTML 응답은 앱 앞단 어딘가에 크기 제한이 있다는 걸 가리키고, 콘솔 에러는 사용자가 왜 뭉뚱그린 메시지를 봤는지 설명해 줘요. 앱이 HTML 페이지를 JSON으로 읽으려고 한 거죠. HAR 파일에는 쿠키와 토큰이 들어 있기 때문에 정리된 파일을 첨부했어요. HAR Sanitizer는 브라우저 안에서 그런 정보를 제거해요.
약한 리포트를 좋은 리포트로 바꾸기
지원팀이나 QA팀에서 버그를 분류(triage)한다면, 위의 약한 버전 같은 리포트를 많이 받게 될 거예요. 다음 다섯 가지 질문에 대한 답만 얻을 수 있다면, 되돌려 보내는 것보다 직접 다시 쓰는 편이 빨라요.
- 정확히 무엇을 봤나요? 에러에 대한 설명이 아니라 에러 메시지 자체나 스크린샷을 요청하세요.
- 어디에 있었나요? URL이나 화면 이름, 그리고 계정이요.
- 바로 직전에 무엇을 했나요? 마지막 두세 가지 동작이면 보통 재현을 시작하기에 충분해요.
- 매번 일어나나요? 아니라면 대략 얼마나 자주 일어나는지, 그리고 더 잘 일어나게 만드는 조건이 있어 보이는지요.
- 무엇을 하려던 참이었나요? 이 답으로 기대 결과와 실제 영향을 알 수 있어요.
다섯 가지를 메시지 하나로 한꺼번에 물어보세요. 리포터, 특히 고객은 질문 한 번에는 기꺼이 답하지만, 세 번째쯤 되면 포기해 버려요. 답을 받으면 직접 버그를 재현해 보고, 위 예시의 비교처럼 알게 된 내용을 덧붙이세요. 직접 재현하고 증거까지 첨부한 버그는 그냥 전달된 이메일보다 훨씬 빨리 처리돼요.
좋은 예시들의 공통점
- 기능만이 아니라 증상과 조건을 설명하는 제목.
- 알려진 시작점과 사용한 정확한 데이터.
- "틀림"이나 "에러" 대신 정확한 숫자와 에러 메시지.
- 비교: 문제가 생기지 않는 다른 계정, 기기, 달, 파일 크기.
- 민감 정보를 지운 증거 첨부.
- 추측은 추측이라고 표시.
증거를 더 빠르게 수집하기
위의 좋은 버전 대부분에는 콘솔과 Network 패널이 필요했어요. 무료 Chrome 확장 프로그램 Midge는 화면을 녹화하거나 스크린샷을 찍는 동안 이 둘을 함께 캡처해요. 모든 녹화에는 콘솔 로그, 네트워크 요청, 사용자 동작, 기기 정보가 담겨요. 비밀번호, 카드 번호, 토큰, 쿠키는 기기를 떠나기 전에 브라우저에서 가려져요. 제목, 단계, 기대 결과는 여전히 직접 쓰지만, 기술적인 세부 정보는 자동으로 첨부돼요.
관련 가이드
자주 묻는 질문
좋은 버그 리포트 예시는 어떤 모습인가요?
구체적인 제목, 환경, 알려진 시작점부터 번호를 붙인 단계, 정확한 에러 메시지가 담긴 기대 결과와 실제 결과, 발생 빈도, 그리고 스크린샷, 콘솔 에러, 실패한 요청 같은 증거가 들어 있어요.
버그 리포트에서 가장 흔한 실수는 무엇인가요?
재현 단계가 없거나 모호한 거예요. 재현 단계가 없으면 개발자는 버그가 어떻게 생겼는지 짐작해야 하고, 결국 재현 불가로 티켓이 닫히는 경우가 많아요.
버그 리포트에 스크린샷을 넣어야 하나요?
문제가 눈에 보인다면 넣으세요. 에러 메시지도 텍스트로 함께 넣으세요. 텍스트는 검색하고 복사할 수 있으니까요. 버그에 여러 단계나 타이밍이 관련돼 있다면 짧은 녹화도 추가하세요.
이 형식의 빈 양식은 어디서 구할 수 있나요?
Midge 문서에 있는 복사해서 쓰는 버그 리포트 템플릿을 사용하세요. 이 페이지의 좋은 예시와 같은 항목으로 되어 있어요.