새로 생긴 한 줄이 알려주는 네 가지

프롬프트 캐시는 매 요청마다 다시 보내는 대화 내용을 서버가 기억해 두었다가 훨씬 싼 값에 읽어 주는 장치입니다. 원래는 조용히 뒤에서 돌아갈 뿐 얼마나 잘 작동하는지 볼 방법이 없었습니다. 이제 /cost의 세션 항목에 Prompt cache (main) 줄이 추가되어 네 가지를 함께 보여줍니다. 첫째 요청 횟수, 둘째 입력 토큰 중 캐시에서 읽힌 비율, 셋째 캐시를 놓친 횟수와 그때 다시 저장된 토큰 양, 넷째 지금 캐시가 따뜻한 상태인지 식었는지와 적용 중인 유지 시간입니다. 상태 표시줄 스크립트에서도 같은 숫자를 prompt_cache 항목으로 읽어 갈 수 있습니다.

"미스"는 캐시를 못 읽은 게 아니라 다시 처리한 것입니다

여기서 말하는 미스는 캐시가 조금 덜 쓰인 정도를 뜻하지 않습니다. 공식 문서 기준으로 Claude Code는 캐시에서 읽을 수 있었던 내용의 5%를 넘게, 그리고 최소 2,000 토큰 이상을 다시 처리한 요청만 미스로 셉니다. 원래 싼 값에 읽고 지나갈 수 있었던 대화를 제값 주고 다시 밀어 넣었다는 뜻이라, 이 숫자가 곧 새어 나간 비용입니다. 다만 Claude Code가 스스로 대화를 다시 쓴 경우, 즉 대화 압축이나 오래된 도구 결과 정리는 미스가 아니라 "예상된 재구축"으로 따로 셉니다. 내 사용 습관 탓인 미스와 도구가 원래 하는 정리 작업을 섞어 보지 않게 나눠 둔 것입니다.

캐시가 식는 시간은 요금제마다 다릅니다

줄 끝에 붙는 따뜻함 표시가 중요한 이유가 여기 있습니다. 캐시 유지 시간은 모두에게 같지 않습니다. 공식 문서에 따르면 구독 플랜에서는 한 시간이지만, 추가 사용 크레딧을 쓰기 시작하면 5분으로 떨어지고, API 키나 클라우드 제공자를 통해 쓰면 기본이 5분입니다. 점심을 먹고 와서 던진 한 줄짜리 질문이 유독 비싼 이유가 이것입니다. 캐시가 식은 뒤 첫 요청은 그날 쌓아 둔 대화 전체를 처음부터 다시 처리합니다. 크레딧을 쓰면서도 한 시간짜리 유지 시간을 지키고 싶다면 유지 시간을 직접 지정하는 방법이 문서에 안내되어 있습니다.

하루 전에 고쳐진 두 가지, 버전을 올리는 것만으로 줄어드는 비용

숫자를 보여 주는 기능이 나오기 하루 전인 v2.1.248(8월 27일)에서 캐시를 새게 만들던 원인 두 가지가 수정됐습니다. 하나는 로그인 토큰이 갱신될 때 도구 정의가 다시 그려지면서 긴 세션에서 대략 한 시간에 한 번씩 캐시 미스가 나던 문제입니다. 다른 하나는 사용량 초과 상태에서 세션을 이어 붙일 때 예약 작업 도구의 정의가 달라져 첫 턴에서 캐시가 통째로 날아가던 문제입니다. 둘 다 사용자가 뭘 잘못해서 생긴 게 아니라 도구 쪽 문제였습니다. 같은 버전에서 에이전트별로 캐시 유지 시간을 5분이나 1시간으로 지정하는 실험 설정도 추가됐습니다. 요컨대 버전을 최신으로 올리는 것 자체가 비용 관리 작업입니다. claude --version으로 현재 버전을 확인하면 됩니다.

이 줄이 보여주지 않는 것도 알고 봐야 합니다

숫자를 믿되 범위는 알아야 합니다. 이 줄은 메인 대화만 집계하고 서브에이전트는 포함하지 않습니다. 여러 에이전트를 동시에 돌리는 방식으로 일한다면 화면에 보이는 것보다 실제 사용량이 큽니다. 또 /clear로 새 세션을 시작하면 세션 항목 전체와 함께 이 줄도 초기화됩니다. 비용 금액 자체도 로컬에서 토큰 수로 계산한 추정치이므로, 청구 기준을 확인하려면 콘솔의 사용량 페이지를 봐야 합니다. 대신 이 줄은 API의 응답에 담긴 캐시 토큰 값을 그대로 세기 때문에 어떤 제공자나 게이트웨이를 쓰든 동작합니다. 구독 플랜을 쓴다면 /usage 화면에서 캐시 미스가 최근 사용량의 10% 이상을 차지할 때 별도 경고로 표시해 주기도 합니다.

AI 도구 비용은 1인으로 일할 때 사람 몫을 대신하는 고정비에 가깝습니다. 그동안은 "오늘따라 많이 나왔네" 하고 넘길 수밖에 없었지만, 이제 캐시 적중률과 미스 횟수라는 확인 가능한 숫자가 생겼습니다. 오늘 할 일은 세 가지입니다. 버전을 v2.1.251 이상으로 올리고, 작업이 끝날 때마다 /cost에서 캐시 줄을 한 번 보고, 미스가 잦다면 자리를 비우기 전에 대화를 정리하는 습관을 들이는 것입니다.

누끼토끼는 아임웹·식스샵·카페24 제작 실무에 Claude Code와 Cursor를 매일 쓰면서, 어디까지 자동화하고 어디부터 사람이 확인해야 하는지를 강의와 칼럼으로 정리하고 있습니다. 도구의 새 기능이 나올 때마다 제작 현장에서 무엇이 달라지는지 이어서 다루겠습니다.