- Uzun süre çalışan ajan ürünlerinde prompt caching, önceki round-trip’lerdeki hesaplamayı yeniden kullanarak gecikmeyi ve maliyeti çarpıcı biçimde azaltan temel teknolojidir; Claude Code’un tüm mimarisi bunun etrafında tasarlanmıştır
- Caching, prefix matching yöntemiyle çalıştığı için statik içeriği öne, dinamik içeriği arkaya yerleştiren sıralama tasarımı maliyet ve performansı belirler
- Oturum ortasında araçlar veya model değiştirilirse önbellek geçersiz olur; bu nedenle araç kaldırmak yerine hafif stub’lar ve durum geçişi araçlarını kullanan dolaylı tasarım zorunludur
- Bağlam penceresi aşıldığında yapılan compaction (özetleyerek küçültme) işlemi de maliyet patlamasını önlemek için üst konuşmanın cache prefix’ini paylaşmalıdır
- Cache hit oranı uptime gibi izlenmeli ve birkaç puanlık cache miss bile ciddi maliyet ve gecikme etkisi yarattığından incident olarak ele alınmalıdır
- “Cache Rules Everything Around Me” ajanlar için de aynen geçerlidir
- Prompt caching sayesinde Claude Code gibi uzun süre çalışan ajan ürünlerini mümkün kılmak mümkün olur
- Önceki round-trip’in hesaplamasını yeniden kullanarak latency ve cost üzerinde büyük düşüş sağlar
Prompt caching nasıl çalışır ve sistem prompt’u nasıl yerleştirilir
- Prompt caching, prefix matching yöntemiyle çalışır ve API, isteğin başlangıcından her bir
cache_control kesme noktasına kadar olan tüm içeriği önbelleğe alır
- İstekler arasında paylaşılan prefix’i en üst düzeye çıkarmak esastır; bunun için statik içerik önce, dinamik içerik sonra yerleştirilmelidir
- Claude Code’daki yerleşim sırası:
- Statik sistem prompt’u ve araçlar (genel önbellekleme)
- Claude.MD (proje içi önbellekleme)
- Oturum bağlamı (oturum içi önbellekleme)
- Konuşma mesajları
- Bu sıra şaşırtıcı derecede kolay bozulur ve
statik sistem prompt’una ayrıntılı zaman damgası eklemek,
araç sırasının deterministik olmayan şekilde karıştırılması,
araç parametrelerinin güncellenmesi
gibi nedenlerle önbellek geçersizleşebilir
Sistem mesajlarını kullanan güncelleme stratejisi
- Zaman bilgisinin değişmesi veya kullanıcının dosya değiştirmesi gibi, prompt içindeki bilginin bayatlayabildiği durumlar vardır
- Prompt’u doğrudan güncellemek cache miss’e yol açarak kullanıcı maliyetini artırabilir
- Bunun yerine bir sonraki turda mesaj olarak iletme yöntemi kullanılır
- Claude Code, bir sonraki user message veya tool result içine
<system-reminder> etiketiyle güncel bilgiyi ekler
- Örneğin “artık Wednesday” gibi bir zaman güncellemesi verir
- Böylece system messages kullanılarak önbellek korunabilir
Oturum ortasında model neden değiştirilmemeli
- Prompt cache’i modele özgüdür, bu yüzden önbellekleme maliyet hesabı sezgiyle uyuşmayabilir
- Örnek: Opus ile 100k token’lık bir konuşmada basit bir soru için Haiku’ya geçilirse, Haiku için cache baştan kurulmak zorunda kalır; bu da soruyu Opus ile yanıtlamaktan daha pahalı olabilir
- Model geçişi gerekiyorsa en iyi yöntem sub-agent yaklaşımıdır; Opus’un diğer modele bir "handoff" mesajı hazırlayıp iletmesi şeklinde
- Claude Code’un Explore agent’ı Haiku kullandığında bu yöntemi uygular
Oturum ortasında araç ekleme veya kaldırma yasak
- Araç kümesini değiştirmek, önbellek geçersizliğinin en yaygın nedenlerinden biridir
- Araçlar cache’lenmiş prefix’in bir parçası olduğundan, tek bir aracı eklemek ya da kaldırmak tüm konuşmanın önbelleğini geçersiz kılar
-
Plan Mode — cache odaklı tasarım
- Sezgisel yaklaşım: kullanıcı plan mode’a girince yalnızca salt okunur araçları bırakmak → önbelleği bozar
- Gerçek tasarım: tüm araçları her zaman isteğe dahil etmek ve EnterPlanMode ile ExitPlanMode’u araç olarak uygulamak
- Plan mode’a girildiğinde sistem mesajıyla talimat verilir: yalnızca kod tabanını incele, dosya düzenleme yapma, tamamlayınca ExitPlanMode çağır
- Araç tanımları asla değişmez
- Ek fayda: EnterPlanMode modelin doğrudan çağırabildiği bir araç olduğu için, zor bir problem algılandığında otonom biçimde plan mode’a geçmek mümkündür ve önbellek bozulmaz
-
Tool Search — kaldırmak yerine lazy loading
- Claude Code’da onlarca MCP aracı yüklenebilir; hepsini dahil etmek maliyeti yükseltir, kaldırmak ise önbelleği bozar
- Çözüm: defer_loading yaklaşımıyla, araçları kaldırmak yerine yalnızca adlarını içeren hafif stub’lar (
defer_loading: true) göndermek
- Model ihtiyaç duyduğunda ToolSearch aracı üzerinden tam şemayı yükler
- Aynı stub’lar her zaman aynı sırada bulunduğu için cache’lenmiş prefix kararlı kalır
- API’nin tool search özelliğiyle bu daha da kolaylaştırılabilir
Context forking — compaction
- Bağlam penceresi aşıldığında, konuşma özetlenerek yeni bir oturum başlatılan bir compaction işlemine girer
- Sezgisel uygulama (farklı sistem prompt’u ve araçlar olmadan ayrı bir API çağrısıyla özet üretmek), ana konuşmanın cache prefix’iyle hiç eşleşmediği için tüm giriş token’ları tam ücretlendirilir
-
Cache-Safe Forking çözümü
- Compaction çalıştırılırken üst konuşmayla aynı sistem prompt’u, kullanıcı bağlamı, sistem bağlamı ve araç tanımları kullanılır
- Üst konuşmanın mesajları öne yerleştirilir ve compaction prompt’u sona yeni bir kullanıcı mesajı olarak eklenir
- API açısından bu istek, üst konuşmanın son isteğiyle neredeyse aynıdır; bu yüzden cache’lenmiş prefix yeniden kullanılabilir ve yeni token’lar yalnızca compaction prompt’undan ibarettir
- Bağlam penceresi içinde compact mesajı ve özet çıktı token’ları için bir "compaction buffer" bırakmak gerekir
- Anthropic bu kalıba dayanarak compaction özelliğini doğrudan API’ye yerleştirmiştir; geliştiriciler de bunu doğrudan kullanabilir
Temel derslerin özeti
- Prompt caching prefix matching’dir; prefix’in herhangi bir yerindeki değişiklik, ondan sonraki tüm cache’i geçersiz kılar → tüm sistem bu kısıt etrafında tasarlanmalıdır
- Sistem prompt’unu değiştirmek yerine konuşma sırasında sistem mesajı eklemek, önbelleği korumak açısından daha avantajlıdır
- Konuşmanın ortasında araçları veya modeli değiştirmeyin → durum geçişlerini araç olarak modelleyin, araç kaldırmak yerine lazy loading kullanın
- Cache hit oranı uptime gibi izlenmelidir; birkaç puanlık cache miss oranı bile maliyet ve gecikme üzerinde dramatik etki yaratır
- Fork işlemleri (compaction, özetleme, skill çalıştırma) üst konuşmanın prefix’ini paylaşmalıdır ki cache hit mümkün olsun
- Bir ajan geliştiriyorsanız, ilk günden itibaren prompt caching merkezli tasarım yapmalısınız
5 yorum
Prompt engineering'den context engineering'e geçişin kilit nokta olduğu söyleniyor; pratikte ise cevap galiba "ilgi alanlarının ayrılması".
Persona, davranış kuralları ve belleği ayrı dosyalarda yönetmek, context rot'u azaltmada etkili oluyor. Monolitik bir prompt yerine yalnızca gereken dosyaları yüklemek, attention budget açısından çok daha avantajlı. Bu yüzden OpenClaw (veya benzer framework'ler) persona (
SOUL.md), davranış kuralları (AGENTS.md) ve belleği (MEMORY.md) ayrı ayrı yönetiyor gibi görünüyor.Ah, demek ki Opus’un token fiyatı bu yüzden bu kadar pahalıymış.
Antigravity ile Claude Code’un bağlam yönetimi farkına dair bir inceleme olup olmadığını merak ediyorum.
Aynı Opus modeli ama belli ki aralarında fark vardır. :)
Gerçekten çok faydalı bir yazı.
Asıl hedef kitle:
Claude Code gibi “uzun süre çalışan ajanlar” geliştirenler
(özellikle ürün/platform mühendisleri, LLM altyapı mühendisleri)
Kimler için en faydalı olur?
✅ 1) Yapay zeka ajanı ürünleri geliştiren ekipler
✅ 2) LLM maliyeti/gecikmesini optimize eden mühendisler
✅ 3) Bir sürü MCP aracı bağlayan kişiler
Buna karşılık, genel kullanıcılar neredeyse hiç bakmaz
Bu, “prompt nasıl iyi yazılır” türü bir yazı değil
Daha çok, “prompt’u ürün mimarisi seviyesinde nasıl ele almak gerekir” üzerine
Tek cümleyle özet
Bu, LLM’yi bir “sohbet” değil bir “üretim sistemi” olarak inşa edenlere yönelik bir yazıdır.
Docker katmanı optimizasyonundan farksız gibi görünüyor.