Temel iddia
- Yapay zeka kodlama ajanları için bağlam dosyasını (AGENTS.md)
/init komutuyla otomatik oluşturmak, ajanın performansını aslında düşürüyor ve maliyeti %20'den fazla artırıyor
- Temel sorun, ajanın kendi başına keşfedebileceği bilgilerin tekrar verilmesi
- AGENTS.md içine yalnızca ajanın kodu okuyarak öğrenemeyeceği bilgiler konmalı
Araştırma sonuçları: AGENTS.md faydalı mı, zararlı mı
- Lulla et al. (ICSE JAWs 2026): GitHub PR 124 üzerinde, yalnızca AGENTS.md'nin varlığı/yokluğu değiştirilerek karşılaştırılan eşleştirilmiş deney
- AGENTS.md varken çalışma süresi %28,64 azaldı, çıktı token'ları %16,58 azaldı
- Bu çalışmada kullanılan dosya, geliştiriciler tarafından gerçekten bakımı yapılan ve projeye özgü bilgi içeren bir dosyaydı
- ETH Zurich araştırması: 4 ajan, SWE-bench vb. üzerinde test edildi ve LLM tarafından otomatik üretilen dosyalar ile geliştirici yazımı dosyalar ayrıştırıldı
- LLM'nin otomatik ürettiği bağlam: görev başarı oranı %2-3 düştü, maliyet %20+ arttı
- README gibi mevcut belgelerin tamamen kaldırıldığı ortamda ise LLM üretimi dosya performansı aksine %2,7 artırdı
- Geliştiricinin doğrudan yazdığı dosya: başarı oranını yaklaşık %4 artırdı, maliyeti ise en fazla %19 yükseltti
- Sonuç: Kötü olan otomatik üretim değil, tekrarın kendisi
- Aynı bilgiyi iki kez vermek yalnızca gürültü ekliyor; gerçek fayda, geliştiricinin yazdığı keşfedilemeyen bilgilerden geliyor
Otomatik üretim neden zararlı
- Otomatik üretilen AGENTS.md çoğunlukla ajanın zaten kendi başına keşfettiği bilgileri içeriyor
- Kod tabanı özeti (Sonnet 4.5 çıktılarının %100'ü, GPT-5.2 çıktılarının %99'u bunu içeriyor)
- Dizin yapısı, teknoloji yığını, modül açıklamaları
- Zaten bilinen bilgiyi yeniden vermek yalnızca token tüketiyor ve değer üretmiyor
- Çapalama etkisi: Eski kalıp ve desenlerden söz edilirse, daha iyi alternatifler olsa bile ajan o kalıplara saplanabiliyor
- Bu, "Lost in the Middle" araştırmasıyla (Liu et al., 2024) uyumlu — uzun bağlam dikkat dağıtarak performansı düşürüyor
AGENTS.md'ye ne konmalı, ne konmamalı
- Konmalı (ajanın keşfedemeyeceği bilgiler)
- Araç belirtimi: "paket yönetimi için
uv kullanılacak"
- Sezgisel olmayan kurallar: "testler mutlaka
--no-cache ile çalıştırılmalı; aksi halde fixture false positive üretiyor"
- Sistem kısıtları: "auth modülü özel middleware kullanıyor, standart Express'e refactor edilmemeli"
- Belgede araçlardan söz edildiğinde ajan bunları görev başına 1,6-2,5 kez kullanıyor; belgelendirilmediğinde bu sayı 0,05'in altına düşüyor
- Konmamalı (ajanın kendi başına keşfedebileceği bilgiler)
- Dizin yapısı, monorepo yerleşimi
- Teknoloji yığını özeti, standart mimari kalıplar
Statik dosyaların yapısal sınırları
- İyi yazılmış bir AGENTS.md'nin bile temel bir zayıflığı var — dosya statik, görev ise dinamik
- Tek bir dosyadaki talimatlar, görev türüne göre koşullu dallanma yapamıyor
- Belge düzenleme işinde bile "commit öncesi tüm testleri çalıştır" talimatı uygulanıp token ve zaman boşa harcanıyor
- CSS refactor sırasında DB migration uyarıları yükleniyor, güvenlik düzeltmesine performans optimizasyonu ipuçları eşlik ediyor
- ACE framework'ü (ICLR 2026): Statik dosya yerine generator/reflector/curator pipeline'ı ile bağlamı dinamik olarak evrimleştiren Agentic Context Engineering yaklaşımı, statik yönteme göre %12,3 daha yüksek performans gösterdi
Daha iyi yapı: henüz inşa edilmedi
- AGENTS.md konusunda birçok kişi bağımsız olarak aynı sonuca ulaşıyor
- Doğru yapı tek dosya değil, yönlendirme katmanı + gerektiğinde yüklenen odaklı bağlam
- Katman 1 - Protokol dosyası: Kod tabanı özeti ya da stil rehberi değil, bir yönlendirme belgesi
- Mevcut persona'ları ve çağrılma koşullarını, becerileri ve sorumlu görev türlerini, MCP bağlantılarını ve kullanım amaçlarını tanımlar
- Yalnızca ajanın keşfedemeyeceği en az düzeyde repo bilgisini içerir; bunun dışında hiçbir şey konmaz
- Katman 2 - Persona/beceri dosyaları: Görev türüne göre seçmeli olarak yüklenir
- UX ajanı ile backend ajanı farklı bağlamlar yükler; birbirlerinin bağlamını yüklemez
- Katman 3 - Bakım alt ajanı: Protokol dosyasının doğruluğunu korumaya adanmış ajan
- Belgeler bozulur — ETH Zurich araştırmasında bile henüz yeni oluşturulmuş dosyalar test edildiği halde performans düşüşü görüldü
- 6 ay dokunulmamış bir AGENTS.md, çoktan değiştirilmiş bağımlılıkları ya da değişmiş dizin yapısını anlatıyorsa durum çok daha vahim olur
- Şu anda önde gelen kodlama ajanlarının hiçbiri bu mimariyi kolayca uygulayacak lifecycle hook'lar sunmuyor — alt ajanlar ve scoped context ile yaklaşılabiliyor ama burada hâlâ doldurulmamış bir araç boşluğu var
Otomatik optimizasyon
- Arize AI, CLAUDE.md talimatlarını elle yazmak yerine otomatik optimizasyon döngüsü kullanıyor
- Ajanı eğitim görevlerinde çalıştır → sonucu değerlendir → başarısızlık nedenine dair LLM geri bildirimi üret → meta prompting ile talimatları iyileştir → tekrarla
- Cross-repo testlerinde +%5,19, in-repo testlerinde +%10,87 doğruluk artışı sağlandı
- Optimize edicinin ortaya çıkardığı rahatsız edici gerçek: Bir insanın kod tabanını anlamasına yardımcı olan şey ile LLM'nin gezinmek için ihtiyaç duyduğu şey aynı değil
- "Bu servis repository pattern kullanıyor" gibi bilgiler geliştiriciye doğal olarak faydalı görünür, ancak model için gürültü olabilir
- Tersine, modelin gerçekten ihtiyaç duyduğu şeyleri (belirli import path ayrımları, sezgisel olmayan dosya adlandırma kuralları vb.) geliştirici zaten içselleştirdiği için yazmayı düşünmeyebilir
- AGENTS.md'yi elle yazmak, geliştiricinin ajanın neye ihtiyaç duyduğunu bildiğini varsayar
- Ampirik kanıtlar muhtemelen bilmediğine işaret ediyor
- Optimize edici, "önemli sanılan şey" ile "sonucu gerçekten değiştiren şey" arasındaki farkı buluyor
- Bu, yazmayı tamamen bırakın demek değil — %5 anlamlıdır ama dönüştürücü değildir. Söylenen şey, sezgilere gevşek tutunup gerçekten test etmek
AGENTS.md'ye bakmanın doğru zihniyeti
- AGENTS.md'yi, henüz düzeltilmemiş bir sürecin kaydı olarak görmek gerek
- Eklenen her satır, kod tabanında yapay zeka ajanını şaşırtacak kadar belirsiz bir nokta olduğunun işaretidir; bu da yeni bir insan katkıcının da muhtemelen aynı yerde zorlanacağı anlamına gelir
- Doğru tepki, bağlam dosyasını büyütmek değil, kök nedeni düzeltmek
- Ajan utility'leri alakasız bir dizine koyuyorsa → dizin yapısı başlı başına kafa karıştırıcıdır, yeniden düzenlenmeli
- Ajan kullanım dışı kalmış dependency'leri kullanmayı sürdürüyorsa → import yapısı bunların yanlış biçimde çok kolay seçilmesine yol açıyordur, düzeltilmeli
- Ajan type checking'i atlıyorsa → talimatlara bel bağlamak yerine bunu build pipeline'ında otomatik yakalamak gerekir
- AGENTS.md kalıcı yapılandırma değil, bir teşhis aracıdır — satır ekle, ajanın bu hatayı neden tekrarladığını araştır, kök nedeni düzelt, sonra o satırı sil
- Denenebilecek bir teknik: Neredeyse boş bir AGENTS.md ile başla ve yalnızca şu talimatı ekle: "Bu projede şaşırtıcı ya da kafa karıştırıcı bir şey bulursan yorum bırak." Ajanın önerdiği eklemelerin çoğu kalıcı saklanacak bilgi değil, kod tabanındaki belirsizlik noktalarının işaretleridir
Pratik öneriler
/init çalıştırmayı bırak — repoda hiç belge yoksa başka, ama aksi halde otomatik üretilen çıktı mevcut belgelerle çakışır- AGENTS.md'ye tek satır eklemeden önce şunu sor: "Ajan bunu kodu okuyarak anlayabilir mi?" Cevap evetse yazma
- Ajan tekrar tekrar başarısız olduğunda, bağlam dosyasını büyütmeden önce önce kod tabanının kendisini düzelt
- Kod yapısını iyileştir, linter kuralları ekle, test kapsamını genişlet — bunlardan sonra hâlâ çözülmediyse AGENTS.md'ye dokun
- CI/CD ya da otomatik inceleme pipeline'larında ajanları büyük ölçekte çalıştırıyorsan, %15-20 maliyet ek yükünün binlerce çalıştırma boyunca bileşik şekilde birikeceğini unutma
- Ajanı yeni işe başlayan biri gibi onboard etme içgüdüsü (ofis turu, organizasyon şeması, mimari anlatımı) doğaldır; ama kodlama ajanı yeni çalışan değildir — prompt'u tamamlamadan önce bile tüm kod tabanında grep çalıştırabilir. Ajanın ihtiyacı harita değil, mayınların yeridir
9 yorum
Sonuçta bunun bir context savaşı olduğu söyleniyordu...
Agent için olan md ile kullanıcı için olan md’yi ayrı ayrı oluşturtmak gerekmez mi diye düşünüyorum.
Tamamen katılıyorum. İnsanın rahat okuyabildiği yapı (README) ile LLM'in kolayca parse edebildiği yapı (AGENTS.md) tamamen farklı çünkü. Tüm bağlamı düşünmeden otomatik üretip olduğu gibi vermek, sadece API token maliyetini boşa harcıyor; üstelik halüsinasyonların da daha da artmasına sık sık tanık oldum. Sonuçta uğraştırıcı olsa da, ajanlar için yönergeleri insanların bizzat sıkıştırıp arındırması en verimli yöntem gibi görünüyor.
Başlangıçta README vardı; AGENTS.md de aslında ajanlar için hazırlanmış bir README’dir.
Ama onun için zaten bir README yok mu?
Ama modelin kendisi birkaç ay içinde değişiyor
ve modele göre agent’ları güncellemek gerekiyor...
Uygun bir agent yapısı oluşturmaya harcanan zamandan daha hızlı değişen şey modelin kendisi değil mi?
İnsan araca alışamadan araç değişip gidiyor yani...
Sonuçta en önemli şeyin context'i yalın ve az token'lı tutmak olduğu görünüyor.. Bu açıdan bakınca Çince karakterler oldukça kullanışlı olabilir gibi geliyor. haha
Model için İngilizce zaten neredeyse 1 kelime = 1 karakter (token) gibi; aslında fiilen Çince karakterler gibi değil mi?
Oo, böyle bir yaklaşımı hiç düşünmemiştim ama kulağa mantıklı geliyor!
Vay ..