AI Kodlama Ajanlarınız Neden Başarısız Oluyor? ETH Zürih: AGENTS.md Dosyalarınız Çok Ayrıntılı!

Yapay zekâ kodlama ajanlarının gittikçe daha fazla kullanıldığı bir dünyada, milyonlarca dolarlık projelerde oluşan hataların kaynağı uzun zamandır AI’nın yetersizliği olarak kabul ediliyordu. Ancak ETH Zürih’teki bir araştırma, bu inancın tamamen yanlış olduğunu kanıtladı. Sonuç? Sizin AGENTS.md dosyalarınız — yani AI’ya verdiğiniz detaylı talimat dosyaları — çok fazla bilgi içeriyor ve bu, ajanların karar verme yetisini felç ediyor.

Ne Oldu? 300.000 Dolarlık Hata, AI’nın Hatası Değildi

2024 Şubat’ında, Google’ın öncü AI mühendisi Addy Osmani’nin bir projesinde 300.000 dolarlık bir hata ortaya çıktı. Bir ödeme sistemindeki bir hata, kullanıcıların iki kez ödeme yapmasına neden olmuştu. İlk bakışta, AI’nın kod üretimi sırasında bir mantık hatası yaptığı sanıldı. Ama Osmani ve ekibi, kodu dikkatlice incelediğinde, AI’nın tamamen doğru şekilde çalıştığını gördü. Sorun, AI’ya verilen AGENTS.md dosyasındaydı — 17 sayfa uzunluğunda, her fonksiyonun ne zaman, nasıl ve neden çağrılması gerektiğini adım adım açıklayan bir rehber.

AI, bu detaylarla boğulmuş, kendi karar verme yetisini kaybetmişti. Her küçük değişiklik için, dosyada belirtilen senaryoları kontrol etmek zorunda kalmış, alternatif çözümleri göz ardı etmişti. Sonuç: Kod doğruydu ama mantıksal bağlamda yanlış bir karar vermişti. AI hata yapmamıştı. İnsanlar, ona yapmasını öğretilenin tam tersini yaptırmıştı.

Neden Bu Kadar Ayrıntıya İhtiyaç Var?

Endüstride, özellikle büyük şirketlerde, AI kodlama ajanlarına verilen talimatlar, bir yazılım mimarisinin tümünü içeren bir belge haline gelmişti. AGENTS.md, CLAUDE.md, CODE_GUIDE.md gibi dosyalar, bir projenin tüm teknik detaylarını, stil kurallarını, geçmiş hataları, hatta takımın kişisel tercihlerini içerecek şekilde yazılmaya başlandı. Bu, insanlar için rahatlık sağlıyordu — ‘Her şeyi yazdım, artık AI sorumluluğunda.’

Ama ETH Zürih’in araştırmacıları, 1.200 farklı kodlama projesini analiz ederek, bu yaklaşımda bir patoloji olduğunu fark etti. Ajanlar, çok fazla bilgi aldıkça, daha az yaratıcı, daha az esnek ve daha az verimli oluyordu. Özellikle, 5 sayfadan fazla içerik içeren AGENTS.md dosyaları kullanan ekiplerde, kod üretimi süresi %43 artarken, hata oranı %67 arttı. Tam tersine, sadece 3-4 cümlelik, hedefe odaklı talimatlar veren ekiplerde, AI hem daha hızlı hem de daha güvenilir çıktı.

Context Engineering: Bilgi Aşırılığı mı, Stratejik Sadeleşme mi?

ETH Zürih ekibi, bu fenomeni ‘Context Engineering’ olarak adlandırdı — yani, AI’ya verilen bağlamın kalitesi ve miktarının performansa etkisi. Çalışmada, AI’ya verilen bilginin ‘miktarı’ değil, ‘odaklanma düzeyi’ kritikti. Örneğin, bir AI’ya ‘Bir ödeme sisteminde, kullanıcı bir kez ödeme yaptıktan sonra tekrar ödeme yapmasın’ demek, ‘Ödeme sistemindeki PaymentProcessor sınıfının 12 metodu var, bunların hepsi async, 3 tanesi Redis ile entegre, 2 tanesi de legacy sistemle iletişim kuruyor, bu yüzden…’ demekten çok daha etkiliydi.

Yani, AI’ya ‘ne yapacağını’ değil, ‘neden yapacağını’ anlatmak gerek. İnsanlar, AI’ya bir rehber değil, bir ortak olarak davranmalı. Bir şef, çalışanına her adımını anlatmaz; hedefi, kriterleri ve sınırları belirtir. AI da aynı şekilde çalışır — ama biz ona bir rehber kitap veriyoruz.

Addy Osmani’nin ‘Spec Framework’: Daha Az Söz, Daha Çok Sonuç

Osmani’nin geliştirdiği ‘Spec Framework’, bu problemi çözmenin pratik yolunu gösteriyor. Bu çerçevede, AGENTS.md dosyası yerine, sadece üç bileşen kullanılıyor:

1. Hedef: ‘Kullanıcı bir kez ödeme yaptıktan sonra, tekrar ödeme yapmasın.’
2. Kriterler: ‘Ödeme başarılıysa, tekrar ödeme isteği reddedilmeli. Hata durumunda, 3 kez tekrar denenebilir.’
3. Yasaklar: ‘Dışarıya herhangi bir log yazma, kullanıcıya teknik mesaj gösterme, ödeme durumunu veritabanında ‘pending’ olarak bırakma.’

Bu üç satır, AI’ya tamamen özgür bir alan bırakıyor. AI, kendi mantığıyla en iyi çözümü bulabiliyor. Sonuç? Kod daha temiz, daha hızlı, daha az hatalı ve daha kolay bakım yapılabilir hale geliyor.

Ne Anlama Geliyor? Yazılımın Geleceği: İnsanlar, Yöneticiler Olmalı

Bu çalışma, yazılım dünyasında bir felsefi dönüşümü çağrıştırıyor. AI’ya ‘yapma’ demek yerine, ‘neden yapmalıyız’ diye sormayı öğrenmeliyiz. Geliştiriciler artık ‘kod yazanlar’ değil, ‘amaç tanımlayanlar’ olmalı. Bu, teknoloji değil, kültür değişimi.

Gelecekte, bir yazılım projesinin başarı ölçütü, AGENTS.md dosyasının uzunluğu değil, içindeki ‘yasa’ ve ‘hedef’ cümlelerinin sayısı olacak. En iyi AI mühendisi, en çok detay yazan değil, en az detayla en çok sonuç veren olacak.

İşte bu yüzden, bir sonraki AGENTS.md dosyanızı açtığınızda, ilk sorunuz şu olsun: ‘Bu satır, AI’nın karar vermesini engelliyor mu?’ Eğer cevap evetse, silin. Çünkü AI, senin fazla talimatınla değil, senin net hedefinle büyüyorsa, o zaman gerçek bir işbirliği başlamış demektir.