Prompt Cache가 비용을 줄이지 못하는 이유와 prompt-cache-skills 진단법

Claude Code나 Cline의 월 청구액이 실제로 필요한 금액보다 30%~50% 높을 수 있습니다. 사용량이 많아서가 아니라 Prompt Cache가 작동하지 않기 때문입니다.

많은 AI 코딩 Agent는 prompt caching을 기본으로 사용하지만, 설정의 작은 변화 하나로 전체 캐시 prefix가 무효화될 수 있습니다. system prompt에 타임스탬프가 들어가거나, cache key 계산이 틀리거나, 캐시 스위치가 꺼져 있거나, TTL이 너무 짧은 경우입니다. 오류도 나지 않고 청구서도 알려 주지 않으므로 매달 높은 API 비용만 보게 됩니다.

prompt-cache-skills는 이렇게 조용히 실패하는 캐시 설정을 수정하는 drop-in skill 모음입니다. 적합한 상황에서는 거의 0에 가깝던 캐시 적중률을 80% 이상으로 높일 수 있습니다. 아래에서는 캐시 과금 원리, 네 가지 주요 실패 원인, 대표적인 skill 수정 사례, 검증 방법을 설명합니다.

Prompt Cache가 비용을 줄이는 방식

Prompt Cache의 절감 원리는 간단합니다. 안정적인 prefix를 캐시에 저장하고 반복 사용할 때 일반 입력 token보다 훨씬 낮은 비용을 지불합니다.

API마다 과금 필드 이름은 다르지만 원리는 같습니다.

과금 유형	과금 특징	적용 상황	대표 공급자
cache_creation_input_tokens	처음 캐시를 만들며 일반 token보다 비싼 경우가 많음	긴 prefix의 첫 요청	Anthropic
cache_read_input_tokens	캐시 적중 시 일반 token의 약 10% 수준	안정적인 prefix 반복 사용	Anthropic
일반 입력 token	정상 요율로 과금	짧은 요청 또는 자주 변하는 prefix	모든 공급자
cached_tokens (OpenAI)	캐시 적중 시 비용이 약 50% 감소	안정적인 prefix 재사용	OpenAI
cached content (Gemini)	캐시 유지 시간에 따라 과금	긴 context	Google Gemini

Anthropic을 예로 들어 보겠습니다. system prompt가 2,000 token이고 같은 Agent가 하루에 100번 재사용한다면, 캐시 적중 시 이 2,000 token은 일반 입력 비용의 약 10%인 cache_read 요율로 계산됩니다. 이 항목만으로 입력 비용을 약 90% 줄일 수 있습니다.

캐시가 실제로 효과를 내려면 prefix가 안정적이고 여러 번 재사용되어야 합니다. system prompt에 타임스탬프나 임의 ID가 있어 매 요청마다 바뀌면 캐시 prefix를 매번 다시 계산해야 하며, cache_creation 비용이 일반 요청보다 더 비싸질 수도 있습니다.

Agent 캐시가 계속 실패하는 이유

다음 문제는 오류를 내지 않습니다. 청구 금액은 보이지만 구체적으로 어디에서 낭비되는지 찾기 어렵습니다.

1. 변동 메시지가 prefix를 깨뜨립니다. system prompt의 앞부분에 타임스탬프, 임의 ID 또는 매 요청마다 달라지는 값이 있으면 전체 캐시 prefix가 무효화됩니다. 가장 흔한 원인입니다.

2. Cache key가 없거나 잘못되었습니다. 일부 Agent 도구는 캐시 표시를 제대로 설정하지 않거나 사용자 정의 cache key 계산을 잘못합니다. prefix 내용은 안정적이어도 API가 캐시 가능한 내용으로 인식하지 못합니다.

3. 캐시가 기본적으로 꺼져 있습니다. 일부 Agent 도구는 prompt caching을 기본으로 비활성화하므로 설정 파일에서 직접 켜야 합니다. Agent가 자동으로 처리한다고 생각해도 계속 일반 token 요금이 부과됩니다.

4. TTL이 너무 짧습니다. 캐시 유효 시간이 한 시간처럼 짧은데 실제 요청 간격이 그보다 길면, 다음 요청 시점에는 이미 캐시가 만료되어 있습니다.

구체적인 증상은 Agent마다 다릅니다. prompt-cache-skills 저장소의 README는 도구별 증상을 정리합니다. 원인이 의심되면 먼저 저장소의 SKILL.md가 현재 도구와 맞는지 확인하세요.

prompt-cache-skills란 무엇인가

prompt-cache-skills는 모든 AI 코딩 Agent가 직접 읽고 적용할 수 있는 drop-in skill 모음입니다.

구분	설명
성격	AI 코딩 Agent가 직접 읽고 적용할 수 있는 수정 patch로 구성된 drop-in skill 모음
목표	적합한 상황에서 나쁘거나 부분적인 적중률을 80%~99%로 향상
적용 Agent	Claude Code, Codex, Cline, Cursor, Devin, Gemini CLI, OpenCode, Aider, Continue, Roo Code 등
저장소	https://github.com/OnlyTerp/prompt-cache-skills
사용 방식	저장소 지정 → Agent 자동 적용 → 적중 검증, 또는 skills/ 디렉터리의 patch를 직접 적용
시간 절약	각 API의 캐시 세부 사항을 직접 조사하는 시간 절약

현재 프로젝트에는 약 99개의 star가 있습니다. skills 목록과 이름은 바뀔 수 있으므로 구체적인 내용은 저장소 README를 기준으로 확인하세요.

직접 점검할 때는 공급자별 prompt caching 문서를 찾고, Agent 설정 차이를 비교하며, 어떤 필드가 prefix를 깨뜨리는지 추측해야 합니다. 이 skill 모음은 각 실패 원인을 이미 식별하고 수정 diff와 검증 방법까지 제공한다는 장점이 있습니다.

prompt-cache-skills로 Agent를 수정하는 방법

Agent가 자동으로 수정하게 하는 방법과 skills/ 디렉터리를 보고 직접 수정하는 방법이 있습니다.

방법 1: Agent가 자동으로 수정하게 하기(권장)

첫째, 저장소를 지정합니다. AI 코딩 Agent에 다음 문장을 보내세요.

https://github.com/OnlyTerp/prompt-cache-skills를 읽고 skills/에서 현재 사용 중인 harness와 맞는 모든 skill을 적용해 줘. 대상 확인 → diff 적용 → SKILL.md에 따라 검증 순서로 진행해 줘.

둘째, Agent는 Cline, Continue, Aider처럼 현재 사용하는 도구를 식별하고 일치하는 skill 목록을 보여 줍니다. 각 skill이 다루는 실패 원인도 확인할 수 있습니다.

셋째, diff를 검토합니다. 각 skill 디렉터리의 SKILL.md에는 수정 대상과 구체적인 변경 사항이 있습니다. 안전한 변경인지 자세히 읽어 보세요.

넷째, 변경을 적용합니다. 확인 후 Agent가 로컬 또는 프로젝트 설정 파일에 diff를 적용하도록 합니다. 먼저 원본 설정을 백업하는 것이 좋습니다.

다섯째, 적중을 검증합니다. tools/check_cache.py로 캐시가 실제로 작동하는지 확인합니다. 자세한 방법은 아래 “캐시가 실제로 적중했는지 검증하는 방법”을 참고하세요.

방법 2: 직접 수정하기

Agent가 설정을 자동으로 바꾸게 하고 싶지 않다면 직접 적용할 수 있습니다.

첫째, 저장소를 엽니다: https://github.com/OnlyTerp/prompt-cache-skills

둘째, skills/ 디렉터리에서 사용 중인 도구의 skill을 찾습니다. 예를 들어 cline-fix-volatile-msg 또는 continue-enable-defaults가 있습니다.

셋째, SKILL.md를 읽습니다. 각 skill 디렉터리는 대상, 증상, 수정 지점, 검증 방법을 설명합니다.

넷째, 설명에 따라 설정 파일을 직접 수정합니다.

다섯째, tools/check_cache.py로 캐시 적중을 검증합니다.

안전 주의 사항

Agent가 diff를 자동으로 적용하면 로컬 또는 프로젝트 설정이 직접 변경됩니다. SKILL.md에서 각 수정 사항을 이해하고 확인한 뒤 적용하세요. 변경 전에 원본 파일을 백업하는 것이 좋습니다.

Skill 모음 상세 설명: 대표적인 수정 사례

저장소의 각 skill은 대상 Agent, 증상, 수정 diff, 검증 방법을 갖춘 완결된 수정 단위입니다. 다음은 대표 사례입니다.

Skill 이름	대상 Agent	증상	수정 지점
cline-fix-volatile-msg	Cline	system prompt prefix에 타임스탬프가 있어 요청마다 달라짐	변동 메시지 제거 또는 고정
cline-openai-cache-key	Cline + OpenAI	OpenAI cache key 계산 오류	cache key 생성 로직 수정
cline-pin-timestamp	Cline	타임스탬프가 캐시를 무효화함	타임스탬프 고정 또는 제거
continue-fix-volatile-msg	Continue	system prompt에 변동 필드가 포함됨	변동 메시지 정리
continue-enable-defaults	Continue	prompt caching이 기본적으로 꺼져 있음	캐시 설정 활성화
continue-gemini-explicit	Continue + Gemini	Gemini 캐시 설정 누락	캐시 매개변수를 명시적으로 설정
aider-1h-ttl	Aider	캐시 TTL이 한 시간뿐이라 자주 만료됨	TTL 연장 또는 요청 빈도 조정
aider-cache-default-on	Aider	캐시가 기본적으로 꺼져 있음	기본 캐시 스위치 활성화
opencode-detect-openai-compat	OpenCode	OpenAI 호환 모드에서 캐시가 작동하지 않음	OpenAI 호환 API를 감지하고 올바르게 처리
opencode-bedrock-doc-blocks	OpenCode + Bedrock	Bedrock 문서 block 캐시 문제	문서 block 캐시 전략 수정

Skill 목록은 계속 늘어나며 이름도 바뀔 수 있으므로 저장소 README와 skills/ 디렉터리를 기준으로 확인하세요. 현재 목록에 없는 Agent를 사용한다면 기존 skill의 SKILL.md와 patch 파일을 참고하여 비슷한 문제를 직접 점검할 수 있습니다.

캐시가 실제로 적중했는지 검증하는 방법

prompt-cache-skills는 cold/warm 요청을 비교하고 캐시 적중률을 계산하는 tools/check_cache.py를 제공합니다.

사용 단계

첫째, 저장소에서 check_cache.py를 받습니다.
https://github.com/OnlyTerp/prompt-cache-skills/blob/main/tools/check_cache.py

둘째, API 인증 정보를 환경 변수로 설정합니다.

• Anthropic: ANTHROPIC_API_KEY
• OpenAI: OPENAI_API_KEY
• Google Gemini: GOOGLE_API_KEY

셋째, 첫 번째 cold 요청을 실행합니다.

python check_cache.py --provider anthropic --prompt "system prompt" --message "사용자 메시지"

cache_creation_input_tokens 필드를 확인합니다.

• 값이 있으면 캐시가 생성된 것입니다.
• input_tokens 수를 기록합니다.

넷째, 1초 후 warm 요청을 실행합니다. 완전히 동일한 prompt와 message를 사용해 같은 명령을 다시 실행합니다.

다음 필드를 확인합니다.

• cache_read_input_tokens: 값이 있고 0보다 크면 캐시 적중입니다.
• cache_creation_input_tokens: 0이거나 없어야 합니다.
• input_tokens: 캐시된 부분이 일반 입력으로 과금되지 않으므로 크게 줄어야 합니다.

다섯째, 적중률을 계산합니다.

적중률 = cache_read_input_tokens / (cache_read_input_tokens + input_tokens)

예시:

• 첫 요청: input_tokens=2000, cache_creation_input_tokens=1800
• 두 번째 요청: cache_read_input_tokens=1800, input_tokens=200
• 적중률 = 1800 / (1800 + 200) = 90%

여섯째, 작동 여부를 판단합니다.

• 캐시 작동: warm 요청의 cache_read_input_tokens > 0
• 캐시 미작동: warm 요청의 cache_read_input_tokens = 0 또는 필드 없음

warm 요청에서 cache_read_input_tokens가 0이면 앞의 네 가지 실패 원인으로 돌아가 변동 메시지, 잘못된 cache key, 비활성 기본값, 짧은 TTL을 확인하세요.

지표 설명

• cache_creation_input_tokens: 처음 캐시를 만들 때 사용한 token 수를 나타내는 Anthropic 필드
• cache_read_input_tokens: 캐시 적중으로 읽은 token 수를 나타내는 Anthropic 필드
• cached_tokens: 캐시 적중 token 수를 나타내는 OpenAI 필드
• input_tokens: 캐시되지 않은 일반 입력 token

warm 요청의 cache_read_input_tokens = 0은 캐시가 작동하지 않았다는 뜻입니다. 네 가지 실패 원인과 설정을 다시 확인해야 합니다.

이 skill 모음을 권장하거나 권장하지 않는 경우

이 skill 모음은 알려진 캐시 실패를 수정하지만 모든 상황에 맞지는 않습니다.

상황	권장 여부	이유
긴 system prompt + 여러 번의 유사한 요청	권장	안정적인 prefix를 재사용할 수 있어 절감 효과가 큼
Claude Code, Cline 같은 코딩 Agent 도구	권장	프로젝트가 이런 도구를 위해 설계됨
월 청구액 50달러 초과	권장	절감 가능액이 커서 작업할 가치가 있음
prompt caching 설정은 있지만 작동 여부가 불확실함	권장	검증 도구로 확인 가능
짧은 prompt + 일회성 요청	권장하지 않음	캐시 비용이 절감액보다 클 수 있음
실시간 데이터처럼 system prompt가 자주 바뀜	권장하지 않음	prefix가 불안정해 재사용할 수 없음
하루에 몇 번만 호출하는 등 요청 간격이 TTL보다 김	평가 필요	캐시가 만료되어 이득이 적을 수 있음
지원 목록에 없는 Agent 사용	평가 필요	직접 적용하거나 커뮤니티 skill을 기다려야 함

월 청구액이 이미 50달러를 넘고 지원 목록의 Agent를 사용한다면 투자 대비 효과가 클 수 있습니다. 요청 빈도가 낮거나 prefix가 자주 바뀐다면 설정을 변경할 가치가 있는지 먼저 평가하세요.

위험과 주의 사항

이 skill 모음을 사용하기 전에 다음 위험을 알아야 합니다.

1. 프로젝트가 비교적 새롭습니다. 현재 약 99개의 star가 있으며 skills 목록과 이름은 바뀔 수 있습니다. 최신 README를 확인하세요.

2. 자동 설정 변경에는 주의가 필요합니다. Agent가 diff를 적용하면 로컬 또는 프로젝트 설정 파일이 바뀝니다. SKILL.md에서 각 변경을 이해한 뒤 적용 여부를 결정하세요.

3. 공급자마다 과금 필드가 다릅니다. Anthropic은 cache_creation/cache_read, OpenAI는 cached_tokens, Gemini는 cached content를 사용합니다. 최신 공식 문서를 확인하세요.

4. 캐시는 만능이 아닙니다. 짧은 일회성 호출이나 변동 prefix에서는 이득이 거의 없거나 더 비쌀 수 있습니다. 모든 요청에 강제로 적용하지 마세요.

5. 검증 도구에는 한계가 있습니다. check_cache.py는 주로 Anthropic API를 대상으로 합니다. OpenAI와 Gemini 검증은 각 공식 문서도 확인해야 합니다.

6. 적중률은 보장되지 않습니다. 80%~99%는 프로젝트가 제시한 목표입니다. 실제 결과는 prefix, 빈도, TTL 등 여러 요인에 따라 달라집니다.

다음 단계와 관련 글

AI 코딩 비용을 더 줄이려면 다음 글을 참고하세요.

• AI Gateway로 모니터링, 캐시, failover를 중앙화하기 — 여러 공급자를 관리하고 불필요한 비용을 줄입니다

• 응답 품질을 높이는 Prompt Engineering 기법 — prompt를 개선하고 불필요한 token을 줄입니다

• Computer-Use Agent: AI가 컴퓨터를 조작하는 방법 — Agent의 기능을 이해하고 작업 흐름을 개선합니다

공식 자료:

• prompt-cache-skills GitHub 저장소
• Anthropic Prompt Caching 문서
• OpenAI Prompt Caching 문서
• Google Gemini Context Caching 문서