본문으로 건너뛰기

버그 리포트 작성법: 개발자가 바로 고칠 수 있게

고쳐지는 버그 리포트 작성법을 알려 드려요. 구체적인 제목, 정확한 재현 단계, 기대 결과와 실제 결과, 환경 정보, 그리고 증거까지요.

개발자가 바로 작업할 수 있는 버그 리포트를 쓰려면, 먼저 문제를 재현한 다음 이렇게 쓰세요. 구체적인 한 줄 제목, 환경(URL, 브라우저와 버전, 운영체제, 계정), 알려진 시작점부터 번호를 붙인 재현 단계, 기대 결과, 정확한 에러 메시지가 담긴 실제 결과. 그리고 스크린샷이나 녹화, 콘솔 에러, 실패한 네트워크 요청 같은 증거를 첨부하세요. 리포트 하나에는 버그 하나만 담으세요.

좋은 리포트인지 판단하는 기준은 간단해요. 문제를 한 번도 본 적 없는 개발자가 당신에게 아무것도 묻지 않고 자기 컴퓨터에서 문제를 일으킬 수 있을까요? 그렇다면 버그는 아마 빨리 고쳐질 거예요. 개발자가 질문을 들고 다시 와야 한다면, 한 번 오갈 때마다 하루가 사라져요. 항목을 체크리스트로 쓰고 싶다면 버그 리포트 템플릿을 복사하세요.

1. 쓰기 전에 재현하세요

버그를 한 번 더 일으켜 보세요. 그러면서 중요할 수 있는 세부 사항에 주의를 기울이세요.

  • 어떤 계정이나 역할을 쓰고 있었는지.
  • 어떤 데이터가 관련됐는지: 특정 상품, 긴 이름, 빈 목록, 큰 파일.
  • 어떤 단계가 정말 필요한지. 단계를 하나씩 빼 보면서 가장 짧은 경로를 찾으세요.
  • 다른 브라우저나 시크릿 창에서도 일어나는지.

매번 일어난다면 좋아요. 가끔만 일어난다면 세어 보세요. "10번 중 4번"처럼요. 전혀 재현할 수 없더라도 리포트는 하고, 재현하지 못했다고 분명히 적으세요.

2. 이미 리포트됐는지 확인하세요

에러 메시지, 페이지 이름, 몇 가지 키워드로 트래커를 검색하세요. 일치하는 티켓을 찾으면 새 티켓을 열지 말고 거기에 내 정보를 추가하세요. 내 환경, 문제를 일으키는 새로운 방법, 또는 최신 빌드에서도 여전히 일어난다는 사실 같은 것들이요. 중복 티켓은 정보를 여러 곳으로 흩어 놓고 분류(triage) 시간을 낭비하게 해요.

3. 구체적인 제목을 쓰세요

제목은 분류할 때 사람들이 읽는 유일한 부분인 경우가 많아요. 기능이 아니라 문제를 설명하게 하세요.

약한 제목더 나은 제목
로그인 안 됨Safari에서 Google 로그인 시 로그인 페이지로 계속 되돌아옴
리포트 버그매출 리포트 CSV 내보내기에서 1,000번째 이후 행이 빠짐
페이지가 느림청구서가 많은 계정에서 청구 페이지 로딩에 10초 이상 걸림
저장 시 에러이름에 이모지가 있는 프로필을 저장하면 "Invalid input" 반환

유용한 패턴: 무엇이 고장 났는지 + 언제 일어나는지 + 어디서.

4. 환경을 설명하세요

많은 버그는 특정 환경에서만 나타나요. 다음을 포함하세요.

  • 문제가 발생한 페이지의 URL.
  • 브라우저와 버전. 예를 들어 Chrome, Firefox, Safari, Edge와 정보(About) 페이지에 나오는 버전 번호.
  • 운영체제와 기기.
  • 레이아웃 문제라면 화면 크기.
  • 앱에 표시된다면 앱 버전이나 빌드.
  • 계정, 역할, 테스트 사용자, 그리고 그 계정의 특이점(체험 계정, 대규모 조직, 영어가 아닌 언어 설정).
  • 팀이 서버 로그에서 찾을 수 있도록 시간대와 함께 적은 발생 시각.

5. 재현 단계를 쓰세요

단계는 리포트의 핵심이에요. 좋은 단계는:

  • 알려진 상태에서 시작해요: "관리자로 로그인, 대시보드 화면".
  • 번호 하나에 동작 하나만 써요.
  • 정확한 데이터를 명시해요: 상품, 파일, 입력한 텍스트. 실제 비밀번호나 카드 번호는 절대 넣지 말고, 테스트 데이터를 쓰세요.
  • 개발자가 같은 버튼을 찾을 수 있도록, 앱에 표시된 이름을 굵게 쓰거나 따옴표로 감싸요.
  • 버그가 나타나는 순간에서 끝나요.
1. [email protected] (관리자 역할)으로 로그인한다.
2. Settings > Team으로 이동한다.
3. "Invite member"를 클릭한다.
4. "[email protected]"을 입력하고 역할로 "Viewer"를 선택한다.
5. "Send invite"를 클릭한다.

6. 기대 결과와 실제 결과를 쓰세요

둘을 나란히 두세요.

기대 결과: 초대가 대기 중(Pending) 목록에 나타나고 확인 토스트가 표시된다.
실제 결과: 대화상자가 닫히고, 토스트는 표시되지 않으며, 대기 중 목록은 비어 있다.
          새로고침한 뒤에도 초대가 여전히 없다.

원인이라고 생각하는 게 아니라 관찰한 것을 쓰세요. "초대 요청이 실패했다"는 결론이고, "대화상자가 닫히고 목록에 아무것도 나타나지 않았다"는 관찰이에요. 에러 메시지를 봤다면 정확히 텍스트로 복사하세요. 개발자는 그 문자열로 코드를 검색해요.

7. 증거를 추가하세요

증거는 설명을 사실로 바꿔 주고, 원인을 곧장 가리키는 경우가 많아요.

  • 문제 영역을 강조한 스크린샷. 관련 없는 개인 정보는 잘라 내세요.
  • 움직임, 타이밍, 여러 단계가 얽힌 문제라면 화면 녹화. 짧게 유지하고, 문제가 생기기 직전부터 시작하세요.
  • 콘솔 에러. 웹 앱에서는 브라우저 콘솔의 빨간 에러가 가장 유용한 단서인 경우가 많아요. Chrome에서 콘솔 로그를 내보내는 방법을 참고하세요.
  • 실패한 네트워크 요청. 실패한 API 호출의 URL, 상태 코드, 응답 본문이에요. Chrome에서 네트워크 트래픽을 캡처하는 방법을 참고하세요.
  • 팀이 전체 네트워크 세션을 요청한다면 HAR 파일. HAR 파일을 얻는 방법을 따르고, 먼저 HAR Sanitizer로 정리하세요. HAR 파일에는 쿠키와 토큰이 들어 있으니까요.

8. 영향도를 솔직하게 평가하세요

얼마나 심각한지, 몇 명이 영향을 받는지 적으세요. 팀에 심각도 기준이 있다면 그걸 쓰세요. 솔직해야 해요. 모든 게 치명적이라고 표시되면, 실제로는 아무것도 치명적이지 않은 셈이에요. 우회 방법을 찾았다면 적어 주세요. 수정의 시급성이 달라지고, 그동안 고객 지원팀에도 도움이 돼요.

9. 버그는 하나만

같은 페이지에서 문제를 세 개 찾았다면 리포트를 세 개 쓰세요. 그래야 각각 따로 담당자를 지정하고, 고치고, 테스트하고, 종료할 수 있어요. 서로 관련 있어 보이면 연결해 두세요.

10. 연락이 닿게 하세요

제출한 뒤에는 티켓에 질문이 달리는지 지켜보세요. 수정이 배포되면 같은 단계로 다시 테스트하고 확인해 주세요. 나중에 버그가 다시 나타나면 원래 티켓을 다시 열거나 연결해서, 이력이 한곳에 남게 하세요.

흔한 실수

  • "안 돼요", "페이지 문제" 같은 모호한 제목.
  • 빠진 단계, 또는 흐름 중간부터 시작하는 단계.
  • 검색할 수 없는 텍스트 대신 에러 메시지 스크린샷.
  • 티켓 하나에 여러 버그.
  • 리포트에 들어간 실제 비밀 정보: 스크린샷과 로그 속 비밀번호, API 키, 세션 쿠키, 고객 데이터.
  • 감정적인 표현. 차분하고 사실에 근거한 리포트가 화난 리포트보다 빨리 고쳐져요.

좋은 리포트와 나쁜 리포트를 나란히 비교하려면 버그 리포트 예시를 보세요.

적게 쓰고, 더 많이 담으세요

버그 리포트에 드는 노력의 대부분은 기술적인 세부 사항에 들어가고, 리포트하는 사람들이 가장 잘 잊는 것도 바로 그 부분이에요. 무료 Chrome 확장 프로그램 Midge는 화면을 녹화하거나 스크린샷을 찍고 그런 세부 사항을 대신 붙여 주기 때문에, 제목, 단계, 기대한 결과만 쓰면 돼요. 모든 녹화에는 콘솔 로그, 네트워크 요청, 사용자 동작, 기기 정보가 담겨요. 비밀번호, 카드 번호, 토큰, 쿠키는 기기를 떠나기 전에 브라우저에서 가려져요. 리포트는 링크 하나로 공유되고, 팀이 쓰는 어떤 트래커에든 붙여 넣을 수 있어요.

관련 가이드

자주 묻는 질문

버그 리포트에서 가장 중요한 부분은 무엇인가요?

재현 단계, 기대 결과, 실제 결과예요. 이 세 가지가 있으면 개발자는 보통 직접 문제를 확인할 수 있어요. 환경 정보와 스크린샷, 콘솔 에러 같은 증거가 있으면 더 빨라져요.

버그 리포트는 얼마나 길어야 하나요?

빠짐없이 쓰되 최대한 짧게요. 좋은 리포트는 대부분 한 화면에 들어가요. 한 줄 제목, 짧은 요약, 5~10개의 단계, 기대 결과와 실제 결과, 첨부 파일이요.

버그를 재현할 수 없다면 어떻게 하나요?

그래도 리포트하고, 재현할 수 없다고 적으세요. 무엇을 하고 있었는지, 언제 일어났는지 정확히 설명하고, 스크린샷이나 콘솔 에러처럼 가진 증거를 첨부하세요. 발생 빈도는 "한 번 발생"으로 표시하세요.

원인에 대한 내 의견도 적어야 하나요?

관찰과 추측을 분리하세요. 주요 항목에는 본 것을 쓰고, 생각하는 원인이 있다면 추측이라고 표시한 메모 섹션에 덧붙이세요.