에러 근본 원인 특정 및 해결책 제안

에러 근본 원인 특정 및 해결책 제안

에러 메시지에서 근본 원인을 파악하고, 해결 시간을 예측하여 검증된 해결책을 제안합니다. 유사 에러의 패턴을 학습하여 즉시 적절한 대처법을 제시합니다.

사용법

/fix-error [옵션]

옵션

• 없음 : 표준 에러 분석
• --deep : 심층 분석 모드(의존성・환경 요인 포함)
• --preventive : 예방책 중심 분석
• --quick : 즉시 적용 가능한 수정만 제시

기본 예제

# 표준 에러 분석
npm run build 2>&1
/fix-error
"빌드 에러를 분석해서 수정 방법을 제시해줘"

# 심층 분석 모드
python app.py 2>&1
/fix-error --deep
"에러의 근본 원인을 환경 요인까지 포함해서 분석해줘"

# 즉시 수정 중심
cargo test 2>&1
/fix-error --quick
"바로 적용할 수 있는 수정 방법을 제시해줘"

# 예방책 중심
./app 2>&1 | tail -50
/fix-error --preventive
"에러 수정과 향후 예방책을 제시해줘"

Claude 와의 연계

# 에러 로그 분석
cat error.log
/fix-error
"에러의 근본 원인을 파악하고 수정 방법을 제안해줘"

# 테스트 실패 해결
npm test 2>&1
/fix-error --quick
"실패한 테스트를 분석하고 즉시 적용 가능한 수정안을 제시해줘"

# 스택 트레이스 해석
python script.py 2>&1
/fix-error --deep
"이 스택 트레이스에서 문제 지점을 파악하고 환경 요인까지 포함해서 분석해줘"

# 여러 에러를 한번에 해결
grep -E "ERROR|WARN" app.log | tail -20
/fix-error
"이 에러와 경고를 우선순위별로 분류하고 각각의 해결 방법을 제안해줘"

에러 해결 시간 예측

🚀 즉시 수정(5 분 이내)
├─ 오타, import 누락
├─ 환경 변수 미설정
├─ 미정의 변수 참조
└─ 예측 시간: 2-5 분

⚡ 빠른 수정(30 분 이내)
├─ 의존성 불일치
├─ 설정 파일 에러
├─ 타입 불일치
└─ 예측 시간: 10-30 분

🔧 조사 필요(2 시간 이내)
├─ 복잡한 로직 에러
├─ 비동기 처리 경합
├─ API 통합 문제
└─ 예측 시간: 30 분-2 시간

🔬 심층 분석(반나절 이상)
├─ 아키텍처 기인
├─ 다중 시스템 연계
├─ 성능 저하
└─ 예측 시간: 4 시간-며칠

유사 에러 패턴 DB

빈발 에러와 즉시 해결책
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 "Cannot read property 'X' of undefined/null" (빈도: 극고)
├─ 주요 원인: 객체의 null 체크 부족
├─ 해결 시간: 5-10 분
└─ 대처법: Optional chaining (?.) 또는 null 체크 추가

📊 "ECONNREFUSED" / "ENOTFOUND" (빈도: 고)
├─ 주요 원인: 서비스 미기동 또는 URL 설정 오류
├─ 해결 시간: 5-15 분
└─ 대처법: 서비스 기동 확인, 환경 변수 체크

📊 "Module not found" / "Cannot resolve" (빈도: 고)
├─ 주요 원인: 패키지 미설치, 경로 지정 오류
├─ 해결 시간: 2-5 분
└─ 대처법: npm install 실행, 상대 경로 확인

📊 "Unexpected token" / "SyntaxError" (빈도: 중)
├─ 주요 원인: 괄호・인용부호 불일치, 예약어 사용
├─ 해결 시간: 2-10 분
└─ 대처법: 신택스 하이라이트 확인, Linter 실행

📊 "CORS policy" / "Access-Control-Allow-Origin" (빈도: 중)
├─ 주요 원인: 서버 측 CORS 설정 부족
├─ 해결 시간: 15-30 분
└─ 대처법: 서버 CORS 설정, 프록시 설정

📊 "Maximum call stack size exceeded" (빈도: 저)
├─ 주요 원인: 무한 루프・재귀, 순환 참조
├─ 해결 시간: 30 분-2 시간
└─ 대처법: 재귀 종료 조건 확인, 순환 참조 해소

에러 분석의 우선순위 매트릭스

우선순위	아이콘	영향 범위	해결 난이도	대응 기한	설명
Critical	🔴 긴급 대응	넓음	낮음	15 분 이내 착수	시스템 전체 정지, 데이터 손실 위험
High Priority	🟠 조기 대응	넓음	높음	1 시간 이내 착수	주요 기능 정지, 다수 사용자 영향
Medium	🟡 계획 대응	좁음	높음	당일 중 대응	일부 기능 제한, 회피책 있음
Low	🟢 경과 관찰	좁음	낮음	다음 수정 시	경미한 불량, UX 에 미치는 영향 적음

분석 프로세스

Phase 1: 에러 정보 수집

🔴 필수 실행:
- 에러 메시지의 완전한 취득
- 스택 트레이스 확인
- 발생 조건 파악(재현 가능성)

🟡 조기 실행:
- 환경 정보 수집(OS, 버전, 의존관계)
- 직전 변경 이력(git log, 최근 커밋)
- 관련 로그 확인

🟢 추가 실행:
- 시스템 리소스 상황
- 네트워크 상태
- 외부 서비스 상태

Phase 2: 근본 원인 분석

1. 표면적 증상 정리

   • 에러 메시지의 정확한 내용
   • 발생 타이밍과 패턴
   • 영향 범위 파악

2. 심층 원인 파악

   • 5 Whys 분석의 적용
   • 의존관계 추적
   • 환경 차이 확인

3. 가설 검증

   • 최소 재현 코드 작성
   • 격리 테스트 실행
   • 원인 좁혀가기

Phase 3: 해결책 구현

🔴 즉시 대처(핫픽스):
- 증상을 억제하는 최소한의 수정
- 임시 회피책 적용
- 긴급 배포 준비

🟡 근본적 해결:
- 원인에 대한 본질적 수정
- 테스트 케이스 추가
- 문서 업데이트

🟢 예방책 구현:
- 에러 핸들링 강화
- 모니터링・알림 설정
- CI/CD 파이프라인 개선

출력 예시

🚨 에러 분석 리포트
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📍 에러 개요
├─ 종류: [컴파일/런타임/논리/환경]
├─ 긴급도: 🔴 높음 / 🟡 중간 / 🟢 낮음
├─ 영향 범위: [기능명/컴포넌트]
└─ 재현성: [100% / 간헐적 / 특정 조건]

🔍 근본 원인
├─ 직접 원인: [구체적인 원인]
├─ 배경 요인: [환경/설정/의존관계]
└─ 트리거: [발생 조건]

💡 해결책
🔴 즉시 대처:
1. [구체적인 수정 명령/코드]
2. [임시 회피책]

🟡 근본적 해결:
1. [본질적인 수정 방법]
2. [필요한 리팩터링]

🟢 예방책:
1. [에러 핸들링 개선]
2. [테스트 추가]
3. [모니터링 설정]

📝 검증 절차
1. [수정 적용 후 확인 방법]
2. [테스트 실행 명령]
3. [동작 확인 항목]

에러 타입별 분석 기법

컴파일/빌드 에러

# TypeScript 타입 에러
필수 확인(높음):
- tsconfig.json 설정
- 타입 정의 파일(.d.ts)의 존재
- import 문의 정확성

# Rust 라이프타임 에러
필수 확인(높음):
- 소유권 이동
- 참조의 유효 기간
- 가변성 충돌

런타임 에러

# Null/Undefined 참조
필수 확인(높음):
- 옵셔널 체이닝 부족
- 초기화 타이밍
- 비동기 처리의 완료 대기

# 메모리 관련 에러
필수 확인(높음):
- 힙 덤프 취득
- GC 로그 분석
- 순환 참조 감지

의존관계 에러

# 버전 충돌
필수 확인(높음):
- lock 파일의 정합성
- peer dependencies 요건
- 전이적 의존관계

# 모듈 해결 에러
필수 확인(높음):
- NODE_PATH 설정
- 경로 별칭 설정
- 심볼릭 링크

주의사항

• 절대 금지: 에러 메시지의 일부만으로 판단, 검증 없이 Stack Overflow 해결책 적용
• 예외 조건: 임시 회피책은 다음 3 가지 조건에서만 허용
  1. 프로덕션 환경의 긴급 대응(24 시간 이내에 근본 해결 필수)
  2. 외부 서비스 장애(복구 대기 중의 대체 수단)
  3. 알려진 프레임워크 버그(수정 버전 릴리스 대기)
• 권장사항: 근본 원인의 파악을 최우선으로 하고 표면적 수정을 회피

베스트 프랙티스

1. 완전한 정보 수집: 에러 메시지의 처음부터 끝까지 확인
2. 재현성 확인: 최소 재현 코드 작성을 최우선
3. 단계적 어프로치: 작은 수정부터 시작해서 검증
4. 문서화: 해결 과정을 기록해서 지식 공유

자주 하는 실수

• 증상에 대한 대처: 근본 원인을 놓치는 표면적 수정
• 과도한 일반화: 특정 케이스의 해결책을 광범위하게 적용
• 검증 생략: 수정 후의 부작용을 확인하지 않음
• 지식의 속인화: 해결 방법을 문서화하지 않음

관련 명령어

• /design-patterns : 코드 구조의 문제를 분석해서 패턴 제안
• /tech-debt : 기술적 부채의 관점에서 에러의 근본 원인을 분석
• /analyzer : 더 깊은 근본 원인 분석이 필요한 경우