Test neden önemlidir

Yapay zeka destekli kod asistanları, ekiplerin repoya bir "kurallar" dosyası bırakmasına ve modelin her istekte bu direktiflere uymasını beklemesine sıklıkla izin verir. Uygulamada model dosyayı hiç görmeyebilir veya görse bile içeriğini görmezden gelebilir. Claude Code ile yapılan yakın tarihli bir deney her iki sorunu da ortaya koydu. Araç, 72 KB'lık AGENTS.md dosyasını sessizce atladı; aynı dosya CLAUDE.md olarak yeniden adlandırıldığında ise asistan dosyayı yükledi ve her istek için token sayısını artırdı. Bu ekstra token bütçesi gecikmeyi ve maliyeti artırır, ayrıca bir isteği modelin limitinin üzerine çıkarabilir.

"Dosyanın var olması"nın "modelin kurallara uyması" anlamına geldiğini varsayan geliştiriciler, gizli verimsizlikler ve öngörülemeyen çıktılarla karşı karşıya kalma riski taşırlar. Üç aşamalı test; yapılandırma, yükleme ve kullanışlılık olmak üzere her aşamada somut kanıtlar sunmaya zorlar.

Sorulması gereken üç soru

  1. Yapılandırılmış – Dosya, asistanın aradığı yere mi yerleştirildi? Farklı araçlar yolları veya dosya adı geleneklerini sabitler (hard-code); bir uyumsuzluk, dosyanın prompt hattına (pipeline) hiç girmemesi anlamına gelir.
  2. Yüklenmiş – Asistan, dosyayı aldığına dair herhangi bir kanıt sunuyor mu? Bir hash, dosyanın diskteki kimliğini doğrulayabilir ancak yalnızca bir teslimat izi (örneğin bir günlük satırı veya token sayısı), modelin dosyayı gerçekten gözlemlediğini kanıtlar.
  3. Kullanışlı – Dosyanın varlığı görev sonucunu iyileştiriyor mu? Token ekleyen ancak sonucu değiştirmeyen yüklenmiş bir dosya, net bir kayıptır.

Testi çalıştırma

Prosedür, her platformda tekrarlanabilmesi için kasıtlı olarak minimal tutulmuştur.

  1. Görünür bir kural oluşturun – Basit, gözlemlenebilir bir talimat yazın. Örneğin: "Düzenlemeden önce tam olarak iki dosya listeleyin." Kuralın etkisi, asistanın yanıtından kontrol edilebilir.

  2. Araç sürümünü ve modeli kontrol edin – Yeni bir oturum açın, sürüm dizisini ve model tanımlayıcısını not edin. Farklı sürümler, tanıdıkları dosya adını değiştirebilir.

  3. İki çalıştırma gerçekleştirin Çalıştırma A: Aracın tanımadığı bir dosya adı kullanın (örneğin, AGENTS.md). Çalıştırma B: Aracın yerel dosya adını kullanın (örneğin, CLAUDE.md).

    Şunları kaydedin:

    • Dosyanın kaynak hash değeri (disk üzerindeki içeriğin değişmediğini kanıtlamak için).
    • Kullanılan tam yol.
    • Asistanın dosyayı yüklediğine dair kaydettiği herhangi bir kanıt (token sayısındaki artış, açık bir "X.md yüklendi" mesajı vb.).
    • Her bir istek için token sayısı.
    • Görev sonucu (asistan tam olarak iki dosya listeledi mi?).

Eğer Çalıştırma B kuralın uygulandığını gösteriyorsa ve token sayısı beklenen miktarda artıyorsa, dosya hem yüklenmiş hem de kullanışlıdır. Token artışına rağmen kural görmezden geliniyorsa, dosya okunuyor ancak modelin prompt ayrıştırması (parsing) talimatı çöpe atıyor demektir. Bu durumda dosyaya daha fazla metin eklemek işe yaramayacaktır; bunun yerine kuralı sabitlenmiş bir politika kapısına (policy gate) veya bir test düzeneğine (test harness) taşıyın.

Veriler neyi ortaya koyuyor

Claude Code vakası, yapılandırma ile yükleme arasında keskin bir fark olduğunu gösterdi. 72 KB'lık dosya mevcuttu, doğru hash değerine sahipti ve repoyla senkronize edilmişti, ancak asistan dosyaya hiç atıfta bulunmadı. Dosyanın yerel CLAUDE.md olarak yeniden adlandırılması yüklemeyi tetikledi ancak aynı zamanda önemli bir token yükü (overhead) ekledi. Her ekstra token işlem döngülerini tüketir ve isteği hız sınırlarının (rate limits) üzerine çıkarabilir.

Üç aşamalı test, bu tür gizli maliyetleri üretim engelleyicisi (production blocker) haline gelmeden önce gün yüzüne çıkarır. Ekipler, token farkını (delta) yakalayarak kuralın faydasının maliyetinden daha ağır basıp basmadığına karar verebilirler.

Sonuç

Bir kural dosyasının sadece repoda bulunuyor olması, işe yaradığı anlamına gelmez. Bu varsayımı ölçülebilir kanıtlara dönüştürmek için üç aşamalı testi —yapılandır, yükle, kullanışlılığını kanıtla— kullanın. Kanıtlar dosyanın yalnızca bir token tüketicisi (token sink) olduğunu gösterdiğinde, mantığı prompt'tan çıkarıp deterministik bir kapıya (deterministic gate) taşıyın. Sonuç; daha yalın, daha hızlı ve daha öngörülebilir bir yapay zeka kodlama iş akışıdır.