error-detective

name	error-detective
description	TRACE 프레임워크(Trace, Read, Analyze, Check, Execute)를 사용한 체계적인 디버깅 및 에러 해결입니다. 에러 디버깅, 스택 트레이스(stack traces) 분석, 실패 조사, 근본 원인 분석(root cause analysis) 또는 운영 이슈 트러블슈팅 시 사용합니다.

Error Detective - Systematic Debugging and Error Resolution

개요 (Overview)

Error Detective는 에러를 효율적으로 식별, 분석 및 해결하기 위해 체계적인 방법론을 적용하는 종합적인 디버깅 SKILL입니다. TRACE 프레임워크와 구조화된 분석 기법을 사용하여 에러의 초기 발견부터 검증된 해결까지 디버깅 과정을 안내합니다.

핵심 역량 (Core Capabilities)

스택 트레이스 분석 (Stack Trace Analysis)

• 여러 언어에 걸친 스택 트레이스 파싱 및 해석
• 근본 원인(root cause)과 증상 에러(symptom errors) 구분
• 관련 파일 경로 및 라인 번호 추출
• 호출 체인 및 에러 전파 과정 이해

에러 패턴 인식 (Error Pattern Recognition)

• 유형별 에러 분류 (syntax, runtime, logic, integration)
• 공통 에러 패턴 및 안티 패턴 식별
• 프레임워크별 특화 에러 인식
• 에러를 발생 가능한 근본 원인에 매핑

근본 원인 분석 (Root Cause Analysis)

• 증상과 기저 이슈의 구분
• 에러 체인을 따라 원래 발생 지점 추적
• 환경 이슈와 코드 이슈의 실별
• 설정 및 종속성 문제 감지

디버깅 워크플로우 관리

• 구조화된 조사 프로세스
• 가설 생성 및 테스트
• 이해도에 대한 반복적 정밀화
• 조사 결과 및 해결책 문서화

TRACE 프레임워크

TRACE는 어떤 에러든 디버깅할 수 있는 체계적인 5단계 접근 방식입니다:

T - Trace the Error (에러 추적)

목표: 완전한 에러 정보와 컨텍스트 캡처

1. 전체 에러 메시지 수집

   • 전체 스택 트레이스 (처음 몇 줄만이 아닌 전체)
   • 에러 유형 및 메시지
   • 타임스탬프 및 발생 빈도
   • 에러가 발생한 환경

2. 에러 위치 식별

   • 정확한 파일 및 라인 번호
   • 에러가 발생한 함수 또는 메서드
   • 코드 컨텍스트 (주변 라인)
   • 진입점부터 에러 지점까지의 호출 스택

3. 재현 단계 갈무리

   • 재현을 위한 최소한의 단계
   • 사용된 입력 데이터 또는 파라미터
   • 기대 결과 vs. 실제 동작
   • 재현의 일관성 (항상 발생, 간헐적 발생, 드물게 발생)

R - Read the Error Message (에러 메시지 읽기)

목표: 에러 자체에서 모든 정보 추출

1. 에러 구성 요소 파싱

   • 에러 유형/클래스 (TypeError, ValueError 등)
   • 에러 메시지 내용
   • 권장 수정 사항 (제공되는 경우)
   • 관련 에러 또는 경고

2. 에러 시맨틱 이해

   • 해당 언어/프레임워크에서 해당 에러 유형이 의미하는 바
   • 어떤 조건이 이 에러를 유발하는지
   • 에러 메시지가 구체적으로 무엇을 말하고 있는지
   • 에러 코드 또는 상태 코드

3. 에러 카테고리 식별

   • Syntax error (코드 파싱 불가)
   • Runtime error (실행 중 크래시 발생)
   • Logic error (결과가 틀림, 크래시 없음)
   • Integration error (외부 시스템 실패)
   • Performance error (타임아웃, 리소스 고갈)

A - Analyze the Context (컨텍스트 분석)

목표: 에러 주변의 더 넓은 컨텍스트 이해

1. 코드 분석

   • 실패한 라인과 주변 코드 검토
   • 해당 코드의 최근 변경 사항 확인
   • 함수/메서드 시그니처 및 사용법 검토
   • 실패한 코드를 호출하거나 호출되는 관련 코드 검토

2. 데이터 분석

   • 실패 시점의 입력값 조사
   • 데이터 타입 및 구조 확인
   • 데이터가 예상된 형식/제약 사항을 충족하는지 검증
   • 엣지 케이스(edge cases) 또는 예상치 못한 값 식별

3. 환경 분석

   • 종속성 및 버전 확인
   • 설정 파일 검토
   • 환경 변수 검증
   • 필요한 리소스(파일, 네트워크, 메모리) 가용성 확인

4. 상태 분석

   • 에러 발생 시점의 애플리케이션 상태
   • 이 상태로 이어진 이전 작업들
   • 관련된 공유 상태 또는 전역 변수
   • 데이터베이스 또는 외부 시스템 상태

C - Check for Root Cause (근본 원인 확인)

목표: 단순한 증상이 아닌 기저의 이슈 실별

1. 에러 체인 추적

   • 스택 트레이스의 맨 아래(첫 번째 에러)부터 시작
   • 상위로 거슬러 올라가며 원래 원인 탐색
   • 에러 발생 지점과 에러 핸들러 구분
   • 래핑되거나 다시 던져진(re-thrown) 에러 식별

2. 가설 테스트

   • 구체적이고 테스트 가능한 가설 생성
   • 변수 격리 (한 번에 하나씩 변경)
   • 로깅/디버깅 도구를 사용하여 가정 검증
   • 확인되거나 기각된 가설 문서화

3. 일반적인 근본 원인

   • Null/undefined 값: 초기화 또는 검증 누락
   • 타입 불일치 (Type mismatches): 잘못된 데이터 타입 전달 또는 반환
   • Off-by-one 에러: 배열/루프 경계 이슈
   • 경합 조건 (Race conditions): 타이밍에 따른 실패
   • 리소스 고갈: 메모리, 디스크, 커넥션 부족
   • 설정 에러 (Configuration errors): 잘못된 설정 또는 누락된 설정
   • 종속성 이슈 (Dependency issues): 버전 충돌 또는 누락된 라이브러리
   • 권한 에러: 불충분한 접속 권한
   • 네트워크 에러: 연결성, 타임아웃, DNS 이슈
   • 데이터 손상: 유효하지 않거나 예상치 못한 데이터 형식

E - Execute the Fix (수정 실행)

목표: 해결책 구현 및 검증

1. 수정 설계

   • 증상이 아닌 근본 원인 해결
   • 부수 효과(side effects) 및 엣지 케이스 고려
   • 필요한 경우 하위 호환성 계획
   • 가장 유지보수하기 쉬운 해결책 선택

2. 신중한 구현

   • 최소한의 타겟팅된 변경 실시
   • 검증 및 에러 핸들링 추가
   • 향후 디버깅을 위한 로깅 포함
   • 수정 내용 및 근거 문서화

3. 철저한 검증

   • 원래 에러가 해결되었는지 확인
   • 재현 단계를 통해 테스트
   • 엣지 케이스 및 관련 기능 테스트
   • 새로운 에러가 도입되지 않았는지 확인

4. 문서화 및 방지

   • 에러 유발 원인 문서화
   • 해결책 및 작동 이유 문서화
   • 회귀(regression) 방지를 위한 테스트 추가
   • 필요한 경우 문서 업데이트 또는 경고 추가

디버깅 워크플로우

초기 평가 (5분)

1. 전체 에러 메시지 읽기
2. 에러 유형 및 심각도 식별
3. 에러 재현 가능 여부 확인
4. 영향도 평가 (차단형, 성능 저하, 단순 외관상 문제)
5. 조사 우선순위 결정

심층 조사 (15-30분)

1. TRACE 프레임워크를 체계적으로 적용
2. 디버깅 도구 사용 (scripts/debug_helper.py 참조)
3. 가설 생성 및 테스트
4. 진행하면서 발견 사항 문서화
5. 근본 원인으로 좁히기

해결책 구현 (상황에 따라 다름)

1. 근본 원인을 해결하는 수정 설계
2. 적절한 에러 핸들링과 함께 구현
3. 로깅 및 검증 추가
4. 철저한 테스트
5. 해결책 문서화

검증 및 방지 (10분)

1. 원래의 재현 단계로 수정 사항 검증
2. 관련 기능 테스트
3. 회귀 테스트 추가
4. 문서 업데이트
5. 배포 및 모니터링

언어별 공통 에러 패턴

Python

AttributeError: 'NoneType' has no attribute 'X'

• 근본 원인: 객체를 기대했으나 변수가 None임
• 체크 사항: 초기화, 함수 반환값, API 응답
• 해결책: Null 체크 추가, 적절한 초기화 보장

KeyError: 'key_name'

• 근본 원인: 딕셔너리에 기대한 키가 없음
• 체크 사항: 데이터 소스, 파싱 로직, 키 철자
• 해결책: 디폴트값과 함께 .get() 사용, 데이터 구조 검증

ImportError / ModuleNotFoundError

• 근본 원인: 모듈이 설치되지 않았거나 경로에 없음
• 체크 사항: requirements.txt, 가상 환경, PYTHONPATH
• 해결책: 누락된 패키지 설치, 임포트 경로 수정

IndentationError

• 근본 원인: 일관되지 않은 여백 (탭 vs 공백)
• 체크 사항: 에디터 설정, 복사된 코드
• 해결책: 공백(PEP 8)으로 표준화, linter 사용

JavaScript/TypeScript

TypeError: Cannot read property 'X' of undefined

• 근본 원인: undefined 객체의 프로퍼티에 접근
• 체크 사항: 객체 초기화, 비동기 타이밍, API 응답
• 해결책: 옵셔널 체이닝(?. 연산자), null 체크

ReferenceError: X is not defined

• 근본 원인: 선언 전 변수 사용 또는 스코프 벗어남
• 체크 사항: 변수 선언, 스코프, 호이스팅(hoisting) 이슈
• 해결책: 변수 선언, 스코프 수정, 임포트 확인

Promise rejection / Uncaught (in promise)

• 근본 원인: catch 핸들러 없이 비동기 작업 실패
• 체크 사항: API 호출, 파일 작업, async/await 사용
• 해결책: .catch() 추가 또는 await와 함께 try/catch 사용

SyntaxError: Unexpected token

• 근본 원인: 주로 JSON이나 코드 파싱 중 발생하는 유효하지 않은 구문
• 체크 사항: JSON 구조, 괄호 짝 맞추기, 세미콜론
• 해결책: JSON 검증, 구문 수정, 복사/붙여넣기 에러 확인

Java

NullPointerException

• 근본 원인: null 객체 참조에 대해 메서드 호출
• 체크 사항: 객체 초기화, 메서드 반환값
• 해결책: Null 체크 추가, Optional 사용, 초기화 보장

ClassNotFoundException

• 근본 원인: classpath에서 클래스를 찾을 수 없음
• 체크 사항: 종속성, 빌드 설정, 패키지 구조
• 해결책: 종속성 추가, classpath 수정, 패키지/클래스 이름 확인

ConcurrentModificationException

• 근본 원인: 반복(iteration) 중에 컬렉션이 수정됨
• 체크 사항: 중첩 루프, 멀티스레딩, iterator 사용
• 해결책: iterator.remove(), CopyOnWriteArrayList 사용 또는 동기화(synchronization)

에러 심각도 분류

Critical (즉시 수정)

• 애플리케이션 크래시 또는 시작 불가
• 데이터 손실 또는 손상
• 보안 취약점
• 운영 환경 중단 (Outages)
• 결제 또는 트랜잭션 실패

High (조속히 수정)

• 주요 기능 고장
• 사용자에게 영향을 주는 성능 저하
• 여러 사용자에게 영향을 주는 에러
• 복잡한 해결 방법(Workarounds)

Medium (수정 일정 계획)

• 부가 기능 고장
• 영향도가 있는 외관상 이슈
• 쉬운 해결 방법이 있는 에러
• 엣지 케이스 실패

Low (백로그)

• 외관상 이슈
• 사소한 개선 사항
• 드문 엣지 케이스
• 중요하지 않은 경고

디버깅 도구 및 기법

로깅 모범 사례

import logging

# 구조화된 로깅 설정
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# 컨텍스트와 함께 로깅
logger = logging.getLogger(__name__)
logger.debug(f"Processing item: {item_id}, user: {user_id}")
logger.error(f"Failed to process: {error}", exc_info=True)

전략적 중단점 (Breakpoints)

1. 에러 발생 지점: 에러 발생 시의 정확한 상태 포착
2. 에러 발생 전: 입력값 및 사전 조건 확인
3. 에러 발생 후: 에러 전파 과정 관찰
4. 결정 지점 (Decision points): 로직 분기점 검증
5. 루프 내부: 반복 변수 확인

전략적인 Print 디버깅

# 컨텍스트 정보를 포함한 디버그 출력 추가
print(f"DEBUG: function_name called with {param1=}, {param2=}")
print(f"DEBUG: variable state before operation: {var=}")
print(f"DEBUG: condition check: {condition=}, result: {result=}")

이진 탐색 디버깅 (Binary Search Debugging)

에러 위치가 불분명할 때:

1. 코드 경로 중간에 체크포인트 추가
2. 에러가 체크포인트 이전인지 이후인지 판단
3. 남은 절반에 대해 반복
4. 에러 위치에 빠르게 수렴

고무 오리 디버깅 (Rubber Duck Debugging)

누군가에게(혹은 사물에게) 코드를 한 줄씩 설명하기:

1. 가정을 검토하게 함
2. 설명하는 중에 에러를 발견하는 경우가 많음
3. 복잡한 로직을 명확하게 함
4. 지식의 공백을 식별함

Debug Helper 스크립트 사용

scripts/debug_helper.py 유틸리티는 자동화된 보조 기능을 제공합니다:

# 파일에서 스택 트레이스 파싱
python scripts/debug_helper.py parse-trace error.log

# 에러 패턴 추출
python scripts/debug_helper.py analyze-log application.log

# 디버그 세션 시작 (로그 생성)
python scripts/debug_helper.py session start "Login error investigation"

# 세션에 노트 추가
python scripts/debug_helper.py session note "Tested with different users - same error"

# 해결책과 함께 세션 종료
python scripts/debug_helper.py session close "Fixed: Added null check for user.profile"

모범 사례 (Best Practices)

수행할 작업 (Do's)

• 에러 메시지 전체 읽기: 세부 사항을 건너뛰지 마세요.
• 일관된 재현: 디버깅 전에 신뢰할 수 있는 재현 방법을 확보하세요.
• 한 번에 한 가지만 변경: 무엇이 문제를 해결했는지 격리하세요.
• 진행하면서 문서화: 가설, 테스트, 발견 사항을 기록하세요.
• 버전 관리 사용: 디버깅 전에 커밋하여 필요한 경우 되돌릴 수 있게 하세요.
• 테스트 추가: 수정 후 회귀를 방지하세요.
• 근본 원인 수정: 증상에만 땜질하지 마세요.
• 지식 공유: 팀을 위해 해결책을 문서화하세요.

피해야 할 작업 (Don'ts)

• 추측하지 말 것: 데이터로 가정을 검증하세요.
• 에러 읽기를 건너뛰지 말 것: 에러 메시지에는 중요한 정보가 담겨 있습니다.
• 여러 가지를 동시에 변경하지 말 것: 무엇이 해결했는지 알 수 없게 됩니다.
• 충동적으로 코드를 삭제하지 말 것: 먼저 주석 처리하고 왜 그 코드가 있었는지 이해하세요.
• 경고를 무시하지 말 것: 오늘의 경고는 내일의 에러가 됩니다.
• 이해 없이 수정하지 말 것: 다른 것을 망가뜨릴 수 있습니다.
• 테스트를 잊지 말 것: 수정 사항이 작동하고 새로운 이슈를 만들지 않는지 확인하세요.

일반적인 디버깅 시나리오

시나리오 1: "어제는 됐는데"

접근 방식:

1. 최근 변경 사항 확인 (git diff, git log)
2. 종속성 업데이트 검토
3. 환경 변경 사항 확인
4. 시간에 따른 로직(time-dependent logic) 탐색
5. 환경 간 설정 비교

일반적인 원인:

• 최근 코드 변경
• 업데이트된 종속성
• 설정 변경
• 데이터베이스 스키마 변경
• 외부 API 변경
• 인증서 만료

시나리오 2: "내 컴퓨터에선 되는데"

접근 방식:

1. 환경 비교 (OS, 종속성, 설정)
2. 환경 변수 확인
3. 파일 경로 및 권한 검증
4. 환경 간 데이터 비교
5. 하드코딩된 가정사항 탐색

일반적인 원인:

• 다른 종속성 버전
• 누락된 환경 변수
• 다른 파일 경로
• 데이터베이스 상태 차이
• 운영 체제 차이
• 누락된 설정 파일

시나리오 3: "간헐적 실패"

접근 방식:

1. 실패 패턴 식별 (타이밍, 빈도, 조건)
2. 경합 조건(race conditions) 탐색
3. 리소스 가용성 확인
4. 동시 작업 검토
5. 광범위한 로깅 추가
6. 재현 시도 횟수 증가

일반적인 원인:

• 경합 조건
• 메모리 누수
• 외부 서비스 불안정
• 네트워크 이슈
• 타이밍 의존 로직
• 리소스 고갈

시나리오 4: "운영 환경에서만 에러 발생"

접근 방식:

1. 운영 환경 전용 설정 확인
2. 운영 데이터의 특성 검토
3. 운영 환경의 부하/규모 확인
4. 운영 환경의 종속성 검토
5. 보안/권한 설정 검토

일반적인 원인:

• 운영 데이터의 엣지 케이스
• 규모/부하 관련 이슈
• 운영 환경 전용 설정
• 다른 보안 정책
• 방화벽 또는 네트워크 제한
• 운영용으로만 연동된 기능

고급 기법

Bisect Debugging (Git)

어떤 커밋이 버그를 도입했는지 찾기:

git bisect start
git bisect bad                 # 현재 버전에 버그가 있음
git bisect good v1.2.0        # v1.2.0 버전은 정상이였음
# Git이 중간 커밋을 체크아웃함
# 테스트 후 good/bad 마킹
git bisect good/bad
# Git이 범인 커밋을 식별할 때까지 반복
git bisect reset

Heisenbug (관찰자 효과)

디버깅을 시작하면 사라지는 에러:

전략:

• 중단점 없이 로깅 추가
• 디버깅을 위해 운영 환경과 유사한 환경 사용
• 타이밍 및 동시성 이슈 검토
• 초기화/타이밍 종속성 확인
• 비침습적(non-intrusive) 모니터링 사용

메모리 프로파일링 (Memory Profiling)

메모리 누수 및 성능 확인:

# Python 메모리 프로파일링
import tracemalloc

tracemalloc.start()
# ... 코드 실행 ...
snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('lineno')

for stat in top_stats[:10]:
    print(stat)

네트워크 디버깅 (Network Debugging)

API 및 통합 에러 확인:

도구:

• 브라우저 DevTools Network 탭
• 상세 플래그(-v)를 포함한 curl
• API 테스트를 위한 Postman
• 패킷 조사를 위한 Wireshark
• 네트워크 프록시 (Charles, Fiddler)

체크 사항:

• Request/response 헤더
• 상태 코드
• Request/response 바디
• 타이밍 (레이턴시, 타임아웃)
• SSL/TLS 이슈

Quick Reference

TRACE 프레임워크 퀵 체크리스트

☐ T - TRACE
  ☐ 전체 에러 메시지 캡처 완료
  ☐ 스택 트레이스 수집 완료
  ☐ 재현 단계 문서화 완료
  ☐ 환경 식별 완료

☐ R - READ
  ☐ 에러 유형 식별 완료
  ☐ 에러 메시지 분석 완료
  ☐ 에러 카테고리 결정 완료
  ☐ 관련 에러 확인 완료

☐ A - ANALYZE
  ☐ 코드 검토 완료
  ☐ 데이터 조사 완료
  ☐ 환경 검증 완료
  ☐ 상태 조사 완료

☐ C - CHECK
  ☐ 에러 체인 추적 완료
  ☐ 가설 테스트 완료
  ☐ 근본 원인 식별 완료
  ☐ 가정 검증 완료

☐ E - EXECUTE
  ☐ 수정 설계 완료
  ☐ 수정 구현 완료
  ☐ 수정 검증 완료
  ☐ 방지 대책 추가 완료

에러 우선순위 매트릭스 (Error Priority Matrix)

영향도 →      Low        Medium       High        Critical
빈도 ↓
High         Medium     High         Critical    Critical
Medium       Low        Medium       High        Critical
Low          Low        Low          Medium      High
Rare         Backlog    Low          Medium      High

추가 자료

예시 (Examples)

• examples/debugging_workflow.md - 단계별 디버깅 프로세스 예시
• examples/common_errors.md - 자주 발생하는 에러 패턴 및 해결책 카탈로그
• examples/stack_traces.txt - 분석과 함께 제공되는 스택 트레이스 예시

스크립트 (Scripts)

• scripts/debug_helper.py - 트레이스 파싱 및 세션 관리를 위한 Python 디버깅 유틸리티

추가 학습

• 언어별 디버깅 문서
• 프레임워크 에러 핸들링 가이드
• 프로파일링 및 성능 분석 도구
• 테스트 및 품질 보증 실무

---

기억하세요: 디버깅은 탐정 수사입니다. 체계적이고 인내심을 가지며, 증거가 진실로 당신을 인도하게 하세요. 모든 에러 메시지는 당신의 이해를 기다리고 있는 단서입니다.