---
name: "systematic-debugging"
description: "버그, 테스트 실패, 예기치 않은 동작을 체계적으로 진단합니다. 수정안을 제시하기 전에 반드시 근본 원인을 먼저 찾아야 할 때 호출합니다."
---

# 체계적 디버깅

무작위 수정은 시간을 낭비하고 새 버그를 만듭니다. 빠른 땜질은 증상만 가릴 뿐입니다. 이 스킬의 핵심은 **수정 전에 반드시 근본 원인을 찾는 것**입니다.

## 철칙

근본 원인 조사 없이 수정하지 않습니다.

다시 말해, 1단계를 끝내지 않았다면 수정안 제시는 아직 허용되지 않습니다.

## 언제 사용할지

다음과 같은 모든 기술 문제에서 사용합니다.

- 테스트 실패
- 운영 중 버그
- 예기치 않은 동작
- 성능 문제
- 빌드 실패
- 통합 문제

특히 아래 상황에서 반드시 사용합니다.

- 시간이 촉박할 때
- "일단 이것만 빨리 고치면 될 것 같을 때"
- 이미 여러 수정안을 시도했을 때
- 이전 수정이 실패했을 때
- 문제를 완전히 이해하지 못한 상태일 때

다음 상황에서도 생략하지 않습니다.

- 문제가 너무 단순해 보일 때
- 급하게 고쳐 달라는 압박이 있을 때
- 지금 보이는 증상만 없애면 될 것처럼 느껴질 때

## 4단계 프로세스

### 1단계: 근본 원인 조사

수정 전에 반드시 아래를 수행합니다.

- 오류 메시지, 경고, 스택 트레이스를 끝까지 읽습니다.
- 재현 절차를 명확히 만들고, 반복 재현 가능한지 확인합니다.
- 최근 변경 사항, 설정 차이, 의존성 변경, 환경 차이를 확인합니다.
- 다중 컴포넌트 시스템이라면 경계마다 로그와 계측을 추가해 어디서 깨지는지 증거를 모읍니다.
- 호출 스택이 깊다면 잘못된 값이 어디서 시작됐는지 거꾸로 추적합니다.
- 재현이 안정적이지 않다면, 추측 대신 로그와 관찰 지점을 늘립니다.
- 레이어가 여러 개인 시스템이라면 각 경계에서 입력, 출력, 상태 전파를 확인합니다.

### 2단계: 패턴 분석

- 같은 코드베이스에서 정상 동작하는 유사 사례를 찾습니다.
- 참조 구현이 있다면 끝까지 읽고 패턴을 정확히 이해합니다.
- 정상 사례와 문제 사례의 차이를 작은 것까지 모두 나열합니다.
- 필요한 설정, 환경, 전제 조건을 파악합니다.
- "이 정도 차이는 중요하지 않겠지"라고 넘기지 않습니다.

### 3단계: 가설과 검증

- "원인은 X이며 이유는 Y다"라는 단일 가설을 명확히 적습니다.
- 가설을 검증할 수 있는 최소 변경만 적용합니다.
- 한 번에 변수 하나만 바꿉니다.
- 실패하면 수정안을 겹쳐 쌓지 말고 새 가설로 돌아갑니다.
- 모르는 것은 모른다고 인정하고 추가 조사 또는 도움 요청을 합니다.

이 단계의 핵심은 과학적 방법입니다.

- 한 번에 하나의 가설만 세웁니다.
- 한 번에 하나의 변수만 바꿉니다.
- 실패하면 더 많은 수정으로 덮지 않고, 얻은 새 증거를 바탕으로 다시 분석합니다.

### 4단계: 구현

- 먼저 실패하는 테스트나 최소 재현 케이스를 만듭니다.
- 확인된 근본 원인만 겨냥해 한 번에 한 수정만 적용합니다.
- 테스트가 통과하는지, 다른 것이 깨지지 않았는지 검증합니다.
- 수정이 실패하면 즉시 멈추고 다시 1단계로 돌아갑니다.
- 세 번 이상 실패했다면 개별 버그가 아니라 구조적 문제일 가능성을 의심합니다.

세 번 이상 수정이 연속 실패했다면 아래를 질문합니다.

- 우리가 증상을 계속 쫓고 있지는 않은가
- 현재 구조 자체가 문제를 유발하고 있지는 않은가
- 고칠 문제가 아니라 패턴을 바꿔야 하는 상황은 아닌가

## 중단 신호

다음 생각이 들면 멈추고 다시 1단계로 돌아갑니다.

- 일단 빨리 고치고 나중에 조사하자
- X를 바꿔보면 될 것 같다
- 여러 개를 같이 바꾸면 빠를 것 같다
- 테스트는 나중에 쓰자
- 완전히 이해는 못 했지만 아마 맞을 것이다
- 한 번만 더 고쳐보자
- 여기 문제들은 대충 이런 것들이다
- 로그 없이 감으로 수정 방향을 정하자
- 여기저기 같이 바꾸면 하나쯤 맞을 것이다

이 신호들은 대부분 조사보다 추측이 앞서고 있다는 뜻입니다.

## 안티 패턴

- 증상만 감추는 빠른 땜질
- 여러 수정안을 한 번에 넣는 방식
- 재현 없이 감으로 고치는 방식
- 비교 대상 없이 현재 코드만 들여다보는 방식
- 세 번 이상 실패했는데도 구조를 의심하지 않는 방식

## 핵심 원칙

- 증상이 아니라 원인을 수정합니다.
- 계측과 증거 없이 추측하지 않습니다.
- 한 번에 하나만 바꿉니다.
- 재현, 비교, 검증이 없는 수정은 완료가 아닙니다.
- 여러 번 실패하면 구조 자체를 의심합니다.

## 기대 결과

이 스킬을 적용한 결과는 다음을 만족해야 합니다.

- 문제의 재현 절차가 설명 가능해야 합니다.
- 근본 원인을 뒷받침하는 증거가 있어야 합니다.
- 수정안은 하나의 원인에 대응해야 합니다.
- 수정 후에는 재현 테스트 또는 검증 절차가 통과해야 합니다.