Initial commit

2025-11-30 09:05:40 +08:00
commit f525cc10dc
51 changed files with 11777 additions and 0 deletions
--- a/commands/fix-error.md
+++ b/commands/fix-error.md
@@ -0,0 +1,311 @@
+## Error Fix
+
+에러 메시지에서 근본 원인을 파악하고, 해결 시간을 예측하여 검증된 해결책을 제안합니다. 유사 에러의 패턴을 학습하여 즉시 적절한 대처법을 제시합니다.
+
+### 사용법
+
+```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` : 더 깊은 근본 원인 분석이 필요한 경우