Prompt ve Context Engineering

Yapay zekadan aldığınız kodun kalitesi iki şeye bağlı: modele ne dediğiniz (prompt) ve modelin o an neleri gördüğü (context). Bu rehber önce ikisini, sonra projeniz için bir kez yazıp her konuşmada kullanacağınız kural dosyalarını anlatıyor.

Prompt: tarif edin, tahmin ettirmeyin

Prompt, modele verdiğiniz istektir: talimat, ilgili bilgi ve gerekirse örnekler. "Ürün kartını düzelt" gibi belirsiz bir istekte hangi kartın, neyin, nasıl düzeleceğini siz söylemediğiniz için model boşlukları kendi tahminiyle doldurur ve yanlış yeri değiştirebilir.

İyi bir kodlama isteği dört soruya cevap verir:

Zayıf prompt: "Ürün kartını düzelt."

Güçlü prompt: "ProductCard.tsx içinde indirimli ürünlerde eski fiyat görünmüyor. Eski fiyatı üstü çizili göster, Tailwind kullan, yeni paket ekleme. Bitince pnpm test ve pnpm lint geçmeli."

Birkaç alışkanlık büyük fark yaratır:

• Meslektaş testi: İsteği projeyi bilmeyen bir geliştiriciye okutun. İlk sorusu "hangi dosya?" ise isteğe dosyayı ekleyin. Meslektaşın kafası karışıyorsa modele gri alan bırakmışsınızdır; her şeyi net söyleyin¹.

• "Yapma" yerine "yap" deyin, nedenini ekleyin: "Yeni CSS dosyası açma" yerine "Projede Tailwind var, stilleri JSX içinde sınıflarla yaz." Model nedenini bilince benzer durumlarda da doğru davranır¹.

• Örnek gösterin: Fiyat biçimleyen bir fonksiyon istiyorsanız birbirinden farklı üç dört örnek yazın: 1299 → ₺1.299,00, 0 → ₺0,00, 1299.5 → ₺1.299,50. Kural listesinden çok daha net anlatır¹.

• Uzun veri başa, soru sona: Büyük bir dosya veya log yapıştırıyorsanız önce onu, sonra sorunuzu yazın. Anthropic testlerde yanıt kalitesinin %30'a kadar arttığını bildiriyor¹.

• Adım adım düşün demeyin: Güncel modeller zaten kendi içinde düşünüyor. "Adım adım düşün" diye tarif yazmak yerine "iyice düşün" gibi genel bir talimat çoğu zaman daha iyi sonuç verir¹.

• Bölümleri ayırın: Uzun bir prompt'ta kimlik, talimat, örnekler ve bağlamı (ilgili kod, hata mesajı) Markdown başlıklarıyla ayırın. OpenAI'nin önerdiği sıra: kimlik, talimat, örnekler, bağlam².

• Modele göre ayarlayın: Düşünen modele hedefi ve kısıtları söylemek yeter ("sepet toplamı yanlış, kök nedeni bul"). Küçük ve hızlı modele adımları açıkça yazın ("CartSummary.tsx'te total hesabını bul, reduce içindeki hatayı düzelt, testi çalıştır")².

Bittiğini model bilsin

Kodlamada en çok işe yarayan şey, modelin kendi işini kontrol edebileceği bir yol vermektir. Kontrol yoksa model "bitti gibi görünüyor" noktasında durur ve doğrulayan siz olursunuz⁴.

Dosyayı, belirtiyi ve "düzeldi"nin tanımını yazın. Mevcut bir bileşeni örnek gösterin. Her istekte tek hedef olsun⁴.

Bir tuzak daha var: özel bir şey söylemezseniz model hep en olası seçimlere yaslanır ve ürettiği arayüzler birbirine benzer. Aynı yazı tipi, aynı mor gradyan. Anthropic bu görünümü "AI slop" estetiği diye anıyor ve tipografi, renk, hareket ve arka plan için ayrı talimat yazmayı öneriyor¹. Kendi tasarım sisteminizden 4-5 kural yazmanız yeter.

Büyük işi tek cümleyle istemeyin. Önce modelin size soru sormasını isteyin, cevaplardan bir SPEC.md çıksın, uygulamayı temiz bir konuşmada başlatın⁴:

Kupon sistemi eklemek istiyorum. Netleşene kadar bana sorular sor:
nasıl çalışacak, hangi uç durumlar var, neyi yapmayacağız.
Bariz soruları atla. Bitince SPEC.md dosyasına yaz.

Context: modelin gördüğü her şey

Model yalnızca önündeki metne bakar: talimatlar, önceki konuşma, açtığı dosyalar, test çıktıları. Bunların hepsine context (bağlam) denir. Context engineering ise bu bilginin neleri içereceğini yönetmektir³.

Modelin tek seferde işleyebildiği metin miktarına context window (bağlam penceresi) denir ve token ile ölçülür. Bir token kabaca kelimenin dörtte üçü kadardır.

Pencere dolmasa bile bağlam uzadıkça modelin içindeki bilgiyi doğru hatırlaması zorlaşır. Buna context rot denir³. Claude Code dokümanı da aynı şeyi söylüyor: bağlam doldukça performans düşer, bu yüzden en değerli kaynak bağlamdır⁴. Hedef: az ama değerli bilgi.

Pratikte:

• Yeni iş, yeni konuşma. İlgisiz işleri aynı konuşmada biriktirmeyin⁴.

• İki düzeltmeden sonra sıfırlayın. Başarısız denemeler bağlamı kirletir. Öğrendiklerinizle daha iyi bir ilk istek yazıp yeni konuşma açın⁴.

• Önemli kararı dosyaya yazın. Araçlar uzayan konuşmayı özetler, özet küçük ayrıntıları kaybedebilir³. Yalnızca konuşmada söylediğiniz talimat özetten sonra kaybolabilir⁵.

• Ne yüklendiğine bakın. Claude Code'da /context hangi talimat dosyalarının yüklendiğini gösterir⁴.

Kural dosyası: AGENTS.md ve CLAUDE.md

Model her oturuma projeniz hakkında hiçbir şey bilmeden başlar: hangi paket yöneticisini kullandığınızı, testi nasıl çalıştıracağınızı bilmez. Bunları bir dosyaya yazarsanız araç dosyayı her oturumun başında bağlama ekler⁵. AGENTS.md, ajanlar için bir README gibidir. Düz Markdown'dır, zorunlu alanı yoktur⁶.

İyi bir kural dosyası nasıl yazılır?

• Kısa tutun. Claude Code 200, Cursor 500 satırın altını öneriyor⁵, ⁷. Her satır için sorun: "Bunu silersem model hata yapar mı?" Yapmazsa silin⁴.

• Yalnızca koddan anlaşılmayanı yazın. Klasör yapısını ve teknoloji listesini model ilk taramada kendi buluyor. ETH Zürih'in çalışmasında repo özetleri başarıyı artırmadı⁸. Ama "paket yöneticisi uv" gibi bir bilgiyi kendi bulamaz. uv, Python için bir paket yöneticisi. Çalışma Python projeleriyle yapıldı. Frontend'deki karşılığı pnpm, npm, yarn ya da bun. Aynı çalışmada kural dosyasında uv geçince ajan onu görev başına ortalama 1,6 kez kullandı, geçmeyince neredeyse hiç⁹.

• Ajanın tahmin edemeyeceği komutları yazın. git ve npm gibi bildiği araçları anlatmayın⁷.

• Stil kurallarını linter'a bırakın. Style guide'ı kopyalamak yerine linter kullanın⁷.

• Uzun anlatma, işaret et. Kodu kopyalamak yerine dosyayı gösterin, böylece dosya şişmez ve eskimez⁷.

• Her satıra bir ipucu gibi bakın. Ajan sürekli yanlış klasöre dosya koyuyorsa kural eklemek yerine yapıyı düzeltmek daha kalıcı⁹.

• Şu altı alanı kapsayın: komutlar, test, proje yapısı, kod stili, git akışı ve sınırlar. Sınırları üçe bölün: her zaman yap, önce sor, asla yapma¹⁰.

Örnek bir frontend AGENTS.md:

# AGENTS.md

## Komutlar
- Test: `pnpm test:run` (tek dosya: `pnpm vitest run <dosya>`)
- Kontrol: `pnpm lint && pnpm tsc --noEmit`

## Dikkat
- Stil için Tailwind kullan, yeni CSS dosyası açma.
- `legacy/` eski ama üç modül hâlâ import ediyor; içinden dosya silme.

## Sınırlar
- Önce sor: yeni paket eklemek, route yapısını değiştirmek.
- Asla: `.env` dosyalarını okuma veya commit etme.