Fix Error

---
description: "에러 근본 원인 특정 및 해결책 제안. 「에러 고쳐줘」「이 에러 뭐야?」「빌드 에러 고쳐줘」「테스트 실패 해결해줘」등으로 기동."
allowed-tools:
  - Read
  - Edit
  - Grep
  - Glob
  - Bash
---

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

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

## 사용법

```bash
/fix-error [옵션]
```

## 옵션

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

## 기본 예제

```bash
# 표준 에러 분석
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 와의 연계

```bash
# 에러 로그 분석
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
"이 에러와 경고를 우선순위별로 분류하고 각각의 해결 방법을 제안해줘"
```

## 에러 해결 시간 예측

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

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

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

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

## 유사 에러 패턴 DB

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

📊 "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: 에러 정보 수집

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

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

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

### Phase 2: 근본 원인 분석

1. **표면적 증상 정리**
   - 에러 메시지의 정확한 내용
   - 발생 타이밍과 패턴
   - 영향 범위 파악

2. **심층 원인 파악**
   - 5 Whys 분석의 적용
   - 의존관계 추적
   - 환경 차이 확인

3. **가설 검증**
   - 최소 재현 코드 작성
   - 격리 테스트 실행
   - 원인 좁혀가기

### Phase 3: 해결책 구현

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

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

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

## 출력 예시

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

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

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

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

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

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

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

## 에러 타입별 분석 기법

### 컴파일/빌드 에러

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

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

### 런타임 에러

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

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

### 의존관계 에러

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

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

## 주의사항

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

## 베스트 프랙티스

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

### 자주 하는 실수

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

## 관련 명령어

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