johnalbertini14-glitch Systematic Debugging
철칙
근본 원인 파악 없이 수정 시도 절대 금지
4단계 프로세스
Phase 1: 근본 원인 조사
수정 시도 전에 반드시:
- 에러 메시지 정독 — 스택 트레이스 전체 읽기, 줄 번호/파일 경로 기록
- 재현 — 일관되게 트리거 가능한가? 정확한 단계는?
- 최근 변경 확인 — git diff, 최근 커밋, 새 의존성, 설정 변경
- 데이터 흐름 추적 — 잘못된 값이 어디서 시작되는가? 역추적
다중 컴포넌트 시스템일 때: 각 경계에 진단 로그 추가 → 한 번 실행 → 어디서 깨지는지 확인 → 그 컴포넌트만 조사
Phase 2: 패턴 분석
- 작동하는 예제 찾기 — 같은 코드베이스에서 유사한 작동 코드
- 참조와 비교 — 패턴 구현 시 참조 문서 완전히 읽기 (훑어보기 금지!)
- 차이점 식별 — 작동/비작동 간 모든 차이 나열
- 의존성 파악 — 필요한 다른 컴포넌트, 설정, 환경
Phase 3: 가설 검증
- 단일 가설 수립 — "X가 근본 원인이다. 왜냐하면 Y"
- 최소 변경으로 테스트 — 한 번에 하나만 변경
- 검증 — 작동하면 Phase 4, 아니면 새 가설
- 모르면 모른다고 인정 — 추측하지 말 것
Phase 4: 구현
- 실패 테스트 케이스 작성 — 수정 전에 먼저
- 단일 수정 구현 — 근본 원인만 해결, "김에 같이" 개선 금지
- 검증 — 테스트 통과? 다른 테스트 깨지지 않음?
- 3번 이상 수정 실패 시 → 아키텍처 의심
- 매 수정마다 새로운 문제 발견?
- "대규모 리팩토링"이 필요하다면?
- STOP — 근본 설계가 잘못된 것. 주인님과 논의.
🚨 위험 신호 — 즉시 멈추고 Phase 1로
- "일단 X 바꿔보고 되는지 보자"
- "여러 변경을 한꺼번에 테스트"
- "빠른 수정, 나중에 조사"
- "대충 이게 문제인 것 같은데"
- "수동으로 확인했으니 될 거야"
- 조사 없이 수정안 제안
- 2번 이상 수정 시도 실패
합리화 방지
| 핑계 | 현실 |
|---|---|
| "간단한 문제라 프로세스 불필요" | 간단한 버그에도 근본 원인 있음 |
| "급해서 프로세스 따를 시간 없음" | 체계적 디버깅이 추측보다 빠름 |
| "일단 이것부터 시도" | 첫 수정이 패턴을 결정함 |
| "참조 문서가 너무 길어" | 부분 이해 = 버그 보장 |