Geliştirici Olarak Prompt Mühendisliği: Sistem Promptları, Tool Calling ve Türkçe LLM Kullanımı

Önemli Not: Bu yazıdaki teknik bilgiler yazım tarihi itibarıyla geçerlidir. Kullanılan kütüphaneler, API'ler ve servisler zaman içinde değişebilir. Ücretlendirme, yasal düzenleme ve vergi konularında ilgili resmi kaynakları ve uzmanları referans alınız. Bu içerik bilgilendirme amaçlı olup herhangi bir finansal veya hukuki tavsiye niteliği taşımamaktadır.

"Prompt engineering öldü." Bu iddiayı son bir yılda onlarca kez duydunuz, okudunuz. Modeller gelişti, bağlam pencereleri genişledi, araçlar akıllandı — artık ne yazdığınız o kadar önemli değil mi?

Cevap: Kısmen evet, büyük ölçüde hayır.

Gündelik kullanımda — ChatGPT'ye bir şey sormak, Cursor'da bir dosya düzenletmek — prompt engineering'e ayırdığınız özel çaba gerçekten azaldı. Modeller daha anlayışlı, context'i daha iyi işliyor. Bu katmana "vibe prompting" diyebiliriz.

Ama production sistemlerde? Bir uygulamanın kullanıcıya bakan AI katmanında, bir LLM'i API olarak entegre ettiğinizde, veya bir kodlama asistanını proje kurallarıyla yapılandırdığınızda? Prompt mühendisliği hiç bu kadar önemli olmamıştı.

Bu yazı geliştiricilere özel. "Nasıl daha iyi soru sorarım" değil; "nasıl daha iyi sistem tasarlarım" sorusuna yanıt arıyoruz.

İki Farklı Prompt Engineering Dünyası

Geliştirici olarak iki ayrı bağlamda prompt yazarsınız. Bu ayrımı net görmek, doğru teknikleri doğru yerde uygulamanın temelidir.

Katman 1: Kodlama Asistanı Promptları

Cursor, Claude Code, GitHub Copilot gibi araçlarda yazdığınız yapılandırma dosyaları ve direktifler. Buradaki hedef: AI'ın projenizi anlayarak tutarlı, güvenli ve proje kurallarına uygun kod üretmesi.

Araçlar:

Cursor → .cursor/rules/ dizinindeki .mdc dosyaları veya .cursorrules (eski format)
Claude Code → CLAUDE.md (proje kökünde)
GitHub Copilot → .github/copilot-instructions.md

Katman 2: Production App Promptları

Uygulamanızın bir parçası olan, kullanıcılarla etkileşime giren veya arka planda çalışan AI katmanı. Bir müşteri destek botu, otomatik içerik üretici, veri analiz pipeline'ı.

Araçlar:

OpenAI API, Anthropic Claude API, Google Gemini API
Vercel AI SDK, LangChain, LlamaIndex
Structured output (JSON mode), tool calling, streaming

Her iki katman da farklı beceriler, farklı dikkat noktaları gerektirir.

Kodlama Asistanı Promptları: .cursorrules ve CLAUDE.md

.cursorrules Dosyası: Projenizin Kurallar Kitabı

.cursorrules (veya .cursor/rules/ klasöründe .mdc dosyaları), Cursor'un her bağlamda referans aldığı yapılandırma dosyasıdır. İyi yazılmış bir .cursorrules, saatler sürecek tutarsızlık savaşlarını önler.

Etkili bir .cursorrules şablonu:

# Proje: KOBİ Sipariş Yönetim Paneli
# Stack: Next.js 16, TypeScript, Drizzle ORM, Better Auth, PayTR

## Temel Kurallar
- TypeScript kullan, JavaScript üretme
- Tab (sekme) ile girinti yap, space değil
- Tüm arayüz metinleri Türkçe olacak
- Yorum satırları İngilizce olacak

## Güvenlik
- SQL injection için her zaman Drizzle ORM parametreli sorgularını kullan
- Kullanıcı girdilerini doğrudan DOM'a yazma (XSS)
- API key'leri asla kod içine gömmeme, .env'den oku
- PayTR HMAC doğrulamasını her webhook'ta çalıştır

## Mimari
- Server Components varsayılan, Client Component için gerekçe belirt
- Route Handler'lar /api/ altında, server action'lar form submit için
- Drizzle şeması lib/db/schema/ altında bölümlere ayrılmış

## Türkçe Özellikler
- Tarih formatı: dd.MM.yyyy (Türkiye standardı)
- Telefon: +90 ile başlayan format
- Para birimi: TL simgesi ₺, kuruş nokta ayracı (1.250,00 ₺)

İyi bir .cursorrules'un özellikleri:

Kısa ve somut — 200 satırdan uzun kurallar takip edilmiyor
Proje-spesifik — "TypeScript kullan" yerine "Bu projede Drizzle ORM kullan, Prisma kullanma"
Negatifi değil pozitifi tanımla — "Lucide arrow icon KULLANMA, Arrow bileşenini kullan"
Güvenlik notlarını içer — Bu kısmı asla atlama

Claude Code: CLAUDE.md Project Instructions

Claude Code (terminal tabanlı AI coding araç) CLAUDE.md dosyasını projeyi anlamak için kullanır. Format .cursorrules'a benzer ama birkaç fark var:

Proje kökünde CLAUDE.md dosyasını arar
Hem genel hem bölüme özel bilgiler içerebilir
Komutları ve ortam bilgilerini içermeli

CLAUDE.md örneği:

# Proje: [Proje Adı]

## Geliştirme Ortamı
- Dev server her zaman arka planda çalışıyor, başlatma
- bun kullan (npm veya yarn değil)
- Port: 3000

## Komutlar
```bash
bun run build    # Production build
bun run lint     # Biome ile lint
bunx drizzle-kit push  # DB schema güncelle

Kod Stili

Tab ile girinti
Biome formatter (ESLint/Prettier değil)
Türkçe UI metinleri, İngilizce yorumlar


Fark ettiyseniz bu projeye ait gerçek bir `CLAUDE.md` dosyası var — Claude Code onunla çalışıyor. Bu E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness) açısından önemli: gerçek production deneyimi yazan kişi.

---

## Spec-First Geliştirme: Koddan Önce Spec

AI kodlama araçlarıyla çalışmanın en büyük tuzağı: hemen kod üretmeye başlamak.

"Benim için bir kullanıcı yönetim sistemi yaz" → AI birşeyler üretir → üç döngü sonra hâlâ istediğinizi yapmıyor → siz de zamanınızı ayıklama yapmakla geçiriyorsunuz.

**Doğru yaklaşım: Önce spec, sonra kod.**

```markdown
# Kullanıcı Yönetim Sistemi — Teknik Spec

## Kullanıcı Hikayeleri
- Admin, kullanıcı listesini görebilir (ad, email, kayıt tarihi, rol)
- Admin, kullanıcı rolünü admin/user arasında değiştirebilir
- Admin, kullanıcıyı pasif yapabilir (silmez, deaktive eder)

## Teknik Gereksinimler
- Tablo: users (id, email, name, role, isActive, createdAt)
- API: GET /api/admin/users, PATCH /api/admin/users/:id
- Auth: Better Auth session, sadece admin rolü erişebilir
- Frontend: React Table ile sayfalama, arama

## Kabul Kriterleri
- Deaktif kullanıcı giriş yapamaz
- Admin kendini deaktive edemez
- Rol değişikliği anında geçerli olur

## Kapsam Dışı
- Toplu kullanıcı import/export
- Email bildirimleri
- İki faktörlü doğrulama (sonraki sprint)

Bu spec'i AI'a verdiğinizde çıkan kod birinci denemede çok daha yakın olacak. "Kapsam dışı" bölümü özellikle kritik: AI'ın aşmaması gereken sınırları belirtir.

Production App Promptları: Sistem Prompt Mimarisi

Sistem Promptunun Anatomisi

İyi bir sistem promptu birkaç katmandan oluşur:

<system>
  <role>
    You are a customer support specialist for Acme E-commerce.
    You help Turkish customers with order tracking, returns, and product questions.
  </role>

  <context>
    Company: Acme E-commerce, Turkey's leading home goods retailer
    Working hours: 09:00-18:00 weekdays (Turkey time, UTC+3)
    Escalation: Complex issues go to human agents via ticket system
  </context>

  <instructions>
    - Always respond in Turkish, matching the customer's tone
    - Check order status via the order_lookup tool before answering delivery questions
    - Never promise refunds; say "I'll create a return request" instead
    - If question is outside scope, say: "Bu konuda sizi uzman ekibimize bağlayalım"
  </instructions>

  <examples>
    <example>
      <user>Siparişim nerede kaldı?</user>
      <assistant>Sipariş numaranızı alabilir miyim? Hemen takip bilgisine bakayım.</assistant>
    </example>
  </examples>
</system>

Neden XML tag kullanılıyor? Claude (ve birçok modern model) XML tag'lerini parse etmede özellikle güçlü. <instructions>, <context>, <examples> gibi etiketler, modelin farklı bölümlere farklı ağırlık vermesini sağlıyor.

Uzun İçerik Yerleşimi: Performans Artışı için Kritik

API ile LLM kullanırken bir belgeyi analiz ettiriyorsanız, içeriğin nereye koyulduğu önemli:

Yanlış sıra (düşük performans):

[Soru/görev] ... [Uzun belge içeriği]

Doğru sıra (yüksek performans):

[Uzun belge içeriği] ... [Soru/görev]

İçeriği başa, sorguyu sona koymak — özellikle uzun bağlamlarda — belirgin performans artışı sağlıyor. Modelin sonunda ne yapması gerektiğini bilmesi, daha önceki içeriği ona göre işlemesini kolaylaştırıyor.

Rol Verme: Doğru Çerçeveleme

"You are an expert Turkish payment integration developer with 10 years of experience
with PayTR, İyzico, and Craftgate APIs."

Rol tanımı modelin tonunu, derinliğini ve odak noktasını şekillendirir. "Expert" demek yüzeysel yanıtları azaltır; spesifik alan (Türk ödeme sistemleri) ilgisiz bilgiyi filtreler.

Few-Shot Örnekler: En Tutarlı Teknik

Modelin ne yapmasını istediğinizi açıklamak yerine gösterin:

<examples>
  <example>
    <input>PayTR entegrasyonunu nasıl test ederim?</input>
    <output>
      PayTR'ın sandbox ortamında şu adımları izleyin:
      1. merchant_id olarak test kimlik bilgilerinizi kullanın
      2. test_mode parametresini "1" olarak ayarlayın
      ...
    </output>
  </example>
  <example>
    <input>HMAC hatası alıyorum</input>
    <output>
      HMAC-SHA256 hash'ini doğru sırayla oluşturduğunuzu kontrol edin.
      Birleştirme sırası: merchant_id + user_ip + merchant_oid + ...
    </output>
  </example>
</examples>

3-5 örnek genellikle optimal nokta. Daha fazlası context'i şişirir, daha azı tutarsızlığa yol açar. Örnekler <example> etiketleri içinde olmak zorunda değil ama bu format modelin onları örnekler olarak tanımasını güçlendiriyor.

Pozitif Direktif: "Yapma" Değil "Yap"

# Zayıf
"Do not use markdown formatting."

# Güçlü
"Write all responses in plain prose without any markdown. No bullet points, no headers, no bold text."

Modeller negatif talimatları pozitif kadar iyi işlemiyor. Ne yapmaması gerektiğini söylemek yerine, ne yapması gerektiğini somut biçimde tarif edin.

Türkçe vs İngilizce Sistem Prompt Kararı

Bu soru Türk geliştiriciler arasında sık tartışılıyor. Net bir yanıt var:

Öneri: Sistem promptunu İngilizce yazın.

Neden?

Eğitim verisi: Tüm büyük modeller (GPT-4o, Claude, Gemini) ağırlıklı olarak İngilizce içerikle eğitildi. İnstrüksiyonları anlama ve uygulama kapasitesi İngilizce'de daha güçlü.
Token verimliliği: Türkçe, morfolojik açıdan zengin bir dil — aynı kavramı ifade etmek İngilizce'den çok daha fazla token tüketiyor. Sistem promptunuz Türkçe olursa, her API çağrısında daha fazla token harcarsınız.
Teknik terim tutarlılığı: "Route Handler", "Server Component", "middleware" gibi terimler İngilizce'de tek anlam taşıyor. Türkçe çeviride ("Rota İşleyici"?) anlam kayabiliyor.
Debugging kolaylığı: Sorun çıktığında İngilizce sistem promptunu başka kaynaklarla karşılaştırmak çok daha kolay.

Peki kullanıcı Türkçe konuşabilir mi? Kesinlikle. Sistem promptu İngilizce olsa da model, kullanıcının Türkçe mesajlarına Türkçe yanıt verebilir. Bunu sistem promptuna ekleyin:

Respond in the same language as the user.
If the user writes in Turkish, respond in Turkish.
If the user writes in English, respond in English.

Tool Calling: AI'ı Dış Dünyaya Bağlamak

Tool calling (function calling olarak da bilinir), LLM'in dış API'lere, veritabanlarına veya hesaplama araçlarına bağlanabilmesini sağlar. Model, yanıt üretmek yerine "bu araç çağrılsın, sonucu bana ver" kararı alır.

Basit bir örnek — sipariş sorgulama:

const tools = [
  {
    name: "get_order_status",
    description: "Retrieves the current status and tracking info for a customer order",
    input_schema: {
      type: "object",
      properties: {
        order_id: {
          type: "string",
          description: "The order ID, format: ORD-XXXXXX"
        }
      },
      required: ["order_id"]
    }
  }
]

// Model "get_order_status" aracını çağırmaya karar verirse
// siz veritabanından gerçek veriyi çekip modele geri gönderirsiniz

Tool calling'in önemi:

Güncel bilgi: Model eğitim kesim tarihinden sonraki bilgilere erişemez, ama araçlarla gerçek zamanlı veri çekebilir
Güvenilirlik: Hesaplama yerine veritabanı sorgusu — hallucination riski minimize
Ölçeklenebilirlik: Çok sayıda araç → ajan gibi davranış

Prompt Caching: Tekrarlayan Bağlamı Ucuzlatmak

Büyük bir sistem promptunuz varsa — detaylı rol tanımı, şirket bilgisi, SSS veritabanı — her API çağrısında bu içeriği yeniden gönderirsiniz. Bu maliyetli.

Prompt caching bu sorunu çözer: büyük, değişmeyen içeriği önbellekte tutar, sonraki çağrılar için yeniden işlemez.

Anthropic ve diğer sağlayıcıların prompt caching özelliğinin güncel maliyetleri ve limitleri için ilgili sağlayıcının resmi dokümantasyonunu inceleyin. Token maliyeti sağlayıcıya ve plana göre değişkenlik göstermektedir.

Ne zaman prompt caching kullanmalısınız?

Sistem promptunuz 1.000+ token uzunluğunda
Aynı oturum içinde çok sayıda çağrı yapıyorsunuz
Büyük bir belgeyi (hukuk metni, ürün kataloğu) sürekli bağlam olarak kullanıyorsunuz

MCP Nedir? Model Context Protocol

MCP (Model Context Protocol), Anthropic tarafından geliştirilen açık bir standarttır. AI modellerinin dış araçlara, veritabanlarına ve servislere bağlanma protokolünü tanımlar.

Daha önce her AI aracı (Cursor, Claude, GitHub Copilot) kendi entegrasyon biçimini kullanıyordu. MCP bu kaosa ortak bir dil getiriyor.

Nasıl çalışır?

AI Model
    ↓
MCP Client (Cursor, Claude Code...)
    ↓ MCP Protokolü
MCP Server (siz yazarsınız veya hazır kullanırsınız)
    ↓
Gerçek Dünya (veritabanı, API, dosya sistemi...)

Hazır MCP server örnekleri:

GitHub MCP → AI, repolarınıza, issue'larınıza erişebilir
Figma MCP → Tasarım dosyalarını doğrudan okuyabilir
Postgres MCP → Veritabanınızı sorgulayabilir
Filesystem MCP → Dosya okuyup yazabilir

Kendi MCP server'ınızı ne zaman yazarsınız?

Şirket içi bir sistemi (ERP, CRM, sipariş yönetimi) AI araçlarınıza açmak istediğinizde. Geliştirici olarak bu konuda Anthropic'in resmi MCP SDK dokümantasyonunu incelemenizi öneririm.

Güvenlik Tuzakları: AI ile Kod Yazarken Dikkat

Vibe coding ile veya AI yardımıyla hızla kod üretirken belirli güvenlik açıkları sistematik olarak ortaya çıkıyor.

SQL Injection

ORM kullanılmıyorsa parameterized query zorunlu:

// ❌ Tehlikeli — AI bazen böyle üretir
const query = `SELECT * FROM users WHERE email = '${userInput}'`

// ✅ Güvenli — Drizzle ORM
const user = await db.select()
  .from(users)
  .where(eq(users.email, userInput))

XSS (Cross-Site Scripting)

// ❌ Tehlikeli
<div dangerouslySetInnerHTML={{ __html: userContent }} />

// ✅ Güvenli — render edilen metin otomatik escape edilir
<div>{userContent}</div>
// ya da DOMPurify ile sanitize et

Secret Exposure

// ❌ Tehlikeli — API key kod içinde
const apiKey = "sk-1234567890abcdef"

// ✅ Güvenli — environment variable
const apiKey = process.env.OPENAI_API_KEY

CORS Açık Bırakma

AI bazen hızlı çözüm için CORS'u tamamen açar:

// ❌ Tehlikeli
headers.set('Access-Control-Allow-Origin', '*')

// ✅ Güvenli — sadece güvenilir origin'ler
const allowedOrigins = ['https://yourdomain.com']
if (allowedOrigins.includes(origin)) {
  headers.set('Access-Control-Allow-Origin', origin)
}

Rate Limiting Unutulması

AI'ın ürettiği Route Handler'larda rate limiting çoğu zaman eksik kalır. Production'a almadan önce her public endpoint'te kontrol edin.

Kriptografi ve Auth: AI'a Bırakmayın

Şu konularda AI çıktısını kritik gözle inceleyin:

JWT imzalama ve doğrulama mantığı
Şifre hash fonksiyon seçimi (bcrypt parametreleri)
HMAC doğrulama (PayTR gibi sistemlerde kritik)
KVKK/GDPR uyumluluk kararları

Bu alanlarda AI yardımcı olabilir, ama son kararı kendiniz alın veya güvenlik uzmanı görüşü alın.

Hata Debug Promptları: Şablon Kütüphanesi

Birkaç kanıtlanmış debug prompt şablonu:

Hata mesajı analizi:

I'm getting this error in my Next.js 16 application:
[ERROR MESSAGE]

Context:
- File: [dosya adı]
- Line: [satır numarası]
- What I'm trying to do: [kısa açıklama]

What are the most likely causes and how do I fix it?

Kod review isteği:

Review this [Next.js Route Handler / React Server Component / Drizzle schema]
for security issues, performance problems, and alignment with best practices.

[KOD BLOĞU]

Focus especially on: [authentication, SQL injection, TypeScript types, etc.]

Refactor isteği:

Refactor this component to use [specific pattern/approach].
Keep the same functionality but improve [readability/performance/type safety].
Do NOT add new features or change the interface.

[KOD BLOĞU]

"Do NOT add new features" kritik bir kısıtlama. AI refactor yaparken ekstra özellik ekleme eğiliminde — bunu önceden kapatın.

Sıkça Sorulan Sorular

Prompt engineering öğrenmek zaman kaybı mı, modeller zaten anlıyor mu?

Gündelik kullanımda, evet, modeller çok daha anlayışlı. Ama production sistemlerde, tutarlı davranış gerektiren uygulamalarda ve kaynaklarınızı verimli kullanmak istediğinizde prompt mühendisliği hâlâ ciddi fark yaratıyor. Ayrıca iyi yazılmış bir sistem promptu, ileride model değiştirmenizi de kolaylaştırır.

Türkçe prompt yazmak performansı düşürür mü?

Sistem promptu için evet, ölçülebilir fark var. Kullanıcı mesajları için hayır — modeller Türkçe input'u iyi işliyor. Hibrit yaklaşım (İngilizce sistem prompt + Türkçe kullanıcı etkileşimi) en verimli sonucu veriyor.

.cursorrules ne kadar uzun olmalı?

100-300 satır arası optimal. Çok kısa: yeterli bağlam yok. Çok uzun: model her şeye eşit ağırlık veremez, kritik kurallar kaybolabilir. Kuralları sıklığa göre sıralayın — en sık ihlal edilen en başta.

MCP server yazmak zor mu?

Temel bir MCP server, basit bir REST API'dan biraz daha karmaşık. TypeScript ile birkaç saatte bir POC çıkarılabilir. Anthropic'in resmi @modelcontextprotocol/sdk paketi iyi bir başlangıç noktası.

AI ile yazılan kodu nasıl güvenlik açısından kontrol ederim?

Minimum yapılacaklar: OWASP Top 10'u referans alarak manuel inceleme, SQL sorgularını parameterized mi diye kontrol, ortam değişkenlerinin doğru kullanımı, CORS yapılandırması. Daha kapsamlı için: statik analiz araçları (Semgrep, CodeQL) ve production öncesi penetrasyon testi.

Prompt caching ne zaman aktive olur?

Her sağlayıcının farklı minimum eşiği var. Güncel limitler ve aktivasyon koşulları için kullandığınız sağlayıcının (Anthropic, OpenAI, Google) resmi dokümantasyonunu inceleyin — bu değerler sık güncellenebilir.

Sonuç

Prompt engineering öldü değil — dönüştü. Sihirli kelimeler aramak yerini sistematik mimari kararlarına bıraktı.

Geliştirici olarak odaklanmanız gereken üç alan:

Kodlama asistanları için: .cursorrules ve CLAUDE.md dosyalarınızı ciddiye alın. Proje başında yazılan 30 dakika, sonraki haftalarda onlarca saati kurtarır.
Production app'ler için: XML tag yapısı, içerik önce/sorgu sonra sıralaması, pozitif direktifler, few-shot örnekler — bunlar tutarlı davranışın altyapısı.
Güvenlik için: AI çıktısını kör güvenme. SQL injection, XSS, secret exposure, CORS — her PR'da kontrol listesi.

Yapay zeka ile geliştirme süreçlerinizi modernize etmek, vibe coding ve AI araçlarını production'da kullanmak istiyorsanız iletişime geçin. Bu projenin kendisi bu araçlarla inşa edildi — deneyim kağıt üzerinde değil.