Yapay zeka ajanları için kod haritası: grep’siz arama

Yapay zeka ajanları için kod haritası, bir deponun dosyalarını, sembollerini, import’larını, testlerini ve değişiklik geçmişini tutan yerel bir dizindir; ajan bunu sorgulayarak doğru kodu grep’leyip dosya dosya okumak yerine birkaç çağrıda bulur. Daha az dosya okumak bağlam penceresinde daha az şey demektir; bağlam küçüldükçe sonraki her tur ucuzlar.

Bu yazıda ajanların keşfe neden token harcadığını, iyi bir haritada ne olması gerektiğini ve AgentVera’nın proje haritasının bu dizini Claude Code, Codex ve diğer CLI ajanlarına MCP üzerinden nasıl verdiğini anlatıyorum.

Haritası olmayan ajan depoyu nasıl keşfeder?

Tanımadığı bir depoda bir kodlama ajanına “ödeme sayfasına kupon alanı ekle” dersen, elinde yalnızca terminal olsa senin yapacağını yapar:

1. grep -r "checkout" ve 200 sonuç
2. Umut veren dosyaları, çoğu zaman tamamen açmak
3. Import’ları takip edip daha fazla dosya okumak
4. Test dosyasını bulmak için yeniden aramak

Her adım bağlama metin çeker. Bir kez okunan 1.000 satırlık dosya oturumun geri kalanında konuşmada durur ve model konuşmayı her turda yeniden okur. İlk tahminler yanlışsa o dosyalar yine oradadır. Bir oturumun asıl değişiklik yapılmadan çok önce pahalılaşmasının ana nedenlerinden biri budur. Diğer büyük kaynak olan temel bağlam için Claude Code token tasarrufu yazısına bak.

İşe yarayan bir kod haritasında ne olmalı?

Dosya listesi yetmez. Ajan “nerede” ve “bunu değiştirirsem ne bozulur” sorularını kod okumadan yanıtlayabilmeli. İyi bir harita şunları tutar:

Son ikisi göründüğünden önemlidir. Git geçmişi checkout.ts, checkout.test.ts ve pricing.ts’in, aralarında import olmasa bile genelde aynı commit’te değiştiğini bilir.

AgentVera’nın proje haritası nasıl kurulur?

AgentVera her proje klasörü için bir proje haritası kurar:

• Semboller. tree-sitter, TypeScript, TSX, JavaScript, Python ve Go için fonksiyonları, sınıfları, metotları, arayüzleri, tipleri, enum’ları ve sabitleri satır aralıkları, imzaları ve doküman yorumunun ilk cümlesiyle okur. Yaklaşık 30 dil daha yol düzeyinde dizinlenir.
• Import’lar ve testler. Import’lar dosyalara çözülür, testler kapsadıkları koda bağlanır.
• Birlikte değişme. Son 500 commit’in en az 2’sinde birlikte değişen dosyalar birbirine bağlanır. 40’tan fazla dosyaya dokunan commit’ler yok sayılır; böylece büyük bir yeniden adlandırma her şeyi her şeye bağlamaz.
• Neyi atlar. git ls-files ile başlar ve .gitignore’a uyar. node_modules, dist, build, 1 MB’tan büyük dosyaları ve üretilmiş ya da küçültülmüş dosyaları atlar. 20.000’den fazla dosyalı depolarda yalnızca src, lib, app ve packages/*/src gibi kaynak klasörlerini dizinler.

Harita senin bilgisayarında kurulur ve token harcamaz. Dosya değişikliklerini izler, commit geldiğinde birlikte değişme geçmişini yeniden sayar, bir ajan bir dosyayı sorduğunda onu yeniden kontrol eder. Her klasör için tek harita vardır ve orada çalışan bütün ajanlar onu paylaşır; yani projenin ve her worktree’nin kendi haritası olur. Uygulamanın veri klasöründe sıkıştırılmış olarak saklanır.

Ajanların kullandığı MCP araçları

AgentVera her ajana agentvera-map adlı bir MCP sunucusu ekler. Sunucunun talimatları ajana göreve map_related ile başlamasını, bir dosyayı okumadan önce map_outline, kodu değiştirmeden önce map_usages kullanmasını söyler.

map_related görevi düz cümleyle, herhangi bir dilde alır. sepet, kupon ya da ödeme gibi Türkçe kelimeler cart, coupon ve payment gibi İngilizce kod adlarıyla eşleşir. Yani görevi Türkçe yazman sorun değil.

map_api sessiz bir hata kaynağını kapatır: ajanın, sende kurulu olmayan bir kütüphane sürümüne göre ezberden çağrı yazması. Gerçekten kurulu olan sürümün .d.ts dosyalarını okur.

Yeni ajanlar talimatlarında modüllerin, giriş noktalarının ve test komutunun kısa bir özetini de alır; ilk turları testleri nasıl çalıştıracağını bulmaya harcamaz.

Önce ve sonra: aynı görev

Kupon görevi şöyle değişir. Adımlar tipiktir, ölçüm değildir.

Harita olmadan:

grep -rn "checkout" src        # 200 satır sonuç
cat src/checkout/index.ts      # dosyanın tamamı
cat src/checkout/summary.tsx   # dosyanın tamamı, yanlış dosya
cat src/pricing/total.ts       # dosyanın tamamı
grep -rn "total(" src test     # çağıranları ve testleri bul

Haritayla:

map_related "ödeme sayfasına kupon alanı ekle"
  -> src/pricing/total.ts (ad eşleşmesi, checkout ile birlikte değişiyor)
  -> src/checkout/CheckoutForm.tsx (total.ts'i import ediyor)
  -> test/pricing/total.test.ts (test)
map_outline src/pricing/total.ts   # yalnızca semboller ve satırlar
map_usages calculateTotal          # çağıranlar ve testler

Sonra ajan yalnızca ihtiyaç duyduğu satırları okur. İlk sürüm bağlamı gerekmeyen dosyalarla doldurur; ikincisi sıralı bir liste ve bir özetle.

Akıllı araçlar: ajan yine de okursa

Ajanlar her zaman önce haritaya sormaz. Claude Code için AgentVera’nın akıllı araçları hook’larla devreye girer:

• 800 satırı ve 24 KB’ı geçen bir dosyanın ilk tam okuması yerine proje haritasındaki özet döner; ajan ihtiyaç duyduğu kısmı okur.
• Değişmemiş bir dosyanın tekrar okunması engellenir, çünkü içeriği zaten bağlamdadır.
• Test çalıştırmaları ilgili testlere daraltılır.

Hook’ların genel olarak nasıl çalıştığını görmek istersen Claude Code hooks rehberi yazısını oku.

Haritayı açıp kapatmak

Proje haritası varsayılan olarak açıktır ve ücretsiz plana dahildir.

1. Ayarlar → Token tasarrufu’nu aç ve Proje haritası anahtarını bul. Sen kapatmadıkça açıktır.
2. Bir ajanı haritasız bırakmak için ajan düzenleme penceresinde Proje haritası kutusunu boşalt.
3. Haritayı görmek için projenin Detaylar sayfasında Proje haritası sekmesini aç. Import’ları gri, birlikte değişme bağlarını kesikli turuncu çizgilerle gösteren bir grafik çizer. Bir görev yazıp Göster’e basarsan map_related’ın ne döneceğini görürsün.

Harita henüz hazır değilse, örneğin büyük bir depoyu açtıktan hemen sonra, araçlar kurulumun ilerlemesini yanıt olarak verir. Ajan birkaç saniye bekler, sonra normal araçlarına döner.

Gerçekten token kazandırır mı?

Dürüst yanıt: depoya ve göreve bağlı. Ajanın zaten nereye bakacağını bildiği küçük bir depoda kazanç azdır. Ajanın yoksa bir düzine yanlış dosya okuyacağı büyük ya da tanımadığı bir depoda kazanç büyüktür.

Bir sayıya güvenmek yerine kendi işinde ölç. AI verimi sekmesindeki Proje haritası etkisi kartı, haritalı ve haritasız konuşmaları başarı, ilk seferde geçme, görev başına token ve takip mesajı sayısına göre karşılaştırır.

Bilmen gereken sınırlar

• Sembol ayrıntısı TypeScript, TSX, JavaScript, Python ve Go içindir. Diğer diller yol düzeyinde dizinlenir.
• Uzak SSH sunucusundaki ajanlar haritayı almaz.
• Ajan yalnızca kendi klasörünün haritasını okur; worktree’deki bir ajan ana çalışma kopyasını değil, kendi worktree’sini görür.
• AgentVera’nın proje turundaki kod haritası penceresi, kodu senin keşfetmen için ayrı bir özelliktir; ajanların sorguladığı proje haritasıdır.

Özet

Yapay zeka ajanları için kod haritası, körlemesine grep ve okuma keşfinin yerine birkaç hedefli soru koyar: hangi dosyalar, hangi semboller, onları kim kullanıyor, hangi testler kapsıyor. AgentVera’nın proje haritası bu dizini tree-sitter ve git ile yerelde kurar, güncel tutar ve agentvera-map ile MCP kullanabilen her ajana verir; akıllı araçlar da Claude Code’daki büyük ve tekrarlanan okumaları yakalar. Ajanlar kodun hem nerede hem neden öyle olduğunu bilsin diye bunu bir ortak proje hafızasıyla birlikte kullan ve en büyük deponda denemek için ücretsiz planla başla.