클로드 코드(Claude Code)의 비용은 '컨텍스트 길이 × 요청 수'로 결정된다 - 실측 결과 1회 요청당 31배 차이

안녕하세요! 주식회사 무쿠일의 iguchi입니다.

서론

업무 시스템 개발에 Claude Code를 매일 사용하고 있습니다. 어느 날 사용량 로그를 집계해 보니, **과금 대상 입력 토큰의 약 98%가 cache_read(프롬프트 캐시 읽기)**였습니다.

캐시 읽기는 일반적인 입력보다 단가가 저렴하기 때문에, 막연히 '캐시가 작동해서 비용이 적게 들고 있구나'라고 생각하고 있었습니다. 하지만 실제는 그 반대였습니다. 저렴한 단가의 토큰을 엄청난 양으로 계속 재읽고 있었던 것이 비용의 실체였습니다.

본 글에서는 다음 내용을 소개합니다.

• 왜 cache_read가 비용의 대부분을 차지하는지 - 실측 결과, 동일한 1회 요청에 대해 31배의 차이가 발생했던 점
• 이를 바탕으로 팀에서 결정한 운영 규칙
• 본인의 로그로 같은 집계를 할 수 있는 스크립트

결론

Claude Code의 비용은 거의 '컨텍스트 길이 × 요청 수'로 결정됩니다.

대응책은 두 가지입니다.

• 컨텍스트를 짧게 유지하기: 작업이 끝나면 /clear 명령어를 사용하고, 큰 파일은 서브 에이전트에게 읽히도록 합니다.
• 요청 수를 줄이기: 의존 관계가 없는 툴 호출을 한 번의 메시지에 모아서 처리합니다.

이 두 가지는 곱셈으로 작용하여 효과를 발휘합니다.

왜 cache_read가 비용의 대부분을 차지하는가

Claude Code는 툴을 한 번 호출할 때마다 API로 요청을 보냅니다. 그럴 때마다 지금까지의 대화 전체 (시스템 프롬프트, CLAUDE.md, 읽은 파일, 툴 출력, 주고받은 모든 내용)를 다시 전송합니다.

이전에 다뤘던 부분은 프롬프트 캐시에서 읽어오기 때문에 토큰 단가는 저렴해집니다. 하지만 읽어오는 양 자체는 매번 늘어나고 있습니다.

1회 요청당 입력 ≒ 해당 시점의 컨텍스트 길이
세션 전체 입력 ≒ Σ(각 요청 시점의 컨텍스트 길이)

컨텍스트가 요청마다 거의 일정한 양씩 증가한다면, 세션 전체의 입력량은 요청 수의 제곱에 비례합니다. 세션이 길수록 후반부 요청이 더 고가로 책정됩니다.

실측: 1회 요청당 31배 차이

한 시기에 하나의 세션을 13일 동안 계속 사용하며 5,065개의 요청을 보냈습니다.

| 1회 요청당 캐시 읽기 | 1회 요청당 비용 | |
|---|---|
| 장기 세션 후반부 | 약 84만 토큰 | 약 $0.42 |
| 신규 세션 | 약 2.7만 토큰 | 약 $0.013 |

※ 캐시 읽기 단가를 $0.50 / 100만 토큰으로 계산했습니다. 단가는 모델에 따라 다르므로, 본인의 모델 단가로 대체해 주세요.

동일한 1회 툴 호출에 대해 31배의 비용이 발생하고 있었습니다. 작업 내용 자체는 같더라도, 긴 세션 위에서 계속 진행하는 것만으로도 이런 일이 벌어집니다.

최근 로그를 다시 집계해 보아도 경향은 동일했습니다.

sessions : 62
requests : 6,343
input : 13,457 ( 0.0%)
...

컨텍스트 최대 길이가 50~60만 토큰에 달하는 세션들이 상위에 여러 개 나열되어 있었습니다.

운영 규칙

이 결과를 바탕으로 팀의 CLAUDE.md에 다음 규칙을 작성했습니다.

/clear

1. 작업이 끝나면 1개의 태스크(조사부터 구현, 회고까지)가 끝났다면 /clear를 실행합니다. 이전 태스크의 대화를 다음 태스크의 모든 요청에서 재읽지 않기 위해서입니다.

'아까 이어서 하자'라는 생각에 같은 세션을 쓰고 싶어질 때가 있습니다. 하지만 이어지는 데 필요한 정보는 대부분 몇 줄짜리 메모로 충분합니다.

2. 300K 토큰을 넘으면 새로 시작하기

/compact에는 남기고 싶은 내용을 지정할 수 있습니다.

/compact 판정 결과・변경 대상의 file:행・남은 작업만 남기기

주의할 점이 두 가지 있습니다.

자동 compact를 기다리지 않기: 자동 compact는 상한선 근처까지 발동하지 않습니다. 그전까지는 부풀어 오른 컨텍스트를 계속해서 다시 읽게 됩니다.
compact를 중첩하지 않기: 요약의 요약을 하게 되면 내용이 저하됩니다. 두 번째 요약이 필요하다면, 메모를 남기고 새로운 세션을 시작합니다.

3. 큰 파일은 서브 에이전트에게 읽게 하기

150KB 정도 분량의 절차서(약 5만 토큰)를 메인 스레드에서 열 경우, 이후 모든 요청에 이 5만 토큰이 계속 남아 있게 됩니다. 만약 1,000번의 요청이 더 지속된다면,

5만 토큰 × 1,000 요청 × $0.50 / 100만 토큰 ≒ $25

파일을 단 한 번 읽는 것만으로도 이만큼 비용이 발생합니다.

서브 에이전트에게 읽게 하면, 서브 에이전트 측의 컨텍스트는 종료 시점에 폐기되며, 메인 스레드에는 결론만 반환됩니다. 로딩에 드는 비용은 실질적으로 1회분으로 끝납니다.

조사용 서브 에이전트를 읽기 전용이며 저렴한 모델로 정의해 둡니다.

---
name: code-explorer
description: 코드나 파일을 조사하고 위치를 확인하며, 메인 컨텍스트를 오염시키지 않습니다. 큰 파일의 로딩, 다수 파일 간 교차 탐색, 정의 및 사용처 추적에 사용합니다. 결론과 file: 라인, 최소한의 인용만 반환합니다. 편집은 하지 않습니다.
...

정의만 한다고 사용되지 않는다

여기서 막혔습니다. 서브 에이전트를 정의만 해두었다고 해서 97세션・21,095 요청 동안 한 번도 사용되지 않았습니다.

CLAUDE.md에 다음과 같이 상시 유효 지침으로 추가한 후에야 비로소 사용되기 시작했습니다(이후 27세션에서 11회).

| 거대 파일은 `code-explorer` 서브 에이전트를 통해 읽기 (상시 유효 지침. 그때그때의 요청을 기다리지 않음) | ... |

'사용할 수 있다'고 적는 것을 넘어, '사용한다'라고 단정하는 것이 핵심입니다.

4. 의존성이 없는 도구 호출은 1 메시지에 모으기

비용의 또 다른 요인인 요청 수에 관한 내용입니다.

로그를 보면, 도구 호출의 84.2%가 1 메시지당 단발적인 1건이었습니다(평균 1.17건/메시지). 서로 의존하지 않는 여러 파일의 읽기나 검색을 한 번의 메시지로 병렬로 보내면, 요청 수는 그만큼 줄어듭니다.

만약 평균을 2건/메시지로 만들 수 있다면, 요청 수는 약 41% 감소합니다(1.17 / 2 ≒ 0.59). 컨텍스트 길이 대책과 곱셈으로 효과가 나타나므로, 두 가지 모두 할 가치가 있습니다.

CLAUDE.md에는 다음과 같이 작성되어 있습니다.

의존성이 없는 도구 호출은 1 메시지에 모으기.

5. grep 또는 목록의 원시 출력을 스레드에 남기지 않기

수백 줄 분량의 grep 결과도, 한 번 출력되면 컨텍스트에 계속 남아 있게 됩니다. 필요한 것은 '몇 건이 있었는지'와 '어떤 file:라인인지'뿐입니다. 대량으로 나올 것 같은 검색은 서브 에이전트에게 맡기거나, 건수를 제한한 후에 실행합니다.

자신의 로그로 측정하기

Claude Code의 세션 로그는 ~/.claude/projects/<프로젝트>/<세션ID>.jsonl
에 저장되어 있습니다. 각 assistant 메시지의 message.usage
에 토큰 수가 기록되어 있으므로, 이를 집계합니다.

import json, glob, os
from collections import defaultdict
root = os.path.expanduser("~/.claude/projects")
...

python cc_usage.py

cache_read의 비율이 높고, 상위 세션의 최대 컨텍스트 길이가 수십만 토큰에 달한다면, 이 기사의 규칙이 그대로 적용될 것입니다.

참고로, 오래된 세션 로그는 일정 기간이 지나면 자동으로 삭제되므로, 집계할 수 있는 것은 손에 남아있는 기간만큼입니다.

요약

• Claude Code의 입력 비용은 거의 cache_read가 차지하고 있습니다(실측 약 98%) - 비용은 '컨텍스트 길이 × 요청 수'. 긴 세션의 후반부는 한 번의 요청이 비싸집니다(실측 31배)
• 대책:
• 작업이 끝나면
  /clear

• 300K를 초과하면 분할해야 합니다. 큰 파일은 서브 에이전트가 읽게 해야 합니다. CLAUDE.md에 '항상 유효'라고 명시하지 않으면 사용되지 않을 것입니다.

• 서로 의존성이 없는 도구 호출(tool call)은 하나의 메시지로 묶습니다.

• 태스크가 완료되면

"캐시가 작동해서 저렴하다"는 것은 토큰당 비용에 대한 이야기일 뿐입니다. 총량을 살펴보면, 세션의 길이 자체가 가장 큰 비용 요인이었습니다.

Discussion