# Debugging

> 이미 발생한 버그·장애·재현되지 않는 오동작의 원인을 찾을 때 사용한다. "이 에러 왜 나지", "가끔씩만 실패한다", "운영에서만 재현된다", "로그는 있는데 원인을 모르겠다", "롤백해야 하나" 같은 요청에 트리거된다. 재현 → 범위 격리 → 가설 검증 → 수정 → 재발 방지의 절차를 다룬다. 아직 코드를 작성하는 단계면 java-spring-backend를, 변경분의 결함을 미리 찾는 것이면 code-review를 쓴다.

- Skill: `j99way99/debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add j99way99/debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/j99way99/debugging/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: j99way99 (https://skillmd.com/u/j99way99)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/j99way99/debugging

---


# 디버깅 / 트러블슈팅

추측으로 코드를 고치지 않는다. **원인을 특정하기 전에 수정하지 않는다.**

## 절차

1. **증상을 사실로 적는다.** 무엇이, 언제부터, 어떤 입력에서, 얼마나 자주. 관측된 것과
   해석을 섞지 않는다. ("느리다"가 아니라 "p95 응답이 200ms → 3s")
2. **재현 경로를 만든다.** 재현되지 않으면 재현 조건을 좁히는 것이 그날의 작업이다.
   재현 없이 고친 것은 고쳤는지 알 수 없다.
3. **범위를 절반씩 줄인다.**
   - 언제부터인가 → 그 사이의 변경(배포, 설정, 데이터, 의존 서비스)
   - 어디까지 정상인가 → 입력 경계, 계층 경계, 외부 호출 경계에서 값을 확인
4. **가설을 하나 세우고, 그것을 반증할 관측을 정한다.** "이게 원인이면 X가 보여야 한다."
   X를 확인한다. 안 보이면 가설을 버린다.
5. **최소 변경으로 고친다.** 원인이 아닌 부분을 함께 정리하지 않는다.
6. **재발을 막는다.** 이 버그로 실패했을 테스트를 추가한다. 없으면 고친 것이 아니라 덮은 것이다.

## 범위를 좁히는 질문

- 특정 사용자/데이터에서만 나는가 → 데이터 의존
- 특정 시간대에만 나는가 → 배치, 타임존, 만료, 트래픽 피크
- 재시작하면 사라지는가 → 상태 누적, 커넥션/스레드 고갈, 캐시
- 한 인스턴스에서만 나는가 → 배포 불일치, 로컬 상태
- 부하가 있을 때만 나는가 → 동시성, 풀 크기, 타임아웃
- 최근에 바뀐 것이 정말 없는가 → 코드 외 변경(설정, 인증서, 의존 서비스, 데이터 양)

## 증상별 첫 관측 지점

| 증상 | 먼저 볼 것 |
|---|---|
| 간헐적 실패 | 동시성, 재시도, 타임아웃, 외부 의존 |
| 시간이 갈수록 느려짐 | 누적 상태, 커넥션/스레드 풀, 캐시 크기, 데이터 증가 |
| 특정 요청만 느림 | 실행계획 변화, N+1, 외부 호출 지연 |
| 배포 직후 발생 | 변경분 diff, 설정 차이, 스키마-코드 불일치 |
| 응답은 정상인데 데이터가 틀림 | 트랜잭션 경계, 부분 커밋, 순서 의존 |
| 로그에 아무것도 없음 | 예외를 삼키는 지점, 로그 레벨, 다른 인스턴스 |

## 하지 말 것

- 여러 곳을 동시에 바꾸고 "됐다"고 판단하기
- 재현 없이 "아마 이것 때문"으로 마무리하기
- 예외를 잡아서 로그만 남기고 정상 응답으로 바꾸기 (장애를 숨긴다)
- 타임아웃·재시도 값을 근거 없이 늘려 증상만 미루기

## 보고 형식

```
증상: <측정된 사실 + 범위>
재현: <조건 / 재현 불가 시 좁혀진 범위>
원인: <근거가 되는 관측>
수정: <변경 내용과 이유>
재발 방지: <추가한 테스트 또는 관측 수단>
남은 불확실성: <확인하지 못한 것>
```