Orta · ~2 dk okuma #context #prompt #agent

Context Engineering

Bağlam mühendisliği

Modelin her çağrıda gördüğü bağlam penceresine neyin, ne kadarının ve hangi sırayla gireceğini bilinçli olarak tasarlama disiplini.

Tanım

Prompt engineering “talimatı nasıl yazarım?” sorusuyla uğraşır. Context engineering ise daha büyük bir soruyu sorar: modelin bu çağrıda gördüğü tüm token'lar ne olmalı? Bir ajanda bağlam şu parçalardan oluşur:

- System prompt — rol, kurallar, çalışma biçimi - Araç tanımları — isimler, açıklamalar, şemalar - Getirilen belgeler — RAG sonuçları, okunan dosyalar - Bellek — CLAUDE.md gibi kalıcı notlar, önceki oturum özetleri - Mesaj geçmişi — kullanıcı mesajları, model cevapları ve en hızlı büyüyen kalem: araç sonuçları

Anthropic'in Eylül 2025 tarihli “Effective context engineering for AI agents” yazısı yol gösterici ilkeyi şöyle koyar: istenen sonucun olasılığını en çok artıran en küçük, en yüksek sinyalli token kümesini bul. Sebep context rot: pencere doldukça modelin oradaki bilgiyi doğru hatırlama yeteneği azalır. Transformer'da her token diğer her token'a baktığı için (n token için n² ilişki) dikkat sınırlı bir bütçedir; her gereksiz token bu bütçeden yer.

Pratik teknikler: araçları az ve net tutmak; her şeyi baştan yüklemek yerine dosya yolu, sorgu gibi hafif referanslarla “tam zamanında” getirmek; eski araç sonuçlarını temizlemek; pencere dolunca özetlemek (compaction); kalıcı bilgiyi pencere dışındaki notlara yazmak; dağınık araştırmayı kendi bağlamı olan subagent'lara devretmek.

Benzetme

Bir danışmana iş brifingi vermek gibi. 300 sayfalık bir klasörü masasına bırakıp “hepsi burada” dersen önemli üç sayfa kaybolur. İki sayfalık net bir özet, ilgili sözleşmenin yeri ve “gerekirse arşivden şunu iste” notu verirsen, daha hızlı ve daha doğru çalışır.

Context engineering, o iki sayfayı ve arşive giden yolu tasarlamaktır. Masanın büyüklüğü (pencere boyutu) önemli, ama asıl mesele masaya ne koyduğun.

Gerçek dünyadan örnek

Tipik bir senaryo: bir destek ajanı 400 sayfalık ürün dokümanını system prompt'a gömüyor, 60 araç tanımıyla geliyor ve her müşteri kaydını ham JSON olarak geçmişe döküyor. Sonuç: yavaş, pahalı ve sık sık yanlış araç seçen bir ajan.

Yeniden tasarım: - System prompt kısa ve net kurallara iniyor, sabit kısmı önbelleğe (prompt caching) alınıyor. - 60 araç, iyi tanımlanmış 8 araca iniyor. - Doküman prompt'tan çıkıyor; yerine search_docs aracı geliyor, ajan sadece ilgili bölümü çekiyor. - Müşterinin önceki konuşmaları tek paragraflık bir notta tutuluyor. - Eski araç sonuçları belli bir eşikten sonra otomatik temizleniyor.

Model değişmedi; değişen, modelin her turda gördüğü şey.

Kod örnekleri

                                            Anthropic API · bağlamı parça parça kur, bütçeyi ölç
                                            python
                                        
import anthropic

client = anthropic.Anthropic()

SYSTEM = open("prompts/support.md").read()     # kısa, sabit kurallar
tools = [search_docs_tool, get_ticket_tool]    # az ve net araç
notes = open("memory/customer_42.md").read()   # önceki oturumlardan notlar

messages = [{
    "role": "user",
    "content": f"<notes>\n{notes}\n</notes>\n\n{question}",
}]

# Göndermeden önce bağlamın kaç token tuttuğunu ölç
count = client.messages.count_tokens(
    model="claude-opus-5-5",
    system=SYSTEM,
    tools=tools,
    messages=messages,
)
print("input tokens:", count.input_tokens)

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    # Sabit kısım önce gelir ve önbelleğe alınır
    system=[{"type": "text", "text": SYSTEM,
             "cache_control": {"type": "ephemeral"}}],
    tools=tools,
    messages=messages,
)

                                            CLAUDE.md · kalıcı kuralları sohbet geçmişinden ayır
                                            markdown
                                        
# Proje notları

- Paket yöneticisi: pnpm. Testler: `pnpm test`.
- API katmanı `src/api/`, iş kuralları `src/domain/`.
- Veritabanı şemasını değiştirme; migration yaz.

## Compact Instructions

Özetlerken açık kalan hataları, değiştirilen dosyaların
listesini ve kullanıcının verdiği kararları mutlaka koru.

Ne zaman kullan

Birden fazla turda çalışan her ajan — bağlam her turda büyür, tasarlanmazsa bozulur
Ajan doğru bilgiyi “bildiği” halde yanlış davranıyorsa — bilgi muhtemelen gürültü içinde kayboluyor
Maliyet ve gecikme yüksekse — bağlamı küçültmek ikisini birden düşürür
Çok sayıda araç, belge ya da bellek kaynağı birleştirilirken

Ne zaman kullanma

Tek seferlik, kısa bir çağrı — iyi yazılmış bir prompt yeterlidir
Sorun bağlam değil yetenekse — modelin hiç yapamadığı bir işi bağlam düzenlemesi kurtarmaz
Ölçmeden optimize etmek — önce token sayısını ve başarı oranını gör, sonra kırp

Sık yapılan hatalar

Büyük pencereyi çöp kutusu sanmak

1M token'lık bir pencere, 1M token doldurman gerektiği anlamına gelmez. Context rot nedeniyle pencere doldukça hatırlama kalitesi düşer; her kalem yerini hak etmeli.

Araç açıklamalarını ihmal etmek

Araç tanımları da bağlamdır ve her turda tekrar gönderilir. Birbirine benzeyen, belirsiz açıklamalı araçlar modeli yanlış seçime iter.

Önbelleği kendi elinle bozmak

System prompt'un başına tarih-saat gibi her istekte değişen bir şey koymak prompt caching'i boşa çıkarır. Sabit içerik önce, değişken içerik sonra gelmeli.

Kalıcı kuralları sohbet geçmişine bırakmak

Konuşmanın başında söylenen bir kural özetleme sırasında kaybolabilir. Her zaman geçerli olması gerekenleri system prompt'a ya da CLAUDE.md gibi bir dosyaya yaz.