AGENTS.md dosyası, AI Aracıları için bir benioku dosyasıdır: depoda, özellikle bağımsız kodlama aracıları için derleme adımlarını, test komutlarını, araçları, mimari satırlarını ve kodlama yönergelerini açıklayan sabit bir konum. Buradaki fikir, aracıların bu dosyayı önceden okuması ve dolayısıyla testleri nasıl çalıştıracaklarını, kodu nasıl yapılandıracaklarını ve hangi kurallara uymaları gerektiğini daha hızlı anlamalarıdır.
Duyurudan sonra devamını okuyun
OpenAI, Anthropic, GitHub ve Qwen gibi sağlayıcılar bu modeli agresif bir şekilde desteklemektedir. Ek olarak, birçok çerçeve aşağıdakiler gibi komut satırı komutları sağlar: /init mevcut bir depodan otomatik olarak bir AGENTS.md veya CLAUDE.md gibi benzer bir dosya oluşturmak için kullanılır. Sonuç olarak standart hızla yayıldı: 2025 yılına gelindiğinde on binlerce halka açık GitHub deposu zaten bağlam dosyalarıyla donatılmıştı ve bu eğilim artıyor. GitHub'daki AGENTS.md deposu faydaları listeler ve böyle bir dosyanın nasıl oluşturulacağına dair örnekler gösterir.
ETH Zürih'ten bir ekip, AGENTS.md'nin yapısını ve kullanışlılığını inceledi. “AGENTS.md'nin Değerlendirilmesi: Depo düzeyindeki içerik dosyaları kodlama aracıları için yararlı mıdır?” çalışması bu tür dosyaların gerçek temsilci iş akışları üzerindeki etkisini sistematik olarak inceleyen ilk kuruluştur. Bunu yapmak için araştırmacılar iki kriteri birleştiriyor: on bir popüler Python deposundan 300 görev içeren köklü SWE-bench Lite ve daha az bilinen on iki depodan 138 görev içeren AgentBench kıyaslama aracı; bunların tümü geliştiriciler tarafından yazılan gerçek bağlam dosyalarını içeriyor.
Çalışma ekibi, kodlama aracıları Claude Code'u Sonnet 4.5 ile, OpenAI Codex'i GPT-5.2 ve GPT-5.1 mini ile ve Qwen Code'u Qwen3-30B-Coder ile test etti; bunların her biri üç değişkende test edildi: bağlam dosyası olmadan, ilgili aracı geliştiricisinin tavsiyesine göre otomatik olarak oluşturulmuş bir bağlam dosyasıyla ve – AgentBench'te – geliştiriciler tarafından tutulan gerçek bağlam dosyasıyla. Tüm aracılar dosyayı kendi bağlamlarında, AGENTS.md (Codex ve Qwen kodu için) veya CLAUDE.md (Claude kodu) içinde yüklediler. Ekip, başarı oranını test paketlerini titizlikle kullanarak ölçtü: Bir görev yalnızca, aracı yaması uygulandıktan sonra ilgili tüm testler yeşile dönerse çözülmüş olarak kabul edilir.
Gözlem: neredeyse hiç fayda yok, önemli maliyetler
Sonuç çok çarpıcı: LLM tarafından oluşturulan içerik dosyaları, başarı oranını ortalama olarak biraz azaltır – modele bağlı olarak SWE-bench Lite için yaklaşık yüzde 0,5 ve AgentBench için yaklaşık yüzde 2-3 puan. Aynı zamanda, çıkarım maliyetleri ortalama %20 ila %23 oranında artar çünkü aracılar daha fazla adım gerçekleştirir ve daha uzun muhakeme adımları üretir.
İnsan tarafından yönetilen bağlam dosyaları bile yalnızca orta derecede daha iyi performans gösteriyor: Bağlam dosyalarının olmadığı senaryoya kıyasla AgentBench'teki başarı oranını ortalama yüzde 4 puan artırıyorlar, ancak aynı zamanda aracı adımlarının sayısını ve dolayısıyla maliyetleri de bireysel yapılandırmalarda neredeyse %20 artırıyorlar. Açıkça söylemek gerekirse bu, birkaç yüzdelik başarı puanı için önemli ölçüde daha yüksek token tüketimi, daha uzun yürütme süreleri ve daha karmaşık aracı izlemeleri için ödeme yapacağınız anlamına gelir.
Çalışma, aracıların bağlam dosyalarındaki talimatları ciddiye aldığını gösteriyor: Belirli araçlardan veya iş akışlarından bahsedilirse aracılar, proje komut dosyaları, pytest, uv veya depoya özgü yardım araçları gibi bunları daha sık kullanır. Bağlam dosyaları ayrıca ek testlere, dosyalara daha fazla erişime ve veri havuzunda daha ayrıntılı gezinmeye olanak tanır. Yani sorun, modellerin bağlam bildirimlerini göz ardı etmesi değil.
Duyurudan sonra devamını okuyun
Bununla birlikte, ek görev, görevleri daha da zorlaştırır: daha fazla talimat, aracının dikkate alması ve değiştirmesi için daha fazla şey anlamına gelir, bu da görev başına daha fazla akıl yürütme jetonuyla sonuçlanır. Aynı zamanda, bağlam dosyaları, depoya genel bakış açısından zayıf performans gösterir: birçok dosya açıkça dizin yapılarını, bileşenlerini ve giriş noktalarını açıklasa da, ortalama olarak aracılar bir hatayı düzeltmeyle ilgili dosyaları AGENTS.md olmadan olduğundan daha hızlı bulamazlar.
Hedeflenen katma değer yerine gereksiz dokümantasyon
ETH ekibinin önemli bir gözlemi, LLM tarafından oluşturulan içerik dosyalarının genellikle mevcut belgelerle gereksiz olmasıdır: Benioku, Katkıda Bulunma, Dokümanlar ve örnekler klasörleri zaten oluşturma ve test notlarını, mimariye genel bakışları ve stil özelliklerini içerir; aracılar bunları dosya erişimi yoluyla da kullanabilir. Bir ablasyon deneyinde araştırmacılar diğer tüm dokümantasyon dosyalarını arşivden kaldırdılar ve yalnızca oluşturulan içerik dosyasını bıraktılar. Ablasyon deneyi (ablasyon çalışması), bir özellik, katman veya modüller gibi belirli bileşenlerin genel performans üzerindeki etkilerini ölçmek için kaldırıldığı veya değiştirildiği yapay zeka modellerini değerlendirmeye yönelik bir yöntemdir.
Bu kadar zayıf dokümantasyona sahip bir ortamda resim değişir: oluşturulan bağlam dosyaları aniden aracıların başarı oranını ortalama yüzde 2,7 puan artırır ve hatta bazen geliştiricinin orijinal dokümanlarından daha iyi performans gösterir. Açık yorum: Bağlam dosyaları, mevcut bilgiyi biraz farklı bir biçimde tekrarladıklarında değil, aracıların bilgilerindeki gerçek boşlukları doldurduklarında faydalıdır.
Yaklaşık 2.000 depodaki 2.300'den fazla aracı benioku dosyasının ayrı bir ampirik analizi, geliştiricilerin bu tür dosyaları bugün nasıl kullandığını göstermektedir (“Ajan README'leri: Aracı Kodlama için Bağlam Dosyalarının Deneysel Bir Çalışması” çalışmasına bakın). Çoğunlukla işlevsel bağlam içerirler: derleme ve yürütme komutları (durumların %60'ında), uygulama ayrıntıları (neredeyse %70) ve mimari notlar (yaklaşık %68).
Öte yandan, dosyaların yalnızca yaklaşık %15'inde açıkça ele alınan güvenlik ve performans gibi işlevsel olmayan gereksinimler önemli ölçüde yetersiz temsil edilmektedir. Dahası, pek çok dosya uzundur, okunması zordur ve net bir şekilde seçilmiş belgelerden çok, birçok küçük ekleme içeren yapılandırma eserleri olarak geliştirilir; bu, genel bağlam dosyalarının aracılar için neden hızla bilişsel bir yük haline geldiğinin bir başka göstergesidir.
Kullanım için pratik kurallar
Pratik bir bakış açısından bu, AGENTS.md'nin verimli kullanımına yönelik bazı ipuçları anlamına gelir (bkz. GitHub blog makalesi “Harika bir AGENTS.md Nasıl Yazılır”):
- Benioku dosyasında ve belgelerde zaten bulunanları tekrarlamayın. Eğer başka bir yerde muhafaza edilmişlerse, mükerrer tasarım açıklamalarından veya uzun mimari konulardan kaçınılmalıdır.
- Eksik ve anlaşılması zor bağlamlara vurgu. Bu, projeye veya takıma özel komut dosyalarını, özel test kurulumlarını, açık olmayan tuzakları veya aracının normalde yalnızca yoğun deneme yanılma yoluyla öğreneceği alana özgü değişmezleri içerir.
- İstek listeleri yerine minimalist doğrulanabilir kurallar. Her ek kural, aracının arama alanını artırır. “Testler her zaman biter” gibi açıkça gerekçelendirilmiş bazı gereklilikler belirlemek mantıklıdır.
make test-ciYarım düzine alternatif iş akışı yerine “çalıştır”. - Temsilcinin rolünü açıkça kişiselleştirin. GitHub, 2.500'den fazla AGENTS.md dosyasının analizinden, saf test aracısı veya Dokümanlar aracısı gibi özel rollerin genel talimatlardan daha iyi performans gösterdiğini bildiriyor.
- Her şeyi baştan mükemmelleştirmek yerine tekrar tekrar geliştirin. Başarılı temsilci benioku dosyaları, tipik temsilci hatası çeşitlerini gözlemleyen ve hedefe yönelik, kısa düzeltme talimatları türeten ekipler tarafından oluşturulur.
Aracının AGENTS.md dosyasını optimize etmesine izin vermek de yararlı olabilir. LLM, belirsiz formülasyonları, çelişkileri, fazlalıkları veya eksik karar kurallarını belirleyerek ve bunları daha kesin bir şekilde formüle ederek bir AGENTS.md'yi analiz edebilir ve iyileştirebilir. Gözden geçirilmiş talimatlar daha sonra bir aracının davranışını kontrol eder. Bu özellikle, sonucun yalnızca dosyayı yeniden yazmak değil, aynı zamanda aracının gerçekten istenen kuralları daha iyi takip edip etmediğini görmek için örnek görevlerle test etmek olması durumunda kullanışlıdır. Bu nedenle en güvenilir yaklaşım, dilsel açıdan daha güzel bir versiyona dayanmak yerine analiz eden, gözden geçiren ve test eden yinelemeli bir süreçtir.
Kodlama aracılarına sahip ekipler için çıkarımlar
Geliştirme ekipleri için AGENTS.md, ücretsiz bir üretkenlik artışı değil, taviz vermeleri gereken bir kontrol aracıdır. Halihazırda, yüksek oranda yedekli, otomatik olarak oluşturulan içerik dosyaları başarı oranlarını kötüleştiriyor, her aracıyı daha pahalı hale getiriyor ve hata ayıklaması daha zor olan daha karmaşık izler oluşturuyor.
Depo bağlam dosyaları, niş araç zincirleri veya açıkça tanımlanmış aracı rolleri için yetersiz belgelenmiş veya özel kod tabanları gibi özellikle eksik bilgileri sağladıkları durumlarda özellikle faydalıdır. AGENTS.md web sitesinde yer alan “Yapay Zeka Temsilcileri için Beni Oku” beyanı bu nedenle kelimenin tam anlamıyla anlaşılmalıdır: başka bir kapsamlı belge olarak değil, aracılara güvenilir sonuçlar için ihtiyaç duydukları tüm bağlamı tam olarak sağlayan ve daha fazla belirteç gerektirmeyen ince ve kesin bir kullanım kılavuzu olarak.
(not)
Bir yanıt yazın