Claude Code 가이드 #20 — 런타임 에러 & 성능 트러블슈팅

빠른 상태 점검 명령어
# Claude Code 버전 및 상태 확인
claude --version
claude /doctor

# 현재 컨텍스트 토큰 사용량 확인 (세션 내)
claude /status

# MCP 서버 연결 상태 확인
claude mcp list

# 시스템 자원 확인
top -l 1 | grep -E "CPU|PhysMem"   # macOS
free -h && top -bn1 | head -5       # Linux

컨텍스트 초과 시 즉시 조치
# 방법 1: 새 세션 시작 (가장 확실)
# 현재 세션 종료 후 재시작
exit
claude

# 방법 2: /clear 로 컨텍스트 리셋 (같은 세션 유지)
claude /clear

# 방법 3: --continue 플래그로 이전 세션 요약 이어가기
claude --continue

# 방법 4: 컴팩트 모드 요청 (Claude에게 직접)
# "지금까지 내용을 3줄로 요약하고 핵심 상태만 유지해줘"

CLAUDE.md 컨텍스트 최적화 설정 예시
# CLAUDE.md 에 추가
## 컨텍스트 관리 원칙
- 파일 전체를 읽기 전에 필요한 함수/섹션만 먼저 요청할 것
- 작업 단위를 완료할 때마다 진행 상태를 1~2줄로 요약할 것
- 500줄 이상 파일은 Read tool 의 offset/limit 파라미터 사용
- auto-compact: true

타임아웃 진단 및 해결
# API 서버 응답 시간 확인
curl -w "\nTime: %{time_total}s\n" -o /dev/null -s https://api.anthropic.com

# Anthropic 서비스 상태 확인
# https://status.anthropic.com

# 타임아웃 설정 연장 (환경변수)
export CLAUDE_TIMEOUT=120000   # 기본값보다 길게 (ms 단위)

# 프록시 환경에서 keep-alive 설정
export HTTPS_PROXY=http://your-proxy:port
export NO_PROXY=localhost,127.0.0.1

파일 권한 진단 및 해결
# 파일 권한 확인
ls -la /path/to/file

# 현재 사용자 확인
whoami

# 권한 수정 (자신의 파일인 경우)
chmod 644 /path/to/file
chown $(whoami) /path/to/file

# 디렉토리 전체 권한 수정
chmod -R 755 /path/to/directory
chown -R $(whoami) /path/to/directory

# Claude Code 권한 모드 확인 (settings.json)
cat ~/.claude/settings.json | grep -A5 "permissions"

서브에이전트 디버깅
# 에이전트 실행 시 verbose 모드로 진행 상황 확인
claude --verbose

# 개별 에이전트에 명확한 출력 형식 지정 예시
# (Claude에게 직접 지시)
# "서브에이전트 A: src/utils.js 만 수정, 결과를 /tmp/agent-a-result.txt 에 기록"
# "서브에이전트 B: tests/ 디렉토리만 수정, A 완료 후 실행"

# 실패한 에이전트 작업 재시작
claude /resume   # 이전 세션 재개

MCP 연결 진단 및 재시작
# 현재 연결된 MCP 서버 목록 확인
claude mcp list

# 특정 MCP 서버 상태 확인
claude mcp get <server-name>

# MCP 서버 재시작
claude mcp restart <server-name>

# MCP 설정 파일 위치 확인
ls -la ~/.claude/mcp.json
cat ~/.claude/mcp.json

# MCP 서버 프로세스 직접 확인 (예: filesystem MCP)
ps aux | grep mcp

# 설정 파일 경로 오류 시 재등록
claude mcp add filesystem /path/to/mcp-filesystem-server

Git 에러 진단 및 해결
# 현재 Git 상태 확인
git status
git log --oneline -5

# Merge conflict 해결 흐름
git status                          # conflict 파일 확인
# 파일 열어서 <<<<<<< / ======= / >>>>>>> 마커 해결
git add <resolved-file>
git commit

# Pre-commit hook 실패 시 원인 확인
cat .husky/pre-commit               # Husky 사용 시
npm run lint                        # 직접 lint 실행

# Git user 설정 (커밋 불가 시)
git config user.email "you@example.com"
git config user.name "Your Name"

# Push 거부 시 (non-fast-forward)
git pull --rebase origin main       # rebase로 정리 후 push

메모리/CPU 과부하 진단 및 완화
# 메모리 사용량 확인
free -h                             # Linux
vm_stat | grep Pages                # macOS

# Claude Code 프로세스 자원 확인
ps aux | grep claude | awk '{print $3, $4, $11}'

# Node.js 힙 메모리 한도 조정
export NODE_OPTIONS="--max-old-space-size=4096"  # 4GB 허용
claude

# 대용량 프로젝트에서 .claudeignore 활용
# .claudeignore 파일 생성
cat > .claudeignore << 'EOF'
node_modules/
dist/
build/
*.log
.git/
EOF

rate limit 및 네트워크 에러 대응
# Anthropic 서비스 상태 확인
curl -s https://status.anthropic.com/api/v2/status.json | python3 -m json.tool

# DNS 해석 테스트
nslookup api.anthropic.com
dig api.anthropic.com

# 연결 테스트 (HTTP 헤더만)
curl -I --max-time 10 https://api.anthropic.com

# 현재 사용 중인 rate limit 확인 (Console 사용자)
# https://console.anthropic.com/settings/limits

# 자동 재시도 설정 (환경변수)
export CLAUDE_MAX_RETRIES=3
export CLAUDE_RETRY_DELAY=5000  # ms