Salvor: kodlama ajanlarına repoda yaşayan bir hafıza

Sorun

Kod ve git geçmişi neyin değiştiğini gösteriyor, nedenini ise nadiren. Hangi düzeltme denenip bırakıldı, hangi kural yalnızca birinin aklında duruyor, ne bilerek sonraya bırakıldı? Yeni bir oturumun bunların hiçbirinden haberi yok. Sonuçta ya baştan keşfediyor, ya tartışmaya açıyor ya da farkında olmadan bozuyor.

Salvor nedir

Salvor, kodlama ajanları için repo içinde çalışan bir bilgi katmanı. MIT lisansıyla yayınlanıyor. Her şey .salvor/ klasöründe düz Markdown olarak duruyor. Böylece pull request'lerde gözden geçiriliyor ve kodla birlikte sürümleniyor. Barındırılan bir servis ya da açılması gereken bir hesap yok.

En çok kullandığım bölümler:

• L1: projenin şu anki durumuna dair kısa bir not. Her oturum önce bunu okuyor.
• L2: gerekçeleri, geçmişi ve reddedilen fikirleri içeren uzun kayıt.
• Öğrenilmiş hatalar: başarısız olan yöntemler. Tekrar denenmesinler diye yazılıyor.
• Kararlar ve ertelenen bulgular: neyin neden seçildiği, neyin çöpe atılmayıp kenara konduğu.

Yeni bilgi sizin onayınızla kaydediliyor: ajan bir kararı ya da öğrenilmiş hatayı yazmadan önce soruyor. Kurulum Claude Code, Codex ve GEMINI.md ile uyumlu istemciler için giriş dosyaları oluşturuyor. Ajan değiştirdiğinizde aynı hafıza çalışmaya devam ediyor.

Nasıl kullanıyorum

Oturum başında ajan L1'i okuyor, sonra işin gerektirdiği diğer dosyalara bakıyor. Her aşamanın sonunda L1 ile L2'yi güncelletip commit ettiriyorum. Bir şey öğretici bir şekilde başarısız olduğunda, nedeniyle birlikte öğrenilmiş hata olarak kaydediliyor.

En büyük fark, koda hiç girmeyen küçük proje kurallarında ortaya çıkıyor. "Her sayfanın iki dil sürümü de olmalı." "Her değişiklikten sonra sürüm numarasını artır." "Bu sayfa şu sayfaya bağlantı vermeli." Hafıza yokken ajan bunları bazen doğru yapıyor. Yazılı olduklarında çok daha sık doğru yapıyor.

Testlerim ne gösterdi

Aynı görevleri üç düzende çalıştırdım: hafızasız, kısa bir hafıza dosyasıyla ve tam Salvor ile. Salvor'un kendi test paketini de yerelde çalıştırdım. Sayıların tamamı Salvor test sayfasında. Kısaca:

• Tam Salvor iki Codex denemesinde de birinci oldu ya da birinciliği paylaştı.
• Bedeli daha yüksekti: hafızasız çalışmaya göre yaklaşık 1,5–2 kat token ve 2–4 kat süre.
• En büyük kazanç, yukarıdakiler gibi yalnızca hafızada duran kurallardan geldi.
• Test paketinde 186 birim testinin 186'sı geçti.

Ayrıca kör soru testleri yaptım, hafızaya sahte bilgiler yerleştirdim ve Salvor'dan hiç haberi olmayan bir ajanı denedim. Onları diğer Salvor testleri yazısında anlattım.

Yakından bakış: canlı site denemesi

Denemelerden biri, oyunlar, Türkçe ve İngilizce sayfalar ve onay adımının arkasında reklamlar barındıran canlı ve iki dilli bir statik sitede yapıldı. Codex gerçek reponun yerel kopyalarında çalıştı, hiçbir şey yayına alınmadı. Beş gerçek görev aldı: iki dilde yeni bir oyun eklemek, bildirilen bir yerleşim hatasını düzeltmek, mevcut bir oyuna özellik eklemek, yayına alma adımlarını yazmak ve bir sayfaya reklam alanı eklemek. Hiçbir çıktıyı okumadan önce 25 kontrol yazdım.

Bağımsız denetimden sonra puanlar şöyle çıktı: hafızasız 25 üzerinden 17, kısa hafızayla 19, tam Salvor ile 24,5. Fark, ancak projede daha önce çalışmış birinin bileceği şeylerden geldi:

• Sahipsiz sayfalar. Hafıza olmadan yeni oyun sayfasına sitenin geri kalanından hiç bağlantı verilmedi. Ne ziyaretçiler ne de arama motorları onu bulabilirdi. Salvor ile 16 bağlantı aldı.
• Dil sızıntıları. Tam hafızası olmayan iki düzen de İngilizce sayfada Türkçe betikler yükledi. Birinde onay bildirimi İngilizce sayfada Türkçe göründü. Salvor İngilizce sürümleri kullandı.
• Sürüm numaraları. Sitede her değişiklikten sonra sürüm numarasının artırılması gerekiyor. Hafızasız düzen hiç artırmadı. Kısa hafıza tahmin etti. Salvor projenin kendi kuralını uyguladı.
• Kontrol konusunda dürüstlük. Hiçbir düzen tarayıcı açamadığı için yerleşim hatasını göremedi. Üçü de "düzeltildi" dedi, ama yalnızca Salvor doğrulayamadığını söyledi. Sonradan anlaşıldı ki hata haftalar önce zaten düzeltilmişti. Yani üçü de hiçbirinin görmediği bir hatayı "düzeltti".

İki şey bu sonucu dengeliyor. Tam Salvor 17,8 dakika ve 342 bin token harcadı, hafızasız düzen ise 8 dakika ve 209 bin token. Ayrıca sıralama, sürüm numarası kontrollerinin nasıl puanlandığına bağlı: değerlendirme ölçütleri harfiyen okunduğunda puanlar 19, 22,5 ve 20,5 oluyor.

Yetersiz kaldığı yerler

• Hatayı okumak, hatadan kaçınmak demek değil. Bir görev, hata kayıtlı olmasına rağmen her düzende başarısız oldu.
• Ajanlar kaydı değiştiriyor. 5 koşunun 3'ünde ajan, onaylanmış bir öğrenilmiş hata kaydını kendi değişikliğine uyacak şekilde düzenledi ve bunu belirtmedi.
• Durum notu eskiyor. Canlıda 177. sürüm varken L1 "sürüm 176" diyorsa, sonraki oturum yanlış bilgiyle başlıyor. Artık her oturumun başında L1'deki iddiaları gerçek durumla karşılaştıran ve eskimiş olanları işaretleyen küçük bir kontrol çalıştırıyorum.

Kimler için

Aynı proje üzerinde ajanlarla çok sayıda oturum boyunca çalışıyorsanız denemeye değer. Ajanlarınızın sürekli bozduğu üç kuralı yazarak başlayın. Tek seferlik betikler için gereğinden fazla yapı getirir.