부록 C. 트러블슈팅

이 부록에서 다루는 것

자주 발생하는 문제
스스로 해결하는 방법
도움 요청하는 방법

문제 해결 기본 원칙

1. 에러 메시지 읽기

에러가 나면 Claude에게 그대로 보여주세요.

> 이런 에러가 났어:
> [에러 메시지 전체 복사]
> 왜 그런지 설명하고 해결해줘.

2. 최근 변경 확인

“아까까지 됐는데…” → 최근에 뭘 바꿨는지 확인

> 방금 전까지 잘 됐는데 갑자기 안 돼.
> 내가 한 것: [최근 변경 사항]

3. 새 세션으로 시작

해결이 안 되면 깨끗한 상태에서 다시:

# 터미널 종료 후 다시 시작
claude

설치/실행 문제

”command not found: claude”

증상: claude 명령어가 인식되지 않음

원인

Claude Code가 설치되지 않음
PATH에 등록되지 않음

해결

# 1. 설치 확인
npm list -g @anthropic-ai/claude-code

# 2. 없으면 재설치
npm install -g @anthropic-ai/claude-code

# 3. PATH 확인 (출력된 경로가 PATH에 있어야 함)
npm bin -g

”Error: Invalid API key”

증상: API 키 오류

원인: API 키가 없거나 잘못됨

해결

# 1. 환경변수 확인
echo $ANTHROPIC_API_KEY

# 2. 값이 없으면 설정
export ANTHROPIC_API_KEY="sk-ant-..."

# 3. 영구 설정 (Mac/Linux)
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

”Permission denied”

증상: 권한 오류

원인: 해당 폴더/파일에 쓰기 권한 없음

해결

# 1. 권한 확인
ls -la [폴더경로]

# 2. 권한 부여 (본인 소유 폴더만)
chmod 755 [폴더경로]

# 3. 다른 폴더에서 작업
cd ~/Documents  # 확실히 권한 있는 폴더로 이동

실행 중 문제

”Context length exceeded”

증상: 대화가 너무 길어져서 오류

원인: 토큰 한도 초과

해결

# 방법 1: 대화 요약
> /compact

# 방법 2: 새 세션 시작
> /clear

# 방법 3: 특정 부분만 이어서
> 이전 대화 내용 중 [주제]에 대해서만 이어서 진행하자.

”Rate limit exceeded”

증상: 요청이 너무 많아서 차단

원인: API 호출 한도 초과

해결

잠시 기다리기 (보통 1분 내)
요청 빈도 줄이기
API 플랜 업그레이드 고려

응답이 중간에 끊김

증상: Claude 응답이 완성되지 않고 멈춤

원인: 네트워크 문제 또는 긴 응답

해결

# 이어서 요청
> 계속해줘

# 또는 더 구체적으로
> 아까 [마지막 내용] 이후부터 계속해줘

파일을 찾을 수 없음

증상: “File not found” 오류

원인: 경로가 잘못됨

해결

# 1. 현재 위치 확인
> 현재 작업 폴더가 어디야?

# 2. 파일 존재 확인
> 이 폴더에 있는 파일 목록 보여줘

# 3. 정확한 경로로 재시도
> [정확한 경로]에 있는 파일 읽어줘

CLAUDE.md 문제

설정이 적용 안 됨

증상: CLAUDE.md 규칙이 무시됨

원인

파일 위치가 잘못됨
문법 오류
너무 긴 내용

해결

# 1. 파일 위치 확인
> CLAUDE.md 파일 찾아서 보여줘

# 2. 문법 확인
> CLAUDE.md 문법에 문제 있는지 검토해줘

# 3. 길이 확인 (500줄 이하 권장)
> CLAUDE.md가 몇 줄이야?

충돌하는 규칙

증상: 예상과 다른 동작

원인: 여러 CLAUDE.md 파일의 규칙 충돌

해결

# 현재 적용된 모든 설정 확인
> 현재 적용된 CLAUDE.md 내용 전체 보여줘
> (전역, 프로젝트 루트, .claude 폴더 포함)

스킬 문제

스킬이 적용 안 됨

증상: 트리거를 말해도 스킬이 작동 안 함

원인

파일 위치/이름 오류
트리거 매칭 실패
SKILL.md 문법 오류

해결

# 1. 스킬 목록 확인
> 현재 사용 가능한 스킬 목록 보여줘

# 2. 특정 스킬 확인
> [스킬이름] 스킬 내용 보여줘

# 3. 직접 호출 테스트
> [스킬이름] 스킬 사용해서 [작업] 해줘

잘못된 스킬 적용

증상: 의도하지 않은 스킬이 적용됨

원인: 트리거 키워드 중복

해결

# 1. 트리거 확인
> 현재 어떤 스킬이 적용됐어?

# 2. 명시적으로 지정
> [원하는 스킬이름] 스킬만 사용해서 해줘

# 3. 스킬 없이 진행
> 스킬 적용하지 말고 기본으로 해줘

MCP 문제

MCP 서버 연결 실패

증상: MCP 기능이 작동 안 함

원인

설정 파일 오류
서버 설치 안 됨
네트워크 문제

해결

# 1. 설정 확인
> MCP 설정 파일 내용 보여줘

# 2. 연결 상태 확인
> 현재 연결된 MCP 서버 목록 보여줘

# 3. 서버 직접 테스트 (터미널에서)
npx -y @anthropics/mcp-server-[서버이름]

API 키 오류 (MCP)

증상: “Invalid API key” (MCP 서버)

원인: .mcp.json의 API 키가 잘못됨

해결

# 1. 설정 파일에서 키 확인
> .mcp.json 파일 보여줘

# 2. 키 재설정
> [서버이름] MCP 서버의 API 키를 [새 키]로 변경해줘

성능 문제

응답이 너무 느림

증상: Claude 응답 속도가 느림

원인

복잡한 요청
네트워크 지연
많은 컨텍스트

해결

# 1. 요청 단순화
> [복잡한 요청] → [간단한 단계별 요청]

# 2. 컨텍스트 정리
> /compact

# 3. 불필요한 MCP 비활성화

비용이 너무 많이 나감

증상: API 비용 증가

원인

긴 대화
큰 파일 반복 읽기
불필요한 요청

해결

# 1. 비용 확인
> /cost

# 2. 대화 요약으로 토큰 절약
> /compact

# 3. 효율적인 요청
- 한 번에 명확하게 요청
- 필요한 부분만 읽기 요청
- 중복 요청 피하기

도움 요청하기

Claude에게 직접

> 이 문제 해결 방법 알려줘:
> [문제 상황 설명]
> [에러 메시지]
> [이미 시도한 것]

공식 리소스

리소스	용도
GitHub Issues	버그 리포트
공식 문서	사용법 확인
Discord	커뮤니티 질문

이슈 리포트 작성법

## 문제 설명

[무엇이 안 되는지]

## 재현 단계

1. [단계 1]
2. [단계 2]
3. [단계 3]

## 예상 동작

[이렇게 되어야 하는데]

## 실제 동작

[이렇게 됨]

## 환경

- OS: [운영체제]
- Node: [버전]
- Claude Code: [버전]

## 에러 메시지

[에러 메시지]

예방 수칙

1. 정기적으로 `/compact`

긴 대화는 토큰 소모와 오류 원인

2. 중요한 결과는 저장

Claude 응답 중 중요한 건 파일로 저장 요청

> 이 결과를 [파일명].md로 저장해줘

3. 단계별로 진행

한 번에 큰 작업 → 작은 단계로 나눠서

4. 버전 관리

CLAUDE.md, 스킬, MCP 설정은 git으로 관리

git add .claude/ CLAUDE.md .mcp.json
git commit -m "Claude Code 설정 업데이트"

응급 조치

모든 것이 안 될 때

# 1. Claude Code 재시작
exit
claude

# 2. 캐시 정리
rm -rf ~/.claude/cache

# 3. 재설치
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

# 4. 환경변수 재설정
export ANTHROPIC_API_KEY="sk-ant-..."

데이터 날리기 전에

# 현재 대화 내용 백업
> 지금까지 대화 내용을 conversation-backup.md로 저장해줘

빠른 참조 카드

문제	빠른 해결
명령어 안 됨	`npm install -g @anthropic-ai/claude-code`
API 키 오류	`export ANTHROPIC_API_KEY="..."`
토큰 초과	`/compact`
응답 끊김	”계속해줘”
스킬 안 됨	”스킬 목록 보여줘”
MCP 안 됨	”MCP 설정 확인해줘”
전부 안 됨	새 터미널에서 `claude`

참고 자료

리소스	설명
Claude Code GitHub Issues	버그 리포트 및 해결책 검색
Claude Code 공식 문서	Anthropic 공식 가이드
Anthropic Discord	커뮤니티 지원
Claude Code Best Practices	Anthropic 권장 사용법
awesome-claude-code	커뮤니티 리소스 모음

← 부록 B. MCP 서버 가이드 부록 D. OpenCode & Oh My OpenCode →