본문으로 건너뛰기

버그 리포트 템플릿: 무료, Jira, GitHub, Linear용

복사해서 바로 쓰는 무료 버그 리포트 템플릿과 GitHub, Linear, Jira용 버전, GitHub 이슈 폼, 실제로 작성한 예시를 소개해요.

버그 리포트 템플릿은 모든 리포트가 같은 질문에 답하도록 만드는 정해진 항목 묶음이에요. 무엇이 잘못됐는지, 어디서, 어떻게 재현하는지, 원래 어떻게 됐어야 하는지, 그리고 어떤 증거가 있는지요. 아래 템플릿은 제목, 요약, 환경, 재현 단계, 기대 결과와 실제 결과, 발생 빈도, 심각도, 첨부 파일과 로그를 다뤄요. 이슈 트래커나 고객 지원 양식, 채팅 메시지에 복사해서 빈칸을 채우면 돼요. 아래쪽에는 GitHub 이슈 폼을 포함해 GitHub, Linear, Jira용으로 바로 쓸 수 있는 버전도 있어요.

템플릿이 필요한 이유는, 개발자가 시간을 가장 많이 잃는 곳이 수정 작업이 아니라 빠진 정보이기 때문이에요. 정확한 단계, 브라우저 버전, 콘솔 에러가 담긴 리포트는 그날 바로 고쳐지는 경우가 많아요. "결제가 안 돼요"라고만 적힌 리포트는 질문이 길게 오가는 스레드가 되고요.

템플릿

제목: [페이지 또는 기능]에서 [동작]할 때 [무엇이 고장 났는지]

요약
쉬운 말로 한두 문장. 무슨 일이 있었고 누가 영향을 받는지.

환경
- URL:
- 브라우저와 버전:
- 운영체제:
- 기기 / 화면 크기:
- 앱 버전 또는 빌드 (알고 있다면):
- 계정 / 역할 / 테스트 사용자:
- 발생 날짜와 시각 (시간대 포함):

재현 단계
1.
2.
3.

기대 결과
원래 어떻게 됐어야 하는지.

실제 결과
대신 무슨 일이 일어났는지. 정확한 에러 메시지를 텍스트로 복사해서 넣으세요.

발생 빈도
항상 / 가끔 (Y번 중 약 X번) / 한 번 발생

심각도
Blocker / Major / Minor / Cosmetic

우회 방법
문제를 피해 갈 수 있는 방법, 또는 "찾지 못함".

첨부 파일
- 스크린샷 또는 화면 녹화:
- 콘솔 에러:
- 실패한 네트워크 요청 (URL, 상태, 응답):
- HAR 파일 (정리된 것), 요청받은 경우:

메모
그 밖의 내용: 언제부터 시작됐는지, 최근에 바뀐 것, 관련 티켓.

항목별 작성 방법

제목

제목은 50개의 티켓 목록에서 사람들이 훑어보는 부분이니 구체적으로 쓰세요. "무엇이 고장 났는지" + "언제" + "어디서"라는 패턴이 유용해요. "결제 페이지에서 유효한 카드를 입력해도 결제 버튼이 비활성 상태로 남음"이 "결제 버그"보다 훨씬 나아요. "긴급"이나 "고장" 같은 단어만 덩그러니 쓰지 마세요. 그런 정보는 심각도 항목이 담당해요.

요약

기술을 잘 모르는 동료도 이해할 수 있는 한두 문장이에요. 누가 영향을 받는지 안다면 적어 주세요. 모든 사용자인지, 관리자만인지, Safari 사용자만인지, 특정 고객 한 명인지요.

환경

많은 버그는 브라우저, 기기, 계정, 데이터에 따라 달라져요. 정확한 URL, 브라우저 이름과 버전, 운영체제, 사용한 계정이나 역할을 적으세요. 앱에 버전이나 빌드 번호가 표시된다면 함께 적어 주세요. 문제가 발생한 시각을 시간대와 함께 적으면, 개발자가 서버 로그에서 해당 기록을 찾을 수 있어요.

재현 단계

가장 중요한 항목이에요. 단계에 번호를 붙이고, 알려진 상태에서 시작하고("장바구니가 빈 사용자로 로그인한 상태"), 사용한 데이터를 정확히 적으세요. 한 단계에는 한 가지 동작만 쓰세요. 두 번째에 재현하지 못했다면 그렇다고 밝히고, 처음에 한 동작을 최대한 가깝게 설명하세요.

기대 결과와 실제 결과

차이가 분명히 보이도록 나란히 두세요. 에러 메시지는 풀어 쓰지 말고 텍스트로 복사하세요. 개발자는 바로 그 문자열로 코드를 검색해요. "아무 일도 일어나지 않음"도 유효한 실제 결과지만, "에러 메시지 없음, 버튼은 활성 상태로 남음"처럼 무엇을 확인했는지 덧붙이세요.

발생 빈도

"항상" 일어나는 버그가 가장 고치기 쉬워요. "가끔" 일어나는 버그는 더 많은 데이터가 필요하니, 비율을 추정하고("10번 중 3번") 느린 연결이나 큰 파일처럼 관련 있어 보이는 조건을 적어 두세요.

심각도

심각도는 얼마나 짜증이 났는지가 아니라 영향도에 관한 거예요. 흔히 쓰는 기준은 이래요.

심각도의미예시
Blocker핵심 흐름이 불가능하고 우회 방법이 없음아무도 로그인할 수 없음
Major중요한 기능이 고장 났거나 데이터가 틀림, 우회 방법이 번거로움청구서에 합계가 잘못 표시됨
Minor기능은 동작하지만 작은 문제가 있거나 쉬운 우회 방법이 있음페이지를 새로고침하면 정렬이 초기화됨
Cosmetic시각적 문제, 기능에는 영향 없음작은 화면에서 버튼 텍스트가 겹침

언제 고칠지를 정하는 우선순위는 보통 리포트한 사람이 아니라 백로그를 관리하는 팀이 정해요.

우회 방법

우회 방법이 있으면 팀은 수정이 얼마나 급한지 판단할 수 있고, 그동안 고객 지원팀은 고객에게 답할 수 있어요.

첨부 파일과 로그

시간을 가장 많이 아껴 주는 건 증거예요. 문제 영역을 표시한 스크린샷이나, 단계를 보여 주는 짧은 화면 녹화를 첨부하세요. 웹 앱이라면 콘솔 에러와 실패한 네트워크 요청도 추가하세요. Chrome에서 콘솔 로그 내보내기와 Chrome에서 네트워크 트래픽 캡처하기 가이드에서 방법을 볼 수 있어요. 누군가 HAR 파일을 요청하면 HAR 파일을 얻는 방법을 따르고, 먼저 HAR Sanitizer로 정리하세요. HAR 파일에는 쿠키와 토큰이 들어 있으니까요.

작성 예시

제목: 결제 페이지에서 유효한 카드를 입력해도 결제 버튼이 비활성 상태로 남음

요약
결제 페이지에서 유효한 테스트 카드를 입력해도 결제 버튼이 클릭 가능한
상태로 바뀌지 않아 주문할 수 없음. Chrome과 Edge에서 확인.

환경
- URL: https://staging.example.com/checkout
- 브라우저와 버전: Windows 11의 Chrome 154, Edge 154에서도 발생
- 기기 / 화면 크기: 노트북, 1920x1080
- 앱 버전 또는 빌드: web 4.18.0 (푸터)
- 계정 / 역할 / 테스트 사용자: [email protected], 일반 고객
- 날짜와 시각: 2026-11-10 14:32 CET

재현 단계
1. [email protected]으로 로그인한다.
2. "Starter plan, annual"을 장바구니에 담는다.
3. /checkout으로 이동한다.
4. 테스트 카드 4242 4242 4242 4242, 유효기간 12/30, CVC 123을 입력한다.
5. 카드 입력란 바깥을 클릭한다.

기대 결과
결제 버튼이 활성화되고 "Pay $120.00"이 표시된다.

실제 결과
결제 버튼이 회색인 채로 비활성 상태로 남는다. 에러 메시지는 표시되지 않는다.
콘솔 출력: Uncaught TypeError: Cannot read properties of
undefined (reading 'postalCode') at validateCard (checkout.js:214)

발생 빈도
항상 (5번 중 5번)

심각도
Blocker: 고객이 결제할 수 없음

우회 방법
찾지 못함. 프로덕션 빌드 4.17.2에서는 정상 동작.

첨부 파일
- 화면 녹화: 댓글에 링크
- 콘솔 에러: checkout-console.log
- 네트워크: POST /api/cart/validate가 200 반환, 다른 실패 없음

메모
오늘 아침 스테이징 배포 이후 발생.

이 예시가 잘 작성된 이유를 살펴보세요. 단계가 알려진 계정에서 시작해요. 테스트 카드가 명시돼 있어요. 콘솔 에러가 정확히 인용돼 있어요. 리포트한 사람이 다른 브라우저와 이전 빌드까지 확인해서, 이미 원인을 최근 변경으로 좁혀 놓았어요.

짧은 버전

모든 버그에 모든 항목이 필요하지는 않아요. 팀 채팅에 빠르게 남기는 메시지라면 간단한 버전으로 충분해요.

버그: [제목]
위치: [URL], [브라우저/OS]
단계: 1) ... 2) ... 3) ...
기대 결과: ...
실제 결과: ...
증거: [스크린샷 / 녹화 / 콘솔 에러]

사용자의 리포트를 전달하는 고객 지원팀이라면, 고객의 계정 ID, 티켓 링크, 고객이 직접 쓴 표현을 추가하고, 어떤 부분을 직접 재현했는지 표시하세요.

QA 테스트 실행 중이라면 테스트 케이스 ID와 테스트 대상 빌드를 추가해서, 버그가 그것을 찾아낸 테스트로 연결되게 하세요.

GitHub, Linear, Jira용 템플릿

일반 텍스트 템플릿은 어디서나 쓸 수 있어요. 이슈 트래커가 Markdown을 렌더링한다면, 이 버전을 쓰면 제목과 체크리스트가 읽기 좋게 유지돼요.

## 요약
<!-- 한두 문장: 무슨 일이 있었고 누가 영향을 받는지. -->

## 환경
- URL:
- 브라우저와 버전:
- 운영체제:
- 앱 버전 또는 빌드:
- 계정 / 역할:

## 재현 단계
1.
2.
3.

## 기대 결과

## 실제 결과
<!-- 정확한 에러 메시지를 텍스트로 붙여 넣으세요. -->

## 발생 빈도
<!-- 항상 / 가끔 (Y번 중 X번) / 한 번 -->

## 심각도
<!-- Blocker / Major / Minor / Cosmetic -->

## 증거
- [ ] 스크린샷 또는 화면 녹화
- [ ] 콘솔 에러
- [ ] 실패한 네트워크 요청

GitHub Issues

Markdown 버전을 저장소의 .github/ISSUE_TEMPLATE/bug_report.md로 저장하고, 짧은 헤더를 붙이세요. 그러면 GitHub가 "New issue" 선택 화면에서 이 템플릿을 보여 줘요.

---
name: 버그 리포트
about: 무언가가 고장 났어요
labels: bug
---

GitHub는 이슈 폼도 지원해요. 이슈 폼은 템플릿을 사람들이 건너뛸 수 없는 라벨 붙은 입력란으로 바꿔 줘요. 아래 내용을 .github/ISSUE_TEMPLATE/bug_report.yml로 저장하세요.

name: 버그 리포트
description: 무언가가 고장 났어요
labels: ["bug"]
body:
  - type: textarea
    id: summary
    attributes:
      label: 요약
      description: 무슨 일이 있었고, 누가 영향을 받나요?
    validations:
      required: true
  - type: input
    id: url
    attributes:
      label: URL
  - type: input
    id: environment
    attributes:
      label: 브라우저, OS, 앱 버전
      placeholder: macOS 26의 Chrome 154, web 4.18.0
  - type: textarea
    id: steps
    attributes:
      label: 재현 단계
      value: |
        1.
        2.
        3.
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: 기대 결과
    validations:
      required: true
  - type: textarea
    id: actual
    attributes:
      label: 실제 결과
      description: 정확한 에러 메시지를 텍스트로 붙여 넣으세요.
    validations:
      required: true
  - type: dropdown
    id: severity
    attributes:
      label: 심각도
      options:
        - Blocker
        - Major
        - Minor
        - Cosmetic
  - type: textarea
    id: evidence
    attributes:
      label: 스크린샷, 녹화, 로그
      description: 파일을 여기로 끌어다 놓거나 녹화 링크를 붙여 넣으세요.

Linear

Linear에서는 팀 설정에 이슈 템플릿이 있어요. "Bug"라는 이름으로 템플릿을 만들고, 설명에 Markdown 버전을 붙여 넣은 뒤 Bug 라벨과 팀의 트리아지 상태를 지정하세요. 그러면 모든 리포트가 같은 항목으로 시작해요.

Jira

Jira에서는 새 Bug의 설명에 일반 텍스트 버전이나 Markdown 버전을 붙여 넣으세요. Jira Cloud에는 이슈 유형별 기본 설명 기능이 내장돼 있지 않아서, 템플릿이 미리 채워지길 원하는 팀은 Atlassian Marketplace의 이슈 템플릿 앱을 써요. 콘솔 로그와 네트워크 로그가 담긴 화면 녹화 링크는 설명이나 댓글에 넣으면 돼요.

템플릿이 막아 주는 실수

템플릿은 대부분 늘 반복되는 몇 가지 실수를 막는 체크리스트예요.

  • 한 리포트에 여러 버그. 문제 하나에 티켓 하나씩 써야 각각 따로 수정하고, 테스트하고, 종료할 수 있어요.
  • 풀어 쓴 에러. "권한 어쩌고 하는 메시지가 떴어요"는 검색할 수 없어요. 정확한 메시지는 검색할 수 있어요.
  • 빠진 시작점. 흐름 중간부터 시작하는 단계는 그걸 쓴 사람에게만 통해요.
  • 관찰 대신 의견. "API가 고장 났어요"는 추측이에요. "POST /api/orders가 500을 반환함"은 개발자가 확인할 수 있는 사실이에요.
  • 첨부 파일 속 비밀 정보. 관리자 화면 스크린샷, HAR 파일, 콘솔 로그에는 토큰과 고객 데이터가 들어 있을 수 있어요. 첨부하기 전에 잘라 내거나, 흐리게 처리하거나, 정리하세요.

팀의 기본 양식으로 만드세요

대부분의 이슈 트래커는 기본 설명이나 이슈 템플릿을 저장할 수 있어서, 새 버그가 모두 이 제목들로 시작하게 할 수 있어요. 사람들이 실제로 채울 만큼 템플릿을 짧게 유지하세요. 대부분의 리포트에서 비어 있는 항목은 지우세요. 개발자가 같은 후속 질문을 계속한다면, 그 질문을 위한 항목을 추가하세요.

기술 항목은 도구가 채우게 하세요

사람들이 가장 자주 건너뛰는 항목은 기술적인 것들이에요. 브라우저 버전, 콘솔 에러, 실패한 요청이요. 무료 Chrome 확장 프로그램 Midge는 이 정보를 화면 녹화나 스크린샷에 자동으로 붙여 주기 때문에, 리포트하는 사람은 제목, 단계, 기대 결과만 쓰면 돼요. 모든 녹화에는 콘솔 로그, 네트워크 요청, 사용자 동작, 기기 정보가 담겨요. 비밀번호, 카드 번호, 토큰, 쿠키는 기기를 떠나기 전에 브라우저에서 가려져요. 리포트는 Jira, Linear, GitHub Issues, Slack으로 바로 보내거나, 어디에든 붙여 넣을 수 있는 링크로 공유할 수 있어요.

관련 가이드

자주 묻는 질문

버그 리포트 템플릿에는 무엇이 들어가야 하나요?

명확한 제목, 환경(URL, 브라우저, OS, 앱 버전, 계정), 번호를 붙인 재현 단계, 기대 결과, 실제 결과, 발생 빈도, 심각도, 그리고 스크린샷, 영상, 콘솔 로그, 네트워크 요청 같은 증거예요.

이 템플릿을 Jira, Linear, GitHub Issues에서 쓸 수 있나요?

네. Markdown과 잘 맞는 제목으로 된 일반 텍스트라서, 어떤 트래커에든 붙여 넣을 수 있어요. GitHub와 Linear에서는 이슈 템플릿으로 저장할 수도 있고, Jira에서는 Marketplace 앱을 쓰면 돼요.

GitHub 이슈 템플릿은 어디에 두나요?

저장소의 .github/ISSUE_TEMPLATE 폴더에 둬요. .md 파일은 Markdown 템플릿을, .yml 파일은 필수 항목이 있는 이슈 폼을 추가해요. 누군가 새 이슈를 열면 GitHub가 이 템플릿들을 보여 줘요.

심각도와 우선순위는 어떻게 다른가요?

심각도는 버그가 제품이나 사용자에게 얼마나 큰 영향을 주는지를 나타내요. 우선순위는 팀이 얼마나 빨리 고칠지를 나타내요. 거의 쓰이지 않는 관리자 화면의 심각한 버그가 가격 페이지의 사소한 시각적 버그보다 우선순위가 낮을 수 있어요.

모든 항목을 다 채워야 하나요?

아니요. 제목, 단계, 기대 결과와 실제 결과는 꼭 필요해요. 나머지는 아는 만큼 채우고, 모르는 건 추측하지 말고 "알 수 없음"이라고 쓰세요.