비용 최적화

Claude Code는 강력하지만 무분별하게 사용하면 비용이 빠르게 증가합니다. 토큰 효율을 이해하고 올바른 습관을 갖추면 비용을 대폭 줄이면서도 생산성을 유지할 수 있습니다.

비용 구조 이해

구독 vs API

방식	비용 모델	사용량 확인
Max/Pro 구독	월 정액제, 사용량 포함	`/stats`
API 키	토큰 사용량 기반 과금	`/cost`
Bedrock/Vertex	클라우드 제공자 과금	클라우드 콘솔

/cost vs /stats 및 프롬프트 캐시 진단

/cost는 API 토큰 사용량과 비용을 보여줍니다. Max/Pro 구독자는 사용량이 구독에 포함되어 있으므로 /stats로 사용 패턴을 확인하세요.

프롬프트 캐시 상세 추적 (v2.1.251+): /cost 출력에 세션별 프롬프트 캐시 히트율(hit ratio), 미스 횟수, 재캐싱 토큰 수, warm/cold 상태가 표시됩니다 (상태줄 스크립트용 prompt_cache 객체 제공).
캐시 미스 원인 추적 (v2.1.260+): 프롬프트 캐시 미스가 발생했을 때 /cost와 상태줄에 그 추정 원인(도구 정의 변경, 시스템 프롬프트 수정, TTL 만료 유휴 등)을 직접 진단해 줍니다.
지출 한도 게이지 (v2.1.251+): Claude apps gateway를 사용하는 조직 환경의 경우 /usage에 지출 한도(Spend limit) 프로그레스 바가 표시되며 상태줄의 rate_limits.spend_limit 필드로 연동됩니다.

평균 비용 참고치

일반적인 개발자: 활동일 기준 하루 약 $13, 90%의 사용자가 활동일당 $30 미만
월 기준: 개발자당 $150~250 (동시 인스턴스와 자동화 수준에 따라 편차 큼)

공식 문서(code.claude.com/docs/en/costs)의 기업 환경 기준 수치입니다. 구독으로 사용 중이라면 이 금액은 청구와 무관합니다.

토큰 감각 익히기

영문 단어 1개 ≈ 1.3 토큰
한국어 1글자 ≈ 1.5~2 토큰
코드 100줄 ≈ 1,000~2,000 토큰
일반적인 파일 1개 ≈ 500~5,000 토큰

비용 증가의 주요 원인

1. 불필요하게 긴 대화 세션

대화가 길어질수록 이전 메시지 전체가 매번 입력으로 포함됩니다.

# 작업이 바뀌면 /clear로 컨텍스트 초기화
> /clear

# 이름 지정 후 초기화하면 나중에 /resume으로 복귀 가능
> /rename 인증모듈
> /clear

2. 광범위한 요청

# 비효율: 전체 탐색
> 프로젝트 구조 분석해서 문제점 찾아줘

# 효율: 범위 지정
> src/api/ 디렉토리의 에러 핸들링 패턴만 분석해줘

3. 반복적인 컨텍스트 제공

매번 같은 배경 설명을 반복하는 대신 CLAUDE.md에 한 번 정의하세요.

4. 저품질 프롬프트로 인한 재시도

모호한 요청 → 잘못된 결과 → 수정 요청 → 반복. 처음부터 명확하게 요청하세요.

토큰 절감 전략

전략 1: 컨텍스트 관리

# /clear로 작업 간 컨텍스트 분리
[기능 A 작업 완료]
> /clear

# /compact로 컨텍스트 압축 (커스텀 지시 가능)
> /compact 코드 샘플과 API 사용법에 집중해서 요약해줘

CLAUDE.md에서 압축 기본 지시를 설정할 수도 있습니다:

# Compact instructions

compact 시 테스트 출력과 코드 변경사항에 집중해서 요약해줘

전략 2: 모델 선택 최적화

# 간단한 작업에 Haiku 사용
claude --model claude-haiku-4-5-20251001 "이 JSON을 TypeScript 인터페이스로 변환해줘"

# 세션 중 모델 전환
> /model

Sonnet: 대부분의 코딩 작업에 적합하고 Opus보다 저렴
Opus: 복잡한 아키텍처 결정이나 멀티스텝 추론에 사용
Haiku: 간단한 변환, 분류, 형식 작업에 최적

서브에이전트 설정에서 model: haiku를 지정하면 간단한 태스크의 비용을 줄일 수 있습니다.

전략 3: Extended Thinking 조절

Extended Thinking은 기본 활성화(31,999 토큰 예산)이며, thinking 토큰은 출력 토큰으로 과금됩니다:

/model이나 /effort에서 Opus의 effort 레벨 조절
/config에서 thinking 비활성화
환경변수로 예산 제한: MAX_THINKING_TOKENS=8000

단 Fable 5.1(claude-fable-5-1)은 예외입니다 (v2.1.257+) — thinking을 끌 수 없고(/config 토글·MAX_THINKING_TOKENS=0 무효), 고정 예산 없이 항상 adaptive로 동작합니다. Fable 5.1에서는 effort 레벨로 사고 깊이를 조절하세요 (v2.1.257부터 /effort에서 s를 누르면 이번 세션에만 임시 적용 가능). 단가는 1M 컨텍스트 기준 $10/$50(캐시 읽기 $0.25/Mtok)으로 Opus 5 표준가의 2배이므로 비용 민감 작업에는 권장하지 않습니다.

전략 4: MCP 서버 오버헤드 줄이기

각 MCP 서버는 도구 정의를 컨텍스트에 추가합니다:

CLI 도구 선호: gh, aws, gcloud, sentry-cli 등이 더 컨텍스트 효율적
미사용 서버 비활성화: /mcp에서 확인 후 불필요한 서버 비활성화
Tool Search: MCP 도구 설명이 컨텍스트의 10%를 초과하면 자동으로 지연 로드. ENABLE_TOOL_SEARCH=auto:<N>으로 임계값 설정

전략 5: 서브에이전트로 verbose 출력 격리

테스트 실행, 문서 가져오기, 로그 처리 등 출력이 많은 작업은 서브에이전트에 위임하세요. 상세 출력은 서브에이전트 컨텍스트에 남고, 요약만 메인 대화에 반환됩니다.

전략 6: Hook과 Skill 활용

Hook: Claude가 보기 전에 데이터를 전처리 (예: 10,000줄 로그에서 에러만 추출)
Skill: 파일 탐색 없이 도메인 지식 제공

// settings.json — 테스트 출력 필터링 Hook
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

전략 7: CLAUDE.md를 Skill로 분리

CLAUDE.md는 ~500줄 이내로 유지
전문 지침(PR 리뷰, DB 마이그레이션 등)은 Skill로 분리
Skill은 호출 시에만 로드되므로 기본 컨텍스트가 작아짐

전략 8: /claude-api cost-optimize 스킬 활용 (v2.1.247+)

기존 프로젝트의 API 지출 패턴을 체계적으로 프로파일링하고 개선할 수 있습니다:

> /claude-api cost-optimize

현재 프로젝트 코드의 Claude API 호출 지점과 토큰 소비 레버(캐싱 적용 여부, 토큰 위생, 배치 API 활용, effort 수준, 모델 적합성)를 한 단계씩 측정하며 최적화 가이드를 제공합니다.

팀 비용 관리

Workspace 지출 한도

API 사용 시 Console에서 Claude Code Workspace의 전체 지출 한도를 설정할 수 있습니다. 처음 인증하면 "Claude Code" 워크스페이스가 자동 생성되어 중앙 집중식 비용 추적이 가능합니다.

팀 규모별 Rate Limit 권장

팀 규모	TPM / 사용자	RPM / 사용자
1~5명	200k~300k	5~7
5~20명	100k~150k	2.5~3.5
20~50명	50k~75k	1.25~1.75
50~100명	25k~35k	0.62~0.87
100~500명	15k~20k	0.37~0.47
500+명	10k~15k	0.25~0.35

팀 규모가 커질수록 동시 사용자 비율이 낮아져 사용자당 TPM이 줄어듭니다. Rate limit은 조직 레벨에서 적용됩니다.

Agent Teams 토큰 비용

Agent Teams는 여러 Claude Code 인스턴스를 동시에 실행하며, 각각 자체 컨텍스트 윈도우를 유지합니다:

Plan 모드 기준 일반 세션 대비 약 7배 토큰 사용
비용 관리 팁:
- 팀원에게 Sonnet 사용 (능력과 비용의 균형)
- 팀 규모를 작게 유지
- 스폰 프롬프트를 구체적으로
- 작업 완료 후 팀 정리

백그라운드 토큰 사용

Claude Code는 유휴 시에도 소량의 토큰을 사용합니다:

이전 대화 요약 (claude --resume 용)
/cost 같은 커맨드 처리

일반적으로 세션당 $0.04 미만입니다.

비용 vs 생산성

비용보다 중요한 것

비용 절감에 집착해 생산성을 희생하지 마세요. Claude Code에 1,000원을 쓰더라도 그 작업에 10분이 절약된다면 충분히 가치 있습니다.

Claude를 아낌없이 써야 할 작업:

며칠 걸릴 복잡한 리팩토링
익숙하지 않은 기술 스택
버그 원인 파악에 막혔을 때
반복적이고 지루한 대량 작업

비용을 아껴야 할 작업:

이미 방법을 아는 쉬운 작업
단순 검색으로 해결 가능한 정보 조회
직접 짜는 것이 더 빠른 10줄 이내 코드

효율적인 작업 습관

Plan 모드 활용: Shift+Tab으로 복잡한 작업 전에 계획을 세우고 탐색한 뒤 구현
빠른 방향 전환: Esc로 잘못된 방향 중단, /rewind나 Esc+Esc로 되돌리기
검증 기준 제공: 테스트 케이스, 스크린샷, 기대 출력을 미리 제시
점진적 테스트: 파일 하나 작성 → 테스트 → 다음 진행

체크리스트

CLAUDE.md에 프로젝트 컨텍스트 충분히 기술 (~500줄 이내)
작업 전환 시 /clear 실행 습관화
단순 작업에 Haiku 모델 활용
광범위한 요청 대신 구체적인 범위 지정
미사용 MCP 서버 비활성화
전문 지침은 Skill로 분리
팀 Rate Limit 설정 확인

이 챕터를 완료하셨나요?

학습 진도를 체크하여 나의 로드맵 달성률을 높여보세요.

비용 구조 이해​

구독 vs API​

평균 비용 참고치​

토큰 감각 익히기​

비용 증가의 주요 원인​

1. 불필요하게 긴 대화 세션​

2. 광범위한 요청​

3. 반복적인 컨텍스트 제공​

4. 저품질 프롬프트로 인한 재시도​

토큰 절감 전략​

전략 1: 컨텍스트 관리​

전략 2: 모델 선택 최적화​

전략 3: Extended Thinking 조절​

전략 4: MCP 서버 오버헤드 줄이기​

전략 5: 서브에이전트로 verbose 출력 격리​

전략 6: Hook과 Skill 활용​

전략 7: CLAUDE.md를 Skill로 분리​

전략 8: /claude-api cost-optimize 스킬 활용 (v2.1.247+)​

팀 비용 관리​

Workspace 지출 한도​

팀 규모별 Rate Limit 권장​

Agent Teams 토큰 비용​

백그라운드 토큰 사용​

비용 vs 생산성​

효율적인 작업 습관​

체크리스트​