Bagaimana Claude Code menggunakan prompt caching

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 dan hanya melakukan pekerjaan baru untuk 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 diatur

Setiap kali Anda mengirim pesan di Claude Code, aplikasi membuat permintaan API baru. Model tidak mengingat apa pun di antara permintaan, jadi Claude Code mengirim ulang konteks lengkap: prompt sistem, konteks proyek Anda, setiap pesan sebelumnya dan hasil alat, serta 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-baru ini 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 cara kerja prompt caching dalam referensi API untuk mekanisme yang mendasarinya. Untuk mendapatkan hasil maksimal dari pencocokan prefix, Claude Code mengurutkan setiap permintaan sehingga konten yang jarang berubah di antara giliran datang terlebih dahulu: Perubahan pada layer percakapan meninggalkan prompt sistem dan konteks proyek di-cache. Perubahan pada prompt sistem 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, termasuk konten seperti gaya output yang ditetapkan pada awal sesi. Aturan pencocokan prefix menjelaskan sebagian besar perilaku di halaman ini. Plan mode dan skill loading, misalnya, menambahkan instruksi mereka sebagai pesan percakapan, jadi prefix yang di-cache tetap utuh. Dua pengaturan tidak termasuk dalam teks prompt sama sekali, jadi mereka tidak muncul dalam tabel layer. Mereka berperilaku berbeda untuk caching:

• Model: cache dikunci oleh model, jadi setiap model memiliki cache-nya sendiri. Beralih model menghitung ulang seluruh permintaan bahkan ketika kontennya identik. Lihat Beralih model di bawah.
• Effort level: bukan bagian dari kunci cache atau prompt, jadi mengubahnya di tengah sesi tidak berpengaruh pada cache.

​

Tempat cache berada

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

• API key, langganan Claude, atau Claude Platform on AWS: cache berada di infrastruktur Anthropic, diakses melalui Claude API
• Bedrock atau Vertex AI: cache berada di infrastruktur penyajian penyedia cloud Anda
• Foundry: permintaan merutekan ke infrastruktur Anthropic
• Custom ANTHROPIC_BASE_URL atau LLM gateway: cache berada di mana pun permintaan Anda diteruskan, dan apakah caching berfungsi tergantung pada gateway

Untuk apa yang disimpan dan diproses setiap penyedia, lihat data usage. 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 ini menyebabkan permintaan berikutnya kehilangan sebagian atau seluruh cache. Anda melihat satu giliran yang lebih lambat dan lebih mahal, setelah itu prefix baru di-cache. Sebagian besar dapat dihindari di tengah tugas setelah Anda mengetahui biayanya. Perubahan model atau reconnect MCP dapat terasa gratis sampai Anda memperhatikan giliran yang lebih lambat setelahnya.

• Beralih model
• Menghubungkan atau memutuskan server MCP
• Menolak seluruh tool
• Memadatkan percakapan
• Meningkatkan Claude Code

​

Beralih model

Setiap model memiliki cache-nya sendiri. Beralih dengan /model berarti permintaan berikutnya membaca seluruh riwayat percakapan tanpa cache hits, meskipun kontennya identik. Pengaturan model opusplan diselesaikan ke Opus selama plan mode dan Sonnet selama eksekusi, jadi setiap toggle plan-mode adalah perubahan model dan memulai cache segar.

​

Menghubungkan atau memutuskan server MCP

Definisi alat berada di layer prompt sistem, jadi cache membatalkan ketika set alat MCP yang tersedia untuk Claude berubah di antara giliran. Penyebab paling umum adalah server MCP yang terhubung atau terputus di tengah sesi, yang dapat terjadi tanpa tindakan apa pun dari pihak Anda: proses server stdio keluar, sesi HTTP kedaluwarsa, atau server reconnects secara otomatis setelah kegagalan sementara. Server yang terhubung juga dapat mendorong dynamic tool update yang mengubah daftar alatnya. Mengedit konfigurasi MCP Anda tidak dengan sendirinya mengubah cache. Konfigurasi baru berlaku hanya setelah restart, yaitu ketika server terhubung atau terputus. MCP tool search mengurangi berapa banyak setiap alat berkontribusi pada prefix dengan menunda definisi alat lengkap, tetapi set nama alat masih harus tetap stabil agar cache tetap valid.

​

Menolak seluruh tool

Menambahkan nama tool yang sederhana seperti Bash atau WebFetch sebagai deny rule menghapus tool tersebut dari konteks Claude sepenuhnya. Definisi tool berada di layer prompt sistem, jadi menambah atau menghapus salah satu aturan ini di tengah sesi membatalkan cache dengan cara yang sama seperti server MCP yang terhubung atau terputus. Perubahan berlaku pada giliran berikutnya baik Anda menambahkannya melalui /permissions atau dengan mengedit file pengaturan secara langsung. Hanya nama tool yang sederhana, atau bentuk setara Bash(*), yang memiliki efek ini. Deny rules yang dibatasi seperti Bash(rm *), dan semua allow dan ask rules, tidak mengubah tool mana yang Claude lihat. Claude Code memeriksanya ketika Claude mencoba melakukan panggilan, meninggalkan prefix tetap utuh.

​

Memadatkan percakapan

Compaction menggantikan riwayat pesan Anda dengan ringkasan. Dengan desain, ini membatalkan layer percakapan, karena permintaan berikutnya memiliki riwayat baru yang lebih pendek yang tidak berbagi prefix dengan yang lama. Claude Code menggunakan kembali layer prompt sistem dan memuat ulang konteks proyek dari disk, yang cache-hits hanya jika CLAUDE.md dan memory tidak berubah sejak sesi dimulai. Untuk menghasilkan ringkasan, Claude Code mengirim permintaan satu kali dengan prompt sistem, alat, dan riwayat yang sama dengan percakapan Anda, ditambah instruksi summarisasi ditambahkan sebagai pesan pengguna akhir. Karena berbagi prefix Anda, permintaan itu membaca cache yang ada daripada memproses ulang riwayat lengkap. Sebagian besar waktu compaction dihabiskan untuk menghasilkan ringkasan, bukan untuk cache miss. Giliran yang mengikuti membangun kembali cache percakapan hanya untuk ringkasan yang jauh lebih pendek, jadi giliran pasca-compaction bukan bagian yang lambat.

​

Meningkatkan Claude Code

Versi Claude Code baru biasanya memperbarui prompt sistem atau definisi alat, jadi permintaan pertama setelah upgrade membangun kembali cache dari atas. Auto-update mengunduh versi baru di latar belakang tetapi menerapkannya pada peluncuran berikutnya, tidak pernah di tengah sesi, jadi Anda melihat ini sebagai giliran pertama tanpa cache setelah restart daripada kejutan selama sesi. Atur DISABLE_AUTOUPDATER=1 untuk mengontrol kapan upgrade diterapkan.

​

Tindakan yang menjaga cache

Tindakan ini baik menambahkan ke akhir percakapan atau tidak menyentuh permintaan sama sekali. Beberapa di antaranya, seperti mengedit CLAUDE.md atau mengubah gaya output, juga mengapa perubahan pengaturan menunggu restart untuk diterapkan.

• Mengedit file di repositori Anda
• Mengedit CLAUDE.md di tengah sesi
• Mengubah gaya output
• Mengubah mode izin
• Memanggil skills dan commands
• Menjalankan /recap
• Memutar ulang percakapan
• Menelurkan subagent

​

Mengedit file di repositori Anda

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

​

Mengedit CLAUDE.md di tengah sesi

File CLAUDE.md tingkat akar proyek dan tingkat pengguna dibaca sekali pada awal sesi dan disimpan dalam memori. Mengedit mereka 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 nanti, ketika Claude pertama kali membaca file yang cocok. Mengedit satu sebelum dimuat memang berlaku. Setelah dimuat, konten adalah bagian dari riwayat percakapan, jadi edit di tengah sesi tidak secara retroaktif mengubahnya.

​

Mengubah gaya output

Output style adalah bagian dari prompt sistem, yang Claude Code baca sekali pada awal sesi. Mengubahnya melalui /config atau pengaturan outputStyle di tengah sesi tidak membatalkan cache, tetapi perubahan juga tidak berlaku. Claude terus menggunakan gaya yang dimuat pada awal sesi. Gaya baru dimuat pada /clear atau restart berikutnya.

​

Mengubah mode izin

Beralih di antara permission modes, seperti dari default ke accept edits, tidak mengubah prompt sistem atau definisi alat, jadi perubahan mode aman cache. Pengecualiannya adalah plan mode dengan pengaturan model opusplan, yang beralih model di antara Opus dan Sonnet saat Anda memasuki atau meninggalkan plan mode. Itu membuat toggle mode menjadi model switch.

​

Memanggil skills dan commands

Skills dan commands menyuntikkan instruksi mereka sebagai pesan pengguna pada titik invokasi. Tidak ada yang lebih awal dalam percakapan yang berubah.

​

Menjalankan /recap

/recap menghasilkan ringkasan untuk ditampilkan di terminal Anda. Tidak seperti /compact, ini menambahkan ringkasan sebagai output perintah daripada menggantikan 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 cache dibangun darinya pada saat itu, dan layer prompt sistem dan konteks proyek tidak berubah, jadi permintaan berikutnya mencapai entri cache sebelumnya. 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.

​

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. 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. Claude Code memilih TTL untuk Anda berdasarkan cara Anda melakukan autentikasi, dan Anda dapat menggantinya dengan variabel lingkungan.

​

Pada langganan Claude

Pada langganan Claude, Claude Code meminta TTL satu jam secara otomatis. Penggunaan disertakan dalam paket Anda daripada ditagih per token, jadi TTL yang lebih lama tidak membebani Anda apa pun dan hanya mempengaruhi berapa lama cache Anda tetap hangat. Jika Anda telah melampaui batas penggunaan paket Anda dan Claude Code menggunakan usage credits, Anda ditagih untuk penggunaan itu, jadi Claude Code secara otomatis menurunkan TTL menjadi lima menit.

​

Pada API key atau penyedia pihak ketiga

Pada API key, Bedrock, Vertex, Foundry, atau Claude Platform on AWS, Anda membayar tarif per-token, jadi TTL tetap pada lima menit yang lebih murah secara default. Untuk memilih TTL satu jam, atur ENABLE_PROMPT_CACHING_1H=1. Pada 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 Bedrock.

​

Ganti TTL

Atur FORCE_PROMPT_CACHING_5M=1 untuk memaksa TTL lima menit terlepas dari autentikasi. Ini berguna ketika Anda men-debug perilaku cache, membandingkan dua TTL, atau mengganti ENABLE_PROMPT_CACHING_1H yang ditetapkan dalam managed settings.

​

Cakupan cache

Di Claude Code, cache secara efektif dicakup ke satu mesin dan direktori. Prompt sistem menyematkan direktori kerja, platform, shell, versi OS, dan jalur auto-memory, jadi dua sesi di direktori berbeda membangun prefix berbeda dan melewatkan cache satu sama lain. Itu termasuk worktrees dari repositori yang sama, karena setiap worktree memiliki direktori kerjanya sendiri. 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 pada startup cocok, karena prompt sistem juga menangkap cabang dan commit terbaru. 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 menekan bagian per-mesin dari prompt sistem dan berbagi cache di seluruh 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: 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 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. Ini membangun cache-nya sendiri, dimulai tanpa cache hits pada panggilan pertamanya dan menghangat di seluruh giliran-nya sendiri. Subagents menggunakan TTL lima menit bahkan pada langganan, karena TTL satu jam otomatis berlaku untuk percakapan utama. 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. Panggilan summarisasi compaction yang dijelaskan dalam Compacting the conversation menggunakan pendekatan berbagi prefix yang sama.

​

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: 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.

​

Sumber daya terkait

• Lessons from building Claude Code: Prompt caching is everything: alasan desain untuk plan mode, deferred tool loading, dan compaction
• Explore the context window: apa yang dimuat ke konteks dan kapan
• Reduce token usage: strategi di luar caching untuk mengelola ukuran konteks
• Track and reduce costs: pelacakan token cache dan konfigurasi TTL untuk pemanggil Agent SDK
• Prompt caching: mekanisme API yang mendasarinya, breakpoints, dan pricing