systematic-debugging

name	systematic-debugging
description	Root-cause-first debugging methodology. Use when encountering any bug, test failure, or unexpected behavior BEFORE proposing fixes. Prevents random fix attempts that waste time and create new bugs.
metadata	{"author":"misskim","version":"1.0","origin":"Concept from obra/superpowers systematic-debugging, adapted for our workflow"}

Systematic Debugging

철칙

근본 원인 파악 없이 수정 시도 절대 금지

4단계 프로세스

Phase 1: 근본 원인 조사

수정 시도 전에 반드시:

1. 에러 메시지 정독 — 스택 트레이스 전체 읽기, 줄 번호/파일 경로 기록
2. 재현 — 일관되게 트리거 가능한가? 정확한 단계는?
3. 최근 변경 확인 — git diff, 최근 커밋, 새 의존성, 설정 변경
4. 데이터 흐름 추적 — 잘못된 값이 어디서 시작되는가? 역추적

다중 컴포넌트 시스템일 때: 각 경계에 진단 로그 추가 → 한 번 실행 → 어디서 깨지는지 확인 → 그 컴포넌트만 조사

Phase 2: 패턴 분석

1. 작동하는 예제 찾기 — 같은 코드베이스에서 유사한 작동 코드
2. 참조와 비교 — 패턴 구현 시 참조 문서 완전히 읽기 (훑어보기 금지!)
3. 차이점 식별 — 작동/비작동 간 모든 차이 나열
4. 의존성 파악 — 필요한 다른 컴포넌트, 설정, 환경

Phase 3: 가설 검증

1. 단일 가설 수립 — "X가 근본 원인이다. 왜냐하면 Y"
2. 최소 변경으로 테스트 — 한 번에 하나만 변경
3. 검증 — 작동하면 Phase 4, 아니면 새 가설
4. 모르면 모른다고 인정 — 추측하지 말 것

Phase 4: 구현

1. 실패 테스트 케이스 작성 — 수정 전에 먼저
2. 단일 수정 구현 — 근본 원인만 해결, "김에 같이" 개선 금지
3. 검증 — 테스트 통과? 다른 테스트 깨지지 않음?
4. 3번 이상 수정 실패 시 → 아키텍처 의심
   • 매 수정마다 새로운 문제 발견?
   • "대규모 리팩토링"이 필요하다면?
   • STOP — 근본 설계가 잘못된 것. 주인님과 논의.

🚨 위험 신호 — 즉시 멈추고 Phase 1로

• "일단 X 바꿔보고 되는지 보자"
• "여러 변경을 한꺼번에 테스트"
• "빠른 수정, 나중에 조사"
• "대충 이게 문제인 것 같은데"
• "수동으로 확인했으니 될 거야"
• 조사 없이 수정안 제안
• 2번 이상 수정 시도 실패

합리화 방지

핑계	현실
"간단한 문제라 프로세스 불필요"	간단한 버그에도 근본 원인 있음
"급해서 프로세스 따를 시간 없음"	체계적 디버깅이 추측보다 빠름
"일단 이것부터 시도"	첫 수정이 패턴을 결정함
"참조 문서가 너무 길어"	부분 이해 = 버그 보장