AI Agent için Kod Arama: Hangi Aracı Ne Zaman Kullanmalı?

ripgrep hızlı, ast-grep yapısal, semantic search kavramsal. Üçü de iyi araç. Ama AI agent için yanlış soru “hangisi daha iyi”. Doğru soru: bu agent, bu task için, bu context window’da, hangi backend hangi sırayla?

Agent context window’unu beklediğinden hızlı dolduruyorsa sorun model değil. Sorun, sana doğru kod parçasını bulması için harcadığı token’lar. ripgrep ile yapılması gereken bir aramayı semantic search ile yapmak, tipik bir senaryoda onlarca dosyalık net cevabı yüzlerce sonuçlu gürültüye çevirebiliyor (örnek değerler, ölçüm değil). Üstüne agent o gürültüyü okuyup özetlemek için bir tur daha reasoning harcıyor. İki kat kayıp.

Bu yazı grep, ripgrep ve yapay zeka destekli metin arama yazısının doğal devamı. Orada üç katmanı (lexical, structural, semantic) ayrı ayrı tanıttım. Aynı şekilde pre-injection vs MCP tool loop yazısı context’i agent’a nasıl teslim edeceğini ele alıyordu. Bu yazı içeride hangi backend’i hangi sırayla kullanacağını anlatıyor. Delivery ve retrieval, aynı problemin iki yüzü.

Yanlış Soru: “Hangisi Daha İyi”

Bir developer “10 sonuca bakarım, en uygunu seçerim” diyebilir. Agent öyle çalışmıyor. Agent için her sonuç bir token maliyeti, her ek tool call bir tur daha reasoning, her compaction olayı bir context kaybı. Karar matrisi insanınkinden farklı işliyor (varsayım: token-maliyetli akıl yürütme insan göz taramasına benzemez).

Üç Katmanın Hızlı Hatırlatması

• Lexical (rg, ugrep, grep): tam eşleme, hızlı, context-blind. SIMD (Single Instruction, Multiple Data) ile paralel tarama, gitignore farkındalığı, milisaniye düzeyinde sonuç.
• Structural (ast-grep): AST (Abstract Syntax Tree) tabanlı pattern matching. Syntax-aware. Dile özel kurallar yazılabilir. Regex’in çözemediği şekilsel sorguları çözer.
• Semantic (mgrep, embeddings, repo-map): kavramsal eşleme. Doğal dil sorguları, embedding benzerliği, PageRank ile dosya merkezilik ölçümü. Pahalı, kurulum maliyeti yüksek.

Agent Değişkeni Hepsini Bozar

Mayıs 2026’da yayınlanan CoREB benchmark’ı çarpıcı bir bulgu paylaştı: short keyword queries, gerçek developer aramasına en yakın format, test edilen semantic modellerin tamamına yakınını near-zero nDCG@10’a düşürüyor.¹ Yani “auth flow”, “user service”, “handle error” gibi kısa sorgular semantic search’ün en zayıf noktası. Oysa agent prompt’larından çıkan sorguların çoğu bu formatta.

nDCG@10 ne anlama geliyor? normalized Discounted Cumulative Gain at 10. Bilgi getirisi (information retrieval) metriği. İlk 10 sonuca bakar, her sonuca relevans skoru verir, üst sıralardaki ilgili sonuçları daha fazla ödüllendirir, sonucu 0 ile 1 arasına ölçekler. 1.0 = mükemmel sıralama, 0.0 = ilk 10’da ilgili sonuç yok veya çok dipte. Near-zero değer pratikte şu demek: model agent’ın context’ine 10 ilgisiz sonuç dolduruyor, doğru kod parçasını ya hiç getiremiyor ya da kullanılamayacak kadar aşağıda sıralıyor.

Bu bulgu tek başına değil. LLM’lerin davranışsal bozulma modları yazısında belirttiğim context rot ve instruction attenuation tam burada devreye giriyor. Agent çok sonuçla beslenirse hangisinin önemli olduğunu kaybediyor, hangi talimatı izlediğini unutuyor. Yani semantic search’ün “%90 recall” iddiası, agent ekosisteminde “%90 zehre” dönüşebiliyor (analitik çıkarım, doğrudan ölçüm değil).

Yeni Kriterler

Karşılaştırmayı agent perspektifinden yeniden yapmak gerekiyor:

Backend	Latency	Recall	Precision	Token/sonuç	Kurulum	Determinism	Güncelleme
ripgrep	1-5ms	Düşük*	Yüksek	Çok düşük	Yok	Tam	Anlık
ast-grep	10-50ms	Orta	Yüksek	Düşük	Düşük	Tam	Anlık
repo-map	50-200ms	Orta-Yüksek	Orta	Orta	Orta	Tam	İndeks
Embeddings	100ms-1s	Yüksek*	Düşük**	Yüksek	Yüksek	Yok	Yeniden hesap

*recall doğru sorgu yazıldığında. **kısa keyword sorgularında CoREB bulgusu.

Tablodaki latency ve token değerleri tipik repo boyutlarındaki gözlemlere dayanır; donanım, repo büyüklüğü ve indeks durumuna göre değişir.

Karar Ağacı

Karar ağacının kalbinde tek soru var: sorgu tipi ne? Sorgu tipini doğru sınıflandırırsan backend seçimi otomatik geliyor.

Sorgu Tipini Sınıflandır

Sorgu tipi              -> Default backend
Exact symbol/string     -> rg
Pattern + scope         -> rg + path filter
Syntactic shape         -> ast-grep
Semantic intent         -> repo-map first, embeddings last resort
Cross-file refactor     -> ast-grep + repo-map
"Where is X used?"      -> rg -> ast-grep escalation

Bu tablo sade görünüyor ama agent prompt’undan gelen ham sorguyu sınıflandırmak ayrı bir iş. Pratik bir kural: agent sorgusunda tırnak içinde tam string varsa lexical, yapısal kelimeler (function, class, async, return) varsa structural, soru cümlesi formatındaysa semantic.

Backend Escalation Policy

Sınıflandırma yetmez. Recall düşükse veya bütçe izin verirse bir üst katmana çıkmalı. Escalation şu mantıkla işler:

[query] -> classify
   |-- exact?      -> rg -> done (vakaların büyük çoğunluğu)
   |-- structural? -> ast-grep -> rg fallback
   `-- semantic?   -> repo-map (PageRank) -> rg expansion -> embeddings (last)

[every step] -> budget check (tokens used vs cap)
[every step] -> recall check (results count, file diversity)

Üç kontrol noktası var.

1. Sonuç sayısı sıfırsa hemen bir üst katmana çık, ısrar etme.
2. Sonuçlar tek dosyada toplanıyorsa diversity düşük, expand et.
3. Token bütçesi yüzde 50’sini aştıysa stop ve mevcut sonuçlarla devam et.

Architecture decision substrate olarak AI coding agent’lar için yaşayan mimari dokümantasyon yazısında ele aldığım yapılandırılmış doküman yaklaşımı bu noktada hayat kurtarır. repo-map’in işe yaraması için kodun symbol’leri net olmalı, ADR’ler ve modül sınırları belli olmalı.

İki Gerçek Örnek

Örnek 1: Agent “find all auth middleware” diyor.

• Naif yaklaşım: doğrudan semantic search. 200 sonuç döner. auth, middleware, session, login geçen her dosya gelir. Agent 8k token’lık bir wall of text okumak zorunda kalır. Sonra hangisinin gerçek middleware olduğuna karar vermek için ikinci bir tool call yapar. Yine token. Yine tur.
• Doğru yaklaşım:

rg "middleware" --type ts -l   # 12 dosya, ~120 token
ast-grep --pattern 'export function $NAME($_, $_, next) { $$$ }' --lang ts  # 3 gerçek middleware

Bu örnekte iki adımda yaklaşık 400 token; naif yaklaşıma kıyasla bir-iki büyüklük mertebesi tasarruf (örnek hesap, repo’ya göre değişir).

Örnek 2: “where is user session refreshed?”

• Naif yaklaşım: doğrudan semantic. session ve refresh geçen her dosya. Önemli olan da, ilgisiz olan da gelir.
• Doğru yaklaşım: önce repo-map ile session symbol’ünün hangi dosyalarda merkezi olduğunu bul (PageRank ile ranked liste, top 3). Sonra o üç dosyada rg "refresh". Sonuç: 2 hit, doğru fonksiyon.

İki örnekteki ortak fikir: pahalı katmanı scope’u daraltmak için kullan, scope daralınca ucuz katman devreye girer. Tersi değil.

Agent için Üç Görünmez Boyut

Mevcut search araçlarının dokümantasyonu üç boyuta değinmiyor. Agent için en önemli olanlar bunlar.

1. Token Budget Arithmetic

Context window bir bütçedir. Search bu bütçenin bir alt bütçesidir. ARCS adlı 2025 sonu çalışması bunu netleştiriyor: agentic retrieval budgeted synthesize-execute-repair döngüsünde çalışır, accuracy ve cost trade-off’u açıkça optimize edilmelidir.²

Başlangıç heuristic’i olarak search_budget ≈ context_window * 0.15 kullanıyorum (kanonik bir formül değil, kendi default’um); workload’a göre kalibre et. 200k token’lık bir context window’da search için ~30k token ayır. Bu üst sınırdır, sürekli izle. LLM’lerin davranışsal bozulma modları yazısında bahsettiğim context rot, bu bütçenin aşılmasıyla birebir bağlantılı: agent context’in ortasında okuduğu şeyleri unutmaya başlar. Bazı çalışmalarda 50k civarı window’larda yarı dolulukta degradasyon raporlanıyor; tam eşik model ve task’a göre değişir.

Bütçeyi takip etmenin pratik yolu basit: her tool result’ı önce karakter veya token sayısı ile ölç, eşik aştıysa summarize veya truncate et. Bu cluster’ın sıradaki yazısı olan Agent araması için token bütçesi aritmetiği bu hesabı sayısal örneklerle açacak.

2. Result Compression at Tool Boundary

SWEzze çalışması kod context’inin inference time’da %51 ila %71 sıkıştırılabileceğini gösterdi, ortalama 6 kat oran.³ Akademik tarafın iddiası büyük. Solo dev için bu kadar derin gitmeye gerek yok ama temel prensip uygulanmalı: agent’a dönen tool result’ını her zaman sıkıştır.

Pratik format şu:

• file:line + en fazla 2 satır context
• Aynı sonucu farklı satırlardan tekrar tekrar verme (dedup)
• gitignore uyumlu (boilerplate dosyaları otomatik dışla)
• Boş satırlar, fazla whitespace, decorative comment’leri temizle

Bu format Anthropic’in Claude Code’da kullandığı tool result clearing stratejisiyle doğal uyum içinde. Agent ihtiyacı olursa o satırı tekrar açar. Cluster’ın dördüncü yazısı Compaction uyumlu arama çıktısı: pratik bir playbook bu format’ı kod örnekleriyle ele alacak.

3. Speculative Pre-fetching

SpecAgent çalışması ilginç bir fikir öneriyor: agent’ın bir sonraki muhtemel sorgusunu önceden tahmin et, sonucu cache’e koy.⁴ Akademik versiyon LLM-based forecasting kullanıyor, pahalı.

Solo dev için LLM-free versiyon çok daha pratik. Aktif dosyanın import’larını ve top-level symbol’lerini AST traversal ile çıkar, referenced symbol’leri arka planda pre-grep et. Embedding yok, LLM call yok, sadece Tree-sitter + ripgrep. Tipik bir Tree-sitter + ripgrep kombinasyonunda overhead 50ms mertebesinde (kendi denememde; donanıma göre değişir). Agent ikinci sorguyu sorduğunda sonuç zaten hazır.

Bu yaklaşım lokal MCP mimarisiyle güzel birleşiyor. Lokal MCP zaten file system erişimi olan bir process. Background prefetch için ekstra yetki gerekmiyor. Cluster’ın üçüncü yazısı LLM-free SpecAgent: AST tabanlı forecasting bu mini pipeline’ı kuracak.

Mevcut Araçların Bu Çerçevedeki Yeri

Bu çerçeveye göre mevcut araçları yeniden değerlendirmek faydalı. Saf rakip listesi değil, agent perspektifinden uyum analizi:

Araç	Çerçeveye uyum	Eksiği
ripgrep raw	Lexical katmanın temeli, idealden hızlı	Tek başına agent için ham, policy yok
ast-grep	Structural katmanın standartı	Standalone agent policy yok, multi-backend orchestration yok
Aider repo-map	Embedding-free graph rank, deterministik	Aider dışında kullanmak zor
Claude Code Context Engine	Built-in, MCP üzerinden expose edilmiş	Black box, hangi policy çalışıyor görmüyorsun
Sourcegraph Amp, DeepContext	Code graph + semantic, enterprise grade	Solo dev için overkill, maliyet yüksek
Smithery, netresearch skill’leri	Wrapper, free, hızlı kurulum	Tek backend, policy katmanı yok
mgrep, embedding-tabanlı tool’lar	Semantic katmanın gerçek implementasyonu	Kısa sorgu problemi (CoREB), kurulum ağır

Net mesaj: araç eksikliği yok. Policy eksikliği var. Mevcut araçlar tek katmanlı düşünüyor. Üç katmanı bir escalation ve budget kontrolüyle birleştiren orkestrasyon katmanı, ekosistemdeki gerçek boşluk bu.

Pratik Başlangıç: Bu Hafta Ne Yap?

Yukarıdaki tüm teorinin 4 satırlık pratik karşılığı var. Bu hafta agent setup’ında uygulayabilirsin.

Dört Değişiklik

1. CLAUDE.md veya .cursorrules: “Always start search with ripgrep. Escalate to ast-grep only if the query is structural. Use semantic search only when symbol or exact string is unknown.” Bu tek paragraf agent davranışının büyük kısmını düzeltir (ölçüm yok, gözleme dayalı tahmin).
2. Tool result format: yüksek frekanslı sorguları her zaman | head -50 ile sınırla (baskın tasarruf lever’ı), önce rg -l ile dosya kümesini bul, sonra hedeflenmiş rg veya Read. --vimgrep flag’i tasarruf etmiyor; -C N match yoğunluğuna göre 2-6 kat şişirir, sadece gerekliyse ekle. ast-grep için --json + post-process. Agent’a dönen output her zaman sıkıştırılmış olsun.
3. Default budget: search için context window’un %15’inden fazlasını ayırma. Aşıldıysa stop ve mevcut sonuçlarla devam et.
4. gitignore aware everything: rg default olarak gitignore’a uyar, ast-grep için --no-ignore=false set et. node_modules, dist, build agent’a hiç görünmesin.

Bir Hafta Sonra Ölç

Üç metrik takip et:

• Search task başına ortalama token tüketimi
• Resolved task başına tool call sayısı
• Hangi backend kaç kez seçildi (rg / ast-grep / semantic dağılımı)

Eğer semantic ratio %20’nin üstündeyse muhtemelen yanlış sorgu sınıflandırması yapıyorsun (heuristic eşik, sert kural değil). ripgrep + ast-grep ile çözülebilecek sorguları semantic’e yönlendiriyor olabilirsin.

Sıradaki Adım

Bu çerçeveyi bir cluster halinde derinleştiriyorum. Sıradaki üç yazı:

• Agent araması için token bütçesi aritmetiği: sayısal örnekler, formüller, ölçüm notebook’u
• LLM-free SpecAgent: AST tabanlı forecasting: LLM-free prefetch pipeline
• Compaction uyumlu arama çıktısı: pratik bir playbook: result format snippet’leri ve dedup stratejileri

Hepsi yayınlandıkça pillar’a buradan link verilecek.

Footnotes

1. CoREB benchmark. Beyond Retrieval: A Multitask Benchmark and Model for Code Search. arXiv:2605.04615. Bulgu: “Short keyword queries, the format closest to real developer search, collapse every model to near-zero nDCG@10.” https://arxiv.org/abs/2605.04615 ↩
2. ARCS. Agentic Retrieval-Augmented Code Synthesis with Iterative Refinement. arXiv:2504.20434. “Budgeted synthesize-execute-repair loop targeting predictable accuracy-latency trade-offs under fixed iteration and retrieval budgets.” https://arxiv.org/html/2504.20434 ↩
3. SWEzze / Oracle-guided Code Distillation. Compressing Code Context for LLM-based Issue Resolution. arXiv:2603.28119. “Maintaining a stable compression rate of about 6 times across models and reducing the total token budget by 51.8 to 71.3 percent.” https://arxiv.org/abs/2603.28119 ↩
4. SpecAgent. A Speculative Retrieval and Forecasting Agent for Code Completion. arXiv:2510.17925. “Code language models face efficiency constraints from limited context windows and latency budgets, with RAG being used to dynamically fetch relevant snippets.” https://arxiv.org/pdf/2510.17925 ↩

Önemli Noktalar

• 01 Doğru soru hangi tool daha iyi değil. Agent için doğru soru: hangi backend hangi sırayla, hangi token bütçesinde?
• 02 ripgrep default, ast-grep escalation, repo-map kavramsal sorgu için, embeddings last resort. Pratikte vakaların büyük çoğunluğunu çözer (gözleme dayalı tahmin).
• 03 Kısa keyword sorguları (auth flow, user service) semantic modelleri çökertiyor. CoREB benchmark'ı bunu kanıtladı.
• 04 Search bir alt bütçe. Başlangıç heuristic'i: search_budget ≈ context_window * 0.15. Her adımda kontrol et.
• 05 Sonuç formatı önemli. file:line + ≤2 satır context + dedup, raw output'a kıyasla kayda değer token tasarrufu sağlar (kendi ölçümlerimde ~%30-50 bandında, repo ve sorgu tipine göre değişir).

Sık Sorulan Sorular (FAQ)

+ ripgrep yerine doğrudan semantic search kullanmak ne zaman mantıklı?

Sorgu doğal dil ise ve exact symbol bilmiyorsan. Ama önce repo-map dene, embeddings'e en son çık. Embeddings hem pahalı hem CoREB benchmark'ında kısa sorgularda near-zero nDCG@10 çıkıyor.

+ ast-grep'i ne zaman ripgrep yerine seçerim?

Sorgu yapısal şekille ilgiliyse. Örnek: tüm async fonksiyonları bul, tüm try-catch bloklarındaki rethrow'ları yakala. Regex ile yazılabilen ama AST ile çok daha doğru sonuç veren her şey.

+ Claude Code'un kendi context engine'i varken bunu öğrenmenin anlamı var mı?

Var. Built-in engine black box. Hangi backend, hangi bütçeyle, hangi sırayla bilmiyorsun. Kendi policy'ni anlamadan optimize edemezsin. Ayrıca custom skill veya MCP yazıyorsan bu karar senin.

+ Token bütçesini gerçekten saymalı mıyım?

Manuel saymak yerine search backend output'unu sınırla: ripgrep'te -C 2 -m 50, ast-grep'te --json + post-process. Bütçeyi her adımda hatırla, raw dump etme.

+ Embeddings hiç kullanılmayacak mı?

Kullanılır ama nadiren. Cross-repo arama, doğal dil prompt'tan kod bulma, dokümantasyon arama gibi durumlarda. Kod tabanı içi günlük search için vakaların büyük çoğunluğu ripgrep + ast-grep ile çözülür (gözleme dayalı tahmin).