SpyBara
Go Premium

prompt-caching.md 2026-10-06 23:59 UTC to 2026-10-07 20:57 UTC

This page contains 90 additions and 90 deletions.

2026
Tue 6 23:59 Wed 7 20:57

Bagaimana Claude Code menggunakan prompt caching

Claude Code mengelola prompt caching secara otomatis. Lihat mengapa perubahan model memicu giliran tanpa cache yang lambat, berapa biaya /compact, mengapa pengeditan CLAUDE.md tidak berlaku di tengah sesi, dan cara memeriksa tingkat cache hit Anda.

Prompt caching membuat Claude Code lebih cepat dan lebih hemat biaya. Tanpa caching, API akan memproses ulang riwayat lengkap Anda pada setiap giliran. Dengan caching, API menggunakan kembali apa yang sudah diproses, menagih pembacaan ulang pada tingkat token cache, dan hanya memproses sepenuhnya apa yang berubah.

Claude Code menangani prompt caching untuk Anda, kecuali Anda menonaktifkannya. Masih berguna untuk mengetahui cara kerja prompt caching, karena beberapa tindakan membatalkan cache dan membuat respons berikutnya lebih lambat dan lebih mahal saat membangun kembali. Halaman ini mencakup tindakan mana yang melakukan itu, mengapa beberapa pengaturan menunggu restart untuk diterapkan, dan cara memeriksa kinerja cache ketika penggunaan terlihat tinggi.

Bagaimana cache diorganisir

Setiap kali Anda mengirim pesan di Claude Code, sistem membuat permintaan API baru. Model tidak mengingat apa pun di antara permintaan, jadi Claude Code mengirim ulang konteks lengkap: system prompt, konteks proyek Anda, setiap pesan dan hasil tool sebelumnya, dan pesan baru Anda. Konten baru ditambahkan di akhir, yang berarti sebagian besar dari setiap permintaan identik dengan yang sebelumnya. Prompt caching adalah cara API menghindari pemrosesan ulang bagian yang tidak berubah.

API melakukan cache dengan mencocokkan awal setiap permintaan, yang disebut prefix, terhadap konten yang baru saja diproses. Pada giliran normal, prefix adalah seluruh permintaan sebelumnya dan hanya pertukaran terbaru yang baru. Kecocokan bersifat tepat, jadi perubahan di mana pun dalam prefix menghitung ulang semuanya setelahnya. Tidak ada caching per-file atau per-segment. Lihat bagaimana prompt caching bekerja dalam referensi API untuk mekanisme yang mendasarinya.

Empat giliran ditampilkan sebagai batang horizontal yang berkembang. Permintaan setiap giliran berisi semuanya dari giliran sebelumnya ditambah pertukaran terbaru ditambahkan di akhir. Pada giliran dua dan tiga, prefix yang tidak berubah dibaca dari cache dan hanya pertukaran baru yang diproses. Pada giliran empat, system prompt berubah, jadi prefix tidak lagi cocok dan seluruh permintaan diproses ulang dan ditulis. Empat giliran ditampilkan sebagai batang horizontal yang berkembang. Permintaan setiap giliran berisi semuanya dari giliran sebelumnya ditambah pertukaran terbaru ditambahkan di akhir. Pada giliran dua dan tiga, prefix yang tidak berubah dibaca dari cache dan hanya pertukaran baru yang diproses. Pada giliran empat, system prompt berubah, jadi prefix tidak lagi cocok dan seluruh permintaan diproses ulang dan ditulis.

Untuk mendapatkan hasil maksimal dari pencocokan prefix, Claude Code mengurutkan setiap permintaan sehingga konten yang jarang berubah di antara giliran muncul terlebih dahulu:

Layer Konten Berubah ketika
System prompt Instruksi inti, definisi tool Set definisi tool yang dimuat berubah
Konteks proyek CLAUDE.md, auto memory, aturan tanpa cakupan Sesi dimulai, atau setelah /clear atau /compact
Percakapan Pesan Anda, respons Claude, hasil tool Setiap giliran

Perubahan pada layer percakapan meninggalkan system prompt dan konteks proyek di-cache. Perubahan pada system prompt membatalkan semuanya, karena semua konten selanjutnya sekarang berada di belakang prefix yang berbeda. Kolom ketiga memberikan pemicu umum daripada daftar lengkap, dan bagian di bawah mencakup set lengkap.

Aturan pencocokan prefix menjelaskan sebagian besar perilaku di halaman ini. Plan mode dan pemuatan skill, misalnya, menambahkan instruksi mereka sebagai pesan percakapan, jadi prefix yang di-cache tetap utuh.

Dua pengaturan tidak muncul dalam tabel layer tetapi masih mempengaruhi apa yang tetap di-cache:

  • Model: setiap model memiliki cache-nya sendiri. Mengganti model menghitung ulang seluruh permintaan bahkan ketika kontennya identik. Lihat Switching models di bawah.
  • Tingkat effort: pada sebagian besar model, setiap tingkat effort memiliki cache-nya sendiri, jadi mengubah effort di tengah sesi menghitung ulang seluruh permintaan. Pada Opus 5.5, Sonnet 5.5, Haiku 5.5, dan Fable 5.1 dengan kunci API atau langganan Claude, cache tetap utuh secara default. Lihat Changing effort level di bawah.

Tempat cache berada

Caching terjadi di sisi server, dalam infrastruktur apa pun yang melayani model Anda. Tempat itu tergantung pada cara Anda melakukan autentikasi:

  • Kunci API, langganan Claude, atau Claude Platform on AWS: cache berada di infrastruktur Anthropic, diakses melalui Claude API
  • Amazon Bedrock atau Agent Platform Google Cloud: cache berada di infrastruktur serving penyedia cloud Anda
  • Microsoft Foundry: tergantung pada opsi hosting deployment. Deployment Hosted on Azure dilayani di infrastruktur Azure; deployment Hosted on Anthropic dilayani di infrastruktur Anthropic
  • ANTHROPIC_BASE_URL kustom atau LLM gateway: cache berada di mana pun permintaan Anda diteruskan, dan apakah caching bekerja tergantung pada gateway

Claude Code juga menambahkan konteks sistem di tengah percakapan, seperti pemberitahuan perubahan file, dan menandai blok itu untuk caching di setiap penyedia dan koneksi kecuali Anda menetapkan CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS, dalam hal ini blok itu dikirim tanpa cache.

Di endpoint penyedia sendiri, Amazon Bedrock dan Mantle endpoint-nya, Agent Platform Google Cloud, dan Microsoft Foundry melakukan cache pada blok dengan cara yang sama seperti Claude API.

Ketika permintaan Anda melewati LLM gateway, ANTHROPIC_BASE_URL kustom, atau override base-URL penyedia cloud seperti ANTHROPIC_BEDROCK_BASE_URL, apa yang tetap di-cache tergantung pada cara gateway menangani marker cache_control yang dikirim Claude Code:

  • Meneruskannya tanpa perubahan: blok dan percakapan Anda di-cache dengan cara yang sama seperti di endpoint penyedia sendiri.
  • Menolak permintaan yang ditandai dengan error 400 yang menyebutkan cache_control: Claude Code mengirim ulang permintaan dengan marker dipindahkan dari blok dan ke pesan percakapan terakhir Anda, dan menyimpannya di sana untuk sisa percakapan. Blok ditagih sebagai input tanpa cache; percakapan Anda tetap di-cache.
  • Menghapus marker sambil mengembalikan respons sukses: seluruh riwayat percakapan Anda ditagih sebagai input tanpa cache di setiap giliran. Gateway yang mengonversi konten sistem bentuk blok ke string biasa menghapus marker dengan cara yang sama.

Untuk apa yang disimpan dan diproses setiap penyedia, lihat penggunaan data. Di mana pun cache berada, entri kedaluwarsa setelah periode tidak aktif, dan Cache lifetime di bawah mencakup TTL dan cara memperpanjangnya.

Tindakan yang membatalkan cache

Tindakan-tindakan ini dapat menyebabkan permintaan berikutnya kehilangan sebagian atau seluruh cache. Anda akan melihat satu giliran yang lebih lambat dan lebih mahal, setelah itu prefiks baru akan di-cache. Sebagian besar dari tindakan ini dapat dihindari di tengah tugas setelah Anda mengetahui bahwa tindakan tersebut memiliki biaya. Pergantian model dapat terasa gratis sampai Anda memperhatikan giliran yang lebih lambat setelahnya.

Beralih model

Setiap model memiliki cache-nya sendiri. Beralih dengan /model berarti permintaan berikutnya membaca seluruh riwayat percakapan tanpa cache hit, meskipun kontennya identik.

Ketika Anda menjalankan /model di terminal, Claude Code meminta Anda untuk mengonfirmasi pergantian hanya saat cache masih hangat dan model baru bukan model yang menghasilkan respons terakhir. Cache tetap hangat selama satu cache TTL setelah Claude Code terakhir mengirim permintaan dalam percakapan ini atau Claude terakhir merespons. Setelah waktu itu berlalu, cache telah kedaluwarsa, sehingga Claude Code beralih tanpa bertanya.

Sebelum v2.1.238, Claude Code tidak memeriksa cache TTL dan tetap bertanya bahkan setelah cache kedaluwarsa.

Anda juga dapat mewajibkan konfirmasi ini atau melewatkannya dengan hook PreModelSwitch.

Pengaturan model opusplan menggunakan Opus selama plan mode dan Sonnet selama eksekusi, sehingga setiap kali plan mode diaktifkan atau dinonaktifkan merupakan pergantian model dan memulai cache baru.

Fallback model otomatis pada model Fable, Opus 5.5, Sonnet 5.5, dan Opus 5 juga merupakan pergantian model. Ketika pengklasifikasi keamanan menandai permintaan dalam kategori yang memiliki model fallback, Claude Code menjalankan ulang permintaan pada model tersebut dan sesi berlanjut di sana.

Ketika frontmatter skill atau perintah menyebutkan model yang berbeda dari model sesi saat ini, giliran itu juga merupakan pergantian model: permintaan berikutnya membaca seluruh riwayat percakapan tanpa cache hit. Model sesi kembali digunakan pada prompt Anda berikutnya. Skill context: fork justru menetapkan model subagent yang di-fork.

Mengubah tingkat effort

Pada sebagian besar model, mengubah tingkat effort di tengah sesi berarti permintaan berikutnya membaca seluruh riwayat percakapan tanpa cache hit. Saat cache masih hangat, Claude Code meminta Anda untuk mengonfirmasi perubahan terlebih dahulu.

Pada Opus 5.5, Sonnet 5.5, Haiku 5.5, dan Fable 5.1 dengan kunci API atau langganan Claude, mengubah effort tetap mempertahankan cache, dan Claude Code menerapkan tingkat baru tanpa bertanya. Ini tidak berlaku pada Amazon Bedrock, Google Cloud's Agent Platform, atau Claude apps gateway, atau ketika Anda menetapkan CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS atau organisasi Anda memiliki konfigurasi HIPAA.

Sebelum v2.1.260, mengubah effort pada Fable 5.1 dengan kunci API atau langganan Claude juga membatalkan cache.

Mengaktifkan fast mode

Mengaktifkan fast mode menambahkan header permintaan yang merupakan bagian dari kunci cache, sehingga permintaan pertama yang dikirim Claude Code dengan fast mode aktif membaca seluruh riwayat percakapan tanpa cache hit. Claude Code menetapkan header itu sekali ketika giliran dimulai dan mempertahankannya selama seluruh giliran, sehingga ketika Anda mengaktifkan fast mode saat Claude sedang bekerja, cache miss akibat header terjadi pada permintaan pertama giliran Anda berikutnya. Token input yang tidak di-cache tersebut ditagih dengan tarif fast mode, itulah mengapa mengaktifkannya di awal sesi lebih murah daripada mengaktifkannya jauh di tengah sesi yang panjang. Jika model Anda saat ini tidak mendukung fast mode, mengaktifkan fast mode juga mengganti model Anda, dan pergantian itu dengan sendirinya memulai cache baru sejak permintaan berikutnya dalam giliran yang sedang berjalan.

Biaya ini berlaku sekali per percakapan. Setelah giliran fast mode pertama, Claude Code terus mengirim header dan hanya mengubah pengaturan kecepatan permintaan, yang bukan bagian dari kunci cache. Mematikan fast mode, fallback otomatis ke kecepatan standar setelah rate limit, dan mengaktifkannya kembali nanti semuanya mempertahankan cache. Jika Anda kehabisan kredit penggunaan di tengah sesi, Claude Code mencoba ulang setiap permintaan fast mode yang ditolak dengan kecepatan standar dengan cara yang sama, sehingga fallback ini juga mempertahankan cache. /clear dan /compact mengatur ulang hal ini, karena keduanya memang membangun ulang cache pada titik-titik tersebut.

Menghubungkan atau menghapus server MCP

Definisi tool berada di lapisan system prompt, sehingga cache menjadi tidak valid ketika kumpulan definisi tool dalam permintaan berubah antar giliran. Mengaktifkan atau menonaktifkan tool advisor merupakan pengecualian: definisinya berada setelah breakpoint cache, sehingga mengaktifkan atau menonaktifkan /advisor menjaga prefiks yang di-cache tetap utuh. Apakah perubahan server MCP berdampak seperti ini bergantung pada apakah tool search menunda tool MCP sesi, yang merupakan default pada model yang didukung:

  • Tool ditunda: Claude Code mempertahankan daftar tool dari permintaan pertama percakapan untuk seluruh percakapan, sehingga server yang terhubung atau terputus di tengah sesi tidak mengganggu apa pun yang sudah di-cache. Server yang selesai terhubung setelah permintaan pertama menyediakan tool-nya sebagai definisi tertunda yang dimuat Claude sesuai kebutuhan.
  • Tool dimuat di awal: menambahkan definisi membatalkan cache, begitu pula menghapusnya dengan sengaja. Ini berlaku ketika tool search berada di bawah ambang auto-nya, dinonaktifkan, atau tidak tersedia, seperti pada model Google Cloud's Agent Platform yang lebih lama dari generasi Claude 4.5, dengan gateway ANTHROPIC_BASE_URL kustom, atau pada deployment Microsoft Foundry yang di-hosting di Azure setelah Claude Code mendeteksi bahwa deployment tersebut menolak tool search.

Tanpa tool search, apakah perubahan server di tengah sesi membatalkan cache bergantung pada apa yang berubah. Untuk setiap perubahan, tabel ini menunjukkan apakah cache dipertahankan dan apa yang terjadi pada definisi tool dalam permintaan berikutnya.

Perubahan di tengah sesi Cache Definisi tool dalam permintaan berikutnya
Server terhubung, atau pembaruan tool dinamis menambahkan tool Dibatalkan Definisi baru ditambahkan
Server terputus tanpa tindakan apa pun dari Anda, seperti proses server stdio yang berhenti Dipertahankan Definisi server tetap tidak berubah. Panggilan ke salah satu tool-nya mengembalikan error alih-alih dijalankan
Server remote terhubung kembali secara otomatis setelah koneksinya terputus Dipertahankan, kecuali permintaan yang dikirim saat server sedang terhubung kembali menambahkan tool WaitForMcpServers, yang membatalkan cache satu kali Definisi server tetap tidak berubah. Permintaan yang dikirim saat server sedang terhubung kembali dapat menambahkan WaitForMcpServers jika percakapan belum mencantumkannya, dan tool tersebut kemudian tetap tercantum selama sisa percakapan
Anda menghapus tool dengan sengaja, seperti dengan aturan deny atau dengan menonaktifkan servernya di /mcp Dibatalkan Definisi dihapus

Ketika Anda melanjutkan percakapan yang tool-nya dimuat ke dalam prefiks, salah satu server MCP-nya mungkin masih dalam proses terhubung saat permintaan pertama dikirim. Jika transkrip mencatat definisi tool server tersebut, permintaan itu menyertakannya sesuai yang tercatat, sehingga permintaan tidak berubah ketika server selesai terhubung dengan tool yang sama.

Mengedit konfigurasi MCP Anda tidak dengan sendirinya mengubah cache. Konfigurasi baru hanya berlaku setelah restart, yaitu saat server terhubung atau terputus.

Mengaktifkan atau menonaktifkan plugin

Ketika Anda mengaktifkan atau menonaktifkan plugin, biaya perubahan tersebut bergantung pada jenis komponen yang disediakan plugin. Kasus-kasus di bawah ini mencakup setiap jenis komponen, kapan Claude Code menerapkan perubahan, dan apa yang terjadi ketika Anda menonaktifkan plugin lagi dalam sesi yang sama.

Komponen plugin yang mempertahankan cache

Claude Code tidak pernah membatalkan cache untuk skill, perintah, agent, hook, monitor, atau tema dari plugin. Claude Code menambahkan kontennya setelah percakapan yang ada, sehingga permintaan berikutnya membayar konten tersebut dan tetap membaca semua yang ada sebelumnya dari cache.

Plugin yang menyediakan server MCP

Ketika Anda mengaktifkan atau menonaktifkan plugin yang menyediakan server MCP, Claude Code mengikuti aturan yang sama seperti saat Anda menghubungkan atau menghapus server MCP.

Plugin code intelligence

Ketika Anda mengaktifkan plugin code intelligence, Claude mendapatkan tool LSP.

Kapan perubahan plugin diterapkan

Perubahan yang Anda buat di menu /plugin diproses melalui /reload-plugins, yang dijalankan Claude Code untuk Anda ketika Anda menutup menu. Anda membayar biayanya, baik berupa pengumuman yang ditambahkan maupun pembacaan ulang penuh, pada giliran pertama setelah perubahan diterapkan. Claude Code juga dapat menerapkan perubahan dengan sendirinya:

  • Untuk plugin dengan sumber command, Claude Code dapat memuat ulang plugin itu sendiri.
  • Ketika Anda menginstal plugin dari antarmuka /plugin, Claude Code dapat mengaktifkannya selama instalasi. Ringkasan instalasi memberi tahu Anda apakah hal itu dilakukan.
  • Ketika Anda memindahkan sesi dengan /cd pada v2.1.246 atau lebih baru, Claude Code menerapkan plugin yang diaktifkan oleh pengaturan direktori baru sebagai bagian dari perpindahan, tanpa peringatan pembacaan ulang penuh yang menahan /reload-plugins.
  • Dalam sesi interaktif, ketika Anda menambah atau menghapus plugin dalam folder plugin yang Anda berikan dengan --plugin-dir, perubahan diterapkan segera. Jika penerapannya akan memicu pembacaan ulang penuh, Claude Code justru menahan perubahan dan menampilkan pemberitahuan untuk menjalankan /reload-plugins. Memerlukan Claude Code v2.1.265 atau lebih baru.

Ketika /reload-plugins berjalan dan reload akan memicu pembacaan ulang penuh, Claude Code menampilkan peringatan dan tidak menerapkan reload. Jalankan /reload-plugins --force untuk tetap menerapkannya.

/reload-plugins juga berjalan dalam sesi tanpa terminal interaktif, seperti aplikasi desktop, Agent SDK, dan mode non-interaktif dengan -p, ketika Anda mengetikkannya langsung ke dalam sesi. Memerlukan Claude Code v2.1.260 atau lebih baru.

Dalam sesi-sesi tersebut, reload menerapkan semuanya kecuali perubahan server MCP plugin, yang berlaku pada sesi Anda berikutnya sehingga tidak pernah menimbulkan biaya pembacaan ulang penuh di tengah sesi.

Plugin yang Anda aktifkan lalu nonaktifkan dalam satu sesi

Ketika Anda menonaktifkan plugin yang Anda aktifkan sebelumnya dalam sesi, Claude Code mengembalikan bentuk permintaan sebelumnya. Jika prefiks itu masih berada dalam masa berlaku cache-nya, permintaan berikutnya membaca entri cache yang lebih lama alih-alih membangun ulang.

Menolak seluruh tool

Jika Anda menambahkan nama tool saja seperti Bash atau WebFetch sebagai aturan deny, Claude tidak dapat memanggil tool tersebut mulai dari permintaan Anda berikutnya, baik Anda menambahkan aturan melalui /permissions maupun dengan mengedit file pengaturan secara langsung. Ini termasuk aturan yang Anda tambahkan melalui /permissions di tengah giliran.

Ketika tool search aktif, yang merupakan default pada model yang didukung, definisi tool dalam permintaan tidak berubah dan prefiks yang di-cache tetap bertahan. Ketika tool search tidak tersedia atau dinonaktifkan, Claude Code menghapus definisi dari permintaan berikutnya, yang membatalkan cache, begitu pula menghapus aturan tersebut nanti.

Hanya aturan deny yang cocok pada posisi nama tool yang memblokir tool dengan cara ini: nama tool saja, bentuk Bash(*) yang setara, atau glob nama tool seperti "*". Glob yang hanya cocok dengan tool MCP, seperti "mcp__*", memblokir tool-tool tersebut dengan cara yang sama. Aturan deny yang dibatasi cakupannya seperti Bash(rm *), serta semua aturan allow dan ask, tidak mengubah tool mana yang dilihat Claude. Claude Code memeriksanya ketika Claude mencoba melakukan panggilan, sehingga prefiks tetap utuh.

Memadatkan percakapan

Compaction menggantikan riwayat pesan Anda dengan ringkasan. Secara desain, ini membatalkan lapisan percakapan, karena permintaan berikutnya memiliki riwayat baru yang lebih pendek yang tidak berbagi prefiks dengan riwayat lama. Claude Code menggunakan kembali lapisan system prompt kecuali percakapan dilanjutkan sambil mempertahankan system prompt yang seharusnya telah berubah; dalam hal itu, compaction pertama beralih ke prompt saat ini dan lapisan tersebut dibangun ulang satu kali. Claude Code memuat ulang konteks proyek dari disk, yang menghasilkan cache hit hanya jika CLAUDE.md dan memori tidak berubah sejak sesi dimulai.

Untuk menghasilkan ringkasan, Claude Code mengirim permintaan terpisah dengan system prompt, tool, dan riwayat yang sama seperti percakapan Anda, ditambah instruksi peringkasan yang ditambahkan sebagai pesan pengguna terakhir. Saat cache hangat, permintaan itu membaca prefiks Anda dari cache, sehingga /compact di tengah sesi hanya memakan sebagian kecil dari biaya yang tersirat dari ukuran konteks dan menghabiskan sebagian besar waktunya untuk menghasilkan ringkasan.

Setelah jeda yang lebih lama dari masa berlaku cache, tidak ada cache yang tersisa untuk dibaca, sehingga permintaan peringkasan memproses ulang seluruh riwayat sebagai input yang tidak di-cache. Inilah mengapa /compact paling mahal ketika Anda melanjutkan sesi lama. Baik dalam kondisi cache hangat maupun dingin, giliran setelah compaction membangun ulang cache percakapan hanya untuk ringkasan yang jauh lebih pendek, sehingga giliran itu bukan bagian yang lambat.

Mengakumulasi banyak gambar

API membatasi berapa banyak gambar dan PDF yang dapat dibawa setiap permintaan. Untuk angka terkini, lihat Request limits dalam dokumentasi API. Claude Code juga membatasi ukuran total gambar dan PDF dalam satu permintaan, sehingga screenshot besar mencapai batas dengan jumlah gambar yang lebih sedikit dibandingkan screenshot kecil.

Ketika permintaan berikutnya akan melampaui salah satu batas, Claude Code menghapus sekumpulan gambar dan PDF tertua dari apa yang dikirimnya, yang menyisakan ruang untuk lebih banyak gambar sebelum perlu menghapus lagi. Claude tidak dapat lagi melihat gambar yang dihapus. Jika Claude membutuhkan salah satunya lagi, bagikan kembali.

Menghapus gambar mengubah pesan yang memuatnya, sehingga permintaan berikutnya memproses ulang percakapan mulai dari pesan paling awal di antara pesan-pesan tersebut. Karena Claude Code menghapus sekumpulan gambar sekaligus, Anda melihat satu giliran yang lebih lambat per kumpulan, bukan satu untuk setiap screenshot baru.

Meng-upgrade Claude Code

Versi baru Claude Code biasanya memperbarui system prompt atau definisi tool, sehingga percakapan pertama yang Anda mulai setelah upgrade membangun cache-nya dari awal. Auto-update mengunduh versi baru di latar belakang tetapi menerapkannya pada peluncuran berikutnya, tidak pernah di tengah sesi, sehingga Anda melihat hal ini sebagai giliran pertama yang tidak di-cache setelah restart, bukan kejutan di tengah sesi. Atur DISABLE_AUTOUPDATER=1 untuk mengontrol kapan upgrade diterapkan.

Tindakan yang mempertahankan cache

Tindakan-tindakan ini baik menambahkan ke akhir percakapan atau tidak menyentuh permintaan sama sekali. Beberapa di antaranya, seperti mengedit CLAUDE.md, mempertahankan cache karena alasan yang sama mengapa perubahan tidak mencapai sesi yang sedang berjalan sampai /clear, /compact, atau restart.

Mengedit file di repositori Anda

Konten file memasuki konteks hanya ketika Claude membacanya, dan pembacaan menambahkan ke percakapan. Mengedit file yang sebelumnya dibaca Claude tidak secara retroaktif mengubah pembacaan sebelumnya dalam riwayat. Sebaliknya, Claude Code menambahkan <system-reminder> yang mencatat file berubah, dan Claude membacanya kembali jika diperlukan.

Mengedit CLAUDE.md di tengah sesi

File CLAUDE.md tingkat project-root dan user-level Anda dibaca sekali pada awal sesi dan disimpan dalam memori. Mengeditnya di tengah sesi tidak membatalkan cache, tetapi edit juga tidak berlaku. Claude terus bekerja dengan versi yang dimuat pada awal sesi. Konten baru dimuat pada /clear, /compact, atau restart berikutnya.

File CLAUDE.md bersarang di subdirektori dan aturan dengan frontmatter paths: dimuat kemudian, sesuai kebutuhan. Mengedit salah satunya sendiri sebelum dimuat memang berlaku. Setelah dimuat, konten adalah bagian dari riwayat percakapan, jadi edit di tengah sesi tidak secara retroaktif mengubahnya.

Mengubah mode izin

Beralih antara mode izin, seperti dari Manual ke accept edits, tidak mengubah system prompt atau definisi tool, jadi perubahan mode aman untuk cache. Pengecualiannya adalah plan mode dengan pengaturan model opusplan, yang mengalihkan model antara Opus dan Sonnet saat Anda memasuki atau meninggalkan plan mode. Itu membuat toggle mode menjadi model switch.

Mengubah gaya output

Ketika Anda beralih gaya output di tengah sesi dengan /output-style, /config, atau pengaturan outputStyle, Claude menggunakan gaya baru mulai dari pesan Anda berikutnya. Claude Code mengirimkan instruksi gaya baru sebagai pesan dalam percakapan, jadi permintaan itu masih membaca system prompt dan percakapan sebelumnya dari cache.

Sebelum v2.1.251, perubahan gaya di tengah sesi mempertahankan cache tetapi tidak berlaku sampai Anda menjalankan /clear atau memulai sesi baru.

Memanggil skills dan commands

Skills dan commands menyuntikkan instruksi mereka sebagai pesan pengguna pada titik pemanggilan. Tidak ada yang lebih awal dalam percakapan berubah. Skill atau command yang frontmatter-nya menamai model dapat menjadi model switch untuk giliran itu.

Menjalankan `/recap`

/recap menghasilkan ringkasan untuk ditampilkan di terminal Anda. Tidak seperti /compact, ini menambahkan ringkasan sebagai output command daripada mengganti riwayat pesan Anda, jadi prefix yang di-cache tetap utuh.

Memutar ulang percakapan

/rewind memotong percakapan Anda kembali ke giliran sebelumnya. Riwayat yang tersisa adalah konten yang sama yang dibangun cache darinya pada titik itu, dan system prompt serta lapisan konteks proyek tidak berubah, jadi permintaan berikutnya mencapai entri cache yang lebih awal. Setiap giliran sejak saat itu telah membaca melalui prefix itu, yang menjaga entri tetap hangat bahkan jika giliran asli lebih lama dari TTL.

Memulihkan checkpoint file bersama percakapan tidak memiliki efek terpisah pada cache. Konten file memasuki konteks hanya ketika Claude membacanya, sama seperti mengedit file di repositori Anda.

Melanjutkan sesi

Ketika Anda melanjutkan sesi, Claude Code mengirimkan seluruh percakapan lagi, dan permintaan membaca dari cache bagian mana pun dari prefiks yang tidak berubah dan masih dalam masa pakai cache. Tabel lapisan di bagian atas halaman ini mengatakan apa yang berubah di setiap lapisan.

Prompt sistem akan berubah setelah upgrade Claude Code atau dengan teks --append-system-prompt yang berbeda pada resume. Secara default, percakapan yang dilanjutkan mempertahankan prompt sistem yang dimulainya, sehingga riwayatnya masih berada di belakang prompt yang sama, dan perubahan berlaku setelah percakapan dikompakkan atau dalam percakapan baru. Bendera prompt sistem dalam percakapan yang dilanjutkan mencakup kasus di mana Claude Code membangun kembali prompt pada setiap permintaan sebagai gantinya.

Cache lifetime

Prefix yang di-cache kedaluwarsa setelah periode tidak aktif. Setiap permintaan yang mencapai cache mengatur ulang timer, jadi cache tetap hangat selama Anda terus bekerja. Setelah jeda yang cukup lama, permintaan berikutnya menghitung ulang input penuh dan membangun kembali cache, itulah mengapa giliran pertama kembali setelah menjauh dapat terasa jauh lebih lambat.

Pada paket Pro atau Max, ketika Anda melanjutkan sesi besar setelah istirahat lama, Claude Code menawarkan untuk melanjutkan dari ringkasan sehingga permintaan nanti tidak membawa riwayat penuh.

Time to live (TTL) mengontrol berapa lama jeda yang cache bertahan. API menawarkan dua: TTL lima menit, dan TTL satu jam yang menjaga cache tetap hangat melalui istirahat yang lebih lama tetapi menagih penulisan cache dengan tarif lebih tinggi. TTL yang lebih lama membantu ketika Anda meninggalkan sesi idle dan kembali ke sana, karena Anda melewati pemrosesan ulang yang dikenakan prefix yang kedaluwarsa. Ini lebih mahal pada ledakan pekerjaan singkat yang tidak pernah idle melampaui lima menit, di mana tarif penulisan yang lebih tinggi berlaku dan masa pakai cache yang lebih lama tidak digunakan.

TTL mana yang diterima setiap permintaan

Claude Code memutuskan TTL per permintaan, dan setiap permintaan jatuh dalam salah satu dari dua bucket tetap:

  • Main conversation: giliran interaktif Anda, run -p non-interaktif, dan giliran Agent SDK, ditambah pembantu yang Claude Code jalankan inline dengan mereka
  • Everything else: permintaan yang Claude Code buat di luar percakapan itu, seperti subagents, workflows, teammates dalam proses, fork, compaction, dan judul sesi

Kecuali Anda memilih TTL sendiri, Claude Code meminta TTL satu jam hanya pada langganan Claude dalam penggunaan yang disertakan paket Anda. Di sana ia meminta jam untuk percakapan utama, ditambah serangkaian kecil permintaan pembantu yang Anthropic kontrol di sisi server. Tabel ini memberikan TTL default setiap bucket di bawah kedua jenis penagihan.

Request bucket Claude subscription, within plan usage Usage credits, API key, or cloud provider
Main conversation One hour Five minutes
Everything else Five minutes, except the server-controlled helper requests, which get one hour Five minutes

Setelah Anda melampaui batas penggunaan paket Anda dan Claude Code menggunakan kredit penggunaan, Anda ditagih untuk penggunaan itu, jadi Claude Code menurunkan percakapan utama ke TTL lima menit, yang menagih penulisan cache dengan tarif lebih rendah. Untuk menjaga TTL satu jam di sana, pilih TTL sendiri.

Pilih TTL sendiri

Anda dapat mengatur TTL untuk salah satu bucket. Setiap kontrol mengambil 5m atau 1h, dan Claude Code mengabaikan nilai lainnya.

Kedua pengaturan dan kedua variabel lingkungan memerlukan Claude Code v2.1.242 atau lebih baru. Jika Anda masuk dengan API key atau menggunakan penyedia cloud, atur promptCacheTtl ke 1h untuk memberikan percakapan utama cache satu jam. Permintaan di luar itu menjaga default lima menit sampai Anda memilih TTL untuk bucket itu juga.

Ketika lebih dari satu kontrol berlaku, Claude Code mengambil kecocokan pertama dalam urutan ini:

  1. FORCE_PROMPT_CACHING_5M=1, yang memaksa lima menit untuk kedua bucket
  2. Variabel lingkungan bucket
  3. Pengaturan bucket
  4. Untuk permintaan subagent, nilai cacheTtl dalam field frontmatter experimental subagent, yang memerlukan Claude Code v2.1.248 atau lebih baru. Claude Code mengabaikan 1h di sana sementara langganan Claude Anda menggunakan usage credits
  5. ENABLE_PROMPT_CACHING_1H=1, yang meminta satu jam untuk kedua bucket
  6. Default untuk bucket permintaan

Atur FORCE_PROMPT_CACHING_5M=1 ketika Anda men-debug perilaku cache, membandingkan dua TTL, atau mengganti TTL yang lebih lama yang ditetapkan dalam managed settings.

Untuk mengonfirmasi TTL mana yang digunakan penulisan cache percakapan utama Anda, jalankan claude -p "hello" --output-format json dan baca usage.cache_creation dalam hasilnya. Claude Code melaporkan penulisan cache satu jam di bawah ephemeral_1h_input_tokens dan penulisan cache lima menit di bawah ephemeral_5m_input_tokens.

Melalui gateway LLM yang Anda atur dengan ANTHROPIC_BASE_URL, bagian dari permintaan satu jam bepergian dalam header anthropic-beta, jadi konfigurasikan gateway untuk meneruskan header itu tanpa perubahan. TTL satu jam tidak tersedia melalui gateway aplikasi Claude. Di Amazon Bedrock, dukungan prompt caching, panjang prefix yang dapat di-cache minimum, dan ketersediaan TTL satu jam semuanya bervariasi menurut model. Jika hitungan token cache tetap di nol, periksa model yang didukung, wilayah, dan batas dalam dokumentasi Amazon Bedrock.

Cakupan cache

Di Claude Code, cache secara efektif dicakup ke satu mesin dan direktori. Prompt sistem menanamkan jalur auto memory Anda, dan percakapan dibuka dengan pengumuman direktori kerja, platform, shell, dan versi OS. Dua sesi di direktori berbeda oleh karena itu membangun prefix berbeda dan melewatkan cache satu sama lain.

Sesi yang Anda jalankan secara paralel di direktori yang sama membangun prefix yang cocok dan membaca cache satu sama lain. Sesi berurutan berbagi prefix hanya ketika snapshot status git yang diambil pada startup cocok, karena setiap percakapan juga membawa cabang dan commit terbaru dari snapshot itu.

Cache API yang mendasarinya lebih luas. Cache diisolasi di antara organisasi, dan pada beberapa penyedia, di antara workspace dalam organisasi. Dalam batas-batas itu, setiap dua permintaan dengan model dan prefix yang sama membaca cache yang sama. Untuk pemanggil Agent SDK yang menjalankan armada proses otomatis, lihat improve prompt caching across users and machines untuk memindahkan lokasi auto memory keluar dari prompt sistem dan berbagi entri cache prompt sistem di seluruh pengguna dan mesin.

Periksa kinerja cache

Kinerja cache muncul sebagai dua hitungan token yang dilaporkan API pada setiap respons. Cara paling langsung untuk menontonnya secara langsung adalah statusline script yang membaca objek current_usage:

Field Arti
cache_creation_input_tokens Token yang ditulis ke cache pada giliran ini, ditagih dengan tarif penulisan cache
cache_read_input_tokens Token yang disajikan dari cache pada giliran ini, ditagih dengan tarif token cache model, di bawah tarif input standar

Rasio baca-ke-kreasi yang tinggi berarti caching berfungsi dengan baik. Jika kreasi tetap tinggi giliran demi giliran, sesuatu berubah dalam prefix Anda. Bagian actions that invalidate the cache mencantumkan penyebab umum.

Untuk ringkasan per-sesi, jalankan /usage. Setelah respons pertama percakapan utama, Claude Code menambahkan baris Prompt cache (main) ke blok Sesi, menampilkan rasio hit sesi, jumlah miss, dan apakah cache sedang hangat sekarang. Skrip statusline dapat membaca angka yang sama dari objek prompt_cache. Keduanya memerlukan Claude Code v2.1.251 atau lebih baru.

Baris Prompt cache (main) juga menamai kemungkinan penyebab miss terakhir ketika Claude Code dapat mengidentifikasinya, misalnya likely cause: tool definitions changed. Teks kemungkinan-penyebab memerlukan Claude Code v2.1.260 atau lebih baru.

Untuk visibilitas di seluruh organisasi, exporter OpenTelemetry melaporkan token baca dan kreasi cache per pengguna dan sesi. Lihat Monitor usage untuk referensi metrik dan atribut acara.

Subagents dan cache

Subagent memulai percakapannya sendiri dengan prompt sistem dan set alat-nya sendiri, terpisah dari induk. Permintaan pertamanya tidak membaca cache induk, karena kedua prefix berbeda, dan itu menghangatkan cache-nya sendiri di seluruh giliran-nya. Subagents berada di luar bucket TTL percakapan utama, jadi mereka mendapatkan lima menit bahkan pada langganan sampai Anda memilih yang lebih lama.

Cache induk tidak terpengaruh. Dari sisi induk, panggilan dan hasil subagent ditambahkan ke percakapan, meninggalkan prefix induk utuh.

Fork, sebaliknya, mewarisi prompt sistem induk, alat, dan riwayat percakapan dengan tepat, jadi permintaan pertamanya membaca cache induk.

Permintaan lain juga dapat membaca prefix yang di-cache oleh permintaan sebelumnya:

  • Session copies: sesi yang Anda salin dengan /fork menerima instruksi isolasinya sebagai pesan di akhir percakapan yang disalin, jadi cache yang dibangun oleh percakapan asli tetap utuh.
  • Compaction: panggilan summarisasi yang dijelaskan dalam Compacting the conversation menggunakan pendekatan berbagi prefix yang sama.
  • Resumed subagents: ketika Claude melanjutkan subagent, permintaan pertama dari run yang dilanjutkan dapat membaca cache yang di-hangatkan oleh run asli.
  • Workflow fan-outs: dalam workflow fan-out dari agen dengan prefix yang sama, Claude Code menahan semua kecuali yang pertama selama hingga 5 detik secara default, jadi permintaan pertama mereka dapat membaca prefix yang di-cache oleh agen pertama.

Nonaktifkan prompt caching

Menonaktifkan caching kadang-kadang berguna saat men-debug perilaku caching dengan model atau penyedia tertentu. Untuk mematikannya, atur salah satu variabel lingkungan ini ke 1:

Variable Efek
DISABLE_PROMPT_CACHING Nonaktifkan untuk semua model
DISABLE_PROMPT_CACHING_HAIKU Nonaktifkan untuk model Haiku default
DISABLE_PROMPT_CACHING_SONNET Nonaktifkan untuk model Sonnet default
DISABLE_PROMPT_CACHING_OPUS Nonaktifkan untuk model Opus default
DISABLE_PROMPT_CACHING_FABLE Nonaktifkan untuk Fable saja

DISABLE_PROMPT_CACHING_HAIKU berlaku untuk model Haiku default, model yang alias haiku selesaikan. Ini menonaktifkan caching di mana pun model itu berjalan, termasuk percakapan utama ketika itu adalah model utama Anda. Mencakup percakapan utama memerlukan Claude Code v2.1.283 atau lebih baru.

Variabel ini juga mencakup model latar belakang yang Anda atur dengan variabel ANTHROPIC_SMALL_FAST_MODEL yang sudah usang, ketika model itu berbeda dari model utama Anda.

Versi Haiku yang berbeda yang Anda pin sebagai model utama Anda tetap mempertahankan caching; atur DISABLE_PROMPT_CACHING untuk menonaktifkan caching untuk itu.

DISABLE_PROMPT_CACHING_SONNET dan DISABLE_PROMPT_CACHING_OPUS masing-masing berlaku untuk model yang alias sonnet atau opus selesaikan. Jika Anda menetapkan ID model Sonnet atau Opus lain sebagai model utama Anda, model itu tetap mempertahankan caching. Misalnya, sesi pada claude-sonnet-5 tetap mempertahankan caching sementara sonnet selesaikan ke claude-sonnet-5-5. Untuk menonaktifkan caching untuk model itu, atur DISABLE_PROMPT_CACHING.

Untuk menetapkan kebijakan caching di seluruh organisasi, masukkan salah satu dari ini atau TTL variables dalam blok env dari managed settings. Untuk penggunaan normal, biarkan caching diaktifkan.