Prompt Caching Claude Code: Setel TTL, Tekan Tagihan

Saya berpindah dari Sonnet ke Opus sekitar sembilan puluh menit setelah sesi berjalan karena masalahnya jadi lebih berat. Giliran berikutnya terasa jauh lebih lama dan lebih mahal daripada giliran mana pun sebelumnya, dan sepuluh menit saya habiskan dengan yakin bahwa modelnya lambat. Bukan. Setiap model punya cache-nya sendiri, dan saya baru saja membuang sembilan puluh menit prefix ter-cache begitu saja.

Prompt caching diurus untuk Anda dan sebagian besar tidak terlihat, dan justru itulah sebabnya momen ketika ia menagih Anda terasa membingungkan. Tulisan ini membahas cara kerja prefix-nya, dua input cache key yang sama sekali bukan teks prompt, aksi mana yang membatalkan dan mana yang aman, dua bucket TTL beserta cara memilihnya, dan cara mengukur apakah semua itu bekerja.

Satu prefix, dicocokkan persis, tanpa caching per file

Model tidak mengingat apa pun antar-request, jadi Claude Code mengirim ulang semuanya tiap giliran: system prompt, konteks proyek, setiap pesan dan hasil tool sebelumnya, lalu pesan baru Anda. Caching adalah cara API menghindari memproses ulang bagian yang tidak berubah. Ia mencocokkan awal request — prefix-nya — dengan isi yang baru saja diproses, dan pencocokannya persis.

# Claude Code orders every request so the rarely-changing
# content comes first. The API matches the PREFIX exactly, so a
# change anywhere recomputes everything after it.

  1. System prompt    <- tool definitions, output style
                         changes on upgrade, or when the tool set changes
  2. Project context  <- CLAUDE.md, auto memory, unscoped rules
                         changes at session start, /clear or /compact
  3. Conversation     <- your messages, replies, tool results
                         changes every turn

# There is NO per-file or per-segment caching. A change in
# layer 1 invalidates 2 and 3 behind it.
#
# Two more things are part of the cache key without being in
# the prompt text at all:
#   - the MODEL         (each model has its own cache)
#   - the EFFORT LEVEL  (each level has its own cache per model)

Konsekuensi yang sering luput adalah tidak adanya caching per file atau per segmen. Tidak ada yang di-cache satuan. Perubahan di lapisan system prompt membatalkan konteks proyek dan seluruh percakapan di belakangnya, karena semua itu kini berada setelah prefix yang berbeda. Itu pula sebabnya plan mode dan pemuatan skill terhitung murah: keduanya menambahkan instruksinya sebagai pesan percakapan, bukan mengubah apa pun yang lebih awal.

Hal-hal yang membatalkan cache, termasuk dua yang bukan teks

Masing-masing menyebabkan satu giliran yang lebih lambat dan lebih mahal, setelah itu prefix barunya ter-cache. Sebagian besar bisa dihindari di tengah tugas begitu Anda tahu ada harganya:

• Berganti model, atau mengubah effort level. Keduanya bukan bagian dari teks prompt, tetapi keduanya bagian dari cache key, jadi masing-masing punya cache sendiri untuk isi yang sama.
• Menyalakan fast mode, yang menambahkan request header yang termasuk cache key. Biayanya berlaku sekali per percakapan, jadi menyalakannya di awal sesi jauh lebih murah daripada di tengah sesi panjang.
• Menyambung atau memutus MCP server yang tool-nya dimuat ke prefix alih-alih ditunda — dan itu bisa terjadi tanpa tindakan Anda ketika proses stdio keluar atau sesi HTTP kedaluwarsa.
• Menambahkan nama tool polos sebagai deny rule, yang mencabut tool itu dari konteks sepenuhnya dan mengubah lapisan system prompt.
• Memperbarui Claude Code, karena versi baru biasanya mengubah system prompt atau definisi tool.

Hal-hal yang aman, dan kenapa sebagian setting menunggu restart

Daftar ini lebih berguna, karena beberapa di antaranya tampak seperti seharusnya berbiaya padahal tidak:

• Mengedit file di repository Anda. Isi file baru masuk konteks ketika Claude membacanya, dan edit belakangan hanya menambahkan system reminder alih-alih menulis ulang pembacaan sebelumnya.
• Mengedit CLAUDE.md di tengah sesi. Ia tidak membatalkan cache — tetapi editnya juga tidak berlaku, karena file itu dibaca sekali saat sesi dimulai lalu ditahan di memori.
• Mengubah output style, dengan alasan yang sama. Keduanya baru dimuat pada clear, compact, atau restart berikutnya.
• Mengubah permission mode, memanggil skill atau command, dan menjalankan command recap, yang semuanya menambahkan alih-alih menulis ulang.

Rewind adalah yang menarik. Ia memangkas percakapan kembali ke giliran sebelumnya, dan riwayat yang tersisa persis isi yang dipakai membangun cache pada titik itu, jadi request berikutnya mengenai entri cache yang lama. Setiap giliran sejak itu membaca melalui prefix tersebut, dan itu menjaganya tetap hangat. Kalau Anda sudah menempuh jalur yang ingin ditinggalkan sepenuhnya, rewind lebih murah daripada compact — compaction membangun prefix baru, rewind kembali ke yang sudah ada.

Dua bucket, dan satu yang sering menjebak orang

Claude Code menentukan TTL per request, dan setiap request masuk ke salah satu dari dua bucket tetap. API menawarkan TTL lima menit dan TTL satu jam yang bertahan melewati jeda lebih panjang tetapi menagih cache write dengan tarif lebih tinggi.

Apa yang didapat tiap bucket secara default:

// Two controls, one per bucket. Each takes exactly 5m or 1h;
// any other value is ignored. Both need v2.1.242 or later.
{
  "promptCacheTtl": "1h",          // main conversation
  "subagentPromptCacheTtl": "1h"   // subagents, workflows, teammates,
                                   // forks, compaction, session titles
}

# Precedence, first match wins:
#
#   1. FORCE_PROMPT_CACHING_5M=1      forces 5m on BOTH buckets
#   2. the bucket's env var           CLAUDE_CODE_PROMPT_CACHE_TTL
#                                     CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL
#   3. the bucket's setting           the JSON above
#   4. ENABLE_PROMPT_CACHING_1H=1     requests 1h on BOTH buckets
#   5. the default for that bucket
#
# Use FORCE_PROMPT_CACHING_5M=1 to override a longer TTL that
# managed settings imposed, or while measuring the difference.

Cakupan: satu mesin, satu direktori

Di Claude Code, cache secara efektif dibatasi pada satu mesin dan satu direktori. System prompt menyertakan working directory, platform, shell, versi OS, dan path auto memory, jadi dua sesi di direktori berbeda membangun prefix berbeda dan sama sekali tidak saling mengena. Itu termasuk worktree dari repository yang sama, karena tiap worktree punya working directory sendiri — sebuah biaya nyata dari pola parallel worktree yang tidak pernah disebut orang saat merekomendasikannya.

Sesi yang berjalan paralel di direktori yang sama memang membangun prefix yang cocok dan saling membaca cache. Sesi berurutan hanya berbagi prefix bila snapshot git status saat startup sama, karena system prompt juga merekam branch dan commit terakhir. Cache API di bawahnya lebih luas — terisolasi antarorganisasi, dan pada sebagian provider antarworkspace — sehingga dua request mana pun dengan model dan prefix sama di dalam batas itu membaca cache yang sama.

Mengukurnya, supaya Anda berhenti menebak

Dua hitungan token pada setiap respons API memberi tahu apakah semua di atas bekerja. Perhatikan rasionya, bukan angka mutlaknya: rasio read terhadap creation yang tinggi berarti caching bekerja, dan creation yang tetap tinggi giliran demi giliran berarti ada sesuatu di prefix Anda yang bergerak.

# The API reports two counts on every response. A statusline
# script reading current_usage is the cheapest way to watch them.

cache_creation_input_tokens   # written this turn, billed at the WRITE rate
cache_read_input_tokens       # served from cache, ~10% of standard input

# A high read-to-creation ratio means caching is working.
# Creation staying high turn after turn means something in your
# prefix is moving — start with the tool layer.

# Across a team, the OpenTelemetry exporter reports both per
# user and per session, so you can find the one developer whose
# gateway silently stripped the cache markers.

Tiga kebiasaan yang benar-benar menggerakkan angka saya

Semua di atas mengerucut jadi daftar pendek:

1. Pilih model dan effort level di awal sesi, bukan di tengahnya. Keduanya cache key, dan berpindah di tengah tugas menagih pembacaan ulang penuh atas semua yang sudah berjalan.
2. Lakukan compact pada jeda alami antartugas alih-alih membiarkan auto-compaction menyala di tengah tugas, dan pakai rewind alih-alih compact ketika Anda meninggalkan sebuah jalur, bukan menyelesaikannya.
3. Setel TTL subagent ke satu jam sebelum run multi-agent yang panjang, dan biarkan di default selebihnya. Tarif write yang lebih tinggi hanya sepadan ketika memang ada jeda nyata antar giliran.

Alasan mempelajari semua ini bukan tagihannya, melainkan diagnosisnya. Begitu Anda tahu bahwa caching adalah satu pencocokan prefix yang persis dan bahwa model serta effort ada di dalam key-nya, giliran lambat yang tak terjelaskan berhenti menjadi misteri — hampir selalu itu sesuatu yang Anda ubah, dan daftar hal yang bisa mengubahnya pendek. Selebihnya, sesi Anda boleh serumit yang memang dibutuhkan.