AI coding agent’larla çalışırken en büyük verimlilik kaybı kod yazmak değil, her oturumda projeyi yeniden tanıtmak. Bir CLAUDE.md dosyası başlangıç için iyi ama yetmiyor. Bu yazıda, gerçek bir projede deneyerek kurduğum dört katmanlı context engineering ekosistemini anlatıyorum.
Problem: Agent Her Oturumda Sıfırdan Başlıyor
Claude Code, Cursor veya GitHub Copilot ile büyük bir projede çalışırken şu döngüyü yaşarsınız:
- Agent kodu taramaya başlar
- Yüzeysel tarama yüzünden yanlış çıkarımlar yapar (iki farklı modüldeki benzer isimleri karıştırır)
- Context window tool output’larıyla dolmaya başlar
- Siz düzeltirsiniz, agent düzeltmeyi uygular
- Oturum biter, context kaybolur
- Sonraki oturum: 1’e dön
2025-2026 araştırmaları1 gösteriyor ki modeller yapılandırılmış, kalıcı referans noktaları ile beslendiğinde repo taramasına kıyasla belirgin şekilde daha iyi performans gösteriyor. Bu durum “context engineering” disiplinini doğurdu: agent’ın context window’undaki sinyal/gürültü oranını maksimize etme.
Ama bir CLAUDE.md dosyası bu sorunu tek başına çözmüyor. Projede neyin nerede olduğunu, neden o şekilde olduğunu ve o bilgiye ne zaman erişileceğini sistematik olarak yönetmek gerekiyor.
Dört Katmanlı Ekosistem
Gerçek bir SaaS projesinde (event tracking platformu, monorepo, 992 kaynak dosya, 155 ADR) deneyerek kurduğum yapı:
| Katman | Ne | Nasıl | Ne Zaman |
|---|---|---|---|
| 1. Statik referanslar | CLAUDE.md + architecture.md | Her oturum başında otomatik yüklenir | Her zaman |
| 2. JIT arama | mcp-code-search + dnomia-knowledge | Agent ihtiyaç duyduğunda semantik arama | Talep üzerine |
| 3. Karar yönetişimi | /court + ADR’ler | Yeni özellik veya mimari karar öncesi | Karar anında |
| 4. Öğrenme döngüsü | forge retro | Tamamlanan iş sonrası | İş bitiminde |
Her katman bir sonrakini besliyor. Statik referanslar agent’ın başlangıç noktası, JIT arama derinleşme aracı, karar yönetişimi tutarlılık garantisi, öğrenme döngüsü tüm sistemi güncel tutuyor.
Katman 1: Statik Referanslar
CLAUDE.md: Agent’a Talimat Vermek
CLAUDE.md, agent’ın her oturum başında otomatik okuduğu dosya. İçeriği “ne yap, nasıl yap” talimatları:
- Performans kuralları (“barrel import kullanma”, “Promise.all ile paralel çağır”)
- Workflow kuralları (“plan mode’a gir”, “spec yaz”, “ADR oluştur”)
- Deployment komutları (tam çalıştırılabilir string’ler)
- Sınırlar (do/don’t listeleri)
CLAUDE.md’nin işi agent’ı yönetmek. Projenin yapısını anlatmak değil.
architecture.md: Projenin Gerçekliğini Anlatmak
Bu ayrımı keşfetmem birkaç oturum aldı. CLAUDE.md’ye proje yapısı, modül haritası, veri akışı gibi bilgiler koymaya çalıştım. Dosya şişti, okunabilirlik düştü, agent hangi bilginin kural hangisinin referans olduğunu karıştırmaya başladı.
Çözüm: CLAUDE.md agent talimatları, architecture.md proje referansı. İkisi birbirini tamamlıyor ama farklı dosyalarda yaşıyor.
architecture.md’nin içeriği:
| Bölüm | Ne Anlatır |
|---|---|
| Stack ve Dependencies | Tam versiyon numaralarıyla teknoloji yığını |
| Monorepo Yapısı | Dizin ağacı, dosya boyutları, sorumluluklar |
| Modül Haritası | Her modülün sorumluluğu, bağımlılıkları, key dosyaları |
| Data Flow | Verinin sistemde nasıl aktığı (edge’den DB’ye, DB’den destination’a) |
| Veri Modeli | Prisma schema’nın yapılandırılmış özeti |
| Altyapı | Platform, bölge, port, proxy, tunnel bilgileri |
| Mimari Kararlar | Büyük kararlar ve neden alındıkları (ADR referanslarıyla) |
| Performans Kuralları | Gerçek uygulama durumu (uygulanmış/uygulanmamış) |
| Kod Hotspot’ları | Git değişiklik sıklığına göre en çok değişen dosyalar |
| İlişkili Notlar | Vault ve repo dokümantasyonuna cross-reference’lar |
Projemde bu dosya ~3.600 satıra ulaştı. Kulağa çok geliyor ama agent tüm dosyayı her seferinde okumuyor. İhtiyacı olan bölüme atlıyor. Yapı, başlık hiyerarşisi sayesinde bunu kolaylaştırıyor.
Repomix Deneyimi: Neden Gereksiz Kaldı
architecture.md’yi yazarken Repomix’i de denedim. Repomix, kod tabanını tek bir Markdown dosyasına paketleyen, Tree-sitter ile fonksiyon imzalarını çıkaran bir araç.
Sonuçlar:
| Mod | Dosya Sayısı | Token | Değerlendirme |
|---|---|---|---|
| Full (tüm repo) | 992 | 1.9M | Context window’un 10 katı |
| Compressed (tüm repo) | 992 | 1.25M | Hala kullanılamaz |
| Compressed (sadece TS/TSX) | 489 | 90K | Teorik olarak sığar ama context’in yarısı |
Repomix’in ürettiği dizin ağacı ve git-change-count sıralaması yararlı. Hotspot dosyalarını oradan çıkardım. Ama asıl değeri “dosya okuyamayan” araçlarda (ChatGPT web arayüzü, web Claude). Claude Code zaten dosyaları doğrudan okuyor. Yapılandırılmış architecture.md + JIT arama, Repomix’in flat dump’ından daha hedefli bilgi veriyor.
Ayrımın Pratikte Etkisi
architecture.md’den önce agent’ın Inngest proxy worker yapısını araştırması ~20 dakika sürüyordu (SSH denemeleri, API endpoint tahminleri, port taramaları). architecture.md’den sonra agent doğrudan ilgili bölümü okuyor: container adı, portlar, tunnel route’ları, env var’lar. Hepsi tek yerde.
Benzer şekilde, “neden Neon’a geçtik?” sorusuna cevap için eskiden 155 ADR’yi taramak gerekiyordu. Şimdi architecture.md’deki “Mimari Kararlar” bölümünde ADR-127 referansıyla özet var, gerekirse agent ADR dosyasını açıyor.
Katman 2: JIT Semantik Arama
Statik referanslar her oturumda yükleniyor ama her bilgi statik dosyaya sığmaz. 992 dosyalık bir kod tabanında “consent check nerede yapılıyor?” sorusunun cevabı 4-5 farklı dosyaya dağılmış olabilir. Bunu architecture.md’ye yazmak dosyayı patlatır. Bunu agent’ın her seferinde grep ile araması context window’u yer.
Çözüm: agent’ın ihtiyaç duyduğu anda, sadece ilgili bilgiyi çekebileceği semantik arama katmanı.
mcp-code-search: Kod İçin Semantik Arama
mcp-code-search, MCP (Model Context Protocol) üzerinden Claude Code’a bağlanan bir semantik kod arama sunucusu.
Nasıl çalışıyor:
Dizin tarama → Tree-sitter AST parse → Chunk (fonksiyon/class/method) → Embed (jina-v2-base-code) → LanceDB → Hybrid searchAgent “find authentication middleware” veya “rate limiting implementation” dediğinde, grep’ten farklı olarak anlamsal eşleşme yapıyor. “rate-limiter.ts” dosyasını buluyor ama aynı zamanda “token bucket” pattern’ini kullanan ilgisiz isimdeki dosyaları da çıkarabiliyor.
| Özellik | Detay |
|---|---|
| Chunking | Tree-sitter AST (40+ dil) |
| Embedding | jina-embeddings-v2-base-code (768 dim, kod odaklı) |
| Depolama | LanceDB (lokal, sıfır network) |
| Arama | Hybrid: vektör benzerliği + FTS, RRF merge (k=60) |
| Artımlı indeksleme | Hash bazlı, sadece değişen dosyalar |
Neden grep yetmiyor: “Consent kontrolü nerede yapılıyor?” sorusunda grep consent kelimesini arıyor ve 47 sonuç dönüyor. mcp-code-search aynı soruya anlamsal olarak yaklaşıp en ilgili 5-10 chunk’ı döndürüyor. Context window’a 47 dosya yerine 10 snippet giriyor.
dnomia-knowledge: Bilgi Tabanı İçin Semantik Arama
dnomia-knowledge, Markdown, MDX ve kod dosyalarını indeksleyen bir bilgi yönetimi MCP sunucusu.
mcp-code-search’ten farkı:
| mcp-code-search | dnomia-knowledge | |
|---|---|---|
| Odak | Kod dosyaları | Markdown + kod + web içerik |
| Embedding | jina-v2-base-code (kod odaklı) | multilingual-e5-base (çok dilli) |
| Depolama | LanceDB | SQLite + FTS5 + sqlite-vec |
| Chunking | AST tabanlı (fonksiyon/class) | Heading tabanlı (## ve ###) |
| Ek özellik | Benzer kod bulma | Bilgi grafi, web indeksleme |
İkisi birlikte çalışıyor: agent bir mimari soruyu dnomia-knowledge’a, bir implementasyon sorusunu mcp-code-search’e yönlendiriyor. İkisi de MCP üzerinden bağlı, agent hangisinin daha uygun olduğuna kendisi karar veriyor. dnomia-knowledge ayrıca geliştirici etkileşim takibi yapıyor: hangi dosyaların en çok okunduğunu, hangi aramaların boş döndüğünü ve arama sonuçlarını kişiselleştirmek için interaction boost uyguluyor.
Progressive Disclosure: Bilgiyi Kademeli Açmak
1M token context window bile fazla bilgiyle doldurulduğunda performans düşüyor2. Bu yüzden “her şeyi yükle” yerine “lazım olanı çek” yaklaşımı kritik.
Ekosistemde bu şöyle çalışıyor:
- Oturum başı: CLAUDE.md + architecture.md otomatik yüklenir (statik, her zaman gerekli)
- İlk soru: Agent architecture.md’den ilgili bölümü okuyor (jump-to pointer)
- Derinleşme: Agent mcp-code-search veya dnomia-knowledge’a semantik sorgu atıyor (JIT)
- Karar gerekli: Agent ADR dosyasını açıyor (on-demand)
Her adımda context’e sadece gereken bilgi giriyor. Bu, Repomix’in “her şeyi tek dosyaya koy” yaklaşımının tam tersi.
Katman 3: Karar Yönetişimi
Kod tabanının yapısını bilmek ve arama yapabilmek yetmiyor. “Neden Redis yerine Inngest kullanıyoruz?” sorusuna cevap veremezseniz, agent bir gün Redis eklemek isteyebilir. Veya aynı problemi daha önce değerlendirip reddettiğiniz bir yöntemle çözmeye çalışabilir.
/court: Yapılandırılmış Değerlendirme
/court, yeni özellik veya mimari karar öncesi çalışan bir değerlendirme skill’i. Decision Gate framework’ünün 8 kriterini uygular ve sonucu GO, DEFER veya KILL olarak verir.
Ama /court’un context engineering açısından asıl değeri: her karar ADR olarak kaydediliyor. “Neden bu kararı aldık?” sorusunun cevabı, oturum bazlı context’te kaybolmuyor. Agent gelecekte aynı konuya döndüğünde, önceki değerlendirmeyi ve gerekçesini okuyabiliyor.
ADR’ler: Canlı Kısıtlamalar
Architecture Decision Record’lar genellikle pasif log olarak düşünülür. Ama agent ekosisteminde aktif kısıtlamalar:
- Mimari sınırlar: “Collect worker’dan doğrudan DB sorgusu yapılmaz, Hyperdrive üzerinden geçmeli” (ADR-062)
- Veri işleme kısıtlamaları: “PII plaintext olarak loglanamaz, AES-256-GCM + blind index” (ADR-137)
- Reddedilen alternatifler: “Redis cache değerlendirildi, operasyonel yük nedeniyle reddedildi” (ADR-128)
Agent architecture.md’deki “Mimari Kararlar” bölümünden özeti görüyor. Detay gerekirse ADR dosyasını açıyor. Bu sayede aynı tartışma tekrarlanmıyor.
Projemde 155 ADR var. Bunların her birini architecture.md’ye yazmak yerine, 12 büyük kararı 4 kategoride özetledim ve ADR indeksini referans olarak ekledim. Agent özetten başlıyor, gerekirse derinleşiyor.
”Kernel of Truth” Workflow
155 ADR’nin hepsini ben sıfırdan yazmadım. Çoğu “Kernel of Truth” pattern’iyle oluştu: ben bir cümle yazıyorum (“Neon’a geçtik çünkü Docker port bypass güvenlik açığı vardı”), agent bunu yapılandırılmış ADR formatına genişletiyor. Yazma yükü minimum, ama kararın kaydı kalıcı.
Katman 4: Öğrenme Döngüsü
İlk üç katman bilgi sağlıyor. Dördüncü katman bilgiyi güncel tutuyor.
Forge Retro: Tamamlanan İşlerden Pattern Çıkarmak
Forge pipeline’ının son adımı olan /retro, tamamlanan bir özellikten kalıcı pattern’ler çıkarıyor:
- Court kararını oku (neden GO verdik?)
- İmplementasyonu incele (ne değişti?)
- Critique bulgularını kontrol et (ne sorun çıktı?)
- Kalıcı pattern varsa CLAUDE.md’ye veya architecture.md’ye ekle
- Geçici bilgileri temizle
Kritik nokta: retro bilgi tabanını büyütmüyor, buduyor. “Bu pattern 3 kez tekrarlandı, artık kural olsun” diyerek CLAUDE.md’ye ekliyor. “Bu geçici bir workaround’du” diyerek siliyor. Append değil, upsert mantığı.
Döngünün Kapanması
Oturum başı: CLAUDE.md + architecture.md yüklenir
↓
Çalışma: JIT arama ile derinleşme
↓
Karar: /court ile değerlendirme → ADR kaydı
↓
İş bitimi: /retro ile pattern çıkarma
↓
Güncelleme: CLAUDE.md / architecture.md güncellenir
↓
Sonraki oturum: güncel referanslar yüklenirHer iterasyonda referanslar biraz daha doğru, biraz daha güncel oluyor. Agent her oturumda biraz daha az keşif yapıyor, biraz daha çok üretim yapıyor.
Araştırma Temeli
Bu ekosistemi sıfırdan icat etmedim. 2025-2026 araştırmalarından (akademik makaleler, Gemini Deep Research, GPT-4o analizi, Kimi K2.5 araştırması) derlenen bulgular temel oluşturdu:
Codified Context yaklaşımı1: 108.000 satırlık bir C# projesinde test edilen üç katmanlı sistem (Hot Memory, Domain Expert Agent’lar, Cold Memory). Kritik bulgu: dokümantasyon altyapıdır, kod gibi bakım gerektirir.
AGENTS.md ekosistemi: Farklı AI araçları için farklı config dosyaları (CLAUDE.md, AGENTS.md, .cursorrules) ama hepsi aynı amaca hizmet ediyor: agent’a yapılandırılmış bağlam vermek. “Nearest-Wins” modeli: monorepo’da root’taki dosya global standartları, alt dizinlerdeki dosyalar yerel rehberliği sağlıyor.
Hybrid yaklaşım konsensüsü: Tüm kaynaklar aynı noktada birleşiyor: “what” otomatik üretilir (schema, tipler, dependency graph), “why” insan yazar (tasarım kararları, kısıtlamalar, trade-off’lar). İkisi birlikte agent’a tam resmi veriyor.
Progressive disclosure: Bilgiyi tümüyle yüklemek yerine, sadece ihtiyaç anında açmak. Jump-to pointer’lar, çalıştırılabilir arama komutları, nested override’lar.
Pratikte Ne İşe Yaradı, Ne Yaramadı
| Yatırım | Sonuç |
|---|---|
| architecture.md (~3.600 satır) | Agent’ın keşif süresi belirgin şekilde düştü. Özellikle altyapı sorularında (port, proxy, tunnel) deneme-yanılma yerine doğrudan referans. |
| ADR indeksi (155 karar) | Tekrar eden tartışmalar bitti. “Bunu daha önce değerlendirdik” diyebilmek çok değerli. |
| mcp-code-search | Grep’e göre daha isabetli, özellikle “X’i yapan tüm yerleri bul” sorgularında. |
| dnomia-knowledge | Vault notları ve dokümantasyon araması için çok yararlı. Kod aramasıyla birlikte tamamlayıcı. |
| /court | Codebase audit’inde 28 görevden 6’sı elenmiş veya ertelenmiştir. Kötü fikirleri erken filtreliyor. |
| Repomix | Hotspot analizi dışında gereksiz kaldı. Claude Code zaten dosya okuyabiliyor. |
| Forge retro | Henüz yeterli veri yok (yeni). Konsept doğru, etki ölçümü için erken. |
Template
Bu yapıyı kendi projenize uyarlamak istiyorsanız, minimum başlangıç seti:
Küçük projeler (tek servis, 50-100 dosya):
- CLAUDE.md (kurallar + komutlar)
- architecture.md’de tek sayfalık yapı özeti yeterli
Orta projeler (monorepo, 200-500 dosya):
- CLAUDE.md + architecture.md (ayrı dosyalar)
- mcp-code-search (semantik kod arama)
- ADR’ler (büyük kararlar için)
Büyük projeler (500+ dosya, birden fazla servis):
- Tam dört katman
- architecture.md’de modül haritası, data flow, altyapı, mimari kararlar
- dnomia-knowledge (dokümantasyon + kod araması)
- /court + forge pipeline
Her durumda: CLAUDE.md talimat verir, architecture.md gerçekliği anlatır. Bu ayrım temel. architecture.md’yi sıfırdan yazmak yerine yapılandırılmış bir template ile başlamak istiyorsanız, bu deneyimlerden türettiğim Living Architecture template’ini inceleyebilirsiniz.
Kaynaklar
Açık Kaynak Araçlar
- living-architecture: Proje agnostik architecture.md template’i
- mcp-code-search: Semantik kod arama MCP sunucusu
- dnomia-knowledge: Bilgi yönetimi MCP sunucusu
- forge: Memory-backed karar-teslim pipeline’ı
Akademik ve Endüstri Kaynakları
- Codified Context: Infrastructure for AI Agents in a Complex Codebase (arxiv.org/html/2602.20478v1)
- AgenticAKM: Agentic Architecture Knowledge Management (arxiv.org/html/2602.04445v1)
- AGENTS.md Standard (aihero.dev)
- C4 Model (c4model.com)
- Repomix (github.com/yamadashy/repomix)
İlişkili Yazılar
- Living Architecture: Proje agnostik architecture.md template’i (10 temel bölüm, 11 opsiyonel modül, 3 derinlik seviyesi)
- AI Agent’lar İçin Yaşayan Mimari Dokümantasyon: Bu ekosistemin araştırma temeli (Codified Context, AGENTS.md, C4 Model, Repomix, ADR, SDD karşılaştırması)
- Claude Code Context Yönetimi: MCP araçlarıyla context window optimizasyonu
- Decision Gate v2: /court skill’inin detaylı anlatımı
- Forge Pipeline: Memory-backed geliştirme pipeline’ı
- Geliştirici Etkileşim Takibi: dnomia-knowledge’ın trace analytics sistemi, hot files, knowledge gaps ve interaction boost
- AI Destekli Codebase Audit: CLAUDE.md ve context engineering’in 6 track’li audit sürecinde nasıl kullanıldığı
- AI Agent Protokolleri Rehberi: MCP’nin diğer 5 açık protokolle birlikte konumlandırılması
Footnotes
- “Codified Context: Infrastructure for AI Agents in a Complex Codebase” (arxiv.org/html/2602.20478v1). 108.000 satırlık bir C# projesinde test edilen üç katmanlı sistem. ↩ ↩2
- Context window doluluk oranı arttıkça model performansının düştüğü birden fazla benchmark’ta gözlemlenmiştir. “Lost in the Middle” (Liu et al., 2023) bu fenomeni ilk belgeleyen çalışmalardan biridir. ↩
- 01 CLAUDE.md agent'a ne yapacağını söyler, architecture.md projenin gerçek yapısını anlatır. İkisi farklı amaçlara hizmet eder ve birbirinin yerine geçemez.
- 02 Tüm bilgiyi context window'a yüklemek yerine, JIT (just-in-time) semantik arama ile sadece lazım olan bilgiyi çekmek daha verimli.
- 03 Karar almadan önce yapılandırılmış değerlendirme (/court) ve kararların ADR olarak kaydedilmesi, agent'ın gelecekte tutarlı kalmasını sağlar.
- 04 Öğrenme döngüsü olmadan ekosistem durağanlaşır. Forge retro'su tamamlanan işlerden kalıcı pattern'ler çıkarıp kuralları güncelleyerek döngüyü kapatır.
+ Context engineering nedir?
AI agent'ın context window'undaki sinyal/gürültü oranını maksimize etme disiplini. Agent'a doğru bilgiyi, doğru zamanda, doğru formatta vermek. Prompt engineering'in ötesinde, sistematik bir altyapı yaklaşımı.
+ CLAUDE.md ile architecture.md arasındaki fark nedir?
CLAUDE.md agent'a talimat verir: 'barrel import kullanma', 'Promise.all ile paralel çağır'. architecture.md projenin gerçekliğini anlatır: hangi modül nerede, veri nasıl akıyor, hangi kararlar neden alındı. Biri 'nasıl çalış', diğeri 'neyle çalışıyorsun'.
+ Repomix gibi araçlar gereksiz mi?
Claude Code gibi dosya okuyabilen araçlarda evet. Repomix 992 dosyalık bir repoyu 1.9M token'a paketliyor, bu context window'un 10 katı. Sıkıştırılmış hali bile 90K token. Yapılandırılmış architecture.md + JIT arama aynı bilgiyi çok daha verimli veriyor. Repomix, dosya okuyamayan araçlara (ChatGPT web, web Claude) repo bağlamı vermek için hala yararlı.
+ Bu ekosistemi kurmak ne kadar efor gerektiriyor?
architecture.md'yi sıfırdan yazmak birkaç oturum sürüyor (benim durumumda ~3.600 satır). Ama agent'ın kendisi de yardım ediyor: ADR'leri tarayıp özetliyor, kod tabanını analiz edip modül haritası çıkarıyor. İlk yatırımdan sonra bakım maliyeti düşük, çünkü her büyük değişiklikte sadece ilgili bölüm güncelleniyor.
+ Solo geliştirici için bu kadar yapı gerekli mi?
Solo geliştirici için daha da gerekli. Takım olsaydınız, biri size 'o kararı şu yüzden almıştık' diyebilirdi. Solo çalışırken AI agent sizin takım arkadaşınız, ama her oturumda sıfırdan başlıyor. Bu ekosistem, agent'ın her seferinde projeyi yeniden keşfetmesini önlüyor.