Prompt debug 2026: finding errors and systematic improvement

[Aior]

Prompt debug — yeni bir disiplin​

Klasik yazılım debug, breakpoint koyma, log ekleme, step-by-step izleme ile yapılır. Prompt debug daha bulanık — model neden yanlış cevap verdi, neden bu format'tan saptı, neden hallüsinasyon yaptı? AIOR projelerinde LLM uygulamaları artırdıkça prompt debug ayrı bir disiplin haline geldi.

Hata kategorileri​

Pratikte gözlemlediğimiz LLM hata sınıfları:

• Format hatası — beklenen JSON yerine markdown, veya field eksik.
• Hallucination — model olmayan bir bilgiyi üretiyor.
• Refusal — model gereksiz yere reddediyor.
• Off-topic drift — model konudan sapıyor.
• Constraint violation — system prompt'taki kuralı ihlal etti.
• Tool misuse — yanlış tool çağırdı veya yanlış parametre.

Her hata sınıfının kendi debug yaklaşımı var.

Logging ne yapmalı?​

Prompt debug için zengin log şart. AIOR'ın log şeması:

• Full system prompt (versiyon hash ile).
• Tüm few-shot örnekleri.
• Kullanıcı input'u.
• Tool definition'ları.
• Model'in raw response'u (sanitize edilmeden önce).
• Tool call decisions ve sonuçları.
• Final response.
• Model + version (claude-opus-4-7 gibi).
• Token count (input, output).
• Latency breakdown.

Bu kayıt bir hata oluştuğunda neden meydana geldiğini anlamak için kritik.

Reproducer'lar — bug fix'in temeli​

Klasik yazılım debug'da olduğu gibi, prompt debug'da da reproducer kritik. Hatayı tetikleyen kullanıcı input'u, system prompt versiyonu ve config'i tek bir test case haline getirilmeli. AIOR'da bu test case'ler regression suite'e eklenir — gelecek prompt iterasyonlarında otomatik kontrol edilir.

Eval suite — gold set ile karşılaştırma​

50-100 manuel onaylanmış input/expected-output pair AIOR projelerinde her LLM uygulamasında bulundurulur. Yeni prompt versiyonu deploy etmeden önce eval suite'te çalıştırılır:

• Format compliance (JSON schema valid mi?).
• Semantic similarity (LLM-as-a-judge ile).
• Toxicity / bias check.
• Latency ve token cost.

Sonuç old vs new karşılaştırması raporu — herhangi bir regresyon görünür hale gelir.

A/B testing production'da​

Eval suite controlled ortamda iyi ama production'da gerçek user davranışını test edemez. AIOR'da A/B test pattern'i: yeni prompt %5 trafikte, %95 eski'de. Real metrics karşılaştırılır:

• Customer satisfaction (CSAT, NPS).
• Task completion rate.
• Escalation rate (human agent'a aktarma oranı).
• Average tokens per session.
• Average latency.

Step-by-step debug — Claude Think modu​

Modern LLM'ler "extended thinking" desteği veriyor — model cevabı vermeden önce reasoning step'lerini gösteriyor. Bu mode'da prompt'un nerede ayrıldığı görünür. AIOR'da debug oturumlarında thinking mode'u aktif tutuyoruz; production'da kapatıyoruz (token maliyeti ve latency).

Prompt diff tooling​

İki prompt versiyonu arasındaki farkı görsel olarak göstermek değişikliklerin etkisini anlamayı kolaylaştırır. AIOR'da kullandığımız basit yaklaşım: git diff yeterli, ama daha sofistike tool'lar (PromptLayer, LangSmith) prompt-aware diff sunuyor.

LLM-as-a-judge yaklaşımı​

İki prompt'un çıktısını karşılaştırmak için başka bir LLM'i judge olarak kullanma. AIOR'da Claude'u judge olarak GPT outputlarını karşılaştırırken veya tam tersi durumda kullanıyoruz. Avantaj: scale (yüzlerce eval otomatik). Dezavantaj: judge model'in kendi bias'ları sonuca yansır.

Common bug pattern'leri ve fix'leri[/HEADING>

• JSON output bozuk — Output formatını system prompt'ta vurgulayın, "Output ONLY JSON" gibi.
• Model konu dışına saptı — Scope sınırlarını netleştirin.
• Refusal çok agresif — System prompt'taki guardrail'leri yumuşatın.
• Tool yanlış parametre — Tool description ve örnek call'lar ekleyin.
• Hallucination — RAG ile context inject edin, "verified information only" kısıtı koyun.

Production incident response​

LLM uygulaması production'da hatalı davrandığında AIOR'ın response pattern'i:

• İlk 15 dakika: bilinen rollback (önceki prompt versiyonuna dön).
• İlk saat: incident channel'da iletişim, etkilenen kullanıcı sayısı tespit.
• 24 saat: root cause analizi, reproducer üretimi.
• Post-mortem: regression test'e ekleme, eval suite'i genişletme.

Sonuç​

Prompt debug klasik debug'dan farklı ama disiplinli yaklaşımla yönetilebilir. Zengin logging, gold-set eval, A/B testing, ve incident response disiplin AIOR'ın standart paketi. Sizin tarafınızda prompt debug için en sık kullandığınız teknik ne — LLM-as-judge, gold set eval, yoksa manual review mi?
​

Prompt debug — a new discipline​

Classic software debug uses breakpoints, logs, step-by-step tracing. Prompt debug is fuzzier — why did the model answer wrong, why did it stray from format, why did it hallucinate? As LLM applications grow on AIOR projects, prompt debug has become a separate discipline.

Error categories​

LLM error classes we observe in practice:

• Format error — markdown instead of expected JSON, or missing field.
• Hallucination — model produces non-existent information.
• Refusal — model refuses unnecessarily.
• Off-topic drift — model wanders off the subject.
• Constraint violation — violated a rule in the system prompt.
• Tool misuse — called the wrong tool or wrong parameters.

Each error class has its own debug approach.

What should logging do?​

Rich logging is mandatory for prompt debug. AIOR's log schema:

• Full system prompt (with version hash).
• All few-shot examples.
• User input.
• Tool definitions.
• Model's raw response (before sanitisation).
• Tool call decisions and results.
• Final response.
• Model + version (e.g. claude-opus-4-7).
• Token count (input, output).
• Latency breakdown.

This record is critical for understanding why an error occurred when it does.

Reproducers — the basis of bug fix​

As in classic software debug, reproducers are critical in prompt debug. The user input that triggered the error, system prompt version, and config should be packaged as a single test case. On AIOR projects these test cases are added to a regression suite — automatically checked in future prompt iterations.

Eval suite — gold-set comparison​

50-100 manually approved input/expected-output pairs are maintained on every LLM application at AIOR. Before deploying a new prompt version, it runs against the eval suite:

• Format compliance (is the JSON schema valid?).
• Semantic similarity (via LLM-as-a-judge).
• Toxicity / bias check.
• Latency and token cost.

The result is an old vs new comparison report — any regression becomes visible.

A/B testing in production​

The eval suite is good in a controlled environment but can't test real user behaviour in production. AIOR's A/B test pattern: new prompt on 5% traffic, 95% on old. Real metrics compared:

• Customer satisfaction (CSAT, NPS).
• Task completion rate.
• Escalation rate (handoff to human agent).
• Average tokens per session.
• Average latency.

Step-by-step debug — Claude Think mode​

Modern LLMs support "extended thinking" — the model shows reasoning steps before giving the answer. In this mode, where the prompt diverges becomes visible. AIOR keeps thinking mode on for debug sessions; off in production (token cost and latency).

Prompt diff tooling​

Visually showing the diff between two prompt versions makes the impact of changes easier to grasp. The simple approach at AIOR: git diff is enough, but more sophisticated tools (PromptLayer, LangSmith) offer prompt-aware diffs.

LLM-as-a-judge approach​

Using another LLM as a judge to compare two prompts' outputs. We use Claude as judge comparing GPT outputs or vice versa. Advantage: scale (hundreds of evals automated). Disadvantage: the judge model's own biases reflect on the result.

Common bug patterns and fixes​

• Broken JSON output — emphasise output format in the system prompt, like "Output ONLY JSON."
• Model went off-topic — clarify scope boundaries.
• Refusal too aggressive — soften guardrails in the system prompt.
• Tool with wrong parameters — add tool description and sample calls.
• Hallucination — inject context with RAG, add "verified information only" constraint.

Production incident response​

When an LLM application misbehaves in production, AIOR's response pattern:

• First 15 minutes: known rollback (return to previous prompt version).
• First hour: communication on incident channel, identify affected user count.
• 24 hours: root cause analysis, reproducer creation.
• Post-mortem: add to regression test, expand eval suite.

Bottom line​

Prompt debug differs from classic debug but can be managed with discipline. Rich logging, gold-set eval, A/B testing, and incident response discipline are AIOR's standard package. What's your most-used technique for prompt debug — LLM-as-judge, gold set eval, or manual review?