Claude Code 토큰 비용 최적화하기 – 1부: 비용 구조와 세션 습관

Claude Code를 팀에 도입하고 나면 비슷한 질문들이 찾아옵니다. 짧은 한 문장의 질문만 했는데 토큰 사용량이 왜 이렇게 높은지, 하루가 끝날 때쯤이면 세션이 왜 이렇게 무거워져 있는지 같은 의문입니다.

Claude Code는 메시지를 보낼 때마다 시스템 프롬프트, 프로젝트 컨텍스트, 지금까지의 전체 대화 이력을 다시 전송하고, 비용은 그 컨텍스트 크기에 비례합니다. 그리고 실제로 지불하는 토큰 단가는 프롬프트 캐싱(prompt caching) 적중률이 정합니다. 이 글은 Claude Code 토큰 비용 최적화를 다루는 2부작 시리즈의 1부로, 비용 구조와 측정 도구, 그리고 개인이 바로 적용할 수 있는 세션 습관을 다룹니다. 캐시 경제학과 Amazon Bedrock을 포함한 조직 단위 비용 관리는 2부에서 이어집니다. 대상 독자는 Claude Code를 실무에서 사용해 본 분들이며, 토큰과 기본 슬래시 명령 사용 경험은 전제하되 프롬프트 캐싱 같은 핵심 개념은 본문에서 정의합니다. 본문의 수치와 기본값은 Claude Code 공식 문서와 Amazon Bedrock 사용자 가이드의 2026년 8월 기준입니다.

1. 비용 구조: 토큰은 어디서 쓰이는가

모델은 요청 사이에 아무것도 기억하지 않습니다. 그래서 Claude Code는 메시지를 보낼 때마다 시스템 프롬프트, 프로젝트 컨텍스트, 지금까지의 모든 대화와 도구 결과 전체를 다시 전송합니다. 한 번의 턴(Turn) 안에서 Claude가 도구를 여러 번 사용하면 그때마다 또 한 번의 요청이 전송됩니다. 토큰 비용이 질문의 길이가 아니라 세션의 크기에 비례하는 이유입니다.

요청은 세 계층으로 이뤄지며, 잘 변하지 않는 내용일수록 앞에 옵니다.

표 1. 요청을 구성하는 세 계층

이 반복 전송을 감당할 수 있게 해 주는 장치가 프롬프트 캐싱입니다. 직전 요청과 동일한 프리픽스(prefix)는 재처리하는 대신 캐시에서 읽어오고, 표준 입력 단가의 약 10%로 과금됩니다. 캐시를 새로 쓰는 비용은 표준보다 비싸지만 한 번뿐이고, 이후 턴은 그 프리픽스를 계속 낮은 단가로 재사용합니다. 표의 TTL(Time To Live)은 캐시가 유지되는 시간입니다.

표 2. 처리 경로별 상대 단가. 캐시 쓰기 비용은 이후 턴의 할인을 얻기 위한 1회성 투자입니다

과금 방식은 접속 방법에 따라 달라집니다. 구독 플랜(Pro, Max, Team)은 달러 대신 사용량 한도를 소모하고, 이 한도는 5시간 롤링 윈도우와 주간 윈도우 단위로 관리됩니다. Claude Console의 API 및 Claude Enterprise와 Amazon Bedrock 같은 클라우드 프로바이더는 토큰 단위로 과금됩니다.

원칙은 하나입니다. 비용은 컨텍스트 크기에 비례하고, 실제로 지불하는 토큰 단가는 캐시 적중률이 정합니다. 이 글의 모든 전략은 이 두 가지 변수를 줄이는 방법입니다.

2. 측정: /usage, /context, /insights

최적화는 측정에서 시작합니다. /usage는 인증 방식에 따라 보여주는 내용이 다릅니다. API 과금 사용자(Claude Enterprise)에게는 현재 세션의 토큰 통계와 추정 비용을 담은 Session 블록을, 구독자에게는 플랜 사용량 바와 최근 사용량의 어트리뷰션(소모 주체별 내역)을 보여줍니다. Skills, 서브에이전트, 플러그인, 개별 MCP 서버가 각각 전체의 몇 %를 차지하는지 확인할 수 있고, 긴 컨텍스트나 캐시 미스처럼 최근 사용량의 10% 이상을 차지하는 행동 플래그도 여기에 함께 표시됩니다.

대표적인 출력 형태는 다음과 같습니다. 표기는 버전에 따라 조금씩 다르지만 담기는 정보는 같습니다.

> /usage

# API 과금 사용자에게 표시되는 Session 블록
Session
  Input      1,242,310 tokens (cache read 1,180,450 | cache write 38,220 | uncached 23,640)
  Output     18,940 tokens
  Est. cost  $4.87

# 구독 사용자에게 표시되는 플랜 사용량과 어트리뷰션
Plan usage
  Session (5h)    ████████░░░░░░░░░░░░  41%   resets 18:00
  Week (all)      ███░░░░░░░░░░░░░░░░░  16%   resets Mon 09:00
  Week (Opus)     █░░░░░░░░░░░░░░░░░░░   4%

Recent usage attribution
  Subagents 28% | MCP: playwright 17% | Skills: pdf 6%

Behavior flags
  Long context sessions 14% | Cache misses after breaks 12%

참고: /usage의 달러 표시는 추정치입니다. Claude Code는 이 금액을 표준 정가 기준으로 로컬에서 계산합니다. 프로모션이나 계약 할인 단가가 반영되지 않으므로 실제 청구액과 다를 수 있습니다. 청구 기준 수치는 Claude Console의 Usage 페이지에서 확인합니다.

/context는 지금 컨텍스트를 무엇이 차지하는지 보여줍니다. MCP 도구 정의, CLAUDE.md, 대화 이력의 비중을 확인해서 어디를 줄일지 정합니다. 상태 표시줄(statusline)을 설정하면 컨텍스트 사용률과 함께 응답마다 돌아오는 cache_creation_input_tokens와 cache_read_input_tokens를 상시 표시할 수 있습니다.

> /context

claude-sonnet-5 | 96.0K / 1.0M tokens (10%)

  System prompt      3.2K  ( 0.3%)
  System tools      12.8K  ( 1.3%)
  MCP tools         28.4K  ( 2.8%)   playwright, github 도구 정의
  Memory files       4.1K  ( 0.4%)   CLAUDE.md, 자동 메모리
  Messages          47.5K  ( 4.8%)   대화 이력과 도구 결과
  Free space       904.0K  (90.4%)

이 예시에서는 선로딩된 MCP 도구 정의가 대화 이력의 절반을 넘는 크기입니다. 이런 비중이 보이면 도구 오버헤드가 점검 대상입니다.

두 가지 캐시 지표를 읽는 법은 단순합니다. 읽기(read)가 쓰기(creation)보다 압도적으로 크면 캐시가 잘 동작하는 상태입니다. 반대로 creation이 턴마다 높게 유지되면 프리픽스가 계속 바뀌고 있다는 신호이므로, 모델 전환이나 도구 구성 변경처럼 캐시를 무효화하는 행동이 없었는지 점검합니다. 무효화 행동의 전체 목록은 2부에서 다룹니다.

/insights는 토큰 수가 아니라 일하는 방식을 분석합니다. 같은 머신의 최근 세션을 최대 200개까지 살펴, 어떤 작업을 자주 반복하는지, 어느 지점에서 요청 의도가 잘못 전달됐는지 같은 작업 흐름의 마찰 지점을 HTML 리포트(~/.claude/usage-data/report.html)로 정리해 줍니다. 분석 자체도 플랜이나 API 사용량을 소모하므로 주기적으로 한 번씩 돌리는 정도가 적당합니다.

3. 컨텍스트 정리: /clear, /compact, /rewind

가성비가 높은 최적화 방법은 컨텍스트를 처음부터 만들지 않는 것입니다. 무관한 작업으로 넘어갈 때는 /clear로 새로 시작합니다. 추가 비용이 없고, 이전 이력이 다음 요청에 포함되지 않습니다. 세션을 나중에 찾아야 하면 /rename으로 이름을 붙인 뒤 비우고, 필요할 때 /resume으로 돌아옵니다.

같은 작업을 이어가면서 컨텍스트만 줄여야 하면 /compact가 이력을 요약으로 교체합니다. /compact Focus on code samples and API usage처럼 보존할 내용을 지시할 수 있고, 매번 같은 지시를 쓴다면 CLAUDE.md에 상시 규칙으로 둡니다.

# Compact instructions

When you are using compact, please focus on test output and code changes

컴팩션(compaction) 자체의 비용도 계산에 넣어야 합니다. 요약을 만드는 요청은 전체 대화를 프롬프트로 보내는 큰 요청입니다. 캐시가 유지되는 동안은 대부분 캐시 읽기로 처리되어 저렴하지만, 캐시 수명이 지난 뒤(예를 들어 오래된 세션을 resume한 직후) 실행하면 전체를 재처리하는 가장 비싼 컴팩션이 됩니다. auto-compact가 작업 한가운데서 끼어들기 전에, 일이 일단락된 지점에서 직접 실행해야 시점을 통제할 수 있습니다.

방향이 틀렸을 때는 컴팩션이 아니라 /rewind입니다. 대화를 이전 턴으로 되돌리면 그 지점까지의 프리픽스는 이미 캐시에 있으므로 다음 요청이 그대로 캐시에 적중합니다. 새 요약을 만들어 캐시를 다시 쌓는 컴팩션보다 되돌리기가 훨씬 저렴합니다.

세 가지 명령의 선택 기준은 다음과 같습니다.

표 3. 컨텍스트 전환 명령의 선택 기준. 셋 중 기존 캐시를 그대로 적중하는 것은 /rewind뿐입니다

auto-compact 윈도우는 기본값이 모델에 맞춰 자동으로 정해집니다. /autocompact 명령으로 윈도우 값을 설정하고(/autocompact auto는 모델 기본값 복귀), CLAUDE_CODE_AUTO_COMPACT_WINDOW 환경 변수로도 조정할 수 있습니다. 다만 윈도우를 낮추면 컴팩션이 잦아져서 요약 요청 비용이 누적되므로, 특별한 이유가 없으면 자동값을 둡니다. Sonnet 5는 기본값으로 약 967,000토큰에서 자동 컴팩션됩니다(다른 모델은 별도 문서화된 임계값이 없습니다).

CLAUDE.md는 세션 시작마다 로드되어 프로젝트 컨텍스트 계층에 상주합니다. 모든 턴이 이 비용을 지불하므로 200줄 이하로 유지하고, 특정 워크플로우에만 필요한 상세 지시는 호출 시에만 로드되는 Skills로 옮깁니다.

주의: 프로젝트 루트와 사용자 레벨 CLAUDE.md는 세션 시작 시 한 번 읽혀 메모리에 유지됩니다. 세션 중에 파일을 고쳐도 캐시는 깨지지 않지만 변경도 반영되지 않습니다. 새 내용은 다음 /clear, /compact, 재시작 때 로드됩니다. 지시가 안 먹힌다고 같은 세션에서 파일을 반복 수정하며 재시도하는 것은 토큰만 낭비합니다.

4. 모델 선택과 사고 깊이

모델 선택이 단가의 첫 결정입니다. 대부분의 코딩 작업은 Sonnet으로 충분하고, Opus는 복잡한 아키텍처 결정이나 다단계 추론에 아껴 씁니다. /model로 전환하고 /config에서 기본값을 정합니다. 조회나 포매팅처럼 단순한 서브에이전트 작업은 서브에이전트 설정에 model: haiku를 지정해 더 낮은 단가로 돌립니다.

effort는 같은 모델 안에서 사고 깊이를 조절합니다. 확장 사고(extended thinking)의 토큰은 출력 토큰으로 과금되고, 기본값으로는 모델에 따라 요청당 수만 토큰까지 사용합니다. 깊은 추론이 필요 없는 작업에서는 /effort 명령이나 /model 화면의 슬라이더로 수준을 낮추고, 고정해 두려면 effortLevel 설정이나 CLAUDE_CODE_EFFORT_LEVEL 환경 변수를 사용합니다. 값은 low, medium, high, xhigh 중에서 선택합니다(환경 변수는 auto도 허용).

{
  "effortLevel": "medium"
}

위 설정은 .claude/settings.json(프로젝트) 또는 ~/.claude/settings.json(사용자)에 둡니다. 셸 환경 변수로도 같은 효과를 냅니다.

export CLAUDE_CODE_EFFORT_LEVEL=medium

thinking 토큰에 고정 상한을 받는 모델은 MAX_THINKING_TOKENS로 제한합니다(예: MAX_THINKING_TOKENS=8000). adaptive reasoning 모델은 0이 아닌 상한 값을 무시하므로 effort로만 조절합니다. Claude Fable 5는 확장 사고를 끌 수 없어서 역시 effort 조절이 유일한 수단입니다.

캐시와의 관계를 알면 바꾸는 시점이 보입니다. 모델과 effort는 각각 별도의 캐시 키라서, 세션 중간에 바꾸면 다음 요청이 전체 이력을 캐시 미적중으로 재처리합니다. opusplan 설정은 plan mode 진입과 이탈마다 Opus와 Sonnet 사이를 오가므로 토글할 때마다 새 캐시를 쌓습니다. 모델과 effort는 세션 초반에 정하고 작업 중에는 유지하는 것이 캐시 관점의 정답입니다.

5. 도구 오버헤드: MCP와 CLI

MCP 서버의 도구 정의는 지원 모델(Claude 4.5 세대 이상)에서 기본적으로 지연(deferred) 로딩됩니다. tool search가 동작하면 도구 이름과 서버 지시만 컨텍스트에 올라가고, 실제 정의는 Claude가 그 도구를 쓰는 시점에 붙습니다. 그래도 서버가 많으면 부담이 쌓이므로 /context로 실제 점유를 확인하고 /mcp에서 쓰지 않는 서버를 비활성화합니다.

지연 로딩이 안 되는 경우가 문제입니다. custom ANTHROPIC_BASE_URL 게이트웨이, 그리고 Claude 4.5 세대보다 앞선 모델을 사용하는 환경에서는 tool search가 동작하지 않아 도구 정의 전체가 프리픽스에 로딩됩니다. 게이트웨이는 ENABLE_TOOL_SEARCH=true로 재정의할 수 있지만, 클라우드 프로바이더의 일부 플랫폼은 재정의되지 않습니다. Amazon Bedrock을 포함해 4.5 세대 이상 모델을 사용하는 환경에서는 Anthropic API와 동일하게 기본 동작합니다. alwaysLoad로 지정한 서버나 도구, threshold 기반 선로딩도 같은 결과를 만듭니다. 이때는 서버 하나가 연결되거나 끊기는 것만으로 캐시 전체가 무효화됩니다.

같은 일을 하는 CLI가 있으면 CLI를 우선합니다. aws, gh, gcloud, sentry-cli 같은 도구는 도구 목록 비용 자체가 없고, Claude가 명령을 직접 실행하면 됩니다.

타입 언어를 쓴다면 코드 인텔리전스 플러그인이 탐색 비용을 줄입니다. LSP의 go to definition 한 번이 grep 한 번과 후보 파일 여러 개 읽기를 대체하고, 편집 직후 타입 에러를 자동 보고해 컴파일을 돌리지 않고도 실수를 잡습니다.

6. 구조적 절약: 서브에이전트, Hook, Skills

장황한 출력은 서브에이전트로 격리합니다. 테스트 실행, 로그 처리, 문서 fetch를 위임하면 장황한 출력은 서브에이전트의 컨텍스트에 남고 요약만 본 대화로 돌아옵니다. 부모의 캐시도 손상되지 않습니다. 다만 서브에이전트는 자체 시스템 프롬프트와 자체 캐시로 시작하고, 구독에서도 5분 TTL을 씁니다.

Hook은 Claude가 보기 전에 데이터를 전처리합니다. 10,000줄 로그를 통째로 읽히는 대신 Hook이 ERROR 줄만 추려서 넘기면 수만 토큰이 수백 토큰이 됩니다. 다음은 테스트 출력에서 실패만 남기는 PreToolUse Hook 예시입니다.

#!/bin/bash
# ~/.claude/hooks/filter-test-output.sh
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# 테스트 명령이면 실패 부분만 남기도록 명령을 재작성한다
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"updatedInput\":{\"command\":\"$filtered\"}}}"
else
  echo "{}"
fi

이 스크립트를 settings.json의 hooks.PreToolUse에 Bash matcher로 연결하면 매 실행 전에 적용됩니다. 전체 설정 예시는 공식 비용 문서에 그대로 있습니다.

CLAUDE.md에 쌓인 워크플로우 지시는 Skills로 옮깁니다. Skills은 호출될 때만 로드되므로 기본 컨텍스트가 가벼워집니다. 프로젝트 아키텍처, 핵심 디렉토리, 네이밍 규칙을 담은 codebase-overview Skills을 만들어 두면, Claude가 구조를 파악하려고 파일 여러 개를 읽는 대신 Skills 호출 한 번으로 같은 맥락을 얻습니다.

에이전트 팀은 실험 기능이며 비용 배수가 큽니다. 팀원마다 별도 인스턴스와 컨텍스트 윈도우를 유지해서, plan mode 기준 일반 세션의 약 7배 토큰을 사용합니다. 사용한다면 팀을 작게, 팀원 모델은 Sonnet으로, 일이 끝난 팀원은 바로 종료합니다.

작업 습관도 토큰입니다. “이 코드베이스 개선해줘”처럼 모호한 요청은 광범위한 스캔을 유발하고, “auth.ts의 login 함수에 입력 검증 추가”는 최소한의 파일만 읽게 합니다. 복잡한 작업은 plan mode(Shift+Tab)로 방향을 합의한 뒤 실행하고, 잘못 가면 Escape로 즉시 멈춰 /rewind 합니다. 테스트 케이스나 기대 출력 같은 검증 목표를 주면 재작업 요청 자체가 줄어듭니다.

7. 마치며

짧은 한 문장의 질문에도 토큰 사용량이 높은 것은 하루 종일 열려 있던 세션이 전체 이력을 매번 재전송하기 때문입니다. 작업을 바꿀 때마다 /clear 하는 습관이 답이고, 여기에 CLAUDE.md를 200줄 이하로 유지하고, 모델과 effort를 작업에 맞추고, 도구 오버헤드를 /context로 점검하는 습관이 더해지면 개인이 통제할 수 있는 낭비 경로는 대부분 닫힙니다.

다만 습관만으로는 설명되지 않는 비용이 남습니다. 자리를 비운 뒤 첫 응답이 유난히 느리고 비싼 이유, 그리고 Amazon Bedrock으로 사용하는 조직에서 사용자별 지출을 확인하는 방법은 캐시의 수명과 조직 단위 관리 체계의 문제입니다. 2부에서는 캐시 경제학(TTL, 무효화 행동, 캐시 범위)과 구독, Claude Console, Amazon Bedrock의 조직 비용 관리, 그리고 전체 적용 우선순위를 다룹니다.

참고 자료

• Manage costs effectively – Anthropic, Claude Code Docs (2026-08-25 확인)
• Model configuration – Anthropic, Claude Code Docs
• Prompt caching – Anthropic, Claude Platform Docs (TTL별 캐시 쓰기/읽기 단가표 포함)
• Lessons from building Claude Code: Prompt caching is everything – Anthropic (plan mode, 지연 도구 로딩, 컴팩션의 설계 배경)

본문의 수치, 기본값, 명령과 환경 변수는 작성 시점의 Claude Code v2.1.x 기준이며, 최신 값은 위 공식 문서에서 확인하시길 바랍니다.