Kodlama ajanları için kod tabanı haritası oluşturma
Graft ile kod deponuzu tree-sitter kullanarak kalıcı bir haritaya dönüştürün. MCP protokolü üzerinden çalışan bu yöntemle ajanların her oturumda yapıyı yeniden taramasını engelleyin.
Kodlama ajanları için kod tabanı haritası nedir
Kodlama ajanları için kod tabanı haritası, deponuzun kalıcı bir dizinidir. Ajan, her yeni oturumda sıfırdan arama yapmak yerine bu dizin üzerinden sorgulama yapar. Graft, bu fikrin bir uygulamasıdır. Kodunuzu tree-sitter ile ayrıştırır, birbirine bağlı markdown düğümlerinden oluşan bir klasör ve sembol bazlı bir bağlantı grafiği oluşturur. Ardından, kodlama ajanlarının dış araçları çağırmak için kullandığı standart arayüz olan MCP (model context protocol) üzerinden erişim araçları sunar.
Graft bir proxy veya ağ geçidi değildir. Ajanınız ile model API'si arasında hiçbir şey bulunmaz. Harita, disk üzerinde ajanın okuduğu bir klasördür. Bu ayrım, hangi sorunu çözdüğünüzü belirler: kendi kendine barındırılan bir token ağ geçidi, halihazırda gönderdiğiniz istekleri ölçümler ve yönlendirirken, bir harita ise göndermeniz gereken toplam istek sayısını değiştirir.
Bu teknik, bu araçtan daha eskidir ve varlığını sürdürmeye devam edecektir. Önce tekniği, ardından mekaniğini öğrenin.
Kodlama ajanları neden yapıyı yeniden keşfederken bağlam tüketir
Bir ajanın, daha önce elli kez gördüğü bir depoda çalışmaya başlamasını izleyin. Dizinleri listeler. Bir sembol için grep komutunu çalıştırır. Fonksiyonun nerede tanımlandığını bulmak için üç dosya açar, ardından kimin çağırdığını bulmak için dördüncü bir dosya açar. Bunların hiçbiri asıl görev değildir. Bu bir oryantasyon sürecidir ve her oturumda girdi token'ları ile ödenir.
Bunun nedeni basittir. Bir modelin oturumlar arasında hafızası yoktur. Ajanın dizin yapınız hakkında öğrendiği her şey, oturum sona erdiğinde atılan bir bağlam penceresinde (context window) yaşar. Bu yüzden aynı keşif süreci sıfırdan tekrar çalışır ve siz bunun bedelini tekrar ödersiniz. Prompt önbellekleme (prompt caching) yalnızca son beş dakika içinde görülen veya ek ücretle son bir saat içinde görülen özdeş bir prompt önekini indirimli hale getirir; bu nedenle dünün keşfini bugünün oturumuna taşıyamaz. Büyük bir depoda oryantasyon aşaması, düzenleme işleminden daha maliyetlidir: kodu bulmak için on araç çağrısı, değiştirmek için ise bir çağrı yapılır. Oryantasyon bu faturanın sadece yarısıdır, düzenleme ise diğer yarısıdır; bu yüzden ajanı çalışan en küçük değişikliğe sadık tutan bir beceriyi, bir harita ile eşleştirmek, ikisi arasında seçim yapmaktan daha değerlidir.
Bir harita, keşif sürecini modelin üzerinden alıp diske taşıyarak bu döngüyü kırar. Bir ayrıştırıcı (parser) depoyu bir kez tarar, hangi sembolün nerede tanımlandığını ve hangisinin hangisini çağırdığını kaydeder, ardından kod değiştikçe bu kaydı güncel tutar. Ajan tek bir soru sorar ve dosya ile satır numarası eklenmiş bir yanıt alır. Tekrarlanan keşif süreci, ucuz bir arama işlemine dönüşür.
Bunun daha zayıf bir versiyonunu zaten kullanıyorsunuz. Kurallarınızı belirten bir AGENTS.md dosyası, ajanın kurallarınızı her seferinde yeniden türetmesini engeller. Oluşturulmuş bir harita ise yapınızı yeniden türetmesini engeller. Fark, bunu kimin yazdığıdır. Talimat dosyasını siz elle yazarsınız, bu yüzden küçük kalır. Haritayı bir ayrıştırıcı oluşturur, bu yüzden on bin dosyayı kapsayabilir. Bütçenin bir oturum içinde nereye harcandığına dair, Claude Code'un bağlam penceresini nasıl harcadığı konusu muhasebeyi açıklamaktadır.
Graft gerçekte ne inşa eder
Depo kök dizinindeki bir graft/ klasörü altında iki adet yapı taşı.
İlki, düğüm başına bir dosya olacak şekilde birbirine bağlı markdown formatında yazılmış bir düğüm grafiğidir. Her düğüm; sade bir İngilizce özet, kaynak koddan çıkarılmış önemli mantık satırlarının bir "özü" (crux), içerik özeti (hash) ile birlikte tam kaynak dosyalar, diğer düğümlere yönelik türü belirtilmiş wiki bağlantıları (depends_on, part_of, uses, implements) ve yeniden oluşturma sürecinde silinmeyen, bir ayrıştırıcının (parser) çıkarım yapamayacağı bağlamları kaydetmenizi sağlayan bir notlar bölümü içerir.
İkincisi ise tree-sitter tarafından çıkarılan, sembol bazlı yapısal grafik olan graft/.graph/wiring.json dosyasıdır: tanımlar, referanslar ve bunlar arasındaki çağrı kenarları (call edges).
Bu ayrım önemlidir çünkü sadece yarısı bir model gerektirir. graft build tamamen tree-sitter tabanlıdır ve hiçbir zaman bir LLM (büyük dil modeli) çağırmaz; bu nedenle deterministiktir ve maliyeti yoktur. graft build --deep ise yazılı özetleri ve sembol bazlı özleri ekler; bunlar model çağrılarıdır ve ücretlendirilir.
Dil desteği kademelidir ve kademe, bir çağrı grafiğine ne kadar güvenebileceğinizi belirler. TypeScript, JavaScript, Python, Go, Java, Kotlin, PHP, Swift ve R dilleri kapsam farkındalıklı dosya içi çözümleme desteğine sahiptir. Rust, C, C++, C#, Ruby, Scala, Elixir, Solidity, OCaml, Zig, Dart, Clojure, Nix ve Lua dilleri ise semboller ve genel çağrı kenarları ile desteklenir; bu, bir kenarın çözümlenmiş bir referanstan ziyade isim eşleşmesi olabileceği anlamına gelir. Derleyici seviyesinde kenarlar, --lsp ve rust-analyzer veya gopls gibi bir dil sunucusu (language server) ile isteğe bağlı olarak etkinleştirilebilir.
Graft kurulumu ve sürüm sabitleme
Graft, Node.js 20 veya daha yeni bir sürüm gerektirir ve MIT lisanslıdır. 17 Ekim 2026 itibarıyla güncel sürüm 15 Ekim 2026 tarihinde yayınlanan 0.23.0'dır; ilk yayınlanan sürüm olan 0.1.0 ise Temmuz 2026 tarihlidir. Yazılımı yeni olarak değerlendirin. 14 Ekim 2026'da yayınlanan 0.22.0 sürümü, projeyi Trail-code olarak yeniden adlandırdı: aynı kod artık @trailhq/trail-code olarak ve trail komutuyla dağıtılırken, @nanonets/graft ise graft komutunu korumaktadır.
Bu kılavuz, 29 Eylül 2026'da yayınlanan ve isim değişikliğinden önceki son sürüm olan 0.21.1 sürümünü sabitlemektedir; çünkü 0.22 ve 0.23 sürümleri, kılavuzun dayandığı komutları değiştirmiştir. 0.22 sürümünden itibaren graft check, dalınızdaki farkı deponun ekip öğrenimleriyle karşılaştırır ve bir çakışma durumunda 1 hata koduyla çıkar; sapma tespiti graft build --check komutuna taşınmıştır ve MCP araçları trail_* olarak adlandırılmıştır (sunucu hala eski graft_* isimlerine yanıt vermektedir). 0.23.0 sürüm notları ayrıca, trail ile yapılandırılmış bir depoda haritanın .trail/cache/ konumuna taşındığını ve Claude Code'un artık bir MCP sunucusu almadığını belirtirken, README dosyası hala graft/ ve .mcp.json yapılarını tarif etmektedir. Sürüm notlarını okuyun ve sabitlemeyi değiştirmeden önce --dry-run komutunu çalıştırın.
npm install -g @nanonets/graft@0.21.1
npm ls -g @nanonets/graftnpm ls -g komutu @nanonets/graft@0.21.1 çıktısını vermelidir. Bu sürümü özellikle sabitleyin. Yalın bir npm install -g @nanonets/graft komutu, çalıştırdığınız anda latest etiketini çözümler; ayda birkaç küçük sürüm yayınlayan bir projede bu durum, Salı günü kullandığınız aracın Pazartesi günü iş arkadaşınızın kurduğundan farklı olmasına neden olur. Sabitlenmiş bir sürüm, CLI bayraklarını ve grafik formatını herkes için aynı tutar, böylece yükseltmeyi siz karar verdiğinizde yaparsınız.
Ardından, sahip olduğunuz bir depoya bağlayın:
cd /path/to/your/repo
graft init --dry-run
graft initgraft init, hangi kodlama aracınızı bağlamak istediğinizi sorar ve ardından grafiği oluşturur. Önce --dry-run komutunu çalıştırın ve dokunmayı planladığı dosyaların listesini okuyun; çünkü bunlardan bazıları deponun dışında yer alır. graft init işlemseldir (idempotent) ve mevcut yapılandırmaların üzerine yazmaz, bu nedenle ikinci kez çalıştırmak güvenlidir. Geri almak için graft uninstall, Graft tarafından yazılan her dosyayı ve yapılandırma girdisini kaldırır; -y bayrağını geçene kadar bu işlem bir deneme çalışmasıdır.
Aynı istem, bir telemetri onay kutusu içerir. 0.12.0 sürümünden beri Graft, varsayılan olarak anonim bir kullanım sinyali gönderir: gruplandırılmış sayımlar ve sabit etiketler; kodunuz, dosya yollarınız veya depo adınız asla gönderilmez. Olaylar günde en fazla bir kez gönderilir; tek bir istisna dışında: npm'in postinstall kancasının arka plan göndericisine hemen ilettiği kurulum olayı. graft init sırasında kutunun işaretini kaldırın, graft telemetry disable komutunu çalıştırın veya kapatmak için DO_NOT_TRACK=1 ayarını yapın (CI ortamında da kendini otomatik kapatır); graft telemetry debug ise göndermeden önce gönderilecek paketi yazdırır.
0.21.1 sürümünde bağlantı; Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent ve Google Antigravity'yi kapsar. Hermes Agent, 0.13.0 sürümünden beri birinci sınıf bir graft init ana bilgisayarıdır ve sabitlenmiş sürümde graft init --agents hermes ve graft init --agents antigravity, diğer tüm ana bilgisayarlar gibi bu ikisini de seçer. Grok, 0.13.0 sürümünde eklenmiştir ve graft init --agents grok ile seçilir. Claude Code en derin entegrasyonu alır: bir MCP sunucu girdisi, grafik boyutunu ve güncelliğini gösteren bir durum satırı, grafiği yeniden oluşturan düzenleme sonrası kancaları ve .claude/ altında bir yetenek dosyası. Diğerleri, araca araçların var olduğunu bildiren bir talimat veya kural dosyası alır (Hermes Agent ve Antigravity, AGENTS.md bölümünü okur) ve Grok ayrıca kendi yapılandırmasında bir MCP bloğu alır. Bu nedenle "Desteklenen", Graft'ın bağlantıyı yazdığı anlamına gelir; dolayısıyla kendi kural dosyasını atlayan bir aracı haritayı da atlayacaktır. Bu, aracıların sizin yazdığınız talimatları görmezden gelmesinin olağan nedenidir ve burada da diğer her yerde olduğu kadar geçerlidir.
Deponuza neler eklenir ve neler git dışında tutulur
graft init sonrasında şunları bekleyebilirsiniz:
graft/: markdown düğüm grafiği vegraft/.graph/wiring.json. Sizin için.gitignoredosyasına eklenir..mcp.json: graft MCP sunucusunu kaydeder, böylece Claude Code onu başlatabilir..claude/settings.json: yerinde birleştirilir, durum satırı ve düzenleme sonrası kancaları (hooks) ekler.AGENTS.md,GEMINI.md,.github/copilot-instructions.md,.cursor/rules/graft.mdc,.kiro/steering/graft.md,.windsurf/rules/graft.md,.grok/skills/graft/SKILL.mdve.adal/skills/graft/SKILL.md: seçtiğiniz aracılarla eşleşen dosyalara eklenen işaretleyici ile sınırlandırılmış bölümler..grok/config.toml: yalnızca Grok seçildiğinde yazılan, depo düzeyinde bir[mcp_servers.graft]bloğu.~/.codex/config.toml,~/.codex/hooks.jsonve~/.codex/hooks/graft/graft-hooks.cjs: makine genelinde, yalnızca Codex seçildiğinde ve~/.codex/zaten mevcutsa yazılır.graft init --no-globalbunları atlar,graft init --no-hooksise kanca ara katmanını (shim) tek başına atlar.
Grafik, node_modules gibi bir önbellektir. Onu commit etmeyin. Koddan saniyeler içinde yeniden oluşturulur, neredeyse her düzenlemede değişir ve commit edilmesi, tek satırlık bir düzeltmeyi hiçbir gözden geçirenin okumayacağı birkaç yüz dosyalık bir farka dönüştürür. Bunun yerine, AGENTS.md ve .mcp.json dahil olmak üzere bağlantı yapılandırmasını commit edin. Bir ekip arkadaşınız depoyu klonladığında, graft build komutunu çalıştırır ve kendi yerel grafiğini oluşturur.
İlk commit işleminizden önce yoksayma kuralının uygulandığını doğrulayın:
grep -n graft .gitignore
git status --shortgrep komutu graft/ içeren bir satır yazdırmalı ve git status --short komutu graft/ altında hiçbir şey listelememelidir. Bu çıktıda graft/ altındaki dosyaların görünmesi, yoksayma girdisinin eksik olduğu veya başka bir yerde geçersiz kılındığı anlamına gelir. Commit etmeden önce bunu düzeltin; çünkü git bir dosya eklendikten sonra onu izlemeye devam eder ve daha sonra yapılacak bir .gitignore düzenlemesi dosyayı izleme dışı bırakmaz.
MCP sunucusunu manuel olarak kaydetmeyi veya yüklediğiniz sürümle sabitlemeyi tercih ederseniz, girdi oldukça basittir:
{
"mcpServers": {
"graft": {
"command": "npx",
"args": ["-y", "@nanonets/graft@0.21.1", "mcp"]
}
}
}Ajanınızın grep yerine kullandığı erişim araçları
Graft, MCP üzerinden altı araç sunar. graft_find_code, bir görev tanımı için dosya ve satır bilgisiyle birlikte sıralanmış düğümleri döndürür. graft_file_api, bir dosyadaki tüm imzaları gövde kısımları olmadan döndürür. graft_trace_calls, çağırıcıları veya çağrılanları birkaç seviye derine kadar tarar. graft_find_all, sembollere göre gruplandırılmış regex eşleşmelerini döndürür. graft_repo_map, yabancı bir depoya ilk bakış atılmasını sağlar. graft_check_freshness, grafiğin kodla hala uyumlu olup olmadığını raporlar.
Her birinin bir CLI eşleniği mevcuttur; ajanınıza gerçekte neyin iletildiğini bu şekilde kontrol edebilirsiniz:
graft map .
graft ask "where do we validate the refresh token"
graft skeleton src/auth/session.ts
graft callers validateRefreshToken
graft callers validateRefreshToken --direction out
graft grep "refresh_token" --jsongraft ask, dosya içerikleri yerine file:line referanslarıyla sıralanmış düğümleri yazdırmalıdır. Tüm mekanizma bundan ibarettir: ajan, doğru dosyayı bulmak için on tanesini okumak yerine bir işaretçi alır ve tek bir dosya açar. Grafiği kendiniz incelemek isterseniz graft viz, localhost üzerinde etkileşimli bir görüntüleyici açar. Eğer graft ask, otuz saniyede cevaplayabileceğiniz bir soru için faydalı bir sonuç döndürmezse, soruyu yeniden ifade edip tekrar sormayın. Sıralı erişim başarısız olabilir ve projenin kendi yetenek dosyası, zayıf eşleşmelerin graft grep, graft skeleton veya graft callers araçlarına geçiş yapılması gerektiği anlamına geldiğini belirtir. Eğer bunlar da sonuç vermezse, sapma olup olmadığını kontrol edin (sabitlenmiş 0.21.1 sürümünde graft check ., 0.22 ve sonrası için graft build --check) ve dilinizin hangi katmanda yer aldığını doğrulayın; çünkü güncel olmayan bir grafik veya geniş katmanlı kenarlar, ajanınızın başarısız olmasına neden olur.
Gözden kaçması kolay bir maliyet vardır. Altı araç tanımı, tüm oturum boyunca her isteğin sistem istemine (system prompt) enjekte edilir. Ajan haritayı kullansa da kullanmasa da bu maliyeti ödersiniz. Bağlama sığacak kadar küçük bir depoda, bu sabit ücret, sağladığı keşif avantajından daha büyük olabilir.
Kod değiştiğinde grafiğe ne olur
Yapısal yenileme ucuz ve otomatiktir. Graft, git yerine çalışma ağacınızı okur; bu nedenle henüz commit etmediğiniz veya stage ettiğiniz bir düzenleme, araç tarafından aynı şekilde görünür. Her sorgu önce çalışma ağacının durumunu kontrol eder (stat) ve yalnızca değişen dosyaları yeniden ayrıştırır. 0.21.1 dokümantasyonu, hiçbir şey değişmediğinde bu kontrolün yaklaşık 3 ms sürdüğünü belirtir; güncel README ise projenin kendi deposunda yaklaşık 50 ms olmak üzere birkaç on milisaniyelik bir süreden bahseder. Tur sonu yeniden oluşturma işlemi yalnızca kodun taşındığı dosyalara dokunur. Disk üzerindeki grafikten yeniden ayrıştırma yapmadan yanıt almak için GRAFT_NO_REFRESH=1 ayarını yapın veya --no-refresh bayrağını geçin. Graft'ın kendisini yükselttikten sonra ihtiyaç duyacağınız her şeyin soğuk yeniden ayrıştırmasını zorlamak için --no-reuse bayrağını kullanın.
Model tarafından yazılan kısım farklı davranır ve sessizce hatalı sonuç verebilecek kısım burasıdır. Özetler ve temel noktalar önbelleğe alınır. Her düğüm, kaynaklarının bir içerik özetini (hash) kaydeder; bu nedenle bir kaynak dosya değiştiğinde düğüm güncel olarak sunulmak yerine eski (stale) olarak işaretlenir. Bu bayrak yalnızca bir şey onun üzerinde işlem yaparsa işe yarar. Tekrar model token'ları harcayarak yenileme yapmak için graft build --deep kullanın.
Eskimişliği görünür kılın:
graft check .
echo $?Sabitlenmiş 0.21.1 sürümünde, 0 çıkış durumu grafiğin kodla eşleştiği, 1 çıkış durumu ise sapma olduğu anlamına gelir. 0.22 sürümünden itibaren graft check, ekip öğrenimi ile çakışma durumunda 1 değerini döndürür ve sapma denetimi graft build --check ile yapılır; bu nedenle sürüm sabitlemesini değiştirdiğinizde komutu da güncelleyin. Bunu bir pre-push hook üzerinden çalıştırın; böylece altı aylık bir harita, Mart ayında yeniden yazılmış bir kod hakkında güvenle yanıt veremez. 0.21.1 README dosyası graft check komutunu yerel bir tazelik sinyali olarak tanımlar, güncel README ise CI için build --check komutunu listeler. Her iki durumda da graft/ git tarafından yoksayılır (git-ignored), bu nedenle yeni bir CI checkout işlemi, iş akışı bir grafik oluşturmadığı sürece grafiksiz başlar.
Yayınlanan kıyaslama verilerini dikkatle inceleyin
0.21.1 sürümünün README dosyası, "4 kata kadar daha ucuz ve 3 kata kadar daha hızlı, doğruluk kaybı olmadan veya daha az kayıpla" ifadesiyle başlıyordu. Mevcut README bu ifadeyi kaldırdı ve daha küçük rakamlarla başladı: "Aynı ajanla aynı görevler üzerinde yapılan 162 çalıştırmada: %32 daha düşük maliyet, %42 daha az önbelleğe alınmamış girdi token'ı, %60 daha az süre ve aynı oranda doğru cevap." Bu veriler, projenin kendi README dosyasında yayınlanan kıyaslamalarından gelmektedir. Projenin tam olarak raporladığı iki çalıştırma aşağıdadır.
Bu grafiğin arkasındaki veriler
[
{
"label": "Controlled sweep",
"run_count": 162,
"token_saving_pct": 42,
"tool_call_saving_pct": 46,
"correctness_pct": 93,
"baseline_correctness_pct": 93
},
{
"label": "SWE-bench Verified",
"run_count": 50,
"token_saving_pct": 23,
"tool_call_saving_pct": 25,
"correctness_pct": 66,
"baseline_correctness_pct": 54
}
]Kontrollü tarama, biri Graft'ın kendisi olmak üzere iki depo üzerinde, görev başına üç deneme ile 162 çalıştırmadan oluşmaktadır. Rapor, 42% daha az önbelleğe alınmamış girdi token'ı ve 46% daha az araç çağrısı bildirmektedir. SWE-bench Verified çalıştırması, her iki kolda da aynı model kullanılarak 50 örnek üzerinde gerçekleştirilmiş olup daha küçük bir tasarruf bildirmektedir: token'ların 23% kadarı ve araç çağrılarının 25% kadarı. On geliştirici sorusu ve beş yeniden üretilmiş birleştirilmiş pull request'ten oluşan 15 PocketBase görevlik üçüncü bir çalıştırma, temel değer olan 13.91 ABD dolarına karşılık toplam 11.02 ABD dolarına mal olmuştur.
Tüm bunları bir satıcı kıyaslaması olarak değerlendirin. Size ne anlatabileceğini sınırlayan iki husus vardır. Kontrollü tarama, yazarlarının üzerinde optimizasyon yaptığı kod tabanı olan Graft'ın kendi deposunu içermektedir. SWE-bench Verified, iyi bilinen açık kaynaklı Python projelerinden gelen sorunların yer aldığı halka açık bir veri kümesidir ve halka açık veri kümeleri, kimse niyet etmese bile araçların optimize edildiği yerlerdir. Bunların hiçbiri, kendine has isimlendirme alışkanlıkları ve ölü kodları olan özel monorepo'nuz hakkında bir beyan değildir.
Doğruluk konusu ikinci bir okumayı hak ediyor. Kontrollü taramada bu oran değişmemiştir: harita ile 93%, haritasız 93%. 54% oranından 66% oranına olan sıçrama sadece SWE-bench Verified üzerinde görülmektedir. Token faturanızı düşüren ve kaliteyi sabit tutan bir araç hala iyi bir kazançtır. Sadece SWE-bench doğruluk sonucunu taramanın token sonucuyla birleştirmeyin ve her ikisini tek bir iddia olarak sunmayın.
Kendi token farkınızı ölçün
Önemli olan tek sayı, kendi deponuzdan elde ettiğiniz sayıdır. Bu yöntem bir öğleden sonranızı alır.
Tam olarak tekrarlayabileceğiniz bir görev seçin. Bir soru sormak, bir düzenleme yapmaktan daha iyidir; çünkü düzenleme depoyu değiştirir ve ikinci çalıştırma artık aynı deney olmaz. "Giriş rotasındaki hız sınırını hangi modül zorunlu kılıyor" sorusu, doğru biçimdedir.
Telemetriyi açın ve kendi terminalinize gönderin:
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claudeKonsol dışa aktarıcı, metrik kayıtlarını toplandıkça yazdırır. İhtiyacınız olan metrik claude_code.token.usage'dur; bu metrik input, output, cacheRead veya cacheCreation değerinde bir type özniteliği taşır. Yönlendirme, dosya içeriklerinin ulaştığı yer olduğu için input ve cacheRead içinde görünür. Bu ikisini toplayın.
Görevi, harita bağlıyken her biri yeni bir oturumda olmak üzere üç kez çalıştırın. Ardından .mcp.json içindeki graft girdisini kaldırın ve üç kez daha çalıştırın. Tekil çalıştırmalar yerine medyan değerleri karşılaştırın; çünkü aracı çalıştırmaları büyük değişkenlik gösterir ve şanssız bir çalıştırma size gerçeğin tam tersini söyleyebilir. Araç çağrı sayısını da kaydedin: araç çağrıları mekanizmadır, tokenlar ise etkidir; bu nedenle araç çağrılarında düşüş olmadan gerçekleşen bir token tasarrufu, başka bir şeyin değiştiği anlamına gelir.
Ardından kıyaslama testinin göstermediği maliyetleri çıkarın. graft build --deep, her tam yenilemede model tokenları harcar. Altı araç şeması her istekte beraberinde gönderilir. Eğer araçlarınız kiraladığınız bir sunucuda çalışıyorsa, aracı harcamasına kesin bir üst sınır koymak, bu durumu sürpriz olmaktan çıkarıp bir bütçe haline getirir ve bir kodlama aracının telemetrisinin gerçekte ne raporladığı, dışa aktarıcıyı etkinleştirdiğinizde makineden nelerin çıktığını kapsar.
Kod tabanı haritası ne zaman işlevini yitirir?
- Depo zaten bağlama sığıyorsa. Tek bir küçük servis için haritaya gerek yoktur; üstelik her istekte altı araç şeması için maliyet ödersiniz. Eğer temsilciniz (agent) bugün herhangi bir dosyayı bir veya iki araç çağrısında bulabiliyorsa, haritayı kullanmayın.
- Diliniz geniş kapsamlı katmandaysa. Genel çağrı kenarları,
graft callersaracının bir çağırıcıyı gözden kaçırmasına veya isim çakışması nedeniyle yanlış bir çağırıcı üretmesine neden olabilir. Bir etki alanına (blast radius) güvenmeden öncegraft grepile doğrulayın. - Grafik güncelliğini yitirdi ve kimse fark etmediyse. 0.21.1 sürümünde
graft check, sapma durumunda 1 koduyla çıkar (0.22 sürümünden itibarengraft build --checkbunu yapar); ancak bu yalnızca bir şey onu çalıştırırsa yararlıdır. Bu bir alışkanlık değil, bir pre-push kancası olmalıdır. - Monorepo kapsam belirlemeye ihtiyaç duyuyorsa. Tek bir git deposuna sahip monorepo bölünmüş değildir; ancak
graft build, alt projeleripnpm-workspace.yaml,package.jsonçalışma alanlarından veya paket bazlıgo.mod,pyproject.tomlveyaCargo.tomldosyalarından algılar ve bunları sıralama kapsamı olarak kullanır.graft ask "..." --in services/billing/ise sorguyu tek bir alt proje ile daraltır. paket başına iç içe AGENTS.md dosyaları oluşturma içgüdüsü, harita için de geçerlidir. - Temsilci bağlantıları görmezden geliyorsa. Haritanın kullanıldığı sonucuna varmadan önce gerçek bir oturumdaki araç çağrılarını izleyin. Hâlâ
grepçalıştıran bir temsilci, size kurallar dosyasını hiç okumadığını söylüyordur.
FAQ
graft/ klasörünü git deposuna eklemeli miyim?
Hayır. graft build, graft/ dosyasını otomatik olarak .gitignore içine ekler; çünkü grafik, node_modules gibi yeniden oluşturulabilir bir önbellektir. Neredeyse her düzenlemede değiştiği için, bu klasörü eklemek gerçek değişiklikleri (diff) yüzlerce oluşturulmuş dosyanın altında bırakır. Ajanlara haritanın varlığını bildiren yapılandırmayı (AGENTS.md ve .mcp.json dahil) ekleyin ve her ekip üyesinin graft build komutunu yerel olarak çalıştırmasını sağlayın. İlk commit işleminizden önce grep -n graft .gitignore ve git status --short ile doğrulama yapın; çünkü git bir dosya eklendikten sonra onu izlemeye devam eder ve sonrasında .gitignore dosyasını düzenlemek dosyanın takibini durdurmaz.
Graft çalıştırmanın bir maliyeti var mı?
Yapısal kısım ücretsizdir. graft build, graft ask, graft check ve altı adet MCP geri alma aracı, hiçbir zaman bir modele çağrı yapmayan tree-sitter işlemleridir. graft build --deep ücretli kısımdır: düz İngilizce özetleri ve sembol bazlı kritik noktaları, GRAFT_PROVIDER, GRAFT_API_KEY, GRAFT_MODEL ve OpenAI uyumlu uç noktalar için GRAFT_BASE_URL ile yapılandırılmış bir LLM aracılığıyla yazar. Graft'ı yalnızca yapısal özellikleriyle çalıştırabilir ve grafik için tek bir token bile harcamayabilirsiniz.
Kod tabanı haritası depomda ne kadar tasarruf sağlar?
Ölçüm yapmadan kimse bunu söyleyemez. Proje, kendi 162 çalıştırmalık taramasında önbelleğe alınmamış girdi tokenlarında %42 oranında, SWE-bench Verified üzerinde ise %23 oranında azalma rapor etmektedir; her iki sonuç da haritasız bir temel yapıya kıyasladır. Bunların her ikisi de satıcı kıyaslamalarıdır, biri kısmen Graft'ın kendi deposunda çalıştırılmıştır ve hiçbiri sizin özel kodunuzu tanımlamaz. Tekrarlanabilir bir soruyu harita ile üç kez, haritasız üç kez; CLAUDE_CODE_ENABLE_TELEMETRY=1 ve OTEL_METRICS_EXPORTER=console ayarları yapılmış şekilde çalıştırın ve ardından input ve cacheRead türleri için claude_code.token.usage değerlerinin medyanını karşılaştırın.
Yeniden düzenleme (refactor) yaptığımda grafiğe ne olur?
Yapı kendini yeniden ayrıştırır. Graft çalışma ağacını kontrol eder ve yalnızca değişen dosyaları yeniden ayrıştırır, bu sayede bir yeniden adlandırma işlemi bir sonraki sorguda yakalanır. Hiçbir şey değişmediğinde, bu kontrol 0.21.1 sürümünde yaklaşık 3 ms, mevcut sürümde ise birkaç on milisaniye sürer; git geçmişi yerine dosyaları okuduğu için commit edilmemiş çalışmaları da görür. Model tarafından yazılan özetler eskiyen kısımdır: her düğüm kaynaklarının bir içerik özetini (hash) saklar ve değişen bir kaynak, düğümü yeniden yazmak yerine "eski" olarak işaretler. Sapma olup olmadığını kontrol edin (0.21.1 sürümünde graft check ., 0.22 ve sonrasında graft build --check) ve ardından yazılı kısmı yenilemek için graft build --deep komutunu çalıştırın.
Hangi kodlama ajanları bugün Graft kullanabilir?
Sabitlenmiş 0.21.1 sürümünde graft init; Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent ve Google Antigravity olmak üzere toplam on bir ana bilgisayarı (host) birbirine bağlar. Değişiklik günlüğü (changelog), Hermes Agent'ı 0.13.0 sürümünden beri birinci sınıf bir ana bilgisayar olarak listelemektedir ve hermes ile antigravity, sabitlenmiş sürümde standart --agents kimlikleridir. Claude Code en fazla özelliği alır: .mcp.json içinde bir MCP sunucu girişi, bir durum satırı, düzenleme sonrası kancalar (hooks) ve .claude/ altında bir yetenek dosyası. Codex, AGENTS.md bölümüne ve ~/.codex/ altında makine genelindeki girişlere sahiptir; graft init --no-global bunları atlar. Grok, bir yetenek dosyasına ve .grok/config.toml içinde bir MCP bloğuna sahiptir. Hermes Agent ve Antigravity, AGENTS.md bölümünü okur, diğerleri ise bir kural veya yönlendirme dosyası alır. Diğer tüm MCP istemcileri, npx -y @nanonets/graft@0.21.1 mcp komutunu kaydederek sunucuyu doğrudan kullanabilir.