Claude 5 nesli için context engineering: eski iyi pratiklerin çoğu artık mit

Anthropic’ten teknik ekip üyesi Thariq Shihipar, Claude 5 nesli modeller için context engineering kurallarının nasıl değiştiğini yazdı. Yazının ana tezi şu: geçmişte iyi pratik sayılan birçok şey artık mit haline geldi ve bazıları aktif olarak zarar veriyor.

Yazı, Anthropic’in Claude Code’un kendi system prompt’unda yaptığı değişikliklerden örnekler veriyor. Yani teorik bir öneri listesi değil, şirketin kendi ürününde uyguladığı değişikliklerin dökümü.

Özet tablo: altı değişim

1. Kurallardan muhakemeye

Claude Code ilk çıktığında Anthropic’in önceliği en kötü senaryolardan kaçınmaktı, örneğin dosya silinmesi. Bu, her zaman doğru olmayabilecek ama güçlü yönlendirmeler yazmak anlamına geliyordu. Eski system prompt’tan bir örnek:

Kodda: varsayılan olarak hiç yorum yazma. Asla çok paragraflı docstring veya çok satırlı yorum bloğu yazma, en fazla tek kısa satır. Kullanıcı istemedikçe planlama, karar veya analiz dokümanı oluşturma; ara dosyalardan değil konuşma bağlamından çalış.

Claude Code’un eski system prompt’u

Bu yönlendirme belirli prompt’lar için yanlıştı. Kullanıcının kendi dokümantasyon tercihleri olabilir veya çok karmaşık kodun bazı bölümleri gerçekten çok satırlı yorum bloğu gerektirebilir.

Eski modellerde bu korumalar olmadan Claude’un yazdığı yorumlar birçok durumda hatalı oluyordu ve Anthropic bu takası kabul etmek zorundaydı. Yeni modellerin muhakemesi ise bu kararları açık kural olmadan verebilecek düzeyde.

Yeni system prompt’ta aynı yerde şu var:

Çevresindeki kod gibi okunan kod yaz: yorum yoğunluğunu, isimlendirmeyi ve deyimlerini ona uydur.

Claude Code’un yeni system prompt’u

Fark yalnızca uzunluk değil. Eski talimat bir yasak, yenisi bir ölçüt. İlki her bağlamda aynı davranışı dayatıyor, ikincisi kararı bağlama devrediyor.

2. Örneklerden arayüz tasarımına

Bu, yazının en çok tartışılacak maddesi. Tool kullanımında bir numaralı kural, Claude’a tool’ları nasıl kullanacağına dair örnek vermekti.

Anthropic’in yeni modellerde bulduğu şey ise şu: örnek vermek modeli belirli bir keşif alanına hapsediyor.

Bu, yaygın prompt engineering öğretisinin tersi. Few-shot örnekleme yıllardır standart tavsiyeydi. Yazı bunun artık bir kısıt haline geldiğini söylüyor.

Önerilen alternatif: örnek yerine tool, script ve dosyalarınızın tasarımına odaklanmak. Claude’un elinde hangi parametreler var ve bunlar nasıl daha ifade edici olabilir?

Verilen örnek Todo tool’u. Status alanını pending, in_progress ve completed arasında bir enumeration olarak listelemek, Claude’a nasıl kullanılacağını zaten ima ediyor. “Aynı anda tek bir öğe in_progress olsun” talimatı ise istenen davranışı tanımlıyor.

Yani doğru tasarlanmış bir parametre seti, örnekten daha az yer kaplayıp daha çok bilgi taşıyor. Bu, API tasarımındaki “iyi bir imza dokümantasyona ihtiyaç bırakmaz” fikrinin agent’lara uyarlanmış hali.

3. Progressive disclosure

Claude Code kodlamaya odaklı olduğu için system prompt’u code review ve doğrulama hakkında detaylı bilgi içeriyordu. Bu bilgiler her zaman gerekli değildi ama gerektiğinde kritikti.

Claude Code artık doğru bağlamı doğru zamanda yüklemekte, yani progressive disclosure‘da yetkin. Anthropic bu yüzden doğrulama ve code review’ı Claude Code’un seçerek çağırabileceği ayrı skill‘lere taşıdı.

Aynı yaklaşım tool’lara da uygulanıyor. Bazı tool’lar deferred loading ile geliyor: agent, kullanmadan önce tam tanımlarını ToolSearch ile aramak zorunda. Bu sayede daha fazla tool bulundurmak mümkün oluyor ve bunlar gerekene kadar context yer kaplamıyor.

Yazının bu bölümdeki uyarısı doğrudan bir mit hedefliyor:

Yaygın bir mit, bu dosyaları karşılaşabileceğiniz her bilinen pratiğin merkezi deposu yapmak istediğinizdir, çünkü Claude aksi halde onu bulamaz. Bunun yerine doğru zamanda yüklenebilecek bir dosya ağacı kurmayı düşünün.

Thariq Shihipar, Anthropic

Bu, CLAUDE.md dosyalarının zamanla şişmesinin tam karşılığı. Her karşılaşılan sorun için bir satır eklenip hiç silinmediğinde, dosya bir referans olmaktan çıkıp her oturumda ödenen sabit bir context vergisine dönüşüyor.

4. Tekrardan basit tool açıklamalarına

Eski Claude modelleri bazen tekrarlanan talimatlara ihtiyaç duyuyordu ya da context penceresinin başındaki talimatlar yerine sonundakileri dinlemeye daha yatkındı. Bu yüzden Anthropic’in system prompt’u hem ana bölümde tool’lara referans veriyor hem de tool açıklamasında talimat tutuyordu.

Bulgu: bu tekrarlar silinebiliyor. Tool’ların nasıl kullanılacağına dair talimatlar system prompt yerine tool açıklamalarına konuyor.

Pratik sonucu, tekrarın artık bir sigorta değil bir israf olması. Aynı bilgiyi iki yere yazmak context harcıyor ve iki yer zamanla birbirinden ayrıştığında çelişki üretiyor.

5. CLAUDE.md hafızasından auto-memory’ye

Anthropic eskiden kullanıcıları # kısayoluyla CLAUDE.md dosyasına otomatik yazarak Claude’un hafızasına kayıt yapmaya teşvik ediyordu.

Artık Claude, işle ve kullanıcıyla ilgili hafızaları kendiliğinden kaydediyor.

6. Basit spec’lerden zengin referanslara

Plan modunda Claude Code büyük ölçüde markdown plan dosyalarına dayanıyordu. Benzer bir pratik, uzun projelerde Claude’un başvurması için spec’leri kod tabanında saklamaktı.

Anthropic artık Claude’un giderek daha karmaşık referansları kaldırabildiğini söylüyor. Basit markdown dosyaları yerine kullanılabilecekler:

• HTML artifact’ler (yeni artifacts özelliğiyle üretilenler)
• Kod biçiminde referanslar. Bir spec, detaylı bir test suite olabilir ya da Claude’un port edeceği başka bir kod tabanındaki bir fonksiyon
• Rubric’ler. Belirli bir alandaki zevkinizi doğrulamaya çalışmasını sağlıyor, örneğin iyi bir API tasarımı neye benzer

Rubric yaklaşımı, dynamic workflow’lar kullanıp o rubric’lerle doğrulayıcı agent’lar başlatarak çalışıyor.

Testi spec olarak kullanma fikri özellikle pratik. Bir test suite hem makine tarafından doğrulanabilir hem de yoruma yer bırakmıyor. Markdown’daki “kullanıcı girişi doğrulanmalı” cümlesinin aksine, bir test tam olarak neyin geçmesi gerektiğini söylüyor.

Context’i katman katman kurmak

System prompt. Ürün bağlamına sıkı sıkıya bağlı. Claude’a hangi üründe çalıştığını ve ne yaptığını söylüyor. Claude Code için muhtemelen hiç değiştirmeyeceksiniz, ama kendi agent harness’ınızı kuruyorsanız çok zaman harcamanız gereken yer burası.

CLAUDE.md. Hafif tutun ve reponun ne işe yaradığını kısaca anlatın. Token’ların çoğunu kod tabanındaki gotcha‘lara harcayın. Örnek olarak verilen durum: tipleri tek bir monolitik dosyada tutup başka hiçbir yerde tutmamak gibi bir organizasyon tercihiniz varsa, yazılacak şey odur.

Uyarı net: Claude’un dosya sisteminize veya reponuza bakarak zaten bileceği bariz şeyleri yazmayın. Progressive disclosure’ı yoğun kullanın; işinizi doğrulamak için birkaç özel talimatınız varsa bir verification skill’i oluşturup CLAUDE.md’den ona referans verin.

Skills. Skill’leri, Claude’un gerektiğinde bilgiye ulaşmasını sağlayan hafif rehberler olarak düşünün. Çok önemli alanlar dışında aşırı kısıtlayıcı yapmaktan kaçının. Uzun skill’leri birden fazla dosyaya bölün. En iyi skill’ler, size, ekibinize veya ürününüze özgü görüşleri, bilgiyi ve pratikleri kodlayanlar.

References. Dosyaları @ ile mention ederek referans olarak dahil edebiliyorsunuz. Spec dosyaları, mockup’lar veya tüm kod tabanları olabilir.

Buradaki tavsiye dikkat çekici: genel olarak kod içindeki dosyaları tercih edin, çünkü Claude’un çok iyi bildiği bir dilde açık ve yüksek sadakatli talimat sağlıyorlar. Verilen örnek şu: bir tasarımın HTML mockup’ı, o tasarımın metin açıklamasından veya ekran görüntüsünden genellikle daha iyi sonuç veriyor.

claude doctor

Anthropic, system prompt, skill ve CLAUDE.md dosyalarınızı sadeleştirmenize otomatik olarak yardımcı olacak claude doctor komutunu kullanıma sundu.

claude doctor

Bu yazının değeri, tavsiyelerin kaynağında. Anthropic kendi ürününün system prompt’unda yaptığı değişiklikleri gösteriyor, yani öneriler test edilmiş. Ancak aynı sebeple sınırı da belli: bunlar Anthropic’in kendi modelleri için kendi gözlemleri. Başka sağlayıcıların modellerinde aynı şekilde işleyeceğinin garantisi yok, özellikle örnek vermeyi bırakma tavsiyesi.

Altı maddenin ortak paydası aslında tek bir fikir: eski modellerin zaaflarını telafi etmek için yazılmış her şey artık ölü ağırlık. Tekrarlar, yasaklar, few-shot örnekler, her ihtimale karşı baştan yüklenen bilgi. Hepsi bir zamanlar gerekliydi ve hiçbiri geri alınmadı.

Bu tespit, Microsoft’un Claude Fable 5.1 duyurusunda söylediğiyle örtüşüyor: aşırı scaffolding daha yetenekli bir modelin etkinliğini sınırlayabilir. İki farklı şirket aynı sonuca varıyorsa, prompt temizliği ertelenebilir bir bakım işi olmaktan çıkmış demektir.

Başlamak için pratik yol: CLAUDE.md dosyanızı açıp her satır için “Claude bunu repoya bakarak zaten bilir mi” diye sorun. Bilirse silin. Geri kalanı da her oturumda gerekmiyorsa bir skill’e taşıyın.

Kaynak: https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models