# 에러 해결 가이드

Claude Code가 에러를 해결하지 못하고 같은 실수를 반복할 때의 대처법.

---

## 에러 해결 3계명

1. **청소하고 시작**: `/clear`로 컨텍스트 초기화
2. **생각하게 시킴**: `think hard` 키워드로 추론 강화
3. **증거를 요구**: 바로 고치지 말고 실패하는 테스트부터 작성

---

## 문제 유형별 해결

### 1. 컨텍스트 오염 (Context Pollution)

**증상**:
- 이전의 잘못된 시도 반복
- 엉뚱한 파일 수정 시도
- Lost in the Middle - 중간 내용 망각

**해결**:
```
/clear
```

**대안** (핵심 기억 유지):
```
/compact [기억해야 할 내용]
```

---

### 2. 컨텍스트 과부하

**증상**:
- `/context`로 확인 시 60%+ 사용
- 응답 품질 저하
- 지시 무시

**해결**:
1. `/context`로 현재 사용량 확인
2. 60% 이상이면 `/compact` 또는 `/clear`
3. 새 대화에서 필수 컨텍스트만 로드

---

### 3. 얕은 추론 (Shallow Reasoning)

**증상**:
- 단순한 수정만 반복
- 근본 원인 분석 없음
- 표면적 증상만 치료

**해결 - Think 키워드**:

| 키워드 | 토큰 | 용도 |
|--------|------|------|
| think | 기본 | 일반적인 버그 |
| think hard | ~1만 | 여러 파일 연관, 원인 불명 |
| ultrathink | ~3만 | 아키텍처, 구조적 문제 |

```
이 에러가 왜 발생하는지 think hard 해서 분석해줘.
```

---

### 4. 환각 (Hallucination)

**증상**:
- 존재하지 않는 함수/메서드 사용
- 잘못된 API 사용법
- 스펙과 다른 구현

**해결 - TDD 방식**:

1. 버그 재현 테스트 작성 요청
2. 테스트 실패 확인
3. 테스트 통과하도록 수정

테스트 코드가 "정답지" 역할 → 환각 감소

---

### 5. 과잉 수정 (Over-modification)

**증상**:
- 버그 고치려다 다른 기능 파손
- 불필요한 파일까지 수정
- Sonnet 4.5의 무분별한 변경

**해결 - Plan Mode**:

1. `Shift + Tab` 두 번
2. 계획 먼저 세우게 함
3. 계획 검토 후 승인

```
이 에러를 고치기 위한 계획을 먼저 세워줘.
계획을 승인할 때까지 코드 수정하지 마.
```

---

### 6. 코드 엉망 (Complete Mess)

**증상**:
- 복구 불가능 수준
- 에러 증가
- 원인 파악 불가

**해결 - Checkpointing**:

```
Esc + Esc 또는 /rewind
```

코드와 대화 모두 이전 상태로 복구.

**대안 - Git 롤백**:
```bash
git checkout .
```

---

## 필승 디버깅 템플릿

복잡한 에러 발생 시:

```
1. /clear

2. 지금 [파일명]에서 이 에러가 발생해:
[에러 로그]

바로 수정하지 말고:
1. think hard 모드로 원인 분석
2. 에러 재현 테스트 작성
3. 테스트 실패 확인 후 수정
```

---

## Think 키워드 상세

### think (기본)

**용도**: 단순 문법 에러, 명확한 원인 버그

```
이 에러의 원인을 think 해서 찾아줘.
```

### think hard (~1만 토큰)

**용도**: 여러 파일 버그, 비동기/동시성, 데이터 흐름

```
이 문제를 think hard 해서 분석해줘.
관련 파일 검토하고 데이터 흐름 추적해.
```

### ultrathink (~3만 토큰)

**용도**: 아키텍처, 설계 결함, 성능 병목, 보안

```
이 시스템 설계를 ultrathink 해서 검토해줘.
구조적 결함이나 확장성 문제 분석해.
```

---

## 에러 유형별 프롬프트

### TypeError / ReferenceError

```
/clear
이 TypeError 원인을 think 해서 찾아줘:
[에러 로그]

어떤 변수가 undefined인지, 어디서 할당 안 됐는지 추적해.
```

### 비동기 에러 (Promise/async-await)

```
/clear
이 비동기 에러를 think hard 해서 분석해줘:
[에러 로그]

Promise 체인과 async/await 흐름 추적해서
어디서 에러가 발생하고 catch 안 되는지 찾아.
```

### API 응답 에러 (4xx/5xx)

```
/clear
이 API가 [상태코드] 에러 반환해:
[요청/응답]

think hard 해서 분석:
1. 요청 형식 올바른지
2. 인증/권한 문제인지
3. 서버 로직 버그인지
```

### 테스트 실패

```
/clear
이 테스트가 실패해:
[테스트 코드와 실패 메시지]

think hard 해서:
1. 테스트 기대값 올바른지
2. 실제 구현이 스펙과 일치하는지
3. 테스트 환경 설정 문제인지
```

---

## 에러 해결 체크리스트

에러 발생 시 순서대로:

- [ ] `/clear`로 컨텍스트 초기화
- [ ] 에러 로그 전체 제공
- [ ] `think` 또는 `think hard` 사용
- [ ] 바로 수정 말고 분석부터
- [ ] 테스트 코드 작성 먼저
- [ ] Plan Mode로 수정 계획 검토
- [ ] 필요 시 `/rewind` 또는 `git checkout .`

---

## Throw-away First Draft

어려운 새 기능:

1. 새 브랜치 생성
2. Claude가 end-to-end로 작성
3. 출력을 mental model과 비교
4. 오류/편향 파악
5. 더 날카로운 프롬프트로 재실행

Claude의 오류와 편향을 드러내는 hindsight 확보.
