# Prompt Debugging: Why Isn't This Working?

> Source: https://sukruyusufkaya.com/en/learn/claude-ustaligi/prompt-debugging
> Updated: 2026-05-13T11:36:39.844Z
> Category: Claude Ustalığı
> Module: 3. Advanced Prompting Techniques
**TLDR:** Prompt not working? Learn a systematic diagnostic tree, logging strategy, and model swap checklist.

> **Hipotez → izole et → düzelt**
>
> Yazılım debug'ı gibi prompt debug'ı da hipotez kurmakla başlar. 'Çalışmıyor' yetersizdir; 'şu girdide şu adımda şu hata oluyor' demek lazımdır.

# Teşhis Ağacı

Prompt çalışmadığında soracağın 5 ardışık soru:

1. **Çıktı format dışı mı geliyor?** → Schema / prefill / validator-loop (Ders 3.2).
2. **Cevap olgusal yanlış mı?** → Bilgi sorunu (RAG / web / kaynak).
3. **Cevap kısa veya yarım mı?** → max_tokens limiti / stop_sequences problemi.
4. **Cevap doğru ama kalitesiz mi?** → Persona, few-shot, model yetkin değil.
5. **Cevap rastgele mi varyant gösteriyor?** → temperature, sampling, prompt'un ambiguite'si.

![Debug karar ağacı: format / olgusal / kısa / kalitesiz / varyant düğümleriyle](/images/learn/claude-ustaligi/diagram-debug-tree.svg)

_Sistematik prompt debug akışı._

## Loglama Stratejisi

Üretimde her çağrıyı şu alanlarla logla:

- **prompt_id**, **prompt_version** (semver)
- **model_id**, **temperature**, **max_tokens**
- **input_token_count**, **output_token_count**
- **system_prompt_hash** (PII'siz)
- **user_input_hash**
- **response_excerpt** (ilk 200 char)
- **eval_score** (varsa LLM-as-judge)
- **user_feedback** (👍/👎)

Bu log Modül 9'da daha derinleşecek; ama prompt'u ilk yazarken bu alanları planla.

```python
# Lightweight prompt logger — production'da CloudWatch / Datadog / Sentry'ye akıt
import json, hashlib, time

def log_call(*, prompt_id, version, model, system, user_input, response, latency_ms):
    rec = {
        "ts": int(time.time()),
        "prompt_id": prompt_id,
        "prompt_version": version,
        "model": model,
        "sys_hash": hashlib.sha256(system.encode()).hexdigest()[:12],
        "input_hash": hashlib.sha256(user_input.encode()).hexdigest()[:12],
        "input_chars": len(user_input),
        "response_excerpt": response[:200],
        "latency_ms": latency_ms,
    }
    print(json.dumps(rec, ensure_ascii=False))
```

### Düzelt 1: 'Daha açık ol' yerine 'Tam olarak böyle ol'

'Daha iyi yaz' yerine "{örnek paragraf}" gibi yaz formatı ver. Modele neyin **iyi** olduğunu önce kendin tanımla.

### Düzelt 2: System prompt'u kısalt, talimatı kullanıcı mesajına taşı

Bazen sistem prompt'u o kadar büyür ki kendi kendiyle çelişir. Persona ve kırmızı çizgileri sistemde tut, görev detayını kullanıcı mesajına al.

### Düzelt 3: Few-shot örneklerini iki katına çıkar (veya yarıya)

Bazen 3 örnek yetersiz, bazen 6 örnek modeli ezberletip dağıtır. Eval setiyle hangi sayının daha iyi çalıştığını ölç.

### Düzelt 4: Modeli yükselt — Sonnet → Opus

Bazı yetenekler model gücünden gelir; ne kadar prompt ezberlersen ezberle Sonnet veremez. Opus'a yükselt, eval skoru artıyorsa kal; yoksa Sonnet'e geri dön (maliyet).

### Düzelt 5: Sıcaklığı (temperature) ayarla

Tutarlı, deterministik cevaplar için `temperature=0` ya da `0.1` kullan. Yaratıcı çıktı için 0.7-1.0. Çoğu üretim adımı için 0-0.3 idealdir.

### Düzelt 6: Negatif komut yerine pozitif yönerge ver

"Cevabı uydurma" yerine "Emin değilsen 'bilmiyorum' yaz ve hangi bilgiyi doğrulamamız gerektiğini listele." Negatif komutlar genelde yetersiz kalır.

**Önce:**
```text
# Önce: belirsiz hata
"Niye yanlış cevap veriyor anlamadım"
```

**Sonra:**
```text
# Sonra: izole hata
- prompt_id: support_classifier@1.4.0
- input: "ödeme yansımadı"
- expected: {"category":"billing"}
- got: {"category":"tech"}
- model: claude-haiku-4-5
- temperature: 0.0
- hipotez: tech ile billing örnekleri benzer formülasyonlarla
  yazılmış, model ayırt edemiyor → daha keskin few-shot ekle.
```

**Boşluk doldurma egzersizi (text):**
```text
Prompt debug akışında ilk 5 soru: format dışı mı, _____ yanlış mı, kısa mı, _____ yetersiz mi, varyant mı? Tutarlı cevaplar için _____ değeri 0 veya 0.1 olmalıdır.
```

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