Bağlam mühendisliği: yapay zeka kodlama ajanları rehberi

Bağlam mühendisliği, bir yapay zeka kodlama ajanının her turda neyi gördüğüne karar verme işidir: bağlam penceresinde hangi talimatların, kural dosyalarının, araç tanımlarının, okunan dosyaların, araç sonuçlarının ve geçmişin bulunacağını, hangilerinin dışarıda kalacağını seçmek. Kodlama ajanlarında bu, prompt’u kurcalamaktan genelde daha önemlidir; çünkü senin yazdığın prompt, modelin okuduğu metnin küçük bir parçası. Pencerenin büyük kısmını kural dosyaları, araç çıktıları ve o ana kadarki konuşma doldurur. Bu bağlamı küçük ve ilgili tutarsan, prompt’u hangi kelimelerle yazarsan yaz, daha iyi sonuç alırsın.

Bu rehberde ajanın bağlamına neyin girdiğini, uzun bağlamın neden bozulduğunu, işe yarayan teknikleri ve bunların işe yarayıp yaramadığını nasıl anlayacağını anlatıyoruz. Claude Code ve Codex ile ilgili bilgiler Ekim 2026 itibarıyladır.

Bağlam mühendisliği ne demek?

Anthropic’in mühendislik yazısı Effective context engineering for AI agents (29 Eylül 2025), bağlamı modelden yanıt üretilirken dahil edilen token kümesi olarak, bağlam mühendisliğini de çıkarım sırasında bu token’ların en iyi kümesini seçip korumak olarak tanımlıyor.

Prompt mühendisliğinden farkı kapsamda ve zamanlamada:

Kodlama ajanı bir döngüde çalışır: oku, araç çağır, sonucu oku, karar ver, yine çağır. Her adım token ekler, her adım da zaten orada olanı yeniden okur. Yazının bağlam mühendisliğine “yinelemeli” demesi bundan: ajan modele neyi geçireceğine her karar verdiğinde seçim yeniden yapılır.

Kodlama ajanının bağlamına neler girer?

İlk mesajından önce yüklenenler ve oturum boyunca büyüyenler:

• Sistem prompt’u ve yerleşik araçlar. CLI belirler. Sen kontrol etmezsin ama her turda bedelini ödersin.
• Kural dosyaları. Claude Code için CLAUDE.md, Codex ve pek çok başka ajan için AGENTS.md. Oturumun başında yüklenir.
• Araç tanımları ve MCP. Ajanın çağırabildiği her aracın bir adı ve açıklaması var; MCP sunucuları bunlara yenilerini ekler. Claude Code, MCP araçlarının tam tanımlarını araç kullanılana kadar erteler; başta yalnızca adlar ve sunucu talimatları yüklenir.
• Okunan içerik. Ajanın okuduğu dosyalar, arama sonuçları, getirdiği dokümanlar.
• Araç sonuçları. Test çıktıları, build log’ları, git diff, veritabanı sorguları, sayfa anlık görüntüleri.
• Konuşma geçmişi. Senin mesajların, ajanın yanıtları ve her başarısız deneme.

Sabit kısım hakkında bir fikir vermesi için: Claude Code’un ilk isteğini standart kurulumda yaklaşık 34,4 bin, yalın kurulumda yaklaşık 13,3 bin token olarak ölçtük (token tasarrufu yazımız). Bu taban yük her turda yeniden gönderilir. /context, /compact ve /clear gibi Claude Code’a özgü ayrıntılar için Claude Code bağlam yönetimi rehberine bak.

Bağlam büyüdükçe neden kötüleşir: bağlam çürümesi

Bağlam penceresinin kesin bir sınırı var ama yumuşak sınır daha önce gelir. Anthropic’in yazısı bunu bir “dikkat bütçesi” olarak anlatıyor: transformer’lar her token’ı diğer her token’la ilişkilendirir, yani n token n² ikili ilişki yaratır ve her yeni token dikkati biraz daha dağıtır. Pencere büyüdükçe modelin içindekini doğru hatırlama yeteneği azalır.

Bağımsız araştırmalar da aynı şeyi gösteriyor. Chroma’nın Context Rot raporu (14 Temmuz 2025) 18 modeli test etti ve bütün deneylerde, basit görevlerde bile, girdi uzadıkça performansın düştüğünü buldu. Kodlama açısından önemli birkaç bulgu:

• İlgili gibi görünen ama ilgisiz tek bir “dikkat dağıtıcı” metin bile doğruluğu düşürdü ve bu etki girdi uzadıkça büyüdü.
• Uzun hafıza testinde bütün modeller, yaklaşık 300 token’lık odaklı prompt’la, yaklaşık 113 bin token’lık tam prompt’a göre çok daha iyi sonuç verdi.

Kodlama ajanında dikkat dağıtıcılar her yerde: düzenlemeden önce okunmuş eski bir dosya sürümü, çoktan düzeltilmiş bir hatanın stack trace’i, reddedilmiş bir yaklaşım. 1M token’lık pencere yer açar, bağışıklık vermez.

İşe yarayan teknikler

Aşağıdakiler Anthropic’in yazısında anlatılan teknikler; her birini kodlama ajanında pratikte ne yapacağına çevirdik.

1. Kural dosyalarını kısa ve kapsamlı tut

Kural dosyalarının bedeli her oturumda ödenir, o yüzden her satır yerini hak etmeli. Claude Code’un bellek belgeleri her CLAUDE.md dosyasını 200 satırın altında tutmayı öneriyor ve uzun dosyaların talimatlara uyumu düşürdüğünü belirtiyor. Tek uzun dosya yerine:

• Kodun bir kısmı için geçerli kuralları paths alanıyla .claude/rules/ altına koy. Yalnızca Claude eşleşen bir dosyayı okuduğunda ya da düzenlediğinde yüklenirler.
• Alt klasörlerde iç içe CLAUDE.md dosyaları kullan. Claude Code bunları o klasörde çalışmaya başlayınca yükler.
• @path ile içe aktarmanın dosyayı düzenlediğini ama maliyetini düşürmediğini bil: içe aktarılan dosyalar, onları çağıran dosyayla birlikte yüklenir.

---
paths:
  - "src/api/**/*.ts"
---

# API kuralları

- Her isteğin gövdesini ortak şemayla doğrula.
- Hataları standart hata formatında döndür.

Codex de AGENTS.md ile benzer çalışır: önce ~/.codex içindeki genel dosyayı, sonra proje kökünden çalışma klasörüne kadar her klasörden bir dosya okur; yakın klasördeki dosyalar sonra gelir ve öncelik kazanır. Toplam boyut project_doc_max_bytes sınırına (varsayılan 32 KiB) ulaşınca yeni dosya eklemeyi bırakır. Bu dosyalara ne yazılacağını CLAUDE.md rehberimizde anlattık.

İçerik konusunda Anthropic’in önerisi “doğru irtifada” yazmak: davranışı yönlendirecek kadar somut, kırılgan if-else mantığına dönüşmeyecek kadar genel. Uzun bir uç durum listesi yerine birkaç tipik örnek daha iyi çalışır.

2. İhtiyaç anında oku

Her şeyi baştan yüklemek yerine hafif referanslar (dosya yolları, fonksiyon adları, bağlantılar) tut ve ajan içeriği gerektiğinde yüklesin. Anthropic örnek olarak Claude Code’u veriyor: dosyaları glob ve grep ile buluyor, büyük verilere hepsini yüklemeden head ve tail ile bakıyor. Pratikte:

• Ajana “etrafa bir bak” demek yerine bir dosyayı ya da sembolü göster.
• Büyük bir dosyanın tamamını okumadan önce taslağını ya da belli satır aralığını iste.
• Kural dosyasında depoya dair kısa bir harita tut (API nerede, testler nerede), gerisini ajan kendisi getirsin.

3. İşi alt ajanlara ayır

Alt ajan kendi temiz bağlam penceresinde çalışır. Keşif için on binlerce token harcayıp ana oturuma yalnızca yoğun bir özet döndürebilir; Anthropic bu özetlerin çoğunlukla 1.000 ila 2.000 token olduğunu söylüyor. Kod tabanını keşfetmek, uzun log okumak ve diff’i temiz bir bağlamda incelemek iyi adaylar.

Alt ajanlar bedava değil. Anthropic’in çoklu ajan araştırma sistemi yazısı (13 Haziran 2025), ajanların sohbete göre yaklaşık 4 kat, çoklu ajan sistemlerinin yaklaşık 15 kat token kullandığını aktarıyor. Kazandığın şey daha küçük bir fatura değil, temiz bir ana oturum.

4. Sıkıştır, eski araç sonuçlarını temizle

Sıkıştırma (compaction), sınırına yaklaşan konuşmayı özetler ve özetten devam eder. Anthropic eski araç sonuçlarını temizlemeyi sıkıştırmanın en güvenli biçimlerinden biri sayıyor: ajanın kırk tur önceki bir test çıktısının ham haline nadiren ihtiyacı olur. API tarafında Anthropic’in bağlam yönetimi duyurusu (29 Eylül 2025), eski araç çağrılarını ve sonuçlarını temizleyen bağlam düzenlemenin 100 turluk bir web arama testinde token kullanımını %84 azalttığını bildirdi.

Kodlama CLI’ında özeti sınıra gelince kendi haline bırakmak yerine yönlendir:

/compact Değiştirdiğimiz dosyaların listesini, başarısız testi ve API kararını koru

İlgisiz bir işe geçerken de eski oturumu sıkıştırmak yerine yeni bir oturum aç.

5. Ajan pencerenin dışında not tutsun

Yapılandırılmış not tutmak, ajanın ilerlemesini bir dosyaya yazıp sonra geri okuması demek. Anthropic’in örnekleri arasında bir NOTES.md dosyası ve yapılacaklar listeleri var. Claude Code’un otomatik belleği de böyle çalışır: depo başına bir MEMORY.md dizini tutar ve her oturumun başında bunun ilk 200 satırı ya da ilk 25 KB’ı yüklenir. Birden fazla ajan ve oturum için ortak bir proje hafızası daha ileri gider; bunu yapay zeka kodlama ajanları için ortak hafıza yazısında anlattık.

6. Körlemesine arama yerine kod haritası kullan

Grep’le arayıp okuyarak keşfetmek pencereyi, çoğu sonradan ilgisiz çıkan dosyalarla doldurur. Kod haritası, ajanın sorgulayabildiği bir dosya, sembol, import ve test dizinidir; ajan önce sıralı bir liste ve bir taslak okur, sonra yalnızca ihtiyaç duyduğu satırları.

7. Araç çıktısını kısa tut

Araç sonuçları genelde pencerenin en büyük ve en gürültülü kısmıdır. Anthropic’in Writing effective tools for agents yazısı (11 Eylül 2025), makul varsayılanlarla sayfalama, aralık seçme, filtreleme ve kesme öneriyor ve Claude Code’un araç yanıtlarını varsayılan olarak 25.000 token’la sınırladığını söylüyor. Aynı fikri dışarıdan da uygulayabilirsin:

• Tüm test paketini değil, tek bir test dosyasını çalıştır.
• Log’ları ajan okumadan önce grep ya da tail ile süz.
• Koca bir sayfa ya da tablo döndüren bir araç yerine odaklı bir CLI komutunu tercih et.
• Projede kullanmadığın MCP sunucularını kapat.

Bağlam mühendisliğini ölçmek

Ölçmeden yine tahmine dönersin. İşe yarayan sinyaller:

• Döküm. Claude Code’da /context, pencereyi neyin kullandığını kategoriye göre ve hangi kural ve bellek dosyalarının yüklendiğini gösterir. Kural dosyalarını ya da MCP kurulumunu değiştirdikten sonra bak.
• Görev başına token. Tek tek oturumları değil, değişiklikten önceki ve sonraki benzer görevleri karşılaştır.
• Tekrarlanan düzeltmeler. Bir kuralı sürekli tekrar ediyorsan ya kural dosyasında yoktur ya da içinde kaybolmuştur.
• İlk denemede başarı. Benzer görevlerde daha az takip prompt’u, asıl istediğin sonuçtur.
• Çürüme belirtileri. Dosyaları yeniden okumak, önceki talimatları unutmak, reddedilmiş bir yaklaşımı tekrarlamak. Bunları görünce sıkıştır ya da temizle.

Her seferinde tek bir değişkeni değiştir. Anthropic’in çoklu ajan yazısı, BrowseComp testinde performans farkının yaklaşık %80’ini tek başına token kullanımının açıkladığını buldu; yani daha çok token bazen daha iyi sonuç gibi görünebilir. Maliyeti ve kaliteyi birlikte karşılaştır.

Kontrol listesi

AgentVera nerede devreye giriyor?

AgentVera; Claude Code, Codex ve diğer CLI ajanlarını tek bir masaüstü uygulamasında yan yana çalıştırır. Yukarıdaki alışkanlıkların yerini tutmaz ama birkaç özelliği bunları çalıştırdığın her ajan için uygular. Hepsi özellik sayfalarında anlatılıyor:

• Token tasarrufu: başlangıç yükünü küçülten bağlam profilleri, her panelde canlı bağlam boyutu, her CLI’ın kendi komutuyla 150 bin token eşiğinde varsayılan olarak açık otomatik sıkıştırma ve test, build, git çıktısını modele ulaşmadan kısaltan RTK.
• Proje haritası: sembollerin, import’ların, testlerin ve birlikte değişen dosyaların yerel dizini; ajanlar bunu map_related, map_outline gibi agentvera-map MCP araçlarıyla sorgular. AI ROI sekmesi, haritayı kullanan ve kullanmayan konuşmaları görev başına token dahil karşılaştırır.
• Brain: dokümanlar, commit’ler, PR’lar ve ajan konuşmalarından kurulan bir proje hafızası. Ajanlar brain_recall ile arar, düzeltmeleri brain_remember ile saklar; isteğe bağlı, en fazla 2.500 karakterlik bir bağlam paketi yeni ajanlara verilir.
• Claude Code için akıllı araçlar: değişmemiş bir dosyanın yeniden okunmasını reddeder, büyük bir dosyada önce taslağını verir, tüm test çalıştırmalarını etkilenen testlere daraltır.

Tek terminalde tek ajan çalıştırıyorsan bu yazıdaki teknikler tek başına da gayet işe yarar; /context, /compact ve bakımlı bir kural dosyası seni yolun çoğunda götürür. AgentVera asıl, birden fazla ajan çalıştırıp hepsine aynı bağlam disiplinini uygulamak istediğinde işe yarar. İndirip tek bir projede deneyebilirsin.

Özet

Bağlam mühendisliği, ajanın her turda gördüğünü seçip düzenlemektir; kodlama ajanlarında prompt’u kurcalamaktan daha çok işe yarar, çünkü prompt pencerenin küçük bir dilimidir. Uzun bağlam daha az güvenilirdir: kural dosyalarını kısa ve kapsamlı tut, ihtiyaç anında oku, keşfi alt ajanlara ver, odak vererek sıkıştır, notları pencerenin dışında tut, kod haritası kullan ve araç çıktısını kısa tut. Sonra ölç: bağlam dökümü, görev başına token ve ilk denemede başarı, bir değişikliğin işe yarayıp yaramadığını söyler.