¶ 8권 — 이슈와 버그 관리하기: 트래커 템플릿과 워크플로
코드를 만들기 시작하면 "이 버그를 어디에 적을 것인가, 누가 언제 고칠 것인가, 얼마나 급한가"라는 질문이 따라온다. 이슈 트래커가 실제로 작동하려면 다음 세 가지가 먼저 정해져 있어야 한다.
- 무엇을 이슈로 기록할 것인가
- 어떤 템플릿으로 남길 것인가
- 어떤 상태를 거쳐 어떻게 종료되고 우선순위는 누가 정하는가
¶ 무엇을 이슈로 기록할 것인가
"일단 다 이슈로 만들자"는 접근은 진짜 버그와 막연한 아이디어, 회의록 할 일이 뒤섞여 우선순위 판단을 불가능하게 만든다. 이슈로 남길 것은 다음 세 가지뿐이다.
- 재현 가능한 결함(버그)
- 구현해야 할 기능/개선(피처)
- 완료 확인이 필요한 작업(태스크)
검증되지 않은 아이디어나 30초짜리 잡무는 남기지 않는다.
¶ 이슈 템플릿 설계하기
템플릿의 목적은 보고자가 빠뜨리기 쉬운 정보를 미리 물어보는 것이다. GitHub의 이슈 폼(YAML 기반)은 input/textarea/dropdown/checkboxes 등의 필드 타입과 필수 항목을 강제할 수 있고, 빈 이슈 생성 자체를 막을 수 있다.
| 템플릿 | 담을 항목 |
|---|---|
| 버그 리포트 | 재현 절차, 기대/실제 결과, 환경 정보, 재현 빈도, 스크린샷 |
| 기능 요청 | 해결하려는 문제, 제안 방식, 고려한 대안 |
| 작업 템플릿 | 완료 조건(DoD), 관련 링크, 예상 소요 |
¶ 상태(Status) 워크플로 정의하기
상태값은 적을수록 좋다는 것이 모범 사례의 공통된 조언이다. 소규모 팀에 권장하는 최소 세트는 다음 여섯 단계다.
- 신규
- 진행중
- 확인 대기
- 완료
- 보류
- 재오픈
상태 전이는 가능한 자동화(PR 머지 시 자동으로 "확인 대기"로 전환)해 수동 부담을 줄인다.
¶ 우선순위와 심각도 구분하기
가장 자주 혼동되는 두 개념이다.
| 개념 | 의미 |
|---|---|
| 심각도(Severity) | "얼마나 망가졌는가"를 나타내는 기술적 판단 |
| 우선순위(Priority) | "언제 고칠 것인가"를 나타내는 비즈니스적 판단 |
둘은 독립적이어서 심각도가 높아도 우선순위는 낮을 수 있다. 중요한 것은 두 필드를 분리하고, "치명적 심각도는 기본적으로 최상위 우선순위로 연결하되 예외가 있으면 우선순위만 조정한다"는 원칙을 공유하는 것이다.
¶ 출시 전 테스트 — 단위 테스트와 통합 테스트
| 구분 | 방식 | 특징 |
|---|---|---|
| 단위 테스트 | 코드 한 조각을 다른 부분과 분리해 검사 | 실행이 빠르고 실패 시 원인 범위가 좁음 |
| 통합 테스트 | 실제 DB까지 연결한 상태에서 여러 컴포넌트가 함께 동작하는 흐름 전체를 검사 | 느리지만 사용자가 겪는 흐름을 그대로 검증 |
실무적으로는 단위 테스트를 먼저 빠르게 돌려 실패 시 즉시 중단하고, 통과한 경우에만 느린 통합 테스트를 이어 돌리는 2단계 구성이 CI 테스트 게이트의 표준 패턴이다.
¶ 테스트에서 발견된 버그 관리 프로세스
발견된 버그는 다음 4단계를 거친다.
- 접수(템플릿으로 이슈 생성)
- 확인중(재현·원인 분석)
- 반영/검증(수정 PR과 회귀 테스트 추가)
- 완료(QA 재확인)
"완료"는 코드가 고쳐졌다는 뜻이 아니라 회귀 테스트가 스위트에 영구히 남아 같은 버그의 재발을 CI가 즉시 잡아낸다는 뜻이다. 버그가 테스트 자산으로 축적되는 것이 테스트 게이트의 신뢰도를 시간이 지날수록 높이는 이유다.
¶ 서비스 오픈 이후 — 장애 관리(SEV 등급)
출시 전 결함과 달리, 운영 환경에서만 드러나는 장애는 SEV1(서비스 전체 중단)부터 SEV4(경미한 결함)까지 등급을 나눠 관리한다. 등급을 나누는 이유는 등급마다 대응 절차와 속도가 완전히 달라야 하기 때문이다.
| 등급 | 대응 |
|---|---|
| SEV1 | 평소의 우선순위 큐를 건너뛰고 즉시 전원 소집 |
| SEV4 | 정상적으로 다음 스프린트 백로그에 편성 |
¶ 참고할 만한 사례
| 구분 | 사례 |
|---|---|
| 국내 | 데브시스터즈가 스프레드시트·트렐로를 거쳐 JIRA를 도입하며 1년간 25건의 점진적 개선을 진행한 사례 |
| 해외 | 구글의 사내 이슈 트래커(Buganizer) 개념 문서 |
¶ 💬 질문이 있으신가요?
아래 댓글로 남겨주세요. 로그인 없이도 바로 남길 수 있습니다.