Pelajaran dari membangun Claude Code: prompt caching adalah segalanya

• Pada produk agen yang berjalan lama, prompt caching adalah teknologi kunci yang secara drastis menurunkan latensi dan biaya dengan menggunakan kembali komputasi dari round-trip sebelumnya, dan seluruh arsitektur Claude Code dirancang berpusat pada hal ini
• Karena caching bekerja dengan metode pencocokan prefiks, desain urutan yang menempatkan konten statis di depan dan konten dinamis di belakang menentukan biaya dan performa
• Jika tool atau model diubah di tengah sesi, cache akan tidak valid, sehingga desain alternatif yang memanfaatkan stub ringan dan tool untuk perpindahan status menjadi hal yang wajib, alih-alih menghapus tool
• Pekerjaan compaction (meringkas/mengecilkan ringkasan) yang dilakukan saat melampaui context window juga harus berbagi prefiks cache dari percakapan induk agar tidak memicu lonjakan biaya
• Hit rate cache perlu dipantau seperti uptime, dan bahkan beberapa persen cache miss pun dapat berdampak serius pada biaya dan latensi sehingga harus diperlakukan sebagai insiden

---

• “Cache Rules Everything Around Me” juga berlaku apa adanya untuk agen
• Prompt caching memungkinkan produk agen berdurasi panjang seperti Claude Code benar-benar bisa diwujudkan
• Dengan menggunakan kembali perhitungan dari round-trip sebelumnya, latency dan cost bisa ditekan secara signifikan

Cara kerja prompt caching dan penempatan system prompt

• Prompt caching bekerja dengan metode pencocokan prefiks (Prefix), dan API menyimpan cache untuk semua isi sejak awal request hingga setiap titik henti cache_control
• Kuncinya adalah memaksimalkan prefiks bersama antar-request, dan untuk itu konten statis harus ditempatkan lebih dulu, konten dinamis belakangan
• Urutan penempatan di Claude Code:
  • System prompt statis dan tool (cache global)
  • Claude.MD (cache dalam proyek)
  • Konteks sesi (cache dalam sesi)
  • Pesan percakapan
• Urutan ini ternyata sangat rapuh, dan bisa menyebabkan invalidasi cache karena hal-hal seperti:
  detail timestamp dimasukkan ke system prompt statis,
  pengacakan urutan tool yang tidak deterministik,
  pembaruan parameter tool

Strategi pembaruan dengan memanfaatkan system message

• Ada situasi ketika informasi di dalam prompt menjadi usang, misalnya perubahan waktu atau perubahan file oleh pengguna
• Memperbarui prompt secara langsung akan menyebabkan cache miss, yang bisa meningkatkan biaya bagi pengguna
• Sebagai gantinya, gunakan cara mengirimkannya sebagai message pada giliran berikutnya
  • Claude Code menyisipkan informasi pembaruan pada user message berikutnya atau tool result dengan tag <system-reminder>
  • Misalnya memberikan pembaruan waktu seperti “sekarang hari Wednesday”
• Dengan memanfaatkan system messages seperti ini, cache dapat tetap dipertahankan

Mengapa model tidak boleh diubah di tengah sesi

• Prompt cache unik untuk tiap model, sehingga perhitungan biaya caching bisa berbeda dari intuisi
• Contoh: dalam percakapan 100k token di Opus, jika untuk pertanyaan sederhana Anda beralih ke Haiku, maka cache untuk Haiku harus dibangun ulang dari nol, sehingga biayanya justru bisa lebih tinggi dibanding menjawab tetap dengan Opus
• Jika perpindahan model memang diperlukan, pendekatan terbaik adalah pola sub-agent, yaitu Opus menyiapkan dan meneruskan pesan "handoff" ke model lain
  • Explore agent di Claude Code menerapkan cara ini saat menggunakan Haiku

Jangan menambah atau menghapus tool di tengah sesi

• Mengubah himpunan tool adalah salah satu penyebab invalidasi cache yang paling umum
• Karena tool merupakan bagian dari prefiks yang di-cache, menambah atau menghapus satu tool saja akan membatalkan cache seluruh percakapan

• Plan Mode — desain yang berpusat pada cache

  • Pendekatan intuitif: saat pengguna masuk plan mode, hanya menyisakan tool read-only → merusak cache
  • Desain sebenarnya: semua tool selalu disertakan di setiap request, dan EnterPlanMode serta ExitPlanMode diimplementasikan sebagai tool
    • Saat masuk plan mode, instruksi dikirim lewat system message: hanya telusuri codebase, jangan edit file, dan panggil ExitPlanMode saat selesai
    • Definisi tool tidak pernah diubah
  • Keuntungan tambahan: karena EnterPlanMode adalah tool yang bisa dipanggil langsung oleh model, model bisa masuk plan mode secara otonom saat mendeteksi masalah sulit tanpa merusak cache

• Tool Search — lazy loading alih-alih menghapus

  • Claude Code dapat memuat puluhan tool MCP; jika semuanya disertakan biayanya tinggi, tetapi jika dihapus cache akan rusak
  • Solusinya adalah metode defer_loading, yaitu mengirim stub ringan yang hanya berisi nama tool (defer_loading: true) alih-alih menghapus tool
    • Jika diperlukan, model memuat skema lengkap melalui tool ToolSearch
    • Karena stub yang sama selalu ada dalam urutan yang sama, prefiks cache tetap stabil
  • Ini juga bisa disederhanakan melalui fitur tool search pada API

Forking konteks — compaction

• Saat context window terlampaui, dilakukan compaction dengan meringkas percakapan lalu memulai sesi baru
• Implementasi intuitif (membuat ringkasan lewat panggilan API terpisah tanpa system prompt dan tool yang sama) tidak cocok sama sekali dengan prefiks cache dari percakapan utama, sehingga semua token input dikenai biaya penuh

• Solusi Cache-Safe Forking

  • Saat menjalankan compaction, gunakan system prompt, konteks pengguna, konteks sistem, dan definisi tool yang sama seperti pada percakapan induk
  • Tempatkan pesan percakapan induk di depan, lalu tambahkan prompt compaction sebagai user message baru di bagian akhir
  • Dari sudut pandang API, request ini hampir identik dengan request terakhir dari induk sehingga prefiks cache dapat digunakan kembali, dan token baru hanya prompt compaction itu sendiri
  • Di dalam context window perlu disediakan "buffer compaction" untuk pesan hasil kompak dan token output ringkasan
  • Berdasarkan pola ini, Anthropic membangun fitur compaction langsung ke dalam API agar pengembang bisa menerapkannya sendiri

Ringkasan pelajaran utama

• Prompt caching adalah pencocokan prefiks, dan perubahan di titik mana pun dalam prefiks akan membatalkan semua cache setelahnya → seluruh sistem harus dirancang dengan batasan ini sebagai pusatnya
• Daripada mengubah system prompt, lebih baik menyisipkan system message di tengah percakapan agar cache tetap terjaga
• Jangan mengubah tool atau model di tengah percakapan → modelkan perpindahan status sebagai tool, dan gunakan lazy loading alih-alih menghapus tool
• Hit rate cache harus dipantau seperti uptime, karena bahkan beberapa persen cache miss saja bisa berdampak dramatis pada biaya dan latensi
• Pekerjaan fork (compaction, ringkasan, eksekusi skill) harus berbagi prefiks induk agar cache hit bisa terjadi

• Jika Anda membangun agen, rancanglah dengan prompt caching sebagai pusat sejak hari pertama

[tomlee]

Peralihan dari prompt engineering ke context engineering adalah kuncinya, dan secara praktis tampaknya jawabannya adalah "pemisahan kepentingan".

Jika persona, aturan perilaku, dan memori dikelola dalam file yang berbeda-beda, itu efektif untuk mengurangi context rot. Dibandingkan prompt monolitik, memuat hanya file yang diperlukan jauh lebih menguntungkan bagi attention budget. Karena itu, tampaknya OpenClaw (atau framework serupa) mengelola persona (SOUL.md), aturan perilaku (AGENTS.md), dan memori (MEMORY.md) secara terpisah.

[armila]

Ah, jadi itu alasan harga token Opus begitu mahal.
Saya penasaran apakah ada ulasan tentang perbedaan manajemen konteks antara Antigravity dan Claude Code.
Meskipun sama-sama model Opus, pasti ada perbedaannya. :)

[ng0301]

Ini benar-benar artikel yang sangat membantu.

[fantajeon]

Pembaca yang tepat:

Orang-orang yang membuat “agen yang berjalan lama” seperti Claude Code
(khususnya engineer produk/platform, engineer infrastruktur LLM)

Siapa yang akan paling terbantu?
✅ 1) Tim yang membuat produk agen AI

• Agen IDE (jenis Claude Code, Cursor, Copilot Workspace)
• Agen riset
• Agen otomatisasi untuk pekerjaan berdurasi panjang

✅ 2) Engineer yang mengoptimalkan biaya/latensi LLM

• Tulisan ini pada dasarnya adalah: “optimasi prompt caching = performa/biaya produk”
• Orang infrastruktur akan langsung paham saat membacanya.

✅ 3) Orang yang memasang banyak tool MCP

• Masalah cache rusak saat tool ditambah/dihapus
• Masalah memodelkan implementasi plan mode sebagai “tool”

Sebaliknya, pengguna umum hampir pasti tidak akan membacanya

Ini bukan tulisan seperti “cara menulis prompt dengan baik”

Melainkan

“bagaimana prompt harus ditangani di level arsitektur produk”

Ringkasnya dalam satu kalimat

Ini adalah tulisan untuk orang-orang yang membangun LLM bukan sebagai “chat”, melainkan sebagai “sistem produksi”.

[heycalmdown]

Kurang lebih sama seperti optimisasi layer Docker.