# Designing and Versioning Prompt Templates

> Source: https://sukruyusufkaya.com/en/learn/claude-ustaligi/prompt-sablon-tasarimi
> Updated: 2026-05-13T09:29:28.710Z
> Category: Claude Ustalığı
> Module: 2. Prompt Engineering Foundations
**TLDR:** Production prompts should be treated like code: templates, parameters, versions, tests, and monitoring. Learn to manage them with software-grade discipline.

> **Bu derste**
>
> Prompt'u kod gibi yönetmek isteyen ekipler için: şablon dili, parametre yönetimi, semver, A/B test, eval, izleme.

# Promptları Kod Gibi Yönet

Üretimde prompt'lar üç sebeple kod gibi disiplinli yönetilmelidir:

1. **Tekrarlanabilirlik** — Aynı prompt hep aynı sonucu vermeli.
2. **Hesap verebilirlik** — "Bu cevap hangi sürümden geldi?"
3. **Geliştirme döngüsü** — Yeni sürüm geçişi güvenli olmalı.

Bu yüzden prompt'ları **template + parameter** olarak ayır, **semver**'le (örn. `v1.3.2`) etiketle ve test setiyle doğrula.

![Prompt yaşam döngüsü: yaz → test et → review → dağıt → izle → geri besle](/images/learn/claude-ustaligi/diagram-prompt-lifecycle.svg)

_Prompt yaşam döngüsü._

## Şablon Dili Seçimi

Şablon motoru, parametre yerleşimini standartlaştırır. Yaygın seçimler:

### Jinja2 (Python)

```jinja
<role>{{ role }}</role>

<context>
{{ context }}
</context>

<task>{{ task }}</task>

{% if examples %}
<examples>
{% for ex in examples %}
  <example>
    <input>{{ ex.input }}</input>
    <output>{{ ex.output }}</output>
  </example>
{% endfor %}
</examples>
{% endif %}

<input>{{ user_input }}</input>
```

### Mustache (dilden bağımsız)

```mustache
<role>{{role}}</role>
<context>{{context}}</context>
<task>{{task}}</task>
{{#examples}}
<example>
  <input>{{input}}</input>
  <output>{{output}}</output>
</example>
{{/examples}}
<input>{{user_input}}</input>
```

### f-string (Python — en sade)

```python
def build_prompt(role, context, task, user_input):
    return f"""<role>{role}</role>
<context>{context}</context>
<task>{task}</task>
<input>{user_input}</input>"""
```
Küçük projelerde gayet yeterli. Karmaşık döngüler gerektiğinde Jinja'ya geç.

## Versiyon Yönetimi

Prompt'lar **semver**'le takip edilmelidir:

- **MAJOR (v2.0.0):** Davranışı kıran değişiklik. Çağıran kodun da güncellenmesi gerekir.
- **MINOR (v1.4.0):** Geriye dönük uyumlu yetenek eklendi. Yeni alanlar, yeni few-shot.
- **PATCH (v1.4.1):** Yazım, ton, küçük örnek değişimi. Tüm eski cevaplar hala geçerli.

Her sürümü **registry**'de sakla: bir Mongo koleksiyonu, bir git repo, ya da Anthropic console üzerindeki "Prompt Library".

```yaml
# prompts/support_classifier.yaml
id: support_classifier
version: 1.4.1
owner: support_team
created_at: 2026-04-12
updated_at: 2026-05-08
model: claude-sonnet-4-6
temperature: 0.0
max_tokens: 256
system_prompt: |
  Sen müşteri destek bileti sınıflandırıcısısın.
  Sadece geçerli bir JSON cevap ver.
parameters:
  - name: user_message
    type: string
  - name: history
    type: array
    items: string
test_set:
  - id: t-001
    input:
      user_message: "şifremi unuttum"
    expected:
      category: "auth"
  - id: t-002
    input:
      user_message: "kredi kartım reddedildi"
    expected:
      category: "billing"
```

## A/B Test ve Eval

Yeni prompt sürümünü canlıya almadan **eval seti** üzerinde dene. Eval setinin %95'i geçmeden ve insan onayı verilmeden production'a alma.

Üretimde **A/B test**:

- %10 trafiği yeni sürüme yönlendir.
- Anahtar metriklerde (CSAT, çözüm süresi, halüsinasyon oranı) regresyon yoksa %50'ye, sonra %100'e ölçeklendir.
- Regresyonda otomatik rollback.

```python
import random

def get_prompt_version(user_id: str, rollout_percent: float = 0.1) -> str:
    """Stable A/B routing — aynı user her zaman aynı sürümü görsün."""
    h = hash(user_id) % 1000
    return "v1.4.1" if h / 1000 < rollout_percent else "v1.4.0"

users = [f"u{i:04d}" for i in range(20)]
for u in users:
    print(u, "→", get_prompt_version(u, 0.2))
```

### Eval set hangi 5 boyutu kapsamalı?

1. **Doğruluk** — Cevap olgusal olarak doğru mu?
2. **Format uyumu** — JSON / XML schema'ya uyuyor mu?
3. **Halüsinasyon** — Kaynaksız iddialar var mı?
4. **Token bütçesi** — Beklenen sınırlar içinde mi?
5. **Edge case dayanıklılığı** — Çok kısa, çok uzun, boş, prompt-injection denemeleri.

### Üretimde hangi metrikleri izlemeliyim?

- **Latency p50 / p95 / p99**
- **Token in / out per call**
- **Cost per call ve günlük toplam**
- **Eval skoru** (otomatik LLM-as-judge ile)
- **Hata oranı** (model hatası, parse hatası, validasyon hatası)
- **Kullanıcı feedback'i** (👍/👎 oranı)

Modül 9'da observability'e dönerek detayları işleyeceğiz.

**Boşluk doldurma egzersizi (text):**
```text
Üretim prompt'ları kod gibi yönetilmelidir: _____ , parametre, _____ ve eval. Davranışı kıran değişiklikler _____ versiyon yükseltmesi gerektirir. Yeni sürümü canlıya almadan _____ test ile dene.
```

> ✋ Kontrol noktası: `q-206-mc1`

> 📝 İlgili quiz: `module-2-final`

## Modül 2 — Tamam!

Bu modülde Claude'la nasıl konuşulduğunu temelden öğrendin: prompt'un dört kemiği, spesifiklik, few-shot, CoT, XML ve şablon yönetimi. Modül 3'te ileri tekniklere geçiyoruz: persona tasarımı, output format kontrolü, çoklu adım görev ayrıştırma ve token ekonomisi.