AI ile uygulama geliştirirken sık yapılan hatalara (belirsiz hedefler, zayıf promptlar, eksik değerlendirme, UX boşlukları) ve bunlardan nasıl kaçınılacağına dair pratik rehber.
AI uygulamaları başlangıçta genellikle kolay görünür: bir API bağlarsınız, birkaç prompt yazarsınız ve demo etkileyici görünür. Sonra gerçek kullanıcılar gelir; dağınık girdiler, belirsiz hedefler ve kenar durumlar ortaya çıkar—ve uygulama tutarsız, yavaş veya kendinden emin bir şekilde yanlış olmaya başlar.
Bir “yeni başlayan hatası” yetenekle ilgili değildir. Yeni bir bileşenle inşa etmekle ilgilidir: olasılıksal, bağlama hassas ve bazen makul görünen cevaplar uyduran bir model. Birçok erken başarısızlık, ekiplerin bu bileşeni normal bir kütüphane çağrısı gibi davranmaları yüzünden olur—deterministik, tamamen kontrol edilebilir ve iş hedefleriyle zaten hizalanmış gibi.
Bu rehber hızlıca riski azaltmak için yapılandırıldı. En yüksek etki sağlayan sorunları önce düzeltin (problem seçimi, baz hatlar, değerlendirme ve güven için UX), sonra optimizasyona (maliyet, gecikme, izleme) geçin. Sadece birkaç değişiklik yapmaya zamanınız varsa, sessiz başarısızlıkları engelleyenleri önceliklendirin.
AI uygulamanızı bir zincir olarak düşünün:
Projeler erken başarısız olduğunda sorun genellikle “model kötü” değildir. Zincirdeki bir bağlantı tanımsız, test edilmemiş veya gerçek kullanım ile uyumsuzdur. Aşağıdaki bölümler en yaygın zayıf halkaları ve her şeyi yeniden inşa etmeden uygulayabileceğiniz pratik düzeltmeleri gösterir.
Pratik bir ipucu: hızlı ilerliyorsanız, güvenle yineleyebileceğiniz ve anında geri alabileceğiniz bir ortam kullanın. Koder.ai gibi platformlar burada yardımcı olabilir çünkü akışları hızlıca prototipleyebilir, değişiklikleri küçük tutabilir ve bir deney kaliteyi düşürdüğünde anında snapshot/rollback yapabilirsiniz.
Yaygın bir başarısızlık modu "önce AI ekleyelim" sonra nerede kullanacağımızı aramaktır. Sonuç, demoda etkileyici ama gerçek kullanımda alakasız (veya sinir bozucu) bir özelliktir.
Bir modeli seçmeden veya prompt tasarlamadan önce kullanıcının işini sade bir dille yazın: ne başarmaya çalışıyor, hangi bağlamda ve bugün bunu zorlaştıran ne?
Sonra ölçebileceğiniz başarı kriterleri tanımlayın. Örnekler: “bir yanıt taslağı hazırlama süresini 12 dakikadan 4 dakikaya düşürmek”, “ilk yanıt hatasını %2’nin altına çekmek” veya “bir formun tamamlanma oranını %10 artırmak”. Ölçemiyorsanız, AI'nın yardımcı olup olmadığını söyleyemezsiniz.
Yeni başlayanlar genellikle her şeyi bilen bir asistan yapmaya çalışır. v1 için AI'nın net değer kattığı tek bir iş akışı adımını seçin.
İyi v1'ler genellikle:
Aynı şekilde önemli: v1'de olmayacakları açıkça listeleyin (ek araçlar, birden fazla veri kaynağı, kenar-durum otomasyonu). Bu, kapsamı gerçekçi tutar ve öğrenmeyi hızlandırır.
Her çıktı aynı doğruluk düzeyine ihtiyaç duymaz.
Bu çizgiyi erken çizin. Bu, katı korumalar, kaynak gösterimleri, insan onayı mı gerektiğini yoksa bir “taslak yardımcısı”nın yeterli olup olmadığını belirler.
Şaşırtıcı sayıda AI proje “bir LLM ekleyelim” diyerek başlar ve temel bir soruya cevap vermezler: neye kıyasla?
Şu anki iş akışını belgelemezseniz (veya bir non-AI versiyon oluşturmazsanız), modelin yardımcı olup olmadığını, zarar verip vermediğini veya işi sadece başka bir yere mi taşıdığını söyleyemezsiniz. Ekipler sonuçlar yerine görüşler üzerine tartışır.
En basit işe yarayan şeyi başlatın:
Bu baz hat doğruluk, hız ve kullanıcı memnuniyeti için ölçü çubuğunuz olur. Ayrıca problemin gerçekten “dilsel olarak zor” olan kısımlarını ve hangi kısımların sadece yapı eksikliği olduğunu gösterir.
Birkaç ölçülebilir sonucu seçin ve hem baz hat hem AI için takip edin:
Eğer görev deterministikse (formatlama, doğrulamalar, yönlendirme, hesaplamalar), AI yalnızca küçük bir kısmı—ör. tonu yeniden yazmak—ele almalıdır. Güçlü bir baz hat bunu netleştirir ve AI özelliğinizin pahalı bir geçici çözüm olmasını engeller.
Yeni başlayanların yaygın bir paterni “çalışana kadar promptu dene”dir: cümleyi değiştir, bir kere daha iyi cevap al, ve bunun çözdüğünü varsay. Sorun şu ki, yapılandırılmamış promptlar kullanıcılar, kenar durumlar ve model güncellemeleri arasında farklı davranır. Bir kereki başarı, gerçek veri uygulamaya geldiğinde öngörülemez çıktılara dönüşebilir.
Modelin “anlamasını” ummak yerine işi açıkça belirtin:
Bu, belirsiz bir isteği test edilebilir ve tekrarlanabilir bir şeye çevirir.
Zor vakalar için birkaç iyi örnek (“kullanıcı X sorduğunda, Y gibi cevap ver”) ve en az bir karşı-örnek (“Z yapma”) ekleyin. Karşı-örnekler, sayı uydurma veya var olmayan belgeleri kaynak gösterme gibi kendinden emin ama yanlış cevapları azaltmada özellikle faydalıdır.
Promptları bir varlık gibi yönetin: versiyon kontrolüne koyun, isim verin ve kısa bir değişiklik günlüğü tutun (ne değişti, neden, beklenen etki). Kalite değiştiğinde hızla geri alabilirsiniz ve “geçen hafta kullandığımız prompt” hakkında hafızaya dayanarak tartışmayı bırakırsınız.
Yaygın bir hata LLM'den şirketinize özgü gerçekleri (güncel fiyatlandırma kuralları, dahili politikalar, son ürün yol haritası veya destek ekibinizin kenar durumları nasıl yönettiği) bilmesini beklemektir. Model yine de kendinden emin cevaplar verebilir—and işte yanlış rehberlik böyle yayılır.
LLM'yi sağlanan bağlam üzerinde özetleme, yeniden yazma ve mantık yürütmede iyi olan bir sistem olarak düşünün. O, kurumunuzun canlı veritabanı değildir. Eğitim sırasında benzer işletmeleri görmüş olsa bile, güncel gerçeklerinizi bilemez.
Faydalı bir mental model:
Cevabın kurum içi gerçeğe uyması gerekiyorsa, o gerçeği sağlamalısınız.
RAG ekliyorsanız, bunu “işini göster” sistemi gibi ele alın. Onaylı kaynaklardan spesifik pasajlar getirin ve asistanın bunları atıfla göstermesini zorunlu kılın. Alıntı yapamıyorsanız, bir gerçeği öyle sunmayın.
Bu ayrıca prompt biçimini değiştirir: “İade politikanız nedir?” demek yerine “ekli politika özütünü kullanarak iade politikasını açıklayın ve ilgili satırları alıntılayın” deyin.
Bilinmezlik için açık davranışlar oluşturun: "Eğer verilen kaynaklarda cevap bulamazsanız, bilmiyorum deyin ve sonraki adımları önerin." İyi geri dönüşler arasında insan devri, bir arama sayfasına yönlendirme veya kısa bir açıklayıcı soru yer alır. Bu kullanıcıları ve ekibinizi kendinden emin yanlışlardan korur.
RAG (Retrieval-Augmented Generation) bir AI uygulamasını hızla daha akıllı hissettirebilir: dokümanlarınızı takın, birkaç “ilgili” parça getirip modelin cevaplamasını sağlayın. Yeni başlayan tuzağı ise retrieval'ın otomatik olarak doğruluk anlamına geldiğini varsaymaktır.
Çoğu RAG hatası modelin “hiçten uydurması” değildir—sistemin ona yanlış bağlam vermesidir.
Yaygın sorunlar: metnin fikir ortasında parçalanması (tanımlar kaybolur), alakasız retrieval (en iyi sonuçlar anahtar kelime eşleşiyor ama anlam eşleşmiyor), ve güncelliğini yitirmiş dökümanlar. Getirilen bağlam zayıfsa, model hala kendinden emin bir cevap üretir—sadece gürültüye dayalıdır.
Retrieval'ı arama gibi ele alın: kalite kontrollerine ihtiyacı var. Bazı pratik desenler:
Uygulamanız kararlar için kullanılıyorsa, kullanıcıların doğrulaması gerekir. Her iddia kaynak pasajına, döküman başlığına ve son güncelleme tarihine işaret etsin. Kaynakları UI'da gösterin ve referans verilen bölümü açmayı kolaylaştırın.
İki hızlı test çoğunu yakalar:
Sistem güvenilir şekilde getirme ve atıf yapamıyorsa, RAG sadece karmaşıklık ekliyordur—güven değil.
Birçok yeni başlayan ekip birkaç "güzel görünüyor" demosundan sonra AI özelliği yayınlar. Sonuç önceden bellidir: ilk gerçek kullanıcılar kenar durumlarla, format bozukluklarıyla veya modelin kendinden emin ama yanlış cevaplarıyla karşılaşır—ve bunun ne kadar kötü olduğunu ölçme ya da iyileşme takip etme yolu yoktur.
Küçük bir test seti ve birkaç metrik tanımlamazsanız, her prompt değişikliği veya model yükseltmesi şans işi olur. Bir senaryoyu düzeltirken sessizce beşini bozabilirsiniz.
Binlerce örneğe ihtiyacınız yok. Gerçek kullanıcının ne sorduğunu yansıtan 30–100 vaka ile başlayın:
Beklenen “iyi” davranışı saklayın (cevap + gereken format + belirsizlik durumunda ne yapılacağı).
Kullanıcı deneyimine bağlanan üç kontrolle başlayın:
Basit bir yayına alma kapısı ekleyin: hiçbir prompt/model/konfigürasyon değişikliği, aynı değerlendirme setini geçmeden canlıya gitmesin. CI'da çalıştırılacak hafif bir betik bile “düzelttik… ve bozduk” döngülerini önler.
Başlamak için basit bir kontrol listesi oluşturun ve dağıtım sürecinin yanında tutun (bkz. /blog/llm-evaluation-basics).
Birçok yeni başlayan AI uygulama geliştirme demoda harika görünür: tek temiz prompt, tek mükemmel örnek, tek ideal çıktı. Sorun şu ki, kullanıcılar demo senaryoları gibi davranmaz. Sadece "mutlu yollar"ı test ederseniz, gerçek girdiyle karşılaştığında her şey bozulur.
Prodüksiyon benzeri senaryolar dağınık veri, kesintiler ve öngörülemez zamanlamalar içerir. Test setiniz uygulamanın aslında nasıl kullanıldığını yansıtmalı: gerçek kullanıcı soruları, gerçek belgeler ve gerçek kısıtlar (token limitleri, bağlam pencereleri, ağ sorunları).
Kenar durumlar halüsinasyonların ve güvenilirlik sorunlarının ilk ortaya çıktığı yerlerdir. Şunları test edin:
Tek bir istek çalışması yeterli değildir. Yüksek eşzamanlılık, yeniden denemeler ve yavaş model cevapları deneyin. p95 gecikmeyi ölçün ve cevapların beklenenden uzun sürdüğü durumlarda UX'in hala mantıklı kaldığını doğrulayın.
Modeller zaman aşımına uğrayabilir, retrieval hiçbir şey döndürmeyebilir ve API'ler oran sınırlaması yapabilir. Uygulamanızın her durumda ne yaptığını karar verin: “cevap verilemiyor” durumu göster, daha basit bir yaklaşıma dön, açıklayıcı soru sor veya işi sıraya koy. Hata durumları tasarlanmadıysa kullanıcılar sessizliği "AI yanlış" olarak yorumlayacaktır.
Birçok yeni başlayan AI uygulaması modelin "kötü" olmasından değil, arayüzün çıktının her zaman doğruymuş gibi davranmasından çöker. UI belirsizlikleri ve sınırlamaları sakladığında, kullanıcılar ya AI'ya aşırı güvenip yanılır ya da tamamen güvenmeyi bırakır.
Kontrol etmeyi kolay ve hızlı hale getirin. Faydalı desenler:
Uygulamanız kaynak sağlayamıyorsa bunu açıkça söyleyin ve UX'i otoriter ifadeler yerine taslaklar/öneriler yönünde değiştirin.
Girdi eksikse kendinden emin bir cevap zorlamayın. 1–2 açıklayıcı soru ekleyin ("Hangi bölge?", "Hangi zaman aralığı?", "Hangi ton?"). Bu halüsinasyonları azaltır ve kullanıcıların sistemin onlarla birlikte çalıştığını hissetmesini sağlar.
Kullanıcılar ne olacağını önceden tahmin edebildiğinde ve hatalardan geri dönebildiğinde güven artar:
Amaç kullanıcıları yavaşlatmak değil—doğruluğun en hızlı yol olmasını sağlamaktır.
Birçok yeni başlayan AI uygulaması modelin "kötü" olmasından değil, ne olmaması gerektiğine kimsenin karar vermemesinden başarısız olur. Uygulamanız zararlı tavsiye üretebiliyor, özel verileri açığa çıkarabiliyor veya hassas iddialar uydurabiliyorsa, sadece kalite problemi değil—güven ve sorumluluk sorunu yaşarsınız.
Basit bir “reddet veya yükselt” politikasını sade dille yazın. Uygulamanın neyi yanıtlamaması gerektiğini (kendine zarar verme talimatları, yasa dışı faaliyetler, tıbbi veya hukuki direktifler, taciz) ve hangi durumların insan incelemesi gerektireceğini (hesap değişiklikleri, yüksek riskli öneriler, bir reşit olmayanı içeren durumlar) belirtin. Bu politika üründe uygulanmalı, umuda bırakılmamalıdır.
Kullanıcıların kişisel veri (isim, e-posta, faturalar, sağlık bilgileri) yapıştıracağını varsayın.
Topladığınız veriyi minimize edin ve ham girdileri kaydetmekten kaçının. Kaydetmeden önce hassas alanları kırpın veya tokenize edin. Verinin saklanacağı, eğitim için kullanılacağı veya üçüncü taraflarla paylaşılacağı durumlarda açık onay isteyin.
Debug için günlükler istersiniz ama günlükler sızıntı olabilir.
Saklama süreleri belirleyin, kimlerin konuşmaları görebileceğini sınırlayın ve ortamları (dev vs prod) ayırın. Daha yüksek riskli uygulamalar için audit trail ve inceleme iş akışları ekleyin ki kim neye neden eriştiğini kanıtlayabilesiniz.
Güvenlik, gizlilik ve uyumluluk kağıt işleri değildir—bunlar ürün gereksinimleridir.
Yaygın bir sürpriz: demo anlık ve ucuz görünür, sonra gerçek kullanım yavaş ve pahalı olur. Bu genellikle token kullanımı, yeniden denemeler ve “daha büyük modele geç” kararlarının kontrolsüz bırakılmasından kaynaklanır.
En büyük sürücüler genellikle öngörülebilirdir:
Erken dönemde bile açık bütçeler belirleyin:
Ayrıca prompt ve retrieval'ı gereksiz metin göndermeyecek şekilde tasarlayın. Örneğin, eski konuşma dönüşlerini özetleyin ve tüm dosyalar yerine en alakalı birkaç snippet'i ekleyin.
“İstek başı maliyet”i değil başarılı görev başı maliyeti optimize edin (örn. “sorun çözüldü”, “taslak kabul edildi”, “soru kaynak gösterimle cevaplandı”). İki kez başarısız olan ucuz istek, bir kez başarılı olan biraz daha pahalı istekten daha maliyetli olabilir.
Fiyatlandırma katmanları planlıyorsanız, limitleri erken taslağı çıkartın (bkz. /pricing) ki performans ve birim ekonomisi sonradan sorun olmasın.
Birçok yeni başlayan “doğru” olduğunu düşünerek log toplar—sonra onlara bakmaz. Uygulama yavaş yavaş bozulur, kullanıcılar yollarını bulur ve ekip neyin yanlış olduğunu tahmin etmeye devam eder.
İzleme şu soruları yanıtlamalı: Kullanıcı ne yapmaya çalışıyordu, nerede başarısız oldu ve nasıl düzeltti? Birkaç yüksek-sinyalli olayı takip edin:
Bu sinyaller "sadece kullanılan token" sayısından daha eyleme geçirilebilir.
Kötü cevapları işaretlemeyi kolaylaştırın (başparmak aşağı + isteğe bağlı neden). Sonra bunu operasyonelleştirin:
Zamanla değerlendirme setiniz ürününüzün “bağışıklık sistemi” olur.
Desenlerin kaybolmaması için hafif bir triaj süreci oluşturun:
İzleme ekstra iş değildir—aynı hatayı yeni biçimlerde göndermeyi bırakmanın yoludur.
İlk AI özelliğinizi inşa ediyorsanız, modeli "alt etmeye" çalışmayın. Ürün ve mühendislik tercihlerini açık, test edilebilir ve tekrarlanabilir yapın.
Dört şeyi dahil edin:
Doğru olabilecek en küçük iş akışıyla başlayın.
İzin verilen eylemleri tanımlayın, mümkünse yapılandırılmış çıktı zorunlu kılın ve "Bilmiyorum / daha fazla bilgi gerekli"yi geçerli bir sonuç olarak ekleyin. RAG kullanıyorsanız sistemi dar tutun: az kaynak, sıkı filtreleme ve açık atıflar.
Koder.ai ile inşa ediyorsanız, faydalı bir desen Planlama Modunda başlamak (workflow, veri kaynakları ve reddetme kurallarını açık yapmak), sonra küçük değişikliklerle yinelemek ve prompt veya retrieval tweak'i regresyona soktuğunda snapshots + rollback kullanmaktır.
Yayınlamadan önce doğrulayın:
Kalite düşükse, şu sırayla düzeltin:
Bu ilerlemeyi ölçülebilir tutar—rastgele prompt denemelerinin strateji haline gelmesini engeller.
Eğer her seferinde yığını yeniden inşa etmeden daha hızlı göndermek istiyorsanız, hızlı yineleme ve temiz üretim teslimini destekleyen araçları seçin. Örneğin, Koder.ai chat'ten React frontend, Go backend ve PostgreSQL şemaları oluşturabilir; yine de kaynak kodunu dışa aktarmanıza ve özel alan adlarıyla dağıtmanıza izin verir—AI özelliğiniz prototipten kullanıcıların güvendiği bir şeye döndüğünde kullanışlıdır.
Start by writing the job-to-be-done in plain language and define measurable success (e.g., time saved, error rate, completion rate). Then pick a narrow v1 step in an existing workflow and explicitly list what you’re not building yet.
If you can’t measure “better,” you’ll end up optimizing demos instead of outcomes.
A baseline is your non-AI (or minimal-AI) “control” so you can compare accuracy, speed, and user satisfaction.
Practical baselines include:
Without this, you can’t prove ROI—or even tell if AI made the workflow worse.
Write prompts like product requirements:
Then add a couple of examples and at least one counter-example for “do not do this.” This makes behavior testable instead of vibes-based.
Assume the model does not know your current policies, pricing, roadmap, or customer history.
If an answer must match internal truth, you need to provide that truth via approved context (docs, database results, or retrieved passages) and require the model to quote/cite it. Otherwise, force a safe fallback like “I don’t know based on the provided sources—here’s how to verify.”
Because retrieval doesn’t guarantee relevance. Common failures include bad chunking, keyword-matching instead of meaning, stale documents, and feeding too many low-quality chunks.
Improve trust with:
If you can’t cite it, don’t present it as fact.
Start with a small, representative evaluation set (30–100 cases) that includes:
Track a few consistent checks:
Run it before every prompt/model/config change to prevent silent regressions.
Demos cover “happy paths,” but real users bring:
Design explicit failure states (no retrieval results, timeouts, rate limits) so the app degrades gracefully instead of returning nonsense or going silent.
Make verification the default so users can check quickly:
The goal is that the safest behavior is also the easiest path for users.
Decide upfront what must not happen, and enforce it in product behavior:
Treat these as product requirements, not “later compliance work.”
The biggest drivers are usually context length, tool round trips, multi-step chains, and retries/fallbacks.
Put hard limits in code:
Optimize cost per successful task, not cost per request—failed retries are often the real expense.
