debugging git:20260826.34a9b20A

Immutable. This exact content is served forever at /api/v1/blob/065af540c0528449.

---
name: debugging
description: 체계적 디버깅 및 버그 수정 스킬
compatibility: omp
---

# Debugging Skill

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

## 핵심 원칙

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

## 디버깅 프로세스

### 1단계: 버그 재현

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

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

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

### 2단계: 근본 원인 분석

도구 활용:
```bash
# 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단계: 검증

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

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

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

## 체크리스트

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