systematic-debugginglisted

# systematic-debugging **핵심 원칙**: 수정을 시도하기 전에 항상 근본 원인을 찾는다. 증상 수정은 실패다. **이 절차를 글자 그대로 지키지 않는 것은 디버깅의 취지를 저버리는 것이다.** ## 철칙 ``` 근본 원인 조사 없이 수정하지 않는다 ``` 근본 원인 조사(아래 「절차」의 1단계)를 마치지 않았다면 수정을 제안할 수 없다. ## 적용 대상 모든 기술적 문제에 쓴다. 테스트 실패, 프로덕션 버그, 예상 밖 동작, 성능 문제, 빌드 실패, 통합 문제. **특히 다음 상황에서 쓴다**: - 시간 압박을 받을 때(급하면 추측이 달콤해진다) - "빠른 수정 하나면 될 것" 같을 때 - 이미 여러 수정을 시도했을 때 - 앞선 수정이 듣지 않았을 때 - 문제를 온전히 이해하지 못했을 때 **다음 이유로 건너뛰지 않는다**: - 문제가 단순해 보인다(단순한 버그에도 근본 원인이 있다) - 급하다(서두르면 재작업이 확정된다) - 지금 당장 고쳐야 한다(체계적인 쪽이 헤매는 것보다 빠르다) ## 절차 각 단계를 마쳐야 다음으로 간다. ### 1단계. 근본 원인 조사 **어떤 수정이든 시도하기 전에** 한다. 1. **에러 메시지를 정독한다** - 에러·경고를 건너뛰지 않는다 - 거기에 정확한 해법이 들어 있는 경우가 많다 - 스택 트레이스를 끝까지 읽는다 - 라인 번호·파일 경로·에러 코드를 기록한다 2. **일관되게 재현한다** - 신뢰성 있게 유발할 수 있는가 - 정확한 절차가 무엇인가 - 매번 일어나는가 - 재현되지 않으면 데이터를 더 모은다. 추측하지 않는다 3. **최근 변경을 확인한다** - 무엇이 바뀌어 이것을 일으켰나 - git diff, 최근 커밋 - 새 의존성, 설정 변경 - 환경 차이 4. **다중 컴포넌트 시스템에서 증거를 모은다** 시스템에 컴포넌트가 여럿이면(CI → 빌드 → 서명, API → 서비스 → DB) 수정을 제안하기 전에 진단 계측을 넣는다. ``` 각 컴포넌트 경계마다: - 컴포넌트에 들어가는 데이터를 로깅 - 컴포넌트에서 나오는 데이터를 로깅 - 환경·설정 전파를 확인 - 각 층의 상태를 확인 한 번 돌려 어디서 깨지는지 보여주는 증거를 모은다 그 증거로 실패 컴포넌트를 특정한다 그 컴포넌트만 파고든다 ``` 이렇게 하면 어느 층이 실패하는지 드러난다. 예를 들어 비밀값은 워크플로까지 정상 전달됐고, 워크플로에서 빌드로 넘어가는 경계에서 깨졌다. 5. **데이터 흐름을 추적한다** 에러가 콜스택 깊은 곳에 있으면 역방향으로 추적한다. 상세 기법은 [root-cause-tracing.md](root-cause-tracing.md)에 있다. 요약하면 이렇다. 나쁜 값이 어디서 비롯됐는가. 무엇이 나쁜 값으로 이것을 호출했는가. 출처를 찾을 때까지 위로 올라간다. 증상이 아니라 출처를 고친다.