Prompt Açıklığının Mimari, Veri Modelleri ve Bakım Üzerindeki Etkisi

Prompt Açıklığı Ne Demektir (ve Neden Önemlidir)\n\n“Prompt açıklığı”, ne istediğinizi rekabet eden yorumlara az yer bırakacak şekilde ifade etmek demektir. Ürün açısından bu, açık çıktılar, kullanıcılar, kısıtlar ve başarı ölçüleri olarak görülür. Mühendislik açısından ise girdiler, çıktılar, veri kuralları, hata davranışı ve fonksiyonel olmayan beklentiler (performans, güvenlik, uyumluluk) gibi açık gereksinimlere dönüşür.\n\n### Zincirleme etki: prompt → kod\n\nBir prompt sadece AI'ye ya da ekip arkadaşına verdiğiniz metin değildir. Tüm inşanın tohumu gibidir:\n\n- Prompt niyeti ifade eder (hangi problemi çözüyoruz ve neden).\n- Gereksinimler niyeti test edilebilir ifadelere çevirir.\n- Tasarım kararları gereksinimleri mimari tercihlere (servisler, sınırlar, API'ler, veri depoları) dönüştürür.\n- Kod bu tercihleri ve süreçte yapılan varsayımları uygular.\n\nPrompt net olduğunda, sonraki çıktılar genellikle uyumlu olur: “ne demek istedik” üzerine daha az tartışma, son dakika değişiklikleri daha az ve kenar durumlarda daha az sürpriz yaşanır.\n\n### Belirsizlik neden pahalıdır\n\nBelirsiz promptlar insanları (ve AI'yi) boşlukları varsayımlarla doldurmaya zorlar—ve bu varsayımlar roller arasında nadiren örtüşür. Bir kişi “hızlı” derken alt saniye yanıtları kastedebilir; bir diğeri haftalık rapor için yeterli olduğunu düşünebilir. Bir kişi “müşteri” derken deneme kullanıcılarını dahil edebilir; bir diğeri hariç tutar.\n\nBu uyuşmazlık yeniden çalışmaya yol açar: tasarımlar uygulama başladıktan sonra revize edilir, veri modelleri migrasyon ister, API'ler kırıcı değişiklikler alır ve testler gerçek kabul kriterlerini yakalayamaz.\n\n### Açıklık yardımcı olur, ama mucize değil\n\nNet promptlar temiz bir mimari, doğru veri modelleri ve sürdürülebilir koda ulaşma olasılığını önemli ölçüde artırır—ancak garanti etmez. İncelemeler, ödünleşmeler ve yineleme hâlâ gerekir. Fark şu ki, açıklık bu konuşmaları somut (ve daha ucuz) hâle getirir; aksi takdirde varsayımlar teknik borca dönüşür.\n\n## Açıklığın Mimari Kaliteye Yayılımı\n\nBir prompt belirsizse, ekip (insan ya da AI) boşlukları varsayımlarla doldurur. Bu varsayımlar bileşenlere, servis sınırlarına ve veri akışlarına sertleşir—çoğunlukla kimsenin hangi kararın verildiğini fark etmeden önce.\n\n### Belirsiz promptlar uyumsuz sınırlar oluşturur\n\nPrompt “kimin neyi sahiplenmesini” söylemiyorsa, mimari genellikle “şimdi işe yarayan neyse o”ya doğru kayar. Tek bir ekranı veya acil entegrasyonu karşılamak için ad-hoc servisler yaratılır; stabil bir sorumluluk modeli yoktur.\n\nÖrneğin, “abonelik ekle” gibi bir prompt faturalamayı, hakları ve müşteri durumunu tek bir kapsayıcı modülde karıştırabilir. Sonrasında her yeni özellik ona dokunur ve sınırlar gerçek alanı yansıtmayı bırakır.\n\n### Erken tercihler geri alınması pahalıdır\n\nMimari yol bağımlıdır. Bir sınır seçtiğinizde aynı zamanda şunu da seçmiş olursunuz:\n\n- doğrulamanın nerede yapıldığı\n- iş kurallarının nerede çalıştığı\n- verinin nasıl çoğaltıldığı veya paylaşıldığı\n\nİlk prompt kısıtları (örn. “iade desteklenmeli”, “hesap başına birden fazla plan”, “prorasyon kuralları”) açıklamazsa, esnemeyen sade bir model kurabilirsiniz. Sonradan düzeltmek genellikle migrasyonlar, sözleşme değişiklikleri ve entegrasyonların yeniden test edilmesi anlamına gelir.\n\n### Açıklık dallanma seçeneklerini azaltır\n\nHer netleştirme olası tasarım ağacını daraltır. Bu iyidir: daha az “belki” yolu, kazara mimarileri azaltır.\n\nKesin bir prompt sadece uygulamayı kolaylaştırmaz—ödünleri görünür kılar. Gereksinimler açık olduğunda ekip sınırları kasıtlı seçebilir (ve nedenini belgeleyebilir), derlemeden çıkan ilk yorumu miras almak zorunda kalmaz.\n\n### Belirsizliğin yaygın belirtileri\n\nPrompt belirsizliği hızla ortaya çıkar:\n\n- kapsam genişlemesi (“buradayken şu da yapılsın mı?”)\n- kırılgan entegrasyonlar (parterler belgelenmemiş davranışa dayanır)\n- tekrarlanan mantık (aynı kurallar servisler arasında tekrar uygulanır)\n- karışık sahiplik (kuralın nerede olduğu belirsiz)\n\nNet promptlar mükemmel mimari garanti etmez, ama sistem yapısının gerçek problemi yansıtma ve büyüdükçe sürdürülebilir olma şansını önemli ölçüde artırır.\n\n## Prompttan Sistem Sınırlarına ve Sorumluluklara\n\nNet promptlar sadece bir “cevap” almanızı sağlamaz—aynı zamanda sistemin ne için sorumlu olduğunu ilan etmeye zorlar. Bu, temiz bir mimariyle, nereye ait olmadığı belli olmayan bir özellik yığını arasındaki farktır.\n\n### Hedefler ve non-goallar servis sınırlarını tanımlar\n\nPromptunuz “kullanıcılar faturaları PDF olarak 30 saniye içinde dışa aktarabiliyor” gibi bir hedef belirtirse, bu hemen belirli sorumlulukları çağrıştırır (PDF oluşturma, iş takibi, depolama, bildirimler). “v1'de gerçek zamanlı işbirliği yok” gibi bir non-goal ise websockets, paylaşılan kilitler ve çatışma çözümü gibi unsurların erken eklenmesini engeller.\n\nHedefler ölçülebilir ve non-goallar açık olduğunda daha keskin çizgiler çizebilirsiniz:\n\n- Hangi işlemlerin senkron olması gerektiği (UI bekler) vs. asenkron (arka plan görevleri)\n- Hangi verinin güçlü tutarlılık gerektirdiği vs. “nihai tutarlılığın yeterli” olduğu\n- Neyin ayrı bir serviste olması gerektiği vs. API içinde bir modül olduğu\n\n### Aktörleri ve iş akışlarını bileşenlere eşleyin\n\nİyi bir prompt aktörleri (müşteri, yönetici, destek, otomatik zamanlayıcı) ve tetikledikleri temel iş akışlarını tanımlar. Bu iş akışları bileşenlere temiz şekilde eşlenir:\n\n- UI: formlar, paneller, yükleme/indirme, durum görüntüleri\n- API: doğrulama, orkestrasyon, politika uygulama, toplama\n- Worker'lar: uzun süren görevler, yeniden denemeler, toplu işleme\n- Depolama: kaynak-of-gerçek tablolar, dosya/nesne depolama, denetim logları\n\n### Önden adlandırmanız gereken çapraz-kesen endişeler\n\nPromptlar genellikle mimariyi domine eden “her yerde” gereksinimleri kaçırır: kimlik doğrulama/authorization, denetim, hız sınırları, idempotentlik, yeniden denemeler/zaman aşımı, PII işleme ve gözlemlenebilirlik (loglar/metrikler/izler). Belirtilmezlerse tutarsız uygulanırlar.\n\n### Hızlı kontrol listesi: promptunuz mimari açıdan tam mı?\n\n- Net hedefler + açık non-goallar\n- Aktörler ve üst iş akışları listelenmiş\n- Beklenen ölçek/gecikme ve hata beklentileri\n- Veri sahipliği (kaynak-of-gerçek) ve saklama kuralları\n- Çapraz-kesen endişeler: auth, denetim, hız limitleri, yeniden denemeler\n- Her iş akışı için “Bitti” kriterleri (kabul kriterleri)\n\n## Prompt Açıklığı ve Veri Modeli Doğruluğu\n\nBir veri modeli genellikle SQL yazılmadan çok önce yanlış gider—promptun belirsiz isimler kullanması yüzünden. customer, account, user gibi kelimeler birden fazla gerçek dünyadaki anlama gelebilir ve her yorum farklı bir şema yaratır.\n\n### Belirsiz isimler nasıl dağınık şemalar yaratır\n\nPrompt “müşterileri ve hesaplarını sakla” dediğinde aşağıdaki sorularla karşılaşırsınız:\n\n- customer bir kişi mi, şirket mi yoksa her ikisi mi?\n- account bir fatura profili mi, giriş hesabı mı, banka hesabı mı yoksa abonluk mu?\n- user müşteriyle aynı mı, yoksa müşterileri yöneten bir çalışan mı?\n\nTanımlar yoksa ekipler nullable sütunlar, her şeyi koymak için catch-all tablolar ve type, notes veya metadata gibi aşırı yüklenmiş alanlar ekleyerek telafi eder; bunlar zamanla “her şeyin koyulduğu yer” haline gelir.\n\n### Kesin tanımlar anahtarları, ilişkileri ve kısıtları iyileştirir\n\nAçık promptlar isimleri kurallar olan varlıklara çevirir. Örneğin: “Bir Customer bir kuruluştur. Bir User bir kuruluşa ait olabilen bir giriştir. Bir Account ise her kuruluş için bir faturalama hesabıdır.” Artık güvenle tasarlayabilirsiniz:\n\n- Anahtarlar: customer_id ile user_id birbirinin yerine kullanılamaz\n- İlişkiler: bire-çok mu yoksa çok-çok mu olduğu tahmine bırakılmaz\n- Kısıtlar: benzersizlik (email kuruluş başına), gerekli alanlar, geçerli durumlar\n\n### Veri yaşam döngüsü “ölümsüz” kayıtları önler\n\nPrompt açıklığı ayrıca yaşam döngüsünü kapsamalıdır: kayıtların nasıl oluşturulduğu, güncellendiği, devre dışı bırakıldığı, silindiği ve saklandığı. “Müşteriyi sil” sert silme, yumuşak silme veya yasal saklama ve kısıtlı erişim anlamına gelebilir. Bunu önceden belirtmek kırık yabancı anahtarlar, yetim veriler ve tutarsız raporlama riskini azaltır.\n\n### İsimlendirme tutarlılığı ve aşırı yüklenmiş alanlardan kaçınma\n\nAynı kavram için tablolar ve API'lerde tutarlı isimler kullanın (örn. hep customer_id, bazen org_id kullanmayın). Tekil kavramları aşırı yüklenmiş sütunlar yerine modellemeyi tercih edin—billing_status ile account_status’ı ayrı tutun; tek bir status alanına beş farklı anlam yüklemeyin.\n\n## Güçlü Veri Modelleri İçin Ne Belirtmelisiniz\n\nBir veri modeli, önceden verdiğiniz ayrıntılar kadar iyidir. “Müşterileri ve siparişleri sakla” diyen bir prompt demo için çalışan bir şema üretebilir ama gerçek dünyada kopyalar, importlar ve eksik kayıtlarla başarısız olur.\n\n### Temel varlıklar ve kimlikler\n\nVarlıkları açıkça adlandırın (örn. Customer, Order, Payment) ve her birinin nasıl tanımlandığını belirtin.\n\n- Birincil tanımlayıcılar: UUID mi, email mi, hesap numarası mı, yoksa bileşik anahtar mı?\n- Harici tanımlayıcılar: Kayıtlar diğer sistemlerden senkronize edilecek mi (örn. CRM ID)? Birden fazla harici ID olabilir mi?\n- Benzersizlik kuralları: Email globalde mi benzersiz, tenant başına mı, yoksa hiç benzersiz değil mi?\n\n### Durumlar, geçişler ve yaşam döngüsü kuralları\n\nBirçok model durum belirtilmediği için bozulur. Aşağıdakileri netleştirin:\n\n- İzin verilen durumlar (Taslak → Gönderildi → Ödendi → İade)\n- İzin verilen geçişler ve tetikleyicileri\n- Durumların değiştirilebilir olup olmadığı (örn. “Ödendi” geri alınabilir mi?) ve değişikliklerin nasıl denetleneceği\n\n### Doğrulama, gerekli alanlar ve format\n\nNeyin mevcut olması gerektiğini ve neyin eksik olabileceğini açıkça belirtin.\n\nÖrnekler:\n\n- Gerekli vs opsiyonel alanlar (örn. telefon opsiyonel, faturalama adresi faturalama için gerekli)\n- Alan kısıtları (min/maks uzunluk, izin verilen karakterler)\n- Doğrulama zamanlaması (oluşturma sırasında, güncellemede veya iş akışı kilometre taşlarında)\n\n### Zaman, para, yerel ayar ve zaman dilimi\n\nBunları erken belirtin ki gizli tutarsızlıklar çıkmasın:\n\n- Zaman damgalarını UTC olarak saklayın mı? Orijinal zaman dilimini de saklayın mı?\n- Para birimini ISO 4217 olarak mı saklayın (USD/EUR) ve kuruş/cent birimiyle mi? Yuvarlama kuralları?\n- Yerel biçimlendirme yerine normalize depolama mı?\n\n### Kenar durumlar: kopyalar, birleştirmeler, importlar, eksik veri\n\nGerçek sistemler dağınık gerçekliği yönetmek zorundadır. Şu şekilde başa çıkmayı netleştirin:\n\n- Kopya tespiti ve birleştirme kuralları (hangi alan kazanır, ne korunur)\n- Eksik alanlı import kayıtları (bunlar “eksik” olarak kabul edilebilir mi?)\n- Birden fazla kaynaktan gelen çakışan güncellemeler ve denetim gereksinimleri\n\n## API Sözleşmeleri: Prompt Açıklığının Hızlı Getirisi\n\nAPI sözleşmeleri, prompt açıklığının faydasını en hızlı gördüğünüz yerlerden biridir: gereksinimler açık olduğunda API yanlış kullanılmaya daha zor hale gelir, sürümlendirmesi kolaylaşır ve kırıcı değişiklikler daha az olur.\n\n### Kırıcı değişiklikleri önlemek için spesifik olun\n\n“Siparişleri güncelleyen bir endpoint ekle” gibi belirsiz promptlar uyumsuz yorumlara yol açar (kısmi vs tam güncellemeler, alan adları, varsayılan değerler, async vs sync). Açık sözleşme gereksinimleri erken kararlar aldırır:\n\n- Hangi alanlar yazılabilir, gerekli veya değiştirilemez\n- Güncellemelerin PUT mı (replace) yoksa PATCH mı (partial) olduğu\n- Geriye dönük uyumluluk kuralları (örn. “yeni alanlar opsiyonel olmalı; mevcut alanların anlamını asla değiştirmeyin”)\n\n### Hata işleme: başarısızlık modlarını tasarımın parçası yapın\n\n“İyi hatalar”ın nasıl görünmesi gerektiğini tanımlayın. En azından belirtin:\n\n- Senaryoya göre durum kodları (400 doğrulama, 401/403 yetki, 404 bulunamadı, 409 çakışma, 429 hız sınırı)\n- Tutarlı bir hata gövdesi (makine kodu, insan mesajı, alan düzeyinde detaylar, korelasyon/istek ID'si)\n- Yeniden deneme beklentileri: hangi hatalar yeniden denenebilir ve önerilen backoff davranışı\n\n### Sayfalama, filtreleme, sıralama ve idempotentlik\n\nBuradaki belirsizlik istemci hatalarına ve dengesiz performansa yol açar. Kuralları belirtin:\n\n- Sayfalama stili (cursor vs offset), limitler ve kararlı sıralama garanti(leri)\n- Desteklenen filtreler ve türleri (tam eşleşme, aralıklar, enumlar)\n- Sıralama alanları ve varsayılan sıralama\n- Yazılarda idempotentlik (idempotency key'ler, dedupe penceresi, çoğaltılmış istek davranışı)\n\n### Örnekler ve kısıtlarla belgeleyin\n\nSomut istek/yanıt örnekleri ve kısıtları (min/maks uzunluk, izin verilen değerler, tarih formatları) ekleyin. Birkaç örnek uzun bir metinden daha fazla yanlış anlamayı engeller.\n\n## Sürdürülebilirlik: Belirsizliğin Uzun Vadeli Maliyeti\n\nBelirsiz promptlar sadece “yanlış cevaplar” üretmez. Kod yolları, veritabanı alanları ve API yanıtları arasında yayılan gizli varsayımlar yaratır. Sonuç: yazılan yazılım yalnızca oluşturucunun tahmin ettiği varsayımlar altında çalışır ve gerçek kullanım farklılaşınca bozulur.\n\n### Gizli varsayımlar kırılgan koda dönüşür\n\nBir prompt örneğin “iade destekle” gibi boşluk bırakırsa, ekipler farklı yerlerde farklı doldurur: bir servis iadeyi ters işlem olarak görür, başka bir servis ayrı bir işlem kabul eder, üçüncüsü kısmi iadeleri sınırlamaz.\n\nAçık promptlar varsayım yerine invariants belirtir (“iadeler 30 gün içinde izinli”, “kısmi iadeye izin verilir”, “dijital ürünler için stok yeniden sağlanmaz”). Bu ifadeler sistem genelinde öngörülebilir davranış sağlar.\n\n### Açıklık kodu ve testleri sadeleştirir\n\nSürdürülebilir sistemler akıl yürütmesi daha kolay olan sistemlerdir. Prompt açıklığı şunları destekler:\n\n- Okunabilir kod: girdiler ve durumlar tanımlı olduğunda daha az savunmacı şube olur.\n- Basit testler: test vakaları doğrudan kabul kriterlerine eşlenir, “ya olursa” senaryolarını kovalamaz.\n- Daha güvenli refaktörler: davranış tanımlıysa iç yapıyı değiştirip sonuçları doğrulayabilirsiniz.\n\nEğer AI destekli geliştirme kullanıyorsanız, net gereksinimler modelin tutarlı uygulamalar üretmesini sağlar; “mantıklı ama uyuşmayan parçalar” yerine uyumlu kod parçaları çıkar.\n\n### İşletilebilirlik: loglama ve metrikler opsiyonel detay değildir\n\nSürdürülebilirlik sistemi çalıştırmayı da kapsar. Promptlar şu gözlemlenebilirlik beklentilerini belirtmelidir: nelerin loglanacağı (ve nelerin loglanmayacağı), hangi metriklerin önemli olduğu (hata oranları, gecikme, yeniden denemeler) ve hataların nasıl görünür kılınacağı. Bunlar belirtilmezse ekipler sorunları müşteriler keşfetmeden sonra fark eder.\n\n### Sürdürülebilirlik sinyalleri\n\nBelirsizlik genellikle düşük uyumluluk ve yüksek bağımlılık olarak kendini gösterir: alakasız sorumluluklar birlikte paketlenir, her şeyi dokunan “yardımcı” modüller görünür ve davranış çağırana göre değişir. Net promptlar uyumlu bileşenleri, dar arayüzleri ve öngörülebilir sonuçları teşvik eder—bu da gelecekteki değişiklikleri daha ucuz hâle getirir. Pratik bir uygulama için bkz. /blog/review-workflow-catch-gaps-before-building.\n\n## Daha İyi Promptlara Dönüştürme: Önce – Sonra Örnekleri\n\nBelirsiz promptlar belirsiz metin üretmekle kalmaz—tasarımı “generic CRUD” varsayımlarına iter. Daha net bir prompt kararları erkenden zorunlu kılar: sınırlar, veri sahipliği ve veritabanında neyin doğru olması gerektiği.\n\n### Önce: belirsiz prompt\n\n> “Öğeleri yönetmek için basit bir sistem tasarla. Kullanıcılar öğe oluşturup güncelleyip paylaşabilsin. Hızlı ve ölçeklenebilir olsun, temiz bir API olsun. Değişiklik geçmişi tutulsun.”\n\nBir inşa edicinin (insan veya AI) güvenilir şekilde çıkaramayacağı konular:\n\n- “öğe” nedir (alanlar, yaşam döngüsü, benzersizlik)?\n- “paylaş” ne demek (genel link mi, belirli kullanıcılar mı, ekipler mi)?\n- “geçmiş” nedir (tam anlık görüntüler mi, difler mi, kim ne zaman değiştirdi, saklama)?\n\n### Sonra: kısıtlarla daha net prompt\n\n> “Generic item'ları yöneten bir REST API tasarlayın, kurallar: itemların title (zorunlu, maks 120), description (opsiyonel), status (draft|active|archived), tags (0–10). Her item tam olarak bir owner (user) aittir. Paylaşım item-başına belirli kullanıcılarla rol viewer|editor şeklinde; genel link yok. Her değişiklik denetlenebilir olmalı: kim neyi ne zaman değiştirdiğini saklayın ve son 50 değişikliği getirilebilsin. Fonksiyonel olmayan: p95 okuma gecikmesi \u003c 200ms; yazma throughput'u düşük. Veri modeli varlıkları ve endpointleri sağlayın; hata durumları ve izinleri dahil edin.”\n\nŞimdi mimari ve şema seçimleri hemen değişir:\n\n- Mimari: ayrı bir Authorization bileşeni (rol kontrolleri) ve yazma yolunda bir Audit Log; düşük yazma yükü varsa karmaşık cache gerekmez.\n- Şema: items, item_shares (rol ile many-to-many) ve item_audit_events (append-only). status enum olur ve tag'ler 10-limitini zorlamak için join tabloya taşınır.\n\n### Hızlı çeviri tablosu\n\n| Belirsiz ifade | Netleştirilmiş versiyon |\n|---|---|\n| “Öğeleri paylaş” | “Belirli kullanıcılarla paylaş; roller viewer/editor; genel link yok” |\n| “Geçmiş tut” | “Actor, zaman damgası, değişen alanları içeren audit event'leri sakla; son 50 getirilebilir” |\n| “Hızlı ve ölçeklenebilir” | “p95 okuma gecikmesi \u003c 200ms; düşük yazma throughput; ana iş yükünü tanımla” |\n| “Temiz API” | “Endpoint listesi + istek/yanıt şekilleri + izin hataları” |\n\n## Daha İyi Tasarımlar İçin Pratik Prompt Şablonu\n\nNet bir prompt uzun olmak zorunda değil—yapılandırılmış olmalı. Amaç, mimari ve veri modelleme kararlarını tahmin etmeden açık hale getirecek kadar bağlam sağlamaktır.\n\n### Kopyala/yapıştır şablonu\n\n```text

1. Goal

• What are we building, and why now?
• Success looks like: <measurable outcome>

2. Users & roles

• Primary users:
• Admin/support roles:
• Permissions/entitlements assumptions:

3. Key flows (happy path + edge cases)

• Flow A:
• Flow B:
• What can go wrong (timeouts, missing data, retries, cancellations)?

4. Data (source of truth)

• Core entities (with examples):
• Relationships (1:N, N:N):
• Data lifecycle (create/update/delete/audit):
• Integrations/data imports (if any):

5. Constraints & preferences

• Must use / cannot use:
• Budget/time constraints:
• Deployment environment:

6. Non-functional requirements (NFRs)

• Performance: target latency/throughput, peak load assumptions
• Uptime: SLA/SLO, maintenance windows
• Privacy/security: PII fields, retention, encryption, access logs
• Compliance: (if relevant)

7. Risks & open questions

• Known unknowns:
• Decisions needed from stakeholders:

8. Acceptance criteria + Definition of Done

• AC: Given/When/Then statements
• DoD: tests, monitoring, docs, migrations, rollout plan

9. References

• Link existing internal pages: /docs/<...>, /pricing, /blog/<...>