facts: 토큰 과금 체계와 프롬프트 캐싱 제원

토큰 기반 과금 체계에서 실제 비용을 결정하는 것은 GPU 또는 TPU의 추론 시간이다. Claude Code의 비용은 사용하는 모델의 크기, 토큰의 방향(입력/출력), 그리고 캐싱 여부에 따라 결정된다. 추론 과정은 요청과 컨텍스트를 읽는 '프리필(Prefill)' 단계와 응답을 생성하는 '디코드(Decode)' 단계로 나뉜다. 디코드 단계는 토큰을 하나씩 순차적으로 생성하므로 GPU 점유 시간이 길며, 이로 인해 출력 토큰 비용은 입력 토큰보다 약 5배 높게 책정된다.

프롬프트 캐싱은 서버가 이전에 처리한 동일한 토큰 시퀀스의 상태를 보존하여 재계산을 피하는 기술이다. 캐시에서 데이터를 읽을 때의 비용은 일반 입력 비용의 0.1배이며, 캐시에 토큰을 기록할 때는 최대 2배의 비용이 발생한다. 한 번 기록된 캐시는 이후 모든 턴에서 0.1배의 저렴한 비용으로 읽히므로, 세션이 길어질수록 캐싱 효율이 비용 절감의 핵심이 된다.

명령어 실행 결과의 처리에는 `BASH_MAX_OUTPUT_LENGTH` 설정이 적용된다. 출력 내용이 30,000자를 초과하면 Claude Code는 전체 내용을 파일로 저장하고, 대화 컨텍스트에는 짧은 미리보기와 파일 경로만 삽입하여 토큰 낭비를 막는다.

how-it-works: 캐시 무효화 메커니즘과 컨텍스트 누적 구조

캐시 유효성은 요청의 시작점부터 완전히 일치해야 유지되는 구조다. Claude Code는 '도구 정의 $\rightarrow$ 시스템 프롬프트 $\rightarrow$ 대화 내용(CLAUDE.md 포함)' 순서로 요청을 보낸다. 이 접두사(Prefix) 부분에 변화가 생기면 그 뒤에 오는 모든 내용은 캐시를 사용할 수 없게 되어 다시 전체 가격으로 프리필된다. 예를 들어 세션 중간에 모델을 변경하거나 `/effort` 설정을 바꾸면 캐시가 무효화되어 비용 급증이 발생한다.

컨텍스트에 쌓이는 데이터는 시간이 지날수록 누적된다. 모델이 읽은 파일 내용이나 실행한 명령어의 출력값은 해당 세션이 끝날 때까지 매 턴마다 다시 전송된다. 캐싱 덕분에 읽기 비용은 낮지만, 누적된 데이터는 모델이 추론해야 할 컨텍스트 창을 점유하여 처리 효율에 영향을 준다. 특히 400줄의 테스트 통과 메시지처럼 제한치(30,000자) 미만이지만 불필요하게 긴 출력물은 매 턴 비용을 가중시키는 요인이 된다.

서브에이전트는 메인 세션과 분리된 독립적인 컨텍스트 창을 가진다. 서브에이전트는 자체적인 시스템 프롬프트와 도구, CLAUDE.md를 가지지만 메인 세션의 대화 기록은 공유하지 않는다. 작업 완료 후 메인 세션으로 전달되는 것은 최종 답변뿐이며, 작업 과정에서 발생한 모든 중간 토큰과 도구 실행 결과는 폐기된다. 이는 로그 분석처럼 대량의 데이터를 처리해야 하지만 결과값만 필요한 작업에서 컨텍스트 오염을 방지하는 기제로 작동한다.

implementation-impact: 비용 효율화를 위한 세션 및 에이전트 운영 전략

사용자가 체감하는 비용 차이는 요청의 구체성에 따라 갈린다. "테스트가 실패한다"는 모호한 요청은 모델이 `grep`이나 파일 읽기를 반복하게 만들어 불필요한 토큰을 컨텍스트에 누적시킨다. 반면 "@utils.test.ts의 실패하는 테스트를 수정해달라"와 같이 특정 파일을 지정하면 탐색 과정이 생략되어 읽기 호출 횟수와 토큰 소비를 즉각적으로 줄일 수 있다.

세션 관리 도구인 `/clear`와 `/compact`는 컨텍스트 최적화의 핵심이다. 새로운 작업을 시작할 때 `/clear`를 사용해 이전 작업의 맥락을 완전히 삭제하거나, 동일 작업 중에서도 초기 단계의 불필요한 기록이 많아졌을 때 `/compact`를 통해 컨텍스트를 압축해야 한다. 또한 `/loop` 기능을 사용할 때는 주의가 필요하다. 루프는 설정된 세션의 전체 대화를 매번 함께 전송하며, 마지막 턴 이후 1시간이 지나면 캐시 미스가 발생해 비용이 상승하므로 별도의 터미널 세션에서 실행하는 것이 효율적이다.

개발자는 모호한 자연어 요청 대신 파일 경로를 직접 지정하는 습관을 들여 탐색 토큰을 줄이고, 로그 분석 등 고출력 작업은 반드시 서브에이전트에게 위임하여 메인 세션의 컨텍스트 팽창과 비용 스파이크를 방지해야 한다.