debugginglisted

# 디버깅 **철칙: 근본 원인을 규명하기 전에는 수정을 제안하지 않는다.** 증상 수정은 실패다 — 급할수록 추측-수정 반복(thrashing)이 체계적 진행보다 느리다. ## 절차 (순서를 지킨다) 1. **에러를 끝까지 읽는다.** 스택트레이스는 아래(근원)부터. 답이 이미 거기 있는 경우가 많다. 2. **재현 먼저.** 실패를 다시 일으키는 최소 명령/입력을 확보하고, 가능하면 **실패하는 테스트**로 박제한다 — 그게 곧 완료 기준이다. 재현이 안 되면 고치지 말고 증거를 더 모은다. 3. **최근 변경을 본다.** `git diff`·최근 커밋·의존성·환경. 어제까지 됐다면 코드보다 환경(버전·PATH·환경변수)이 바뀐 경우가 많다. 4. **작동하는 유사 사례와 비교한다.** 같은 레포에서 되는 코드를 찾아 차이를 전부 나열한다. "그건 상관없겠지"라고 걸러내지 않는다 — 걸러낸 것이 범인인 경우가 많다. 5. **가설 하나 → 최소 변경으로 검증.** "Y 때문에 X 가 원인이다"라고 문장으로 적는다. 한 번에 한 변수만. 실패하면 새 가설로 — 수정 위에 수정을 쌓지 않는다. 다층 시스템(API → 서비스 → DB)이면 고치기 전에 경계마다 로그를 넣어 **어느 층이 깨지는지 증거부터** 확보한다. 6. **근본 원인을 한 문장으로 말한 뒤** 최소 수정 + 2의 테스트 통과로 마친다. 지나가는 김에 정리하지 않는다. ## 레드 플래그 — 이 생각이 들면 멈추고 1로 돌아간다 - "일단 이것만 바꿔보고 안 되면 조사하자" - "아마 X 일 거야, 그것부터 고치자" - "여러 군데 고치고 한 번에 테스트 돌리자" - "완전히 이해는 안 되지만 이러면 될 것 같다" - 데이터 흐름을 추적하기 전에 수정안 목록부터 나열하고 있다 ## 3회 규칙 수정 시도가 **3번 실패하면 멈춘다.** 네 번째 수정이 아니라 구조를 의심할 차례다 — 고칠 때마다 다른 곳에서 새 증상이 나오면 가설이 아니라 아키텍처가 틀린 것이다. 지금까지의 가설·반증을 정리해 보고하고 방향을 확인받는다. | 합리화 | 실제 | |---|---| | "단순한 버그라 절차가 과하다" | 단순한 버그에도 근본 원인은 있다. 절차는 단순할수록 빠르다 | | "급하니 일단 고치고 보자" | 첫 수정이 패턴을 만든다. 추측 반복이 더 느리다 | | "테스트는 고친 뒤에 쓰겠다" | 실패를 본 적 없는 테스트는 검증이 아니다 | > 참고: [obra/superpowers](https://github.com/obra/superpowers) 의 systematic-debugging 을 > 이 번들 형식에 맞게 압축·재구성했다.