Araştırma: Eski CLAUDE.md ve AGENTS.md dosyaları, ajanların yüzde 90'ında çalışan kodun yerine geçiyor

Yaygın olarak kullanılan iki kodlama ajanı üzerinde yapılan kontrollü bir araştırma, bir depodaki talimat dosyası gerçek kodla çeliştiğinde ajanların onda dokuz kez eski dosyaya uyduğunu ve bazen çalışan modülleri dosyaya uydurmak için yeniden yazdığını ortaya koydu. Araştırmayı ele alan dev.to'daki bir yazı, ajanın kullanıcı düzeyindeki yapılandırmasına eklenecek tek bir cümlenin bu davranışı tersine çevirdiğini gösteriyor.

Talimat dosyaları donuk kalırken kod ilerliyor

dev.to makalesinde atıf yapılan iki anket sorunun ne kadar yaygın olduğunu çerçeveliyor. Denisov-Blanch ve diğ. (2026), 441 şirket deposunu analiz edip yapay zekâ yapılandırma dosyalarının yüzde 73,8'inin bir kez commit edildiğini ve bir daha hiç değiştirilmediğini buldu. Treude ve Baltes (2026), 356 herkese açık depoyu inceleyip talimat dosyalarının yüzde 23,0'inin artık var olmayan kod öğelerine atıfta bulunduğunu saptadı. Başka bir deyişle, tipik bir deponun talimat katmanı, kurulum gününden kalma bir anlık görüntü.

Deney neyi ölçtü

Çekirdek deneyi Georgia Tech ve UC Boulder'dan Xiaonan Xu ile Wenjing Wu (arXiv:2610.30571) gerçekleştirdi; her biri çalışan modüllere, geçen bir test paketine ve bir konvansiyonu dayatırken kodun tutarlı biçimde başka bir konvansiyon kullandığı bir talimat dosyasına sahip 40 Python projesi kullanıldı. 16 konvansiyon kategorisi arasında print() ile logging, os.path ile pathlib ve dize sabitleri ile Enum yer alıyordu. Claude Code'dan (v2.1.302, Claude Sonnet 5.5 üzerinde) ve Codex CLI'dan (v0.163.0, GPT-6 Sol üzerinde) birer özellik eklemeleri istendi; bu, 320 gözetimsiz çalışma ve 720 konvansiyon seçimi üretti.

Dosya kodu yeniyor

Öncelik kuralı olmadığında, 720 seçimin yüzde 90,1'i eski talimat dosyasını izledi ve yalnızca yüzde 4,2'si mevcut kodu izledi. Dosyaya bağlılık Claude Code için yüzde 86,4, Codex CLI için yüzde 93,9 oldu.

İki ayrıntı öne çıkıyor. Claude Code, 80 çalışmanın 79'unda CLAUDE.md ile kod arasındaki çelişkiyi açıkça raporladı, yine de seçimlerinin yüzde 86,2'sinde dosyaya uydu — bir örnekte her modülün logging ve pathlib kullandığını gözlemledi, sonra da yeni özelliği yine de print() ve os.path ile yazdı. Codex CLI daha da ileri gitti: 80 çalışmanın 20'sinde AGENTS.md'ye uydurmak için mevcut çalışan modülleri yeniden yazdı; 9 dosya boyunca ortanca 198 satır kaldırdı ve bu 20 yeniden yazmanın 17'si projenin özgün test paketini bozdu.

Talimatlar canlı koddan üstün sayılıyor neden

Araştırma bu davranışın kökenini ajanların bağlamı sunma biçimine bağlıyor. Talimat dosyaları genellikle komutlar biçiminde yazıldığından, "ilerleme için print() kullan" gibi bir satır, yalnızca yazıldığı andaki kodu tarif etse bile bir zorunluluk olarak okunuyor. Harness'ler bu dosyaları ayrıcalıklı bir katmanda sunuyor: Claude Code, CLAUDE.md'yi system prompt'un hemen ardından bağlayıcı olarak işaretleyen bir çerçeveyle enjekte ederken, Codex CLI AGENTS.md'yi bir INSTRUCTIONS etiketiyle sarıyor. Kaynak kodun kendisi ise daha sonra, bir dosya okuma aracı üzerinden geliyor — ve frontier modeller prompt injection'a karşı bir savunma olarak talimatları araç çıktısının üstüne koyacak şekilde eğitildiğinden, güncelliğini yitirmiş bir kural canlı depodan üstün sayılıyor.

Tek cümlelik çözüm

Çelişki talimat katmanında yaşandığından yazarlar düzeltmeyi orada yaptı ve kullanıcı düzeyindeki talimat dosyasına bir cümle ekledi (Claude Code için ~/.claude/CLAUDE.md, Codex CLI için ~/.codex/AGENTS.md):

"Bir deponun dokümantasyonu ile mevcut kodu çeliştiğinde, mevcut kodda kullanılan konvansiyonları izle ve nihai yanıtında dokümantasyon ile kod arasında bulduğun her tutarsızlığı belirt."

Aynı 40 projede bu cümle yerindeyken, araştırma mevcut kodu izleyen seçimlerin yüzde 4,2'den yüzde 91,4'e çıktığını bildiriyor — Claude Code için yüzde 7,5'ten yüzde 94,4'e, Codex CLI için yüzde 0,8'den yüzde 88,3'e. Codex CLI'nın çalışan modülleri yeniden yazması 20 çalışmadan sıfıra düştü, genel test geçirme oranı yüzde 89,4'ten yüzde 100'e çıktı (yalnızca Codex CLI yüzde 78,8'den yüzde 100'e yükseldi) ve her iki ajan da her nihai yanıtta güncelliğini yitirmiş kuralları listelererek bakımcılara somut bir yapılacaklar listesi sundu.

Dosyaları dürüst tutmak

dev.to makalesi bakım önerileri de ekliyor: paylaşılan konvansiyonları tek bir kök AGENTS.md dosyasında tutup CLAUDE.md'den @path sözdizimiyle içe aktarın ya da Claude Code'u her iki dosyayı da yükleyecek şekilde yapılandırın; böylece ikisi hiçbir zaman ayrışmaz. Dizinlere özgü kuralları, yalnızca eşleşen dosyalara dokunulduğunda yüklenen .claude/rules/ altındaki yol kapsamlı dosyalarına taşıyın; ve bir geçişten sonra, talimat dosyalarını silinmiş atıflar, eksik komutlar ve çelişen kurallar açısından taramak için /doctor prompt-audit komutunu çalıştırın (Claude Code v2.1.283 veya üzeri).

Neden önemli

Bu, tanıdık bir başarısızlık modunu — "ajan modülümü yeniden yazdı" ya da "konvansiyonlarımızı görmezden geldi" — bir model hatası değil, talimat hiyerarşisinin öngörülebilir bir sonucu olarak yeniden çerçeveliyor. CLAUDE.md veya AGENTS.md içine konan her şey, tarif ettiği refactor'dan daha uzun ömürlü olabilen yük taşıyan bir metne dönüşüyor ve deneyler, ajanların bunu çalışan, test edilmiş yazılıma karşı dayatacağını gösteriyor. Çözüm tek bir cümleye mal oluyor, depoyla değil kullanıcıyla birlikte seyahat ediyor ve gelecekteki her çalışmayı dokümantasyon çürümesini ortaya çıkaran bir denetime dönüştürüyor. Kodlama ajanları benimseyen ekipler, talimat dosyalarını sürümlü yapılar olarak, tarif ettikleri kodla birlikte gözden geçirilip güncellenen yapılar olarak ele almalı.