Claude Code 가이드 #9 — 트러블슈팅 & 팁
토큰 최적화, 자주 발생하는 에러, 비용 관리 방법. 실무에서 만나는 문제와 해결법.
Claude Code를 실무에서 쓰다 보면 토큰 초과, 컨텍스트 유실, 비용 관리 등의 문제를 만나게 됩니다. 이 편에서는 자주 발생하는 문제와 해결법, 비용을 줄이는 팁을 정리합니다.
토큰 최적화
Claude Code의 컨텍스트 윈도우는 제한이 있습니다. 대형 프로젝트에서는 토큰을 효율적으로 관리해야 합니다.
- /context 명령어 활용: 현재 컨텍스트 사용량 확인 + 최적화 제안
- project-state.md: 프로젝트 상태를 압축 문서로 관리 (80~95% 토큰 절약)
- 필요한 파일만 언급: "전체 프로젝트를 봐줘" 대신 구체적 파일 지정
자주 발생하는 에러
- API 400 에러: ANTHROPIC_BASE_URL + 프록시 환경에서 발생. tool_reference 블록 비활성화로 해결
- effort 파라미터 미지원: 커스텀 모델 ID 사용 시 발생. 표준 Claude 모델명 사용
- 메모리 누수: 스트리밍 응답 버퍼 미해제. 최신 버전 업데이트로 해결
비용 관리
Claude Code 비용을 관리하는 핵심 전략입니다.
- effort 레벨 조절: 간단한 작업은 low effort로 실행 (비용 절감)
- 모델 선택: 복잡한 작업만 Opus, 일반 작업은 Sonnet 사용
- AGENTS.md 자동 생성 비추천: 오히려 비용이 20% 증가한다는 연구 결과
- 세션 분리: 주제별로 세션을 나누어 컨텍스트 오염 방지
다음 (마지막) 편에서는 최신 업데이트 추적 방법을 다룹니다.
claude-code트러블슈팅토큰비용에러