# /error-log - 에러 학습 (Compounding Engineering)

> **"모든 실수가 규칙이 된다"**
>
> 1. 에러 발생 시 **5 Whys 분석**
> 2. 패턴 **일반화**
> 3. **NEVER/ALWAYS 규칙** 생성
> 4. **CLAUDE.md ERROR_LOG**에 기록

---

## 사용법

```bash
# 마지막 에러 분석
/error-log

# 특정 에러 분석
/error-log "TypeScript 에러 TS2322"

# 주간 에러 리뷰
/error-log --weekly
```

---

## 에러 분석 프로세스

```
/error-log
    │
    ├── Phase 1: 에러 수집
    │   ├── 에러 메시지
    │   ├── 발생 위치
    │   └── 발생 상황
    │
    ├── Phase 2: 5 Whys 분석
    │   └── 근본 원인까지 파고들기
    │
    ├── Phase 3: 패턴 일반화
    │   └── 유사 상황 식별
    │
    ├── Phase 4: 규칙 생성
    │   └── NEVER/ALWAYS 형식
    │
    └── Phase 5: ERROR_LOG 기록
```

---

## Phase 1: 에러 수집

### 1.1 마지막 에러 확인

```bash
# 최근 Gate 실패 로그
cat .claude/logs/tool.log | tail -50

# 테스트 실패 로그
cat /tmp/test_output.txt 2>/dev/null | tail -30
```

### 1.2 에러 정보 수집

```markdown
## 🔍 에러 정보 수집

### 에러 메시지
```
{전체 에러 메시지}
```

### 발생 위치
- **파일**: `src/auth/login.ts`
- **라인**: 45
- **함수**: `validateToken()`

### 발생 시점
- **명령어**: `pnpm test`
- **Gate 단계**: Test (2/4)
- **시각**: 2026-01-09T14:30:00Z

### 환경
- Node: v20.10.0
- Git Commit: abc1234
```

---

## Phase 2: 5 Whys 분석

### 2.1 분석 템플릿

```markdown
## 🤔 5 Whys 분석

### Why 1: 왜 이 에러가 발생했는가?
> **현상**: 테스트에서 401 응답 반환
> **답변**: 토큰 검증 실패

### Why 2: 왜 토큰 검증이 실패했는가?
> **현상**: JWT 검증 함수에서 에러
> **답변**: JWT_SECRET이 undefined

### Why 3: 왜 JWT_SECRET이 undefined인가?
> **현상**: process.env.JWT_SECRET 값 없음
> **답변**: .env.test 파일에 설정 누락

### Why 4: 왜 .env.test에 설정이 없는가?
> **현상**: 파일 자체가 없음
> **답변**: .env.example만 있고 테스트 환경용 파일 미생성

### Why 5: 왜 이것이 감지되지 않았는가? (근본 원인)
> **현상**: 코드에서 환경변수 존재 검증 없음
> **답변**: 시작 시 필수 환경변수 체크 로직 없음

### 🎯 근본 원인
**환경변수 사용 시 존재 검증 없이 바로 사용**
```

---

## Phase 3: 패턴 일반화

### 3.1 에러 유형 분류

| 유형 | 설명 | 이 에러? |
|------|------|---------|
| 타입 에러 | TypeScript 컴파일 | ❌ |
| 런타임 에러 | 실행 중 발생 | ✅ |
| 로직 에러 | 잘못된 결과 | ❌ |
| 아키텍처 위반 | 의존성/구조 | ❌ |
| SSOT 위반 | 분산/중복 | ❌ |

### 3.2 유사 상황 식별

```markdown
### 📊 패턴 분석

**이 에러의 일반화**:
- **패턴**: 환경변수 미설정 → 런타임 에러
- **영향 범위**: 모든 환경변수 사용처
- **재발 가능성**: 높음

**유사 상황**:
1. DATABASE_URL 미설정 시 DB 연결 실패
2. API_KEY 미설정 시 외부 API 호출 실패
3. PORT 미설정 시 서버 시작 실패

**공통점**:
모든 경우 **환경변수 존재 검증 없음**
```

---

## Phase 4: 규칙 생성

### 4.1 NEVER 규칙

```markdown
### 🚫 NEVER 규칙

```
NEVER process.env.X 직접 사용 without 존재 검증
→ 이유: 미설정 시 undefined로 런타임 에러 발생
```

**적용 예시**:
```typescript
// ❌ NEVER
const secret = process.env.JWT_SECRET;

// ✅ 대신
const secret = process.env.JWT_SECRET;
if (!secret) throw new Error('JWT_SECRET is required');
```
```

### 4.2 ALWAYS 규칙

```markdown
### ✅ ALWAYS 규칙

```
ALWAYS 새 환경변수 추가 시:
1. .env.example에 문서화
2. 코드에서 존재 검증
3. README에 설명 추가
```

**적용 예시**:
```typescript
// src/core/config/validateEnv.ts
const requiredEnvVars = ['JWT_SECRET', 'DATABASE_URL'];

export function validateEnv() {
  for (const key of requiredEnvVars) {
    if (!process.env[key]) {
      throw new Error(`Missing required env: ${key}`);
    }
  }
}
```
```

---

## Phase 5: ERROR_LOG 기록

### 5.1 기록 내용 프리뷰

```markdown
## 📝 ERROR_LOG 기록 프리뷰

CLAUDE.md에 다음 내용이 추가됩니다:

---

### [2026-01-09] JWT 토큰 검증 실패 - 환경변수 누락

- **상황**: pnpm test 중 login.test.ts 실패 (401 반환)
- **원인**: JWT_SECRET 환경변수가 테스트 환경에 미설정
- **해결**: 
  1. .env.example에 JWT_SECRET 추가
  2. .env.test 생성 및 값 설정
  3. 앱 시작 시 필수 환경변수 검증 로직 추가
- **예방**: 
  - NEVER process.env.X without 존재 검증
  - ALWAYS 환경변수 추가 시 .env.example 동시 업데이트
- **증거**: test_output_20260109.txt

---

추가하시겠습니까?

> **(y)** 추가
> **(e)** 수정 후 추가
> **(n)** 취소

선택: ___
```

### 5.2 CLAUDE.md 업데이트

```bash
# ERROR_LOG 섹션에 추가
# CLAUDE.md 끝부분의 ERROR_LOG 섹션에 append
```

---

## 완료 메시지

```markdown
## ✅ 에러 학습 완료

### 요약
| 항목 | 값 |
|------|-----|
| 에러 | JWT 토큰 검증 실패 |
| 근본 원인 | 환경변수 존재 검증 없음 |
| 추가된 규칙 | NEVER 1개, ALWAYS 1개 |

### ERROR_LOG 업데이트
- 위치: CLAUDE.md > ERROR_LOG 섹션
- 제목: [2026-01-09] JWT 토큰 검증 실패

### Compounding Engineering
```
에러 발생 → 분석 → 규칙화 → 영구 학습
```

**이 에러는 다시 발생하지 않습니다.**

### 다음 단계
1. 수정 적용
2. `/gate` 재실행
```

---

## 주간 에러 리뷰

### /error-log --weekly

```markdown
## 📊 주간 에러 리뷰 (2026-01-03 ~ 2026-01-09)

### 통계
| 항목 | 값 |
|------|-----|
| 총 에러 | 5건 |
| Gate 실패 | 3건 |
| 런타임 에러 | 1건 |
| SSOT 위반 | 1건 |

### 가장 빈번한 패턴
1. **환경변수 관련** (3회)
2. **타입 불일치** (2회)

### 추가된 규칙
- NEVER process.env without 검증
- ALWAYS 타입 가드 추가
- NEVER 매직 넘버 하드코딩

### 개선 제안
1. 앱 시작 시 환경변수 일괄 검증 모듈 추가
2. CI에서 타입 체크 강제

### 효과
- 이전 주 대비 에러 20% 감소 (추정)
```

---

## 중복 에러 감지

동일/유사 에러 재발생 시:

```markdown
## ⚠️ 중복 에러 감지!

**현재 에러**: 환경변수 DATABASE_URL 미설정
**기존 기록**: [2026-01-05] JWT_SECRET 미설정

### 기존 규칙 확인
```
ALWAYS 환경변수 추가 시 .env.example 동시 업데이트
```

### 문제점
규칙이 무시되었거나 불충분함

### 규칙 강화 제안
```
ALWAYS 환경변수 추가 시:
1. .env.example 업데이트 (기존)
2. validateEnv()에 추가 (신규)
3. README에 문서화 (신규)
```

강화된 규칙 적용하시겠습니까?
> **(y)** 적용
> **(n)** 유지
```
