Claude 가이드 #1: Prompt Caching — 같은 자료 비용을 10%로 줄이는 잠깐 기억하기

이 글은 Claude API 공식 문서의 Prompt Caching(프롬프트 캐싱) 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/build-with-claude/prompt-caching 마지막 확인: 2026-05-12

1. 한 줄 요약

#

Claude에게 같은 자료를 매번 보내지 마세요. 한 번 보내고 다음부터는 10% 가격에 다시 읽어옵니다.

2. 무엇이고 왜 좋을까

#

단골 식당이 메뉴를 외워두는 것과 같습니다.

Claude에게 긴 자료(매뉴얼, 책, 강의 노트)와 함께 질문을 하면, AI는 매번 그 자료 전체를 처음부터 다시 읽습니다. 그런데 같은 자료로 여러 번 질문할 거라면, 그건 너무 낭비겠죠. 프롬프트 캐싱(Prompt Caching, “잠깐 기억해두기”) 은 자료를 한 번만 보내두면 다음 질문부터는 그 자료를 “이미 외운 것"처럼 빠르게 꺼내 쓰는 기능입니다.

핵심 수치 하나만 기억하세요: 캐시에서 다시 읽을 때는 원래 비용의 10%만 냅니다. 같은 100페이지 매뉴얼로 10번 질문하면, 자료비를 9번 아끼는 셈입니다.

기본 보관 시간은 5분이고, 자료를 다시 쓸 때마다 5분이 갱신됩니다. 더 길게 두고 싶으면 1시간 옵션도 있습니다(가격은 조금 더 비쌉니다).

3. 이런 상황에서 써요

#

이 기능이 진짜 빛나는 건 “같은 자료를 여러 번 본다"는 상황입니다. 세 가지 일상적인 예를 보여드릴게요.

상황 1: 학생 — 강의 PDF 한 권으로 시험 공부

#

50페이지짜리 전공 강의 자료 PDF가 있습니다. 시험 기간이 다가오니 “이 단원 핵심만 정리해줘”, “이 개념과 저 개념 차이는 뭐야?”, “예상 문제 5개 만들어줘” 같은 질문을 계속 던지고 싶어요.

매번 PDF 전체를 첨부하면 답변 한 번에 자료비를 풀로 내야 합니다. 자료를 한 번 캐시해두면, 그다음 질문들은 자료비 10%만 내고 답변을 받을 수 있어요. 시험 공부하는 1~2시간 동안 같은 자료로 수십 번 물어볼 수 있죠.

상황 2: 직장인 — 회사 매뉴얼·정책 Q&A

#

100페이지짜리 사내 운영 매뉴얼을 들고 일하는 분이라면, 동료들이 매일 같은 질문을 합니다. “휴가 신청 절차는?”, “출장비 정산은 어떻게?”, “이 양식은 어디서 찾아?”

매뉴얼 전체를 한 번 캐시에 올려두면, 직원 누가 어떤 질문을 해도 매뉴얼은 이미 외운 상태입니다. 답변 비용이 1/10 가까이 줄어드니, 사내 챗봇이나 안내 도우미를 훨씬 부담 없이 굴릴 수 있어요.

상황 3: 일반인 — 책 한 권을 두고 이런저런 질문

#

전자책 한 권을 통째로 첨부해서 “이 책의 핵심 주장은 뭐야?”, “3장에서 작가가 든 사례를 다시 설명해줘”, “이 책과 비슷한 책 추천해줘” 같은 대화를 이어가고 싶을 때.

긴 책 본문을 한 번만 첨부하고 캐시해두면, 이후 질문은 자유롭게 늘려도 됩니다. 가족에게 공유할 독서 노트를 만들거나, 자기계발서를 한 권 끝까지 분석하는 데에 잘 어울리죠.

4. 가볍게 시작하기

#

💻 개발 경험이 있으신가요? 아래 코드는 Python(파이썬) 기준 가장 짧은 예시입니다. 비개발자라면 “이런 식으로 쓰는구나” 정도로 보고 넘어가셔도 좋습니다. 코드는 보조이고, 진짜 중요한 건 아래의 한국어 풀이예요.

import anthropic

client = anthropic.Anthropic()

# 긴 매뉴얼을 system 자리에 넣고, 그 블록에 "이거 기억해둬" 표시(cache_control)를 붙입니다
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "(여기에 회사 매뉴얼 전체 텍스트가 들어갑니다. 길어도 OK.)",
            "cache_control": {"type": "ephemeral"}  # ← 이 한 줄이 캐시 활성화
        }
    ],
    messages=[
        {"role": "user", "content": "휴가 신청 절차를 알려줘"}
    ],
)

print(response.usage)  # 캐시가 잘 됐는지 확인하는 곳

코드 핵심은 딱 한 줄, "cache_control": {"type": "ephemeral"} 입니다. “이 자료는 잠깐 기억해둬"라고 Claude에게 표시해주는 거예요. 같은 매뉴얼로 5분 안에 다음 질문을 하면 자동으로 캐시에서 꺼내 씁니다. 응답에 같이 따라오는 usage 안의 cache_read_input_tokens(캐시에서 읽은 토큰 수)가 0보다 크면 “캐시가 잘 작동했다"는 뜻입니다.

5. 흔한 오해와 함정

#

⚠️ 함정 1: “캐시만 켜면 무조건 싸지죠?”

#

아니요. 첫 질문은 오히려 살짝 더 비쌉니다. 자료를 “외워두는” 작업비(원래 가격의 1.25배)가 들거든요. 같은 자료로 두 번째 질문부터 진짜 이득(원래의 10%)이 생깁니다. 한 번만 쓰고 버릴 자료라면 캐시를 켤 이유가 없어요.

⚠️ 함정 2: “분명 캐시 켰는데 왜 비용이 그대로지?”

#

자료가 너무 짧으면 캐시가 작동하지 않습니다. 모델마다 최소 길이가 있어요(예: Opus 4.5/4.6/4.7은 4,096토큰, Sonnet 4.5는 1,024토큰 — 한국어로는 대략 A4 한두 장 분량). 짧으면 그냥 무시되고 일반 가격으로 처리됩니다. 오류 메시지도 안 나오니, 응답의 cache_creation_input_tokens(캐시 생성 토큰)와 cache_read_input_tokens(캐시 읽기 토큰)가 둘 다 0이면 “아, 길이가 부족했구나” 하고 알 수 있어요.

⚠️ 함정 3: “5분 지나면 다시 처음부터 내야 해요?”

#

기본 보관 시간은 5분이지만, 자료를 다시 쓸 때마다 5분이 새로 시작됩니다. 그러니 5분 안에만 다음 질문이 들어오면 계속 캐시가 살아 있어요. 만약 더 띄엄띄엄 쓴다면 "ttl": "1h" 옵션으로 1시간까지 늘릴 수 있습니다(보관 비용은 조금 더 비쌉니다).

6. 한 단계 더 (관심 있는 분만)

#

🎯 여기까지 오신 분 환영합니다. 이 섹션은 호기심 있는 분을 위한 보너스입니다. 본문만 읽어도 충분하니, 부담 없이 넘어가셔도 좋아요.

1시간 캐시 — 띄엄띄엄 쓰는 분들을 위해

#

기본 5분이 너무 짧다면, 캐시 옵션에 ttl(Time To Live, “유효 시간”) 한 줄만 추가하면 됩니다.

system=[
    {
        "type": "text",
        "text": "(긴 매뉴얼 텍스트)",
        "cache_control": {"type": "ephemeral", "ttl": "1h"}  # 1시간 보관
    }
]

비용 시뮬레이션 — 진짜 얼마나 아낄까?

#

Claude Sonnet 4.6 기준, 100페이지 매뉴얼(약 80,000토큰)을 10번 질문한다고 가정하면:

10번 질문 기준 약 78% 절약. 매뉴얼을 자주 묻는 챗봇이라면 차이가 훨씬 더 커집니다.

7. 한 마디

#

처음엔 “캐시”, “토큰”, “TTL” 같은 단어가 낯설어 보이지만, 막상 해보면 표시 한 줄 붙이는 게 전부예요. 같은 자료로 두 번 이상 질문할 일이 있다면, 안 쓸 이유가 없습니다.

만약 “이상하다, 캐시가 작동 안 하는 것 같은데?” 싶다면 위의 함정 1~3 중 하나일 가능성이 큽니다. 자료가 너무 짧진 않은지, 5분 이상 지나진 않았는지, 첫 질문이라 아직 외우는 중인지 — 이 세 가지만 차분히 확인해보세요.

다음 글에서는 Claude 가이드 #2: Batch Processing(일괄 처리) — 한꺼번에 보내고 50% 할인받기 를 다룰 예정입니다. 캐시가 “같은 자료를 여러 번"이라면, 배치는 “다른 질문을 한꺼번에"입니다. 두 기능을 같이 알면 비용을 정말 야무지게 다룰 수 있어요.

Claude API 공식 문서를 한국어로 풀어쓴 시리즈입니다. 원문 정확성이 가장 우선, 의역과 친근함은 그 위에서.