debugging

Debugging Skill

버그를 체계적으로 재현하고 근본 원인을 분석하여 수정하는 스킬입니다.

핵심 원칙

재현 테스트를 먼저 작성한다. 수정 전에 버그를 재현하는 테스트를 작성하고, 수정 후 테스트가 통과하는지 확인합니다.

디버깅 프로세스

1단계: 버그 재현

1. 버그 재현 조건 파악
   - 어떤 입력/상태에서 발생하는가?
   - 항상 발생하는가, 간헐적으로 발생하는가?
   - 특정 환경에서만 발생하는가?

2. 재현 테스트 작성 (RED)
   - 가장 단순한 재현 케이스로 테스트 작성
   - 테스트가 실패하는지 확인

// 버그 재현 테스트 — 수정 전 FAIL, 수정 후 PASS
func TestBug_IssueNumber_ReproductionTest(t *testing.T) {
    // Given: 버그 발생 조건
    // When: 버그 트리거 동작
    // Then: 기대한 동작 (현재는 실패)
}

2단계: 근본 원인 분석

도구 활용:

# Go: 레이스 컨디션 탐지
go test -race ./...

# 스택 트레이스 분석
go test -v -run TestBug 2>&1

# pprof 프로파일링
go test -cpuprofile cpu.out -memprofile mem.out

근본 원인 분류:

• 로직 오류: 조건문, 계산 실수
• 경계 조건: 빈 입력, 최대값, 최소값
• 동시성: 레이스 컨디션, 데드락
• 타입/변환: 오버플로우, nil 포인터
• 외부 의존성: API 변경, 설정 오류

Caller/shared root-cause rule:

• 증상 위치(symptom location), owning function/path, caller 목록 또는 grep evidence를 기록합니다.
• caller와 shared root-cause path를 먼저 확인한 뒤 패치 위치를 선택합니다.
• 증상 위치만 패치하고 caller/shared root-cause evidence가 없으면 patch plan을 revise-target으로 표시합니다.
• evidence가 증상 위치 자체가 root cause이거나 affected caller가 하나뿐임을 보여줄 때만 focused patch를 허용합니다.

3단계: 최소 수정

원칙:
- 버그 수정에만 집중 (리팩토링 금지)
- 가능한 한 작은 변경
- 사이드 이펙트 최소화

4단계: 검증

# 재현 테스트 통과 확인
go test -run TestBug -v

# 회귀 테스트 실행
go test ./...

# 레이스 컨디션 재확인
go test -race ./...

체크리스트

• 버그 재현 테스트 작성 및 FAIL 확인
• 근본 원인 파악
• caller/shared root-cause path 확인 또는 revise-target 기록
• 최소 수정 적용
• 재현 테스트 PASS 확인
• 전체 테스트 스위트 통과
• 커밋 메시지에 버그 이슈 번호 포함