Agent’a Her Şeyi Anlatma, Nereye Bakacağını Öğret

Muhammet Işık
Lifecycle-Mapped Context Harness Architecture

Agentic coding’de context problemi daha fazla dosya üreterek çözülmez. Gerçek kazanç, bilgiyi doğru katmana koyup detaylı bir şekilde haritalandırarak, agent’a yalnızca ihtiyaç duyduğu bölgeyi okutmaktan gelir.

Kod yazmak ucuzluyor. Bir fonksiyonun ilk taslağını çıkarmak, API endpoint açmak, test iskeleti üretmek artık eskisine göre çok daha az insan emeği istiyor. Fakat maliyet ortadan kalkmıyor; başka yere taşınıyor. Agent neyi değiştirmeliydi? Hangi karar hâlâ geçerli? Bu görev neden açılmıştı? Eski uygulama kasıtlı mı, tesadüf mü? Yeni kod başka bir modülü sessizce bozdu mu? Bir sonraki session aynı işi yeniden mi keşfedecek? Kod üretim maliyeti düşerken context kurma, doğrulama ve review maliyeti büyüyor. Harness’in değeri ne kadar büyük olduğuyla değil, agent’ın doğru bilgiye ne kadar az sürtünmeyle ulaşabildiğiyle ölçülür. Birçok projede bunun için devasa ve karmaşık bilgi altyapıları kurmak yerine; yaşam döngüsüne göre doğru tanımlanmış odaklı Markdown katmanları asgari etkili çekirdeği (minimum viable harness) sağlamak için yeterlidir.

Harness Nedir, Ne Değildir?

Harness engineering’i yalnızca bir AGENTS.md veya CLAUDE.md yazmak olarak görmek eksik kalır.

Harness, agent’ın içinde çalıştığı mühendislik düzenidir: hangi bilgilerle başlayacağı, hangi görev sınırını aşamayacağı, sonuçlarını nasıl doğrulayacağı ve ne zaman insana döneceği.

İyi harness, modelin daha zeki olmasını beklemez. Modelin hataya gidebileceği yolları daraltır ve doğru davranışı mekanik olarak kolaylaştırır.

OpenAI kendi harness engineering deneyiminde de aynı sonuca varmış. Ekip, başta tek bir büyük AGENTS.md dosyası kullanmış. Context’i doldurması, kuralları eşit derecede “önemli” hale getirmesi ve hızla eskimesi nedeniyle bu yaklaşımdan vazgeçmiş. Sonuçta kısa bir AGENTS.md dosyasını ansiklopedi değil, içindekiler tablosu gibi kullanmışlar; ayrıntıları indekslenmiş dokümanlarla ihtiyaç halinde açmışlar.

Önemli ayrım burası:

Harness daha fazla talimat yazmak değildir. Doğru davranışa giden yolları tasarlamaktır.

“Ne Kadar Modüler, O Kadar İyi” Yanılgısı

Monolitik dokümanın sorunları gerçek. Yüzlerce kararın tek dosyada bulunması session başlangıcını pahalı hale getirir, güncel ve eski bilgiyi karıştırır, agent’ın kritik talimatları atlamasına neden olabilir.

Fakat buradan “her konu ayrı dosya olmalı” sonucuna atlamak da doğru değil.

Her küçük karar için ayrı dosya oluşturulduğunda başka bir maliyet çıkar:

  • Agent önce doğru dosyanın adını bulmalıdır.
  • Aynı bilgi birden fazla dosyada tekrar edebilir.
  • Linkler ve indeksler güncel tutulmalıdır.
  • Hangisinin ana kaynak olduğu belirsizleşebilir.
  • Eski veya unutulmuş kayıtlar sahipsiz (orphan) hale gelebilir.

Yazılım mühendisliği saha pratikleri, bu tür dağınık ve yaşam döngüsünden kopuk dokümantasyonların birkaç ay içinde hızla güncelliğini yitirip atıl kaldığını gösteriyor. Dosya sayısını artırmak, erişim mimarisi kurmak değildir.

Dosya modülerliği ile bilgi modülerliği aynı şey değildir.

Bir kaydın ayrı dosyada bulunması şart değildir. Kayıt mantıksal olarak sınırlandırılmış, benzersiz kimlikle adreslenmiş, küçük bir aralık halinde okunabilir ve başka kayıtlardan açıkça ayrılmışsa tek başına erişilebilir bir bilgi birimidir — hangi dosyada olursa olsun.

Grep vs LSP Tartışmasının Aslı

Piyasada sıkça yapılan hata: LSP ile grep’i rakip olarak konumlandırmak.

LSP kaynak kodda sembol ve referans arar. Fonksiyonun nerede çağrıldığını, sınıfın nerede tanımlandığını, bir arayüzün implementation’larını bulur. Bunun için tasarlanmıştır.

Fakat Markdown içindeki karar gerekçeleri, ürün sınırları, config açıklamaları ve DEC-ARCH-021 gibi serbest metin kimlikleri kaynak kodun symbol graph’ının parçası değildir. Bunlar için grep veya rg kullanılır. Mesele birini seçmek değil; ikisini doğru yerde kullanmak. Mesele aracı veya jargonu değil, amacı anlamak.

Birkaç Markdown dosyasında benzersiz bir ID ile hedefli arama yaptırmanın pratik maliyeti ihmal edilebilir düzeydedir. rg -F "DEC-ARCH-021" docs/ komutu milisaniyeler içinde sonuç verir ve modele yalnızca eşleşen satırları aktarır. Bütün dosya context’e girmez.

Gerçek maliyeti belirleyen üç farklı kavramı ayırmak lazım:

Maliyet türü Nedir?
İşletim sistemi arama Diskte arama — birkaç ms, ihmal edilebilir
Context maliyeti Modele aktarılan token — arama sonucu ne kadar geniş?
Navigation maliyeti Agent’ın doğru bilgiyi bulmak için harcadığı tool call, gecikme ve hata riski

Navigation maliyeti asıl risktir. Agent genel bir kelimeyle arama yaparsa onlarca sonuç döner. DEC-ARCH-021 gibi benzersiz bir kimlikle ararsa çoğu durumda doğrudan tek kayda ulaşır.

Benzersiz kimliklerin asıl faydası disk hızında değil, navigation belirsizliğini azaltmasındadır.

Lifecycle Ayrımı: Ne, Neden, Ne Zaman?

Peki bilgi nasıl organize edilmeli?

Kendi projelerimde doğal olarak ortaya çıkan bir desen var. Harness’i dev bir talimat dosyası olarak değil, birkaç dosyanın yaşam döngüsüne göre ayrılmış hali olarak kurdum:

SYSTEM.md  → Sistem ne yapar, mimari sınırları nelerdir?
AGENTS.md  → Nasıl çalışmalıyım?
BOARD.md   → Şu anda ne yapmalıyım?
NOTES.md   → Neden böyle yapmalıyım?
HISTORY.md → Daha önce ne yapıldı, nasıl doğrulandı?

Bunları birbirine bağlayan şey de basit:

Aktif görev → İlgili karar kimliği → Hedefli arama → Küçük bölüm okuma → Uygulama → Test → Kayıt güncellemesi

Agent yeni bir session başlattığında bütün repoyu taramıyor. Board’dan aktif görevi buluyor. Görevdeki karar kimliğiyle Notes’ta yalnızca ilgili bölümü açıyor. History’ye ancak eski bir uygulamayı doğrulaması gerekirse gidiyor.

Bu “birkaç büyük dosya” yaklaşımı mı? Hayır. Dosya sayısı görünen yüz. Asıl mimari şunlardan oluşuyor:

  1. Lifecycle partitioning: Aktif iş, karar gerekçesi, tamamlanmış kanıt ve çalışma kuralları ayrılıyor.
  2. Authority routing: Hangi konuda hangi dosyanın otorite olduğu tanımlı.
  3. Addressable records: Benzersiz kimlikler kullanılıyor.
  4. Progressive disclosure: Bütün dokümanlar başlangıçta context’e yüklenmiyor.
  5. Targeted retrieval: ID araması ve küçük satır aralıkları okunuyor.
  6. Scope gating: Agent tek aktif işin sınırları dışına çıkmıyor.

Aynı desen üç ana dosyada da, konu bazlı on dosyada da, yüzlerce ADR dosyasında da uygulanabilir. Kritik olan dosya sayısı değil, adresleme ve yönlendirme modelidir.

Evet3. İcra & DoğrulamaHayırKüçük Kod DilimiTest ve DoğrulamaGeçti mi?2. Hedefli ErişimKarar KimliğiNOTES: Odaklı Arama1. YönlendirmeKullanıcı İsteğiAGENTS: KurallarBOARD: Aktif GörevKayıtları Güncelle

Piyasa Aynı Yöne Gidiyor

Bu yaklaşım teorik bir öneri değil. Piyasanın gittiği yön aynı:

  • OpenAI, kısa AGENTS.md + indekslenmiş dokümanlar + execution plan kullanıyor. Büyük talimat dosyasından vazgeçmiş durumdalar.
  • Anthropic, CLAUDE.md dosyalarının kısa ve spesifik olmasını, skill ve referansların yalnızca gerektiğinde yüklenmesini öneriyor.
  • Codex, dizin hiyerarşisinde birden fazla AGENTS.md kullanarak path-scoped yönlendirme kuruyor.

Ortak nokta açık:

Agent’a daha fazla bilgi yüklemiyorlar. Bilgiyi hangi aşamada, hangi araçla göreceğini tasarlıyorlar.

2026’da yayımlanan bir araştırma bu resmi daha da netleştiriyor. 138 gerçek görev üzerinde yapılan çalışmada, repo context dosyaları genel olarak görev başarı oranını anlamlı biçimde artırmamış; maliyeti ise ortalama yüzde 20’den fazla yükseltmiş. Araştırmacılar, context dosyalarının yalnızca agent’ın başka türlü bilemeyeceği minimal ve gerekli kuralları içermesini öneriyor.

Bu çalışma benim sistemimi doğrudan test etmiyor. Fakat neden şişkin harness kurmamak gerektiğini güçlü biçimde doğruluyor.

Dosya Ne Zaman Bölünmeli?

Basit bir karar ağacı:

  • Bilgi farklı bir hızda mı değişiyor? Aktif görev listesi her gün değişir, mimari kararlar yılda bir. Evet → böl.
  • Bilgi farklı bir ekibin yetkisinde mi? Evet → böl.
  • Bilgi nadiren mi okunuyor ve çok mu uzun? Evet → ayrı dosyaya al, ID ile haritalandır.
  • İki bölüm neredeyse her görevde birlikte mi okunuyor? Evet → ayırma.
  • Bölmek yeni bir source of truth doğuracak mı? Evet → ayırma. Bir dosya ana kaynak, diğeri yalnızca link olmalı.

Fayda belirgin biçimde maliyeti geçmiyorsa aynı dosyada, ayrı ID’li bölüm olarak bırak.

Ne Yapmalı?

Bu yaklaşımı deneyimlemek isteyenler için minimum etkili çekirdek şundan ibaret:

  1. Her dosyanın tek ve açık bir rolü olsun.
  2. Board’dan karar kaydına çift yönlü ID bağlantısı kurulsun.
  3. Session başlangıcında genel bir tarama yerine aktif görev araması yapılsın.
  4. Notes ve History yalnızca hedefli aramayla açılsın.
  5. Her turda tek görevlik küçük uygulama dilimi yapılsın.
  6. Test ve doğrulamadan sonra lifecycle kaydı güncellensin.

Bu yaklaşımı açık kaynak bir çerçeve olarak uyguladım: ContextRail. Birkaç Markdown dosyası, üç platform validator’ı ve sade bir lifecycle sözleşmesinden ibaret. Şişkin değil, doğrudan kullanılabilir.

Sonuç

Agent’a daha fazla doküman vermek ile agent’ın doğru dokümana ulaşmasını sağlamak aynı şey değildir.

Bir repoyu yüzlerce Markdown dosyasına bölmek erişim mimarisi kurmak değildir. Tek bir büyük talimat dosyasını modele vermek de kurumsal hafıza oluşturmak değildir.

İyi harness, agent’ın her şeyi bilmesini istemez.

Agent’ın bilmediği şey her zaman bilgi değildir. Bazen nereye bakacağını bilmiyordur.

Harness’i şişirmek agent’ı güçlendirmeyebilir. Bazen yalnızca daha fazla şey okumasına neden olur.

Basit harness ile ilkel harness aynı şey değildir.

📚 Kaynaklar

  1. OpenAI, “Harness Engineering: Leveraging Codex in an Agent-First World,” 2026. openai.com
  2. Gloaguen vd., “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?”, arXiv:2602.11988, 2026. arxiv.org (Ayrıca bkz. Lulla, Baltes vd., arXiv:2601.20404)
  3. Anthropic, “How Claude remembers your project,” Claude Code Docs. docs.anthropic.com
  4. OpenAI Developers, “Custom instructions with AGENTS.md,” Codex Docs. developers.openai.com
  5. Michael Nygard, “Documenting Architecture Decisions,” Cognitect, 2011. cognitect.com
  6. Liu vd., “Lost in the Middle: How Language Models Use Long Contexts,” arXiv:2307.03172, 2023. arxiv.org

📋 İlgili Bağlantılar

🔗 Proje Kartı: ContextRail: Agentic Coding İçin Minimum Etkili Proje Hafızası
🔗 Agentic Mikroyönetim Hakkındaki Önceki Yazı: LLM’lerle Dans Etmenin Kuralı: Agentic Mikroyönetim

Son güncelleme: Ekim 2026 | Versiyon: 1.0