systematic-debugging

name	systematic-debugging
description	버그, 테스트 실패, 예상 밖 동작을 수정하기 전에 근본 원인을 체계적으로 조사할 때 사용한다.
disable-model-invocation	false

systematic-debugging

Iron Law

근본원인 조사 없이 수정을 시도하지 않는다.

"일단 이것 바꿔보자", "아마 이게 문제일 거야" — 전부 추측이다. Phase 1을 완료하지 않으면, 수정을 제안할 수 없다.

이 규칙의 문구를 지키는 것이 정신을 지키는 것이다.

4단계 프로세스

각 단계를 완료해야 다음 단계로 넘어간다.

Phase 1: 근본원인 조사

수정 시도 전에 반드시 수행:

1. 에러 메시지 정독

   • 스택 트레이스 전체를 읽는다

   • 라인 번호, 파일 경로, 에러 코드를 기록한다

   • "대충 이런 에러" 금지 — 정확히 읽는다

2. 일관된 재현

   • 정확한 재현 단계를 확인한다

   • 매번 발생하는가? 간헐적인가?

   • 재현 불가 → 추가 데이터 수집, 추측 금지

3. 최근 변경 확인

   • git diff, 최근 커밋, 설정 변경

   • 새 의존성, 환경 차이

   • "이건 관계없을 거야" 가정 금지

4. 다중 컴포넌트 시스템: 진단 계측

   각 컴포넌트 경계마다:
     - 입력 데이터 로깅
     - 출력 데이터 로깅
     - 환경/설정 전파 확인
     - 각 레이어 상태 체크
   
   한 번 실행 → 어디서 깨지는지 증거 수집
   그 다음 해당 컴포넌트 집중 조사
   

5. 데이터 흐름 추적

   • 잘못된 값이 어디서 시작되는가?

   • 무엇이 이 잘못된 값을 전달했는가?

   • 원점을 찾을 때까지 역추적

   • 원점에서 수정, 증상에서 수정하지 않음

Phase 2: 패턴 분석

1. 작동하는 예시 찾기 — 같은 코드베이스에서 비슷하게 작동하는 코드
2. 참조와 비교 — 패턴 구현 시 참조를 완전히 읽기 (대충 훑기 금지)
3. 차이 식별 — 작동하는 것과 깨진 것의 모든 차이 나열
4. 의존성 이해 — 필요한 컴포넌트, 설정, 환경, 가정

Phase 3: 가설 + 테스트

1. 단일 가설 수립 — "X가 원인이다. 왜냐하면 Y"
2. 최소 변경으로 테스트 — 한 번에 하나의 변수만
3. 확인 후 진행 — 맞으면 Phase 4, 틀리면 새 가설 (추가 수정 금지)
4. 모르면 인정 — "모르겠다"가 거짓 확신보다 낫다

Phase 4: 구현

1. 실패 테스트 작성 — 버그를 재현하는 테스트
2. 단일 수정 — 근본원인만 해결, "여기 있는 김에" 개선 금지
3. 수정 검증 — 테스트 통과? 다른 테스트 영향 없는지?
4. 3회 실패 시 아키텍처 재검토 (아래 참고)

3회 실패 규칙

3번 수정을 시도해도 해결 안 되면:

패턴이 근본적으로 잘못되었을 가능성:

• 매 수정이 다른 곳에서 새 문제를 드러낸다
• "대규모 리팩터링"이 필요하다고 느낀다
• 수정할수록 상황이 복잡해진다

멈추고 아키텍처를 질문한다:

• 이 패턴이 근본적으로 건전한가?
• 관성으로 유지하고 있는 건 아닌가?
• 증상 수정 대신 아키텍처 변경이 필요한가?

추가 수정을 시도하기 전에 사용자와 논의한다.

Red Flags — 프로세스로 돌아가라

다음 중 하나라도 해당되면 Phase 1로 복귀:

• "일단 X를 바꿔보자"
• "여러 변경을 한꺼번에 적용하고 테스트하자"
• "테스트 건너뛰고 수동 확인하자"
• "아마 X일 거야, 고쳐보자"
• "완전히 이해는 못했지만 될 것 같아"
• 데이터 흐름 추적 없이 해결책 제안
• 이미 2번 이상 수정 시도한 상태에서 "한 번 더"

합리화 방어

핑계	현실
"단순한 버그, 프로세스 불필요"	단순한 버그도 근본원인이 있다. 프로세스가 빠르다.
"긴급, 시간 없다"	체계적 디버깅이 추측 반복보다 빠르다.
"일단 이것만 해보고"	첫 수정이 패턴을 설정한다. 처음부터 제대로.
"나중에 테스트 추가"	테스트 없는 수정은 유지 안 된다.
"여러 수정 동시에"	뭐가 효과인지 알 수 없다. 새 버그 유발.
"한 번 더 시도" (2회 실패 후)	3회 실패 = 아키텍처 문제. 또 수정하지 말고 재검토.

에이전트 활용

복잡한 디버깅 시 전문 에이전트를 활용한다:

• searcher: 관련 코드/파일 빠른 탐색
• verifier: 수정 후 증거 기반 검증
• challenger: 가설의 취약점 압박 검토

실제 효과

• 체계적 접근: 15-30분에 수정
• 추측 반복: 2-3시간 허비
• 첫 수정 성공률: 95% vs 40%
• 새 버그 유발: 거의 없음 vs 빈번