Kod ajanı gerçekten ilerliyor mu? Agenttrail, planla dosya değişikliğini aynı haritada gösteriyor
GitHub'daki Agenttrail projesi; Claude Code, Codex ve Cursor gibi kodlama ajanlarının planını, araç çağrılarını ve dokunduğu dosyaları yerel bir canlı haritada izlemeyi amaçlıyor.
0 okunma4 dk okumaGitHub
Bir kodlama ajanı yarım saattir çalışıyor: Gerçekten yeni bir bölümü mü bitiriyor, yoksa tamamlandı dediği dosyayı yeniden mi değiştiriyor? GitHub'da yayımlanan Agenttrail, bu soruya sohbet dökümünü okuyarak değil, ajanın planı ile dosya sistemindeki gerçek hareketleri aynı haritada göstererek yanıt vermeyi amaçlıyor.
Agenttrail; Claude Code, OpenAI Codex, Cursor ve dosya düzenleyen diğer ajanlar için yerel çalışan bir gözlemlenebilirlik katmanı. Projedeki bileşenleri, bağımlılıkları, görev durumlarını, son değişen dosyaları ve canlı ajan hareketini yakınlaştırılabilir bir pano üzerinde birleştiriyor. Bir kod yazma ajanı değil; ajanı yönetmiyor veya onun yerine kod üretmiyor.
Hangi sorunu çözüyor?
Terminal günlüğü genellikle “ne oldu?” sorusuna satır satır yanıt verir, fakat projenin hangi parçasında ilerleme kaydedildiğini anlamak zor olabilir. Agenttrail iki sinyali yan yana koyuyor: PLAN.md içindeki beyan edilen iş ve dosya izleyicisinin gözlediği değişiklik. Tamamlanmış görünen bir kartın dosyaları yeniden değişirse pano bunu görünür kılıyor.
Claude Code, yerel kancalar sayesinde araç çağrıları ve görev kartlarında en ayrıntılı görünümü sunuyor. Codex ve Cursor ise dosya izleyicisi üzerinden canlı hareketi gösterebiliyor ve AGENTS.md yardımıyla haritayı güncel tutabiliyor. Bu fark, her ajan için aynı ayrıntı düzeyinin beklenmemesi gerektiği anlamına geliyor.
Nasıl başlanır?
Proje Node.js 20 ve üzerini istiyor. İzlemek istediğiniz deponun kökünde şu komut çalıştırılıyor:
npx agenttrail
Araç yerel panoyu açıyor ve dosya ağacını izlemeye başlıyor. Proje açıklamasına göre hesap, küresel kurulum veya bulut hizmeti gerekmiyor; pano 127.0.0.1 üzerinde çalışıyor ve telemetri göndermiyor.
Tam bileşen haritası için isteğe bağlı başlangıç komutu var:
npx agenttrail init
Bu ikinci komut salt okunur değil. Başlangıç PLAN.md dosyası oluşturuyor; CLAUDE.md ve AGENTS.md dosyalarına çalışma kuralı ekliyor, .agenttrail klasörünü git dışı bırakıyor ve Claude Code için yerel kancalar kuruyor. Bu yüzden önce temiz bir Git durumu almak, değişiklik farkını incelemek ve gerekirse deneme deposu kullanmak gerekiyor.
Üç somut kullanım
- Büyük bir yenileme sırasında ajanın hangi bileşende çalıştığını ve “tamamlandı” işaretli dosyaya dönüp dönmediğini canlı izlemek.
- İki ajanın aynı depoda farklı görevler yürüttüğü durumda, dokundukları dosyaları ve bağımlılık çakışmalarını haritada görmek.
- Uzun bir hata giderme işinde, plan kartlarının ilerleyip ilerlemediğini kontrol ederek müdahale gerektiren duraklamayı erken fark etmek.
Özgün örnek komut şöyle olabilir:
“PLAN.md dosyasını mevcut kod ve Git geçmişiyle doğrula. Projeyi 5-9 anlaşılır bileşene ayır, her bileşen için ilgili dosya desenlerini yaz ve yalnız dosya kanıtı bulunan işleri tamamlandı olarak işaretle.”
Bu komut panonun haritasını yararlı hâle getirir; ancak ajanın bileşen sınırlarını yanlış yorumlaması mümkündür. İnsan geliştirici, kritik bağımlılıkları ve tamamlanma ölçütünü gözden geçirmeli.
Ücretsiz mi?
Agenttrail MIT lisanslı açık kaynak bir proje. Yerel izleme için hesap veya ücretli Agenttrail hizmeti yok. Bununla birlikte izlenen kod ajanının kendi aboneliği veya API kullanımı ayrı maliyet oluşturabilir. npx ilk çalıştırmada paketi internetten indirir; kurumsal ortamlarda paket sürümü sabitlenmeli ve kaynak kodu incelenmeli.
Gizlilik ve güvenlik
Pano yalnız 127.0.0.1'e bağlanacak biçimde tasarlanmış ve proje açıklamasına göre çalışırken kodu değiştirmiyor. Ancak dosya adları, planlar ve ajan hareketleri yine yerel makinede işleniyor. Ekran paylaşırken müşteri adları, gizli depo yolları veya PLAN.md içindeki hassas bilgiler görünür olabilir.
“Telemetri yok” beyanı proje geliştiricisine ait ve incelenen sürüm için geçerli. Yeni sürüm kurmadan önce değişiklik günlüğü ile paket içeriği kontrol edilmeli. init komutunun talimat dosyalarını değiştirmesi de tedarik zinciri açısından önem taşıyor; diff görülmeden değişiklikler kayda alınmamalı.
Benzerlerinden farkı ve bugün ne yapılabilir?
Klasik LLM gözlem araçları çoğunlukla token, gecikme ve maliyeti ölçer. Agenttrail'in odağı, bir yazılım deposunun hangi bölümüne gerçekten dokunulduğu ve planla davranışın uyuşup uyuşmadığı. Tam bir denetim sistemi, erişim kontrolü veya güvenlik tarayıcısı değil.
Güvenli bir deneme akışı
İlk turda haritaya girecek depo seçilir ve gizli müşteri adları bulunmadığı doğrulanır. Git çalışma durumu kaydedilir; yalnız npx agenttrail çalıştırılarak dosya ağacı ve canlı değişiklikler gözlenir. Pano kapatılıp sürecin gerçekten durduğu kontrol edilir. Bundan sonra init komutu ayrı bir dalda çalıştırılır ve AGENTS.md, CLAUDE.md, PLAN.md ile git dışı bırakma dosyasındaki farklar tek tek okunur.
Birden fazla ajan kullanılıyorsa her birine ayrı görev ve çakışmayan dosya alanı vermek gerekir. Agenttrail çakışmayı görünür kılabilir, fakat iki ajanın aynı dosyaya yazmasını engellemez. Bir görev kartının “tamamlandı” görünmesi de testlerin geçtiğini kanıtlamaz; test sonucu ve kod incelemesi ayrı doğrulama olarak kalır.
Proje, büyük depolarda dosya ağacını sınırlandırabileceğini ve görünümün kısaltıldığını bildirdiğini söylüyor. Bu nedenle haritada görünmeyen dosyanın izlenmediği varsayılmamalı; kapsam uyarısı okunmalı ve kritik bileşenler ayrıca kontrol edilmelidir.
Okuyucu bugün kişisel veri içermeyen küçük bir deneme deposunda yalnız npx agenttrail komutuyla salt okunur panoyu açabilir; init seçeneğini ise dosya farkını görmeye hazır olduğunda deneyebilir. Yapay zekâ ajanlarını yalnız hızlarıyla değil, bıraktıkları kanıtla değerlendiren yeni araçlar için Mülk Rehberi Gazetesi'nin rehberlerini takip edin.