Context library (bağlam kütüphanesi), bir AI ajanının çalışırken başvurduğu ve gerektiğinde kendisinin düzenlediği; markdown dosyalarında ya da bağlı araçlarda tutulan kurumsal ve prosedürel bilgi koleksiyonudur. Nielsen Norman Group’un 9 Ekim 2026 tarihli araştırmasına göre ajanı her gün kullanan uzmanların asıl emeği artık prompt yazmak değil, bu kütüphaneyi kurmak ve güncel tutmak.
Aynı hafta Kevin Liao da “Ajanların hafızaya değil dokümantasyona ihtiyacı var” başlıklı bir yazı yayımladı. Liao, vektör veritabanına dayanan hafıza eklentilerini bırakıp ajanın işe başlamadan okuduğu, iş bitince güncellediği markdown belgelerini öneriyor. Biri kullanıcı araştırması, diğeri bir geliştiricinin bir yıllık deneyimi; ikisi de aynı sonuca varıyor: ajan, arkasındaki bağlam kadar işe yarar.
Context library nedir, içinde ne olur?
NN/g’nin tanımında bağlam kütüphanesi yalnızca dosyalardan oluşmuyor. MCP ve API bağlantılarıyla Notion, Slack ve Granola gibi araçlar da kütüphanenin parçası olabiliyor. Asıl ayrım, bağlamın hangi rolü üstlendiği: her işte geçerli olan, tek bir projeye ait olan ya da ajanın içinde arama yaptığı ham akış.
Bağlamın üç rolü
Hafıza eklentileri neden yetmiyor?
Liao’ya göre piyasadaki hafıza eklentilerinin hepsi aynı hattı izliyor: oturum dökümlerini işle, bunlardan hafıza parçacıkları üret, parçacıkları RAG veritabanına ekle, her istemde en benzer 5 tanesini bağlama enjekte et, gerekirse ajana bir arama aracı ver. Üstüne eklenen katmanlar (çok kademeli hafıza, gece hafızayı yeniden yazan “dreamer”lar, yeniden sıralayıcılar) token maliyetini artırıyor ama tasarımı düzeltmiyor.
Liao’nun önerisi döngüyü değiştirmek. Klasik akış “istem → üret → unut” iken, onun açık kaynak eklentisi Operator Memory her göreve iki zorunlu aşama ekliyor: işten önce belgelere danış, iş bitince belgeleri güncelle.
Dokümantasyon modelinin dört ilkesi
- İçerik: Kodun anlatamadığını yaz: gereksinimler, kararlar, kısıtlar, eşleştirmeler, standartlar. Liao’ya göre bu yazılmazsa her oturum niyeti koddan çözmeye yaklaşık 80 bin token harcıyor.
- Keşif: Oturum başında yalnızca yalın bir katalog yüklenir; her belgenin ne olduğunu ve ne zaman açılacağını söyler. Ajan derindeki belgeyi ihtiyaç olunca açar.
- Tazelik: Belgeyi, bağlam hâlâ elindeyken işi yapan ajan yazar. Değişen bilgi sona eklenmez, yerinde yeniden yazılır.
- Disiplin: Ajanlar belgeleri şişirme eğiliminde; talimat yalnızca kodun veremediğini kaydetmesini, kapsam kayınca belgeyi bölmesini ya da birleştirmesini söyler.
| Hafıza eklentisi (RAG) | Dokümantasyon | |
|---|---|---|
| Neyi getirir | En benzer parçacıkları | Kataloğa bakıp ilgili belgeyi |
| Güncellik | Eski parçacık kalır | Değişen bilgi yerinde yeniden yazılır |
| Denetim | Veritabanının içi zor görülür | Markdown; Git’te diff, inceleme, geri alma |
| Altyapı | Vektör veritabanı, gömme, yeniden sıralayıcı | Diskte markdown ve ayarlı bir talimat |
Liao sınırı da kabul ediyor: Operator bazen belgeyi oluşturmak, yeniden yazmak ya da kırpmak için elle müdahale gerektiriyor. Proje BSD-3-Clause lisanslı; GitHub sayfasına göre Claude Code, Codex, OpenCode ve Pi gibi ortamlarda çalışıyor.
NN/g uzman kullanıcılarda ne gözlemledi?
NN/g, farklı sektörlerden Claude’u her gün kullanan ve kapsamlı kütüphaneler kurmuş uzmanlarla nitel bir çalışma yaptı. Makale katılımcı sayısını vermiyor. Kütüphanelerin boyutu çok farklı: bir katılımcı 2.700’den fazla bağlam dosyasını titiz bir hiyerarşide tutarken, bir başkası İndirilenler klasöründe yüzlerce gevşek klasör biriktirmişti.
Dördüncü dersin somut örneği “sızma” (bleeding): bir podcast için yazılmış tasarım yönergesi, bir kitap takip uygulamasına uygulanmış. En kapsamlı kütüphanenin sahibi ise mümkün olduğunca az şey yüklüyor; oturumun başladığı klasör ajanın neyi göreceğini belirliyor. Kuralı şu: “Yana geçmeden önce yukarı ya da aşağı inmeli.” Katılımcıların çoğu dosyaları birkaç yüz satırın altında tutuyordu.
CLAUDE.md dizin kartı nasıl yazılır?
NN/g’nin önerisi her klasöre, içinde ne olduğunu ve ne zaman nasıl kullanılacağını anlatan bir “dizin kartı” dosyası koymak; Claude ekosisteminde bu dosyanın adı CLAUDE.md. Aşağıdaki adımlar NN/g ve Liao’nun önerilerini Claude Code’un resmi hafıza dokümantasyonundaki davranışlarla birleştiriyor.
- Başlangıç dosyasını üret: Claude Code’da
/initkomutu kod tabanını inceleyip derleme komutları, test talimatları ve proje kurallarıyla bir CLAUDE.md oluşturur. Dosya zaten varsa üzerine yazmaz, iyileştirme önerir. - Kök dosyayı katalog gibi yaz: Her alt klasörün ve önemli belgenin ne olduğunu, hangi durumda açılması gerektiğini birer satırla yaz. Belgelerin kendisini buraya yapıştırma.
- Alt klasörlere kendi kartını koy: Claude Code, çalışma dizininin üstündeki CLAUDE.md dosyalarını açılışta yükler; alt klasörlerdekileri ise Claude o klasördeki bir dosyayı okuduğunda ya da düzenlediğinde yükler. Böylece proje bağlamı yalnızca gerektiğinde girer.
- 200 satırın altında tut: Dokümantasyon her CLAUDE.md için 200 satırın altını hedeflemeyi öneriyor; uzun dosya daha çok bağlam harcıyor ve talimata uyumu düşürüyor.
@dosyaile içe aktarma düzen sağlar ama maliyeti azaltmaz, çünkü içe aktarılan dosyalar da açılışta yüklenir. - Kısmi kuralları ayır: Kodun yalnızca bir bölümünü ilgilendiren kuralları
.claude/rules/altına taşı vepaths:alanıyla eşleşen dosyalara bağla; bu kurallar yalnızca o dosyalarla çalışırken yüklenir. - Başka ajanlarla paylaşıyorsan AGENTS.md: Claude Code, çalışma dizininde ya da üstünde CLAUDE.md yoksa AGENTS.md dosyasını okur; ikisi birlikteyse varsayılan olarak yalnızca CLAUDE.md okunur.
Örnek bir klasör yapısı ve kök dizin kartı şöyle görünebilir (içerik örnek amaçlıdır):
calisma-alani/
├── CLAUDE.md # tüm alanın dizin kartı
├── marka/
│ ├── CLAUDE.md # marka klasörünün kartı
│ └── ses-ve-ton.md
└── musteri-x/
├── CLAUDE.md # proje kartı
└── brif.md
# CLAUDE.md (kök)
- marka/: ses ve ton kuralları. Metin yazarken aç.
- musteri-x/: aktif proje. Yalnızca bu proje için çalışırken gir.
- Karar değişirse ilgili dosyayı yeniden yaz, sona not ekleme.
Bağlam kütüphanesinin bakımı nasıl yapılır?
İki kaynağın ortak tavsiyesi: kütüphaneyi bir kez kurup bırakmak, hiç kurmamaktan daha tehlikeli olabilir; çünkü ajan eskimiş bir talimatı bir meslektaş gibi sezemez.
Güncellemeyi ajana yaptır, sonucu çıktının kalitesiyle değerlendir (NN/g).- Ajana denetlet: global ve yerel bağlamı son toplantı dökümleri gibi ortam bağlamıyla karşılaştırıp değişiklik önermesini iste, sonra onayla (NN/g). Claude Code’da
/doctor prompt-audittalimat dosyalarındaki çelişkileri bulmak için kullanılabilir. - Değişen bilgiyi yerinde yeniden yaz; sona ekleme yapmak şişkinlik ve eski referans üretir (Liao).
- Kütüphaneyi Git’te tut: markdown olduğu için diff’lenir, incelenir, geri alınır (Liao).
Her şeyi global yapma; bağlamı projeye yerel tut (NN/g).- Rutinlerin kendiliğinden doğru kalacağını varsayma: NN/g’nin bir katılımcısının günlük görev özeti, kimse fark etmeden kullanıcının çalışma biçiminden uzaklaşmıştı.
- Bağlantıların hep çalışacağını varsayma; kopan MCP bağlantılarını yeniden kurmayı planla (NN/g).
Tasarım ve ürün ekipleri için ne anlama geliyor?
Bağlam kütüphanesi aslında tanıdık bir disiplinin yeni hâli: tasarım sistemi dokümantasyonu. Bileşen kuralları, marka sesi ve geçmiş kararlar ajanın okuyabileceği kısa dosyalara döküldüğünde ajan her oturumda sıfırdan başlamıyor. Tasarım sistemlerinin AI entegrasyonu da tam bu noktada ayrışıyor. Kuralların “tavsiye” olarak kalmasını istemiyorsan Claude Code hooks ile dayatabilir, uzun araştırmaları subagent’lara ayırarak ana bağlamı temiz tutabilirsin. Kütüphaneyi ekiple paylaşmanın bir yolu da Claude eklentisi olarak paketlemek.
Sık sorulan sorular
Context library ile RAG hafızası arasındaki fark nedir?
RAG tabanlı hafıza, geçmiş oturumlardan üretilen parçacıkları benzerliğe göre geri getirir. Context library ise ajanın kataloğa bakıp açtığı, okunabilir ve düzenlenebilir belgelerden oluşur. Liao’ya göre fark, belgenin doğruluğunun ve güncelliğinin denetlenebilmesi.
CLAUDE.md dosyası ne kadar uzun olmalı?
Claude Code dokümantasyonu her CLAUDE.md için 200 satırın altını hedeflemeyi öneriyor. Daha uzun dosyalar daha fazla bağlam harcar ve talimata uyumu düşürür. NN/g’nin katılımcılarının çoğu da dosyalarını birkaç yüz satırın altında tutuyordu.
AGENTS.md ile CLAUDE.md aynı şey mi?
İkisi de ajana proje talimatı veren markdown dosyaları. Claude Code, CLAUDE.md yoksa AGENTS.md’yi okur; ikisi birlikte varsa varsayılan olarak yalnızca CLAUDE.md okunur. Ortak kullanım için CLAUDE.md içinden AGENTS.md içe aktarılabilir.
Bağlam kütüphanesi ne sıklıkla güncellenmeli?
NN/g sabit bir sıklık vermiyor; öncelikler ve süreçler değiştiğinde güncellemeyi öneriyor. Pratikte bunu ajana yaptırmak ve çıktı kalitesi düştüğünde yeni bir güncelleme turu istemek en az emek gerektiren yol.
Bir Yorum Yazın