Claude Sistem İstemleri: Teknik Dokümantasyon İçin Ton Sınırlarını Nasıl Belirlersiniz?

Teknik dokümantasyon, genellikle gerçeklik açısından başarısız olmadan önce ince detaylarda başarısız olur. Bir taslak doğru olabilir ancak çok samimi, çok tanıtım amaçlı, çok uzun, belirsizlik konusunda çok muğlak veya dokümantasyon setinin geri kalanıyla tutarsız olabilir. Claude'u API rehberleri, sorun giderme makaleleri, sürüm notları, dahili çalışma kılavuzları veya geliştirici dokümantasyonu üretmek için kullanıyorsanız, sistem istemi bu kalıcı yazım sınırlarını tanımlamak için en iyi yerlerden biridir.

Ayrıca dikkat edilmesi gereken güncel bir model davranışı değişikliği bulunmaktadır. Eylül 2026 itibarıyla, Anthropic'in kullanımdan kaldırma dokümantasyonu, Claude Opus 4.7 ve sonrası ile Claude Mythos Önizleme için temperature, top_p ve top_k parametrelerinin kullanımdan kaldırıldığını ve bunun yerine davranış kontrolü için istem (prompting) kullanımının önerildiğini belirtmektedir. Bu durum, tonu öncelikle örnekleme parametreleri aracılığıyla şekillendirmeye çalışan eski yöntemlere kıyasla, açık sistem düzeyindeki stil talimatlarını daha önemli hale getirmektedir. Anthropic'in model ve API kullanımdan kaldırma rehberine bakın.

“Ton sınırı” gerçekte neyi kontrol etmelidir?

Bir ton sınırı, birçok dokümantasyon isteği boyunca stabil kalan iletişim davranışını tanımlamalıdır. Bu sadece “profesyonel görünmek” değildir. Faydalı bir sınır genellikle beş şeyi kapsar: hedef kitle, ses tonu, detay düzeyi, kabul edilebilir belirsizlik dili ve biçimlendirme alışkanlıkları.

Örneğin, geliştiricilere yönelik bir dokümantasyon asistanına, profesyonel ve nötr bir tonla yazması, ilk kullanımda tanıdık olmayan terimleri açıklaması, pazarlama dilinden ziyade doğrudan cümleleri tercih etmesi, doğrulanmış gerçekleri varsayımlardan ayırması ve yalnızca gezinmeyi iyileştirdiğinde başlıkları ve kod bloklarını kullanması söylenebilir.

Anthropic'in güncel istem rehberi, açık ve doğrudan talimatları, bir davranışın neden önemli olduğuna dair bağlamı, ton ve yapı için örnekleri ve bir istem farklı türde bilgileri karıştırdığında XML etiketlerini kullanmayı açıkça önermektedir. Ayrıca, sistem isteminde Claude'a bir rol vermenin davranış ve tonu odaklamaya yardımcı olduğunu belirtmektedir. Anthropic'in istem en iyi uygulamalarına bakın.

Ton kuralları sistem isteminde mi yoksa kullanıcı isteminde mi yer almalıdır?

Kalıcı kuralları sistem istemine, göreve özgü talimatları ise kullanıcı istemine koyun. Sistem istemi, “yazılım geliştiriciler için yaz”, “pazarlama iddialarından kaçın”, “tahmin etmek yerine belirsizliği belirt” ve “öz teknik nesir kullan” gibi kurallar için doğru yerdir. Kullanıcı mesajı ise mevcut işi tanımlamalıdır: Örneğin, “Bu sürüm notlarını kullanarak 4. sürümden 5. sürüme geçiş rehberi yaz.”

Bu ayrım, tekrarı azaltır ve dokümantasyon hattınızı test etmeyi kolaylaştırır. Ayrıca, tek bir görev isteğinin tüm editoryal sesinizi yeniden tanımlamasını engeller.

Basit bir sistem istemi deseni

<role>
Sen bir teknik dokümantasyon yazarısın.
</role>

<audience>
Yazılım geliştiriciler ve sistem yöneticileri için yaz.
Genel teknik okuryazarlığı varsay, ancak ürün özgü terimleri ilk kullanımda açıkla.
</audience>

<tone>
Profesyonel, nötr ve doğrudan bir ton kullan.
Abartı veya tanıtım iddialarından ziyade somut dili tercih et.
Argo, dolgu sözcükleri, emojiler ve abartılı kesinlik ifadelerinden kaçın.
Cümleleri makul derecede kısa tut ve paragrafları odaklı tut.
</tone>

<accuracy>
Komutları, özellikleri, sürümleri, kıyaslamaları veya davranışları uydurma.
Doğrulanmış gerçekleri varsayımlardan veya önerilerden ayır.
Gerekli bilgi eksikse, bilinmeyen şeyi belirt.
</accuracy>

<format>
Açıklayıcı başlıklar kullan.
Listeleri yalnızca gerçekten ayrık adımlar veya kontroller için kullan.
Komutlar ve kod için kod blokları kullan.
Yalnızca makaleyi tekrar eden bir sonuç ekleme.
</format>

Bu yöntem işe yarar çünkü her bölümün tek bir işi vardır. Anthropic, karmaşık istemler için tutarlı ve açıklayıcı XML etiketlerini özellikle önermektedir; böylece model talimatları, bağlamı, örnekleri ve girdileri daha güvenilir bir şekilde ayırt edebilir.

Ton kuralları ne kadar spesifik olmalıdır?

Başka bir yazarın ne demek istediğinizi sormadan onları takip edebileceği kadar spesifik olmalıdır. “Profesyonel ol” ifadesi zayıftır çünkü profesyonel API dokümantasyonu, yönetici mimari notları ve son kullanıcı kurulum talimatları hepsi farklı tınlayabilir.

Daha güçlü bir kural, gözlemlenebilir davranışı tanımlar:

Pozitif talimatlar, genellikle yalnızca yasaklama içeren kurallardan daha kolay uygulanabilir. Sadece “tanıtım amaçlı görünme” demek yerine, istenen alternatifi ekleyin: “Faydaları, kullanıcı sonuçlarıyla bağlantılı somut terimlerle açıkla.”

Ton kurallarının teknik doğruluğa zarar vermesini nasıl engellersiniz?

Stilin kanıtları geçmesine izin vermeyin. Yaygın bir hata, kaynak materyal eksik olduğunda modelin ne yapması gerektiğini tanımlamadan “kendinden emin, otoriter yazım” talep etmektir. Bu durum, faydalı dokümantasyon yerine cilalı belirsizliği teşvik edebilir.

Şöyle bir doğruluk sınırı ekleyin:

Dokümantasyon kaynakları bir gerçeği ortaya koymadığında:
- Ürün yeteneğini isimlendirmeden veya arayüz görünümünden çıkarsama.
- Davranışın doğrulanamadığını belirt.
- Gerçek, görevi tamamlamak için gerekliyse eksik kaynağı iste.
- Varsayımları kesin talimatlara dönüştürme.

Teknik dokümantasyon için bu kural, genellikle “halüsinasyonlardan kaçın” şeklindeki genel bir talimattan daha değerlidir, çünkü kanıt eksik olduğunda beklenen davranışı tanımlar.

Sistem isteminde sözcük bolluğunu belirtmeli misiniz?

Evet, belge uzunluğu ve yoğunluğu önemliyse. Anthropic'in güncel istem rehberi, son Claude modellerinin varsayılan iletişim tarzı ve sözcük bolluğu açısından farklılık gösterdiğini belirtir. Dokümantasyon, görünür cevap uzunluğunu tutarlı bir şekilde kontrol edeceğini varsaymak yerine, gerektiğinde özlülük için açıkça istem yapmayı özellikle tavsiye eder.

Pratik bir dokümantasyon sınırı, sabit bir kelime sayısı yerine yoğunluğu tanımlayabilir:

Eylemde bulunmak için gereken bilgiyle başla.
Talimatı güvenli ve belirsizlikten uzak kılmak için yeterli açıklamayı kullan.
Aynı öneriyi girişte, gövdede ve sonuçta tekrar etme.
Basit düzeltmeler için kısa bölümleri tercih et.
Mimari veya geçiş konuları için ödünleşimleri ve ön koşulları daha derinlemesine açıkla.

Bu, genel bir “her zaman 1.000 kelime yaz” talimatından daha iyi ölçeklenir.

Kaç örnek eklemelisiniz?

Nesir kuralları yorumlamaya yer bıraktığında örnekleri kullanın. Anthropic, örnekleri biçim, ton ve yapıyı yönlendirmenin en güvenilir yollarından biri olarak nitelendirir ve az örnekli (few-shot) istemlere güvendiğinizde yaklaşık üç ila beş ilgili ve çeşitli örnek kullanmanızı önerir.

Dokümantasyon için örnekler, tek bir ses örneğini tekrarlamak yerine farklı durumları kapsamalıdır. Faydalı bir küme; kısa bir sorun giderme cevabı, bir API referans paragrafı, veri kaybı hakkında bir uyarı, sürüme bağlı bir not ve modelin bir şeyin doğrulanmadığını söylemesi gereken bir örneği içerebilir.

Örnekleri, istemin kendisi olacak kadar uzun yapmayın. Amaçları deseni göstermektir, her makalenin mekanik olarak kopyalayacağı gizli bir şablon sağlamak değildir.

Yaygın dokümantasyon türleri için hangi ton sınırları faydalıdır?

“Ton” olarak ne kodlanmamalıdır?

İş mantığını, güvenlik politikasını veya gerçeklik kısıtlamalarını muğlak bir stil bölümüne gömmeyin. “Kimlik bilgilerini asla ifşa etme”, “yalnızca onaylanmış kaynaklardan bilgi kullan” ve “komutları yürütme” davranışsal veya güvenlik kurallarıdır, ton tercihleri değildir. Görünür ve test edilebilir kalmaları için onlara ayrı bölümler verin.

Aynı şey çıktı şemaları için de geçerlidir. Bir uygulama geçerli JSON, tam anahtarlar veya makine tarafından okunabilir alanlar gerektiriyorsa, bunu bir stil tercihi olarak tanımlamak yerine bir çıktı sözleşmesi olarak belirtin.

Bir dokümantasyon sistem istemini nasıl test etmelisiniz?

Onu tek bir başarılı örneğe göre yargılamayın. Normal görevleri ve uç durumları içeren küçük bir değerlendirme seti oluşturun. Faydalı bir test paketi şunları içerebilir:

• Basit bir “bunu nasıl kurarım?” isteği.
• Bozucu değişiklikler içeren bir geçiş rehberi.
• Nihai tona sızmaması gereken, pazarlama ağırlıklı dil içeren bir kaynak belge.
• Eksik sürüm bilgisi içeren bir istem.
• Cevabı sağlanan kaynak tarafından belirlenmeyen teknik bir soru.
• Özlülüğün korunması gereken uzun bir açıklama isteği.
• Organizasyonunuzun dokümantasyon politikasıyla çelişen bir stil isteyen bir kullanıcı talimatı.

Çıktıları açık kriterlere göre inceleyin: doğru hedef kitle, nötr ton, desteklenmeyen iddiaların olmaması, uygun detay, tutarlı terminoloji, net belirsizlik ve kullanılabilir yapı. Anthropic'in istem rehberi ayrıca, yalnızca içgüdüye güvenmek yerine net başarı kriterleri tanımlamayı ve sonuçları doğrulamayı önermektedir.

Sistem isteminin şişmesini nasıl önlersiniz?

Kuralları stabil editoryal politika düzeyinde tutun. Bir cümle birkaç durumu hallediyorsa, onu on iki dar yasakla değiştirmeyin. Son modeller için güncel Anthropic rehberi ayrıca aşırı istem yapmaya karşı uyarır: Daha güçlü talimat takibi, tekrarlanan “KRİTİK” veya “MUTLAKA” kuralları gibi agresif eski ifadelerin, normal ifadelerle zaten takip edilecek davranışları yeni modellerde aşırı tetiklemesine neden olabilir.

İyi bir bakım kuralı, önlediği tekrarlayan hatayı adlandırabildikten sonra bir sistem istemi talimatı eklemektir. Bir kural yalnızca tek bir makale için varsa, onu o makalenin kullanıcı istemine koyun.

Yeniden kullanılabilir teknik dokümantasyon sistem istemi

<role>
Sen kıdemli bir teknik dokümantasyon yazarısın.
</role>

<audience>
Kullanıcı isteğinde belirtilen hedef kitle için yaz.
Eğer hedef kitle verilmezse, teknik okuryazar uygulayıcıları varsay.
Alışılmadık ürün özgü terminolojiyi ilk kullanımda açıkla.
</audience>

<tone>
Açık, profesyonel, nötr Amerikan İngilizcesi kullan.
Eylemde bulunmak için gereken bilgiyle başla.
Abartı, samimi dolgu sözcükleri, şakalar, emojiler, abartılı kesinlik
ve pazarlama metni gibi tınlayan ifadelerden kaçın.
Gerçekler doğrulandığında doğrudan ifadeler kullan.
</tone>

<accuracy>
Ürün davranışını, komutları, arayüz etiketlerini, sürümleri,
kıyaslamaları, sınırlamaları veya test sonuçlarını asla uydurma.
Doğrulanmış gerçekleri, koşullu davranışları, önerileri
ve bilinmeyenleri ayır.
Kanıt yetersizse, bunu açıkça belirt.
</accuracy>

<structure>
Gezinmeye yardımcı olan açıklayıcı başlıklar kullan.
Kısa, odaklı paragrafları tercih et.
Numaralı adımları yalnızca sıralı prosedürler için kullan.
Gerçekten ayrık kontroller veya seçenekler için madde işaretleri kullan.
Komutlar ve kod için kod blokları kullan.
Tekrarlayan özetlerden kaçın.
</structure>

<examples>
Ton veya biçim belirsiz kaldığında, üretim isteminde
3-5 görevle ilgili örnek sağla.
</examples>

<quality_check>
Nihai hale getirmeden önce, cevabın istenen hedef kitleyle eşleştiğini,
tutarlı terminoloji kullandığını, desteklenmeyen iddialardan kaçındığını
ve istenen çıktı biçimini takip ettiğini doğrula.
</quality_check>

Amaç her belgenin aynı tınlamasını sağlamak değildir. Amaç sınırları stabil kılmaktır: Doğruluk coşkuya dönüşmez, belirsizlik tahmine dönüşmez, teknik derinlik gereksiz jargona dönüşmez ve özlülük ön koşulları veya güvenlik bilgilerini ortadan kaldırmaz.

İyi tasarlanmış bir Claude sistem istemi, bir editoryal politika katmanı olarak en iyi şekilde çalışır. Kalıcı sesi ve kalite sınırlarını orada tutun, makaleye özgü gereksinimleri kullanıcı isteminde tutun ve her iki katmanın da okuyucularınızın güvenebileceği dokümantasyon üretmeye devam ettiğini doğrulamak için küçük bir değerlendirme seti kullanın.