Notion ve Obsidian'dan Agent'lara: AI İçin Bağlam (Context) Mimarisi Oluşturmak
Context engineering prompt yazma işi değildir. Agent'ın hangi gerçeği nereden okuyacağını, hangi bilginin daha yetkili olduğunu ve eski bilginin nasıl eleneceğini tasarlayan bilgi mimarisidir.
AI ile çalışırken en pahalı hatalardan biri modele yanlış cevap verdirmek değil, eski veya çelişkili bağlamla doğru görünen cevap verdirmektir. Bir yerde Notion kararı, başka yerde README, üçüncü yerde eski prompt ve dördüncü yerde gerçek production davranışı varsa agent bunların hangisinin authoritative olduğunu bilemez.
İyi context sistemi modele daha fazla bilgi vermez; doğru anda doğru otoriteyi verir.
1. Bilgiyi dört sınıfa ayırmak
| Sınıf | Örnek | Otorite |
|---|---|---|
| Product truth | ürün vaadi, kapsam, kullanıcı akışı | product spec / karar kaydı |
| Code truth | mevcut API, schema, route | repository |
| Operational truth | deploy, secret, release süreci | runbook / platform config |
| Working memory | mevcut görev, deney, hipotez | aktif task context |
Bu ayrım küçük görünür ama çelişki çözümünün temelidir. 'Üründe X olmalı' ile 'kod şu an Y yapıyor' aynı tür gerçek değildir. Agent bu farkı biliyorsa tasarım kararı ile mevcut implementasyonu birbirine karıştırmaz.
2. Single source of truth tek dosya demek değildir
Tek kaynak doğrusu, her bilginin tek belgede yaşaması değil; her bilgi türünün yetkili bir evi olmasıdır. API contract repo'da, ürün kararı ADR veya product spec'te, müşteri araştırması research vault'ta, secret ise secret manager'da olabilir. Önemli olan aynı kararın beş yerde manuel kopyasının bulunmamasıdır.
3. Context pack tasarlamak
Agent'a tüm bilgi tabanını göndermek yerine görev türüne göre küçük context pack'ler kullanırım. Örneğin production bug için repo durumu, son deploy, ilgili runbook, schema ve hata çıktısı gerekir; marka metni için bunların çoğu gereksizdir.
type ContextPack = { task: string; authorities: string[]; constraints: string[]; currentState: string[]; decisions: string[]; staleAfter?: string;};4. Retrieval'da yakınlık değil yetki sırası
Semantic search benzer metni bulur; doğru otoriteyi garanti etmez. Aynı konuda eski bir karar yeni karardan daha benzer olabilir. Bu yüzden retrieval sonucuna source type, updatedAt, status ve supersedes gibi metadata eklemek gerekir.
{ "id": "adr-042", "status": "active", "authority": "architecture-decision", "updatedAt": "2026-08-07", "supersedes": ["adr-019"]}5. Decision log olmadan agent hafızası güvenilmez
Bir mimari kararı yalnızca sohbet içinde verdiyseniz gelecekte o kararın bağlamı kaybolur. Kısa ADR kayıtları kullanırım: karar ne, neden, hangi alternatif reddedildi, hangi koşulda tekrar değerlendirilecek? Bu format hem insan hem agent için yüksek sinyal üretir.
# ADR-042: GitHub is code source of truthStatus: activeDecision: production changes originate from the repository.Reason: preview/local drift caused release ambiguity.Revisit when: deployment architecture changes.6. Prompt ile policy'yi ayırmak
Bir agent'a her görevde 'main'e doğrudan pushlama' diye yeniden yazmak yerine bu kuralı kalıcı çalışma policy'sine koymak daha doğrudur. Prompt o anki işi, policy ise tekrar eden sınırları tanımlar. Context sistemi bu iki katmanı karıştırmamalıdır.
7. Freshness birinci sınıf metadata olmalı
Context sistemlerinde en tehlikeli belge yanlış belge değil, eskiden doğru olan belgedir. Pricing, deploy hedefi, platform sürümü, active feature flag ve mimari kararlar için güncellik kuralı tanımlarım. Süresi dolan bilgi otomatik silinmek zorunda değildir; fakat agent'a authoritative olarak sunulmamalıdır.
8. Repo context'i dosya ağacı dump'ı değildir
Coding agent için tüm repo'yu prompt'a dökmek yerine architecture map, package boundaries, commands, source-of-truth dosyaları ve kritik invariants daha değerlidir. Agent daha sonra ihtiyacı olan dosyayı kendisi açabilir. Yüksek kaliteli başlangıç bağlamı token sayısından daha önemlidir.
- Repository/branch doğrulaması
- İlgili modülün sorumluluğu ve bağımlılıkları
- Build/test komutları
- Değiştirilemeyecek product invariant'ları
- Son ilgili ADR'ler
- Deploy ve migration sınırları
9. Context kalite metriği
Bir context sistemini 'model ne kadar iyi cevap verdi?' ile değil, kaç kez eski karar kullandı, aynı bilgiyi kullanıcıya tekrar sordurdu, yanlış repo/branch seçti veya mevcut mimariyle çelişen öneri üretti gibi operasyonel hatalarla ölçmek daha anlamlıdır.
Sonuç: ikinci beyin arşiv değil routing sistemi
Notion veya Obsidian tek başına context architecture değildir. Değer; bilgiyi saklamaktan, doğru göreve doğru otoriteyi yönlendirmeye geçtiğinizde oluşur. İnsan için PKM olan yapı agent için source routing, freshness ve decision system haline gelmelidir.