GitHub 협업에서 이슈 템플릿을 3가지로 나눠 쓰면 작업 목적과 범위가 훨씬 명확해진다.
각각 언제 쓰는지 정리했다.
1. bug_report.md - 버그를 재현하고 원인을 찾기 위해
이미 존재하는 기능이 정상적으로 동작하지 않을 때 사용한다.
버그 이슈의 핵심은 안 된다가 아니라, 개발자가 같은 상황을 다시 만들 수 있어야 한다는 것이다.
재현과 디버깅에 필요한 정보를 구조적으로 남기도록 구성했다.
포함 항목: 문제 요약 / 심각도 / 실행 환경 / 재현 절차 / 예상 결과 / 실제 결과 / 로그
---
name: 버그 리포트
about: 버그나 오류를 발견했을 때 사용해주세요.
title: "[BUG] "
labels: bug
assignees: ""
제목 예시:
[BUG] {어디서} {무슨 문제가} 발생함
예시:
[BUG] 회원가입 페이지에서 이메일 중복 체크가 동작하지 않음
---
## 문제 요약
어떤 문제가 발생했는지 간단히 작성해주세요.
예시: 결제 버튼 클릭 시 아무 반응이 없습니다.
---
## 심각도
[ ] Critical (서비스 불가)
[ ] Major (핵심 기능 장애)
[ ] Minor (일부 기능 이상)
[ ] Trivial (UI 깨짐 등)
---
## 환경
OS:
Browser / Client:
App Version:
Server Environment: local / dev / prod
관련 URL or API:
예시:
OS: Windows 11
Browser: Chrome 146
App Version: v1.0.3
Server Environment: dev
API: POST /api/orders
---
## 재현 절차
예시:
로그인한다.
상품 상세 페이지로 이동한다.
수량을 0으로 입력한 뒤 주문 버튼을 클릭한다.
500 에러가 발생한다.
---
## 예상 결과
원래 어떻게 동작해야 하는지 작성해주세요.
예: 유효하지 않은 수량에 대해 400 에러와 검증 메시지가 반환되어야 한다.
---
## 실제 결과
실제로 어떻게 동작했는지 작성해주세요.
예: 서버에서 500 Internal Server Error가 발생했다.
예: 버튼 클릭 시 아무 반응이 없다.
---
## 로그 / 에러 메시지
가능하면 에러 메시지, 콘솔 로그, 서버 로그를 첨부해주세요.
```text
에러 로그 붙여넣기
```
→ 모든 설명을 삭제한 템플릿 md 파일
2. feature_request.md - 새로운 기능을 만들 때
아직 없는 기능을 새로 개발해야 할 때 사용한다.
버그 이슈와 달리 "무엇을 왜 만들어야 하는가" 가 중심이다.
완료 조건 체크리스트가 핵심인데, 기능 개발은 어디까지 하면 끝인지가 흐려지기 쉽기 때문이다.
"회원가입 API 구현"이라고만 적으면 입력값 검증, 예외 처리, Swagger 반영이 포함인지 모호해진다.
완료 조건이 있으면 작업 범위가 선명해진다.
포함 항목: 작업 목적 / 상세 내용 / API 엔드포인트 / 완료 조건 / 고려 사항 / 관련 이슈 · PR
---
name: 기능 개발
about: 새로운 기능 구현이 필요할 때 사용해주세요.
title: "[FEAT] "
labels: feature
assignees: ""
제목 예시:
[FEAT] {기능명} 구현
예시:
[FEAT] 회원가입 API 구현
[FEAT] 주문 내역 조회 기능 추가
---
## 작업 목적
이 기능이 왜 필요한지 작성해주세요.
예시: 사용자가 서비스에 회원가입할 수 있어야 한다.
예시: 마이페이지에서 자신의 주문 내역을 조회할 수 있어야 한다.
---
## 상세 내용
구현해야 할 내용을 작성해주세요.
예시:
회원가입 요청을 처리하는 API를 구현한다.
이메일 중복 검사를 수행한다.
비밀번호는 암호화하여 저장한다.
입력값 검증을 적용한다.
---
## API / 엔드포인트
필요한 경우 작성해주세요.
Method:
URL:
Request:
Response:
예시:
Method: POST
URL: /api/users/signup
---
## 완료 조건
이슈가 끝났다고 판단할 기준을 작성해주세요.
[ ] API가 정상 동작한다.
[ ] 예외 케이스가 처리된다.
[ ] 단위 테스트를 작성한다.
[ ] Swagger / 문서가 반영된다.
---
## 고려 사항
구현 시 주의할 점이나 제약 조건을 작성해주세요.
예시: 비밀번호는 BCrypt를 사용한다.
예시: 예외 응답 형식은 공통 응답 스펙을 따른다.
예시: 트랜잭션 처리가 필요하다.
---
## 관련 이슈 / PR
Related to:
Depends on:
---
라벨
`feature`
→ 모든 설명을 삭제한 템플릿 md 파일
3. task.md - 기능을 잘게 쪼갠 세부 작업에
큰 기능 이슈 아래에서 실제 구현 단위로 쪼갠 작업을 관리할 때 사용한다.
Part of: #이슈번호로 상위 이슈와 연결할 수 있어, Feature 아래 여러 Task를 묶어 관리하기 좋다.
포함 항목: 작업 내용 / 작업 이유 / 완료 조건 / 참고 자료 / 상위 이슈
---
name: 세부 구현 태스크
about: 기능의 세부 구현, 리팩토링, 테스트 작성 등에 사용해주세요.
title: "[TASK] "
labels: task
assignees: ""
# 제목 예시
[TASK] {할 일}
예시:
[TASK] 주문 API 예외 처리 추가
[TASK] 회원가입 서비스 테스트 코드 작성
---
## 작업 내용
해야 할 일을 구체적으로 작성해주세요.
예시:
주문 생성 시 재고 부족 예외 처리 추가
GlobalExceptionHandler에 예외 응답 연결
에러 코드 정의
---
## 작업 이유
왜 이 작업이 필요한지 작성해주세요.
예: 현재 주문 실패 시 500 에러가 발생하여 원인을 알기 어렵다.
예: 테스트 코드가 없어 회귀 버그를 막기 어렵다.
---
## 완료 조건
[ ] 예외 클래스 추가
[ ] 예외 핸들러 반영
[ ] 테스트 코드 작성
[ ] 정상/실패 케이스 확인
---
## 참고 자료
API 명세:
ERD:
관련 PR:
관련 이슈:
---
## 상위 이슈
Part of: #
---
라벨
`task`
→ 모든 설명을 삭제한 템플릿 md 파일
4. 차이점 한눈에 보기
| Bug | 원래 되어야 하는데 안 될 때 |
| Feature | 없는 걸 새로 만들어야 할 때 |
| Task | 기능을 세부 단위로 쪼갤 때 |
5. 왜 템플릿을 나눠서 써야 할까?
- 이슈 품질이 일정해진다
누가 작성하든 필요한 정보가 빠지지 않는다. - 협업 비용이 줄어든다
버그는 재현 절차, 기능은 완료 조건, Task는 구현 범위를 보면 된다. - PR과 연결하기 쉬워진다
Task 하나를 PR 하나와 대응시키면 작업 단위가 명확해진다.