- Next.js 16 API hedefli bir değerlendirmede, proje köküne eklenen
AGENTS.md belge indeksi, skills tabanlı yaklaşımdan daha yüksek doğruluk elde etti
- Skills, ajanın gerektiğinde çağırdığı bir alan bilgisi paketi biçiminde olsa da, çağrının kararsız olması nedeniyle varsayılan yapılandırmada yalnızca %53 geçiş oranında kaldı
- Buna karşılık, 8KB’ye sıkıştırılmış
AGENTS.md indeksi, tüm testlerde (Build, Lint, Test) %100 geçiş oranına ulaştı
- Bu yöntem, karar noktalarını ortadan kaldırması, her zaman erişilebilir olması ve sıra sorununu çözmesi sayesinde etkin çağrı yaklaşımından daha istikrarlı sonuçlar verdi
- Framework bakımcıları, sürümle eşleşen belge indeksini AGENTS.md içine ekleyerek kod üretim doğruluğunu artırabilir
Sorunun arka planı
- AI kodlama ajanlarının, eğitim verilerinin eski API sürümlerine dayanması nedeniyle en güncel framework’leri doğru şekilde ele alamama sınırı bulunuyor
- Next.js 16’daki
'use cache', connection(), forbidden() gibi yapılar mevcut model eğitim verilerinde yer almıyor
- Tersine, eski sürüm projelerde modelin var olmayan yeni API’leri önermesi sorunu da ortaya çıkıyor
- Bunu çözmek için sürümle eşleşen belge erişim yaklaşımı denendi
İki yaklaşım
- Skills: prompt, araç ve belgeleri bir araya getiren açık standart paketler; ajan gerektiğinde çağırıp kullanıyor
AGENTS.md: proje kökünde bulunan kalıcı bağlam dosyası; her sohbet turunda sürekli başvurulabiliyor- Aynı Next.js belgeleri temel alınarak iki yaklaşım karşılaştırmalı olarak değerlendirildi
Skills yaklaşımının sınırları
- Değerlendirme sonucunda, testlerin %56’sında skill çağrılmadı ve temel geçiş oranı %53 ile iyileşme göstermedi
- Bazı kalemlerde hatta başlangıç düzeyinden daha düşük puanlar (ör. testte %58’e karşı %63) görüldü
- Bunun, mevcut modellerin araç kullanımını istikrarlı şekilde gerçekleştirememesi sorununa işaret ettiği belirtiliyor
Açık talimat ekleme deneyi
AGENTS.md içine “kod yazmadan önce skill çağır” şeklinde açık bir talimat eklendiğinde geçiş oranı %79’a çıktı- Ancak talimat ifadesindeki küçük farklar sonucu ciddi biçimde etkiledi
- “Önce skill çağır” → belge örüntülerine saplanma, proje bağlamını kaçırma
- “Projeyi inceledikten sonra skill çağır” → daha iyi sonuç
- Bu tür dilsel kırılganlık, gerçek kullanımda güvenilirliği düşürüyor
Güvenilir değerlendirme kurma
- İlk testler, belirsiz prompt’lar ve yinelenen doğrulama sorunları nedeniyle yeterince güvenilir değildi
- Bunu iyileştirmek için davranış temelli doğrulama ve Next.js 16’nın eğitim verisinde bulunmayan API’lerine odaklı testler kullanıldı
- Başlıca test API’leri:
connection(), 'use cache', cacheLife(), forbidden(), proxy.ts, cookies(), headers(), after(), refresh() vb.
AGENTS.md yaklaşımının deneyi
- Ajanın seçim süreci ortadan kaldırılarak, belge indeksi doğrudan AGENTS.md içine yerleştirildi
- İndeks, belgelerin tamamı yerine sürüme göre belge yolu listelerinden oluşuyordu
- Ek talimat:
IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.
- Bu, modelin mevcut eğitim verisi yerine belge temelli akıl yürütmeyi öncelemesini teşvik etti
Değerlendirme sonuçları
- AGENTS.md indeksinin eklenmesiyle %100 geçiş oranı elde edildi
- Build, Lint, Test sonuçlarının tümü kusursuzdu
- Karşılaştırmalı istatistikler:
- Baseline %53, Skill varsayılan %53, Skill+talimat %79, AGENTS.md %100
- Pasif bağlam yaklaşımının etkin çağrıdan daha üstün olmasının nedenleri
- Karar noktası yok — bilgi her zaman mevcut
- Tutarlı erişilebilirlik — her turda sistem prompt’una dahil
- Sıra sorununu ortadan kaldırır — belge keşif sırasına bağlı değildir
Bağlam kapasitesi sorununun çözümü
- İlk indeks 40KB idi, ancak sıkıştırma ile 8KB’ye düşürüldü (%80 azalma)
- Boru (
|) ayraçlı yapı ile belge yolları ve dosya adları minimum alanda saklandı
- Ajan,
.next-docs/ dizininden yalnızca gerekli dosyaları okuyarak doğru sürüm bilgisini kullandı
Uygulama yöntemi
Framework geliştiricileri için çıkarımlar
- Skills hâlâ faydalı, ancak genel kod üretim doğruluğunu artırmada AGENTS.md yaklaşımı daha etkili
- Skills, “sürüm yükseltme”, “App Router geçişi” gibi belirli görev odaklı iş akışları için daha uygun
- Öneriler:
- skills iyileşmesini beklemeyin, AGENTS.md’yi hemen kullanın
- Bağlamı düşük tutmak için yalnızca belge indeksini ekleyin
- Eğitim verisinde olmayan API’lere odaklı değerlendirmelerle doğrulayın
- Belgeleri ince taneli bir arama yapısı ile tasarlayın
- Hedef, ön eğitim merkezli akıl yürütmeden arama tabanlı akıl yürütmeye geçiş ve bunu en istikrarlı biçimde uygulayan yöntem
AGENTS.md olarak öne çıkıyor
4 yorum
> Yapay zeka kodlama ajanlarının, eğitim verilerinin eski API sürümlerine dayanması nedeniyle en güncel framework’leri doğru şekilde ele alamama gibi bir sınırlaması var.
Context7 kullanınca bu sorun bir ölçüde çözülüyor.
https://context7.com
context7 verimsiz olduğu için yukarıdaki iki yöntemi kullanıyoruz...
Ne demek istediğinizi anlıyorum ama her seferinde AGENTS.md veya Skills içine şu anda kullanılan tüm framework/kütüphanelerin en güncel dokümantasyon bağlantılarını tek tek derleyip eklemektense, context7’yi yardımcı olarak kullanmak o kadar da kötü bir tercih gibi gelmiyor.
Ayrıca ne GeekNews’te ne de Vercel’in ana metninde context7’den bahsediliyor. Bu yüzden, sanki içeriği yarım adım kadar ileriden yorumlamışsınız gibi geldiği için bu yanıtı bırakıyorum.
(Referans olması açısından söyleyeyim: iyi yazılmış Skills ve AGENTS.md ile token tasarrufu sağlanabildiği zaten bilinen bir gerçek ve ben de bunun gayet farkındayım.)
Hacker News yorumları
Model AGI değil. Sadece dosya düzenleme veya araç çağırma gibi etkiler üretmesi için eğitilmiş bir metin üreticisi
Model, kullanıcının becerilerini “anlayıp” kullanmıyor; bunu insan yapımı örnekler ve kullanım kayıtlarına dayanan pekiştirmeli öğrenme (RL) sayesinde bu tür metinler üreterek yapıyor
Becerileri her zaman kullanmamasının nedeni, bu tür örneklerin henüz yeterince öğrenilmemiş olması. RL ile zorlamak ise modeli daha da aptallaştırabilir
Şu anda yaptığımız şey, gelecekteki modellerin becerileri ne zaman kullanmaları gerektiğini daha iyi öğrenebilmesi için beceri kullanım kayıtları biriktirmek
AGENTS.md ise sadece bağlam. Model en başından beri bağlama uyması için eğitildi
Becerilerin frontmatter kısmı da sonuçta bağlama dahil oluyor; dolayısıyla AGENTS.md daha iyi çalışıyorsa bunun nedeni beceri bilgisinin çıkarılıp enjekte edilme biçimindeki fark olabilir
Bazı ajanlar, hangi beceri bilgisinin büyük modele (ör. Sonnet, Opus) aktarılacağına karar vermek için küçük bir model (ör. Haiku) kullanabilir
Sonuçta kilit nokta, hangi bilginin “ham prompt” içine girdiği
Faydalı ama kusursuz değil. GPT teknolojisinin kendisi ise artık performans durgunluğu dönemine girmiş gibi görünüyor
Bundan sonra iyileşecek kısım, beceriler gibi yardımcı sistemler olacak. Ama şu anki beceri uygulaması, AGENTS.md’yi doğrudan yazmaktan daha kötü
Değerlendirmede vakaların %56’sında becerilerin bir kez bile çağrılmadığı sonucu vardı. Yani belgeye sahipti ama kullanmadı. Buna da “Turing testini geçmiş demek ki…” diye şaka eklenmişti
Aradaki fark şu: AI, gurur yapmadan düzeltme talimatını kabul ediyor
Henüz kıdemli geliştirici seviyesinde değil ama talimatları bir junior’dan daha iyi izliyor
Temel bulgu, belge işaretçilerinin sıkıştırılmasının (compression) etkili olması
İnsanların okuması zor olsa da LLM için doğrudan ve verimli bir referans yapısı
İleride agents.md/claude.md/skills.md gibi sezgisel yöntemler yerine, her zaman yüklenen sıkıştırılmış indeks formatı standart hâline gelebilir
API test paketleri, LLM kod performansını doğrulamak için yeniden kullanılabilir
LLM kullanımı arttıkça, kütüphaneler ve API’ler de buna uyum sağlayacak şekilde evrilmeli
Antigravity’de (=GEMINI.md tabanlı) AGENTS.md kurallarına uyulması istenmiş ama yok sayılmış
Buna karşılık “projede AGENTS.md olup olmadığını kontrol et” prompt’u her zaman çalışmış
Eski “let’s think step by step” ifadesinin chain of thought’u tetiklediği dönemler gibi ilginç bir durum
AGENTS.md sistem prompt’una doğrudan dahil edilirse her zaman bağlamda yer alır
Ama tüm becerileri her seferinde dahil etmek israftır. Bu yüzden Anthropic’in advanced tool use yaklaşımı gibi, sadece gerektiği anda çağıran bir yöntem gerekir
Sonuçta mesele bağlam ile maliyet arasındaki denge. Alan varsa AGENTS.md içine sıkıştırarak koymak verimli olabilir
Bu tür kendi bağlamını yöneten ajanlar bu yıl ciddi ilerleme kaydedecek gibi görünüyor
Claude’un becerilere uyum oranı düşük
Ben de benzer bir alanda çalışıyorum. Proje scaffolding yapısının Claude Code/Opencode sonuçlarını nasıl etkilediğini değerlendirmek istiyorum
Ama Vercel’in test yöntemi net olmadığı için karşılaştırma yapmak zor
AGENTS.md, becerilerden tamamen farklı bir şey değil; becerilerin sadeleştirilmiş bir biçimi
Asıl mesele beceri tasarımının kalitesi, yani AI’ın doğru bilgiye ulaşana kadar geçmesi gereken adım sayısını en aza indirmek
Adım sayısı azaldıkça hata birikimi de azalır
Ayrıca token israfını azaltmak için büyük dosyaları sistem prompt’una yalnızca bir kez koyuyorum
Bloglarda prompt engineering karşılaştırmaları yapıldığında benim hep merak ettiğim şey, tek çalıştırma mı yapıldı yoksa birden çok tekrar mı olduğudur
LLM’ler aynı girdide bile tutarlı sonuç vermiyor
Çoğu zaman anekdot düzeyindeki veriler bilimsellik kisvesine büründürülüyor gibi geliyor
Ama özenli benchmark yapınca görüntülenme az oluyor, üstünkörü yapınca blog trafiği 9 kat artıyor
Sorun çarpık teşvik yapısı
AGENTS.md’den daha iyi bir yöntem de olabilir
.contextklasörü oluşturup proje belgelerini (README, bağımlılık belgeleri vb.) sembolik bağlantılarla içine koymak ve her zaman bağlama yükletmekBöylece LLM en baştan ihtiyaç duyduğu tüm bilgiye sahip olur ve performans artışı ile maliyet düşüşü sağlanabilir
_vendorklasörüne koymak çok daha faydalıLLM kodu doğrudan analiz ederek nasıl çalıştığını anlayabiliyor
Kendi özel ajanımı geliştirirken edindiğim deneyim
read/write_fileöğesini duruma ekleyip sistem prompt’unda görünür hâle getirince çok daha iyi çalıştıŞimdi bunu nicel değerlendirmelerle (evals) kanıtlamaya çalışıyorum. Hissedilen performans oldukça iyi