Docket, yapay zekâ kodlama ajanları tarafından yazılan kod için commit başına kanıt kaydı tutuyor

Hacker News'te öne çıkan açık kaynak bir araç olan Docket, bir yapay zekâ kodlama ajanı yardımıyla üretilen her commit için imzalı bir kanıt kaydı oluşturuyor. İnceleyen kişiye çıplak bir diff vermek yerine, ajandan ne yapmasının istendiğini, yol boyunca neler denediğini, sonucu hangi kontrollerin doğruladığını ve hiçbir insanın açmadığı satırları yeniden inşa ediyor.

Hedeflediği doğrulama boşluğu

GitHub'daki projenin README'si sorunu açıkça ortaya koyuyor: ajanlar, kodu herkesin kontrol edebileceğinden daha hızlı üretiyor ve bitmiş bir diff, arkasındaki çalışmanın hiçbir izini taşımıyor — başarısız olan ilk yaklaşımı, bunu yakalayan testi, kimsenin incelemediği bölgeleri. Harness'ler bu hikâyenin büyük kısmını zaten bir oturum transkripti olarak üretiyor ama commit anında çöpe atıyor. Docket bu transkripti yakalıyor, commit edilen diff ile hizalıyor ve inceleyicinin dikkatini arkasında hiçbir şey olmayan değişikliklere yönlendirmeyi amaçlayan, hunk başına bir kanıt kaydı üretiyor.

Bir kayıt neler içerir

docket show HEAD komutunu çalıştırmak, son commit için risk sırasına göre dizilmiş kaydı yazdırıyor. Her hunk için kaynağı — düzenlemeyi hangi harness ve aracın yaptığı, model ve işlem adıyla birlikte — kaydediyor; düzenlemenin köken aldığı görevi; niyeti, yani ajanın düzenlemeyi yapmadan hemen önce söylediği; ve varsa denemeyi, yani aynı bölgeye yazılıp sonradan silinen kodu ve aradaki başarısız kontrolle birlikte. Satır kapsamı ve test çalıştırmaları gibi makine tarafından doğrulanabilir kanıtlar da ekleniyor, ayrıca o satırlara bir insanın dokunup dokunmadığına dair bir not yer alıyor. Örnek çıktı, kayıtlı bir düzeltmeye atfedilen eklenen satırların payı ve hunk başına bir "kanıt yoğunluğu" puanı gibi metrikleri gösteriyor.

docket explain file:line adlı yardımcı komut, sahip olan commit'i git blame üzerinden çözüyor; böylece okuyucu bir commit hash'inden değil, şüpheli bir kod satırından yola çıkabiliyor. Docket, tam transkriptler gizli bilgi içerdiği ve sınırsız büyüdüğü gerekçesiyle yalnızca kısa, sansürlenmiş alıntılar saklıyor.

Depolama ve bütünlük

Hesap ya da ağ bağımlılığı yok: kayıtlar repository içinde bir orphan ref üzerinde yaşıyor ve denetlenen her commit, Reviewed-by gibi kuralların yanına, kaydın özetini (digest) adlandıran tek bir trailer satırı kazanıyor. README'ye göre tek satırlık log çıktısı değişmiyor ve özet bir URL yerine yerel olarak saklanan imzalı bir kaydı adlandırdığı için geçmiş, barındırılan bir hizmetin ayakta kalmasına asla bağımlı olmuyor.

Kayıtlar yerel bir ed25519 anahtarıyla imzalanıyor ve local_claimed güven etiketini taşıyor; docket verify özeti, imzayı ve belirli bir commite bağlanmayı kontrol ediyor. Her kayıt, yazıldığı şema sürümünü gömülü olarak içeriyor; böylece eski kayıtlar yükseltmeler boyunca okunabilir kalıyor ve docket push kayıtları branch ile birlikte remote'a gönderiyor.

Hook'lar, uç durumlar ve çıkış

Kurulum docket init ile yapılıyor; bu komut trailer'ı yazan bir prepare-commit-msg hook'u — denetlenen ajan kendi denetimini asla kaydetmiyor — onu saklayan bir post-commit hook'u ve Docket'in shell üzerinden yapılan düzenlemeleri gözlemleyebilmesi için Claude Code hook'ları kuruyor. Bir commit'i amend etmek kaydı yeniden inşa ediyor ve trailer'ı değiştiriyor. Merge commit'leri ve içinde atanabilir bir şey bulunmayan commit'ler hiç trailer almıyor.

Rebase ve cherry-pick, kabul edilen zayıf nokta: git bunlar için prepare-commit-msg çalıştırmıyor; dolayısıyla bir trailer, kendisinden üretilmediği bir diff üzerine taşınabiliyor. Docket'ın yanıtı, docket verify'ün trailer'a güvenmek yerine bu uyumsuzluğu raporlaması. Çıkmak, .git/hooks içindeki iki hook dosyasını silmek demek; mevcut trailer'lar geçmişte etkisiz metin olarak kalıyor.

Pull request'ler ve dağıtım

Bir GitHub Action, bir pull request'in commit'lerinin beraberinde taşıdığı kayıtları okuyor ve diff'i yeniden sıralayan tek bir yorum paylaşıyor: doğrulanmamış hunk'lar önce yüzeye çıkarken, sağlam kapsamalı boilerplate altta katlanıyor. Action, geliştiricinin kullandığı aynı statik binary'yi indiriyor; yani runner'larda önceden bir şey kurulu olması gerekmiyor ve sürüm bir tag'e sabitlenebiliyor. Docket'in kendisi, arm64 ve x86-64 için macOS, Linux ve Windows'ta tek bir statik binary olarak dağıtılıyor ve SHA256 checksum'larını doğrulayan bir betikle kuruluyor; kaynaktan derlemek standart bir go install. Demo modu, geçici bir dizinde tek kullanımlık bir repository oluşturuyor — bir ajan bir session-fixation düzeltmesini bir kez batırıyor, bir testin başarısız olduğunu görüyor, sonra düzeltiyor — ve çıkışta temizliyor.

Neden önemli

Kodlama ajanları günlük commit'lerin büyüyen bir payını devraldıkça, darboğaz kod yazmaktan ona güvenmeye kayıyor. Docket'ın bahisleri, incelemenin kanıta karşı bir triyaja dönüşmesi: kapsamı ve geçen testleri olan satırlar kuyruğun dibine inerken doğrulanmamış satırlar üste çıkıyor ve bir değişikliğin ardındaki gerekçe — ajanın terk ettiği yaklaşımlar dahil — oturumla birlikte buharlaşmak yerine hayatta kalıyor. Kanıtı repository içinde, bir orphan ref üzerinde tutmak, sistemi satıcıdan bağımsız kılıyor.

Uyarılar da ciddiye alınmayı hak ediyor: kayıt yerel bir anahtarla imzalanıyor ve olayların anlatımı harness'in kendisinden geliyor; yani bu doğruluğun kanıtı değil, sürecin kanıtısı ve trailer'lar rebase ile cherry-pick altında anlamını yitiriyor. Yine de, ajan yazımı belirli bir kod parçasını kimin kontrol ettiği sorusuna hafif bir yanıt olarak Docket, inceleme araçlarının muhtemelen izlemek zorunda kalacağı bir yön çiziyor.