Maguyva Blog

Sizinle birlikte seyahat eden bağlam

Mon, 07 Sep 2026 00:00:00 GMT

Cursor’ın indeksleyicisi Cursor içinde mükemmel çalışır. Sekme tamamlama, satır içi düzenleme, sohbet ve o penceredeki ajan zaten Cursor’ın açık çalışma alanı için işlettiği bir proje indeksinin üzerinde durur. Cursor yazdığınız tek yüzeyse ve o indeks zaten doğru dosyaları buluyorsa, orada kalın. Bu, dürüst ‘olduğunuz yerde kalın’ durumudur ve bu sayfanın ilk cümlesi olmayı hak eder.

Bu yazı, sıradan bir haftanın diğer yarısıyla ilgili. Aynı repo Claude Code’da da açılıyor, Codex CLI’dan sorgulanıyor, ikinci bir makinede gözden geçiriliyor veya CI’da çalışan bir ajan tarafından sorgulanıyor. Soru ‘hangi indeksleyici daha iyi’ değil. Soru, ajanın bir pencerede güvendiği haritanın, bir sonrakinde güvendiği haritayla aynı olup olmadığı.

Maguyva, sizinle birlikte seyahat eden o haritadır. Uzak bir MCP kod tabanı bağlam katmanıdır. Ajan onu, başka herhangi bir MCP aracını sorguladığı gibi sorgular. Sonuçlar, satır numaralarıyla sıralanmış yollar olarak döner. Cursor editör olarak kalır. Hareket eden şey bağlamdır.

Cursor’ın indeksleyicisi ne işe yarar

Cursor’ın yerleşik indekslemesi, editör içindeki sohbet, ajan ve arama işlevlerinin, modelin ham bağlam penceresine sığana güvenmek yerine ilgili kodu getirebilmesi için var. Bu, bir IDE için doğru tasarımdır. Bu indeks Cursor’a özgüdür. Bir MCP sunucusu değildir ve başka hiçbir istemciden erişilemez.

Bu, yazıldığı sırada Cursor’ın herkese açık belgelerinde ve Cursor’ın kendi açıklamasında anlatıldığı şekliyle şöyle çalışır: birincil arama yolu artık bulut tabanlı bir embedding indeksi değil. Cursor ekibi, topluluk forumunda, güncel modellerin canlı bir ağacı zaten kendi başlarına yeterince iyi keşfedebildiği için özel semantik, embedding tabanlı aramanın grep tabanlı getirme lehine kademeli olarak azaltıldığını açıkladı. Onun yerine, n-gramlardan, ters çevrilmiş listelerden ve Bloom filtrelerinden oluşturulan yerel bir arama indeksi olan Instant Grep var; bu indeks bellekte eşlenmiş bir arama tablosunda tutulur, böylece sorgular bir sunucuda değil geliştiricinin kendi makinesinde çözülür.

İndeksin kendisi, reponun kendi .git/cursor/ dizininde, belirli bir git commit’ine sabitlenmiş şekilde yaşar; o commit’ten bu yana yapılan değişiklikler yeni bir tarama tetiklemek yerine onun üzerine katmanlanır ve indeks yalnızca yerel durum, üzerine inşa edildiği şeyden büyük ölçüde saptığında yeniden oluşturulur. .git içinde yer aldığı için asla izlenmez ve asla push edilmez — klasörü silin, indeks kaybolur. Yalnızca git tarafından izlenen içerik uygun olduğundan .gitignore yapı gereği korunur ve .cursorignore okuma yolunda zorunlu kılınır. O yolda artık sunucu tarafında bir embedding adımı ya da uzak bir vektör veritabanı yok. Daha önceki belgeler, bulut destekli bir tasarımı tanımlıyordu — parça şifreleme, Merkle ağacı üzerinden senkronizasyon, ekip üyeleri arasında indeks yeniden kullanımı — ve Cursor’ın kendi ekibi o zamandan beri bu tasarımın azaltıldığını söyledi, bu yüzden bu yazı onu artık güncel olarak tanımlamıyor.

Editör içinde öne çıkan bir özellik, Cursor’ın Explore alt ajanıdır. Kendi bağlam penceresinde, daha hızlı bir modelde birden çok paralel arama başlatabilir ve yalnızca ilgili bulguları döndürebilir, böylece ana konuşma arama sonuçlarıyla şişmez. Bu, editör içinde gerçek bir güçtür. Onu koruyun.

Çoklu kök çalışma alanları destekleniyor: açık her klasörün bağlamı Agent için kullanılabilir. Worktree gibi bazı git’e bağımlı özellikler çoklu kök kurulumlarında devre dışı bırakılır ve Cloud Agents çoklu kök çalışma alanlarını hiç desteklemez.

Bunların hiçbiri Cursor’ı terk etmek için bir neden değil. Bu, yaşadığı yerde mükemmel olan bir haritanın kesin bir açıklaması.

‘Sizinle birlikte seyahat etmek’ gerçekte ne anlama gelir

Bir harita, aynı sorular birden fazla istemciden açabileceğiniz alıntılarla aynı türden yanıtı döndürdüğünde sizinle birlikte seyahat eder.

Cursor’da: ‘parseConfig nerede tanımlanmış ve onu kim çağırıyor?’
Claude Code’da, aynı repoda: aynı soru.
Codex CLI’da, Cursor penceresini hiç açmamış bir inceleme makinesinde: aynı soru.
MCP konuşan bir CI ajanında: aynı barındırılan anlık görüntüye karşı aynı soru.

Her yüzey kendi özel indeksini oluşturuyorsa, tek bir haritanız yok demektir. Birbirinden uzaklaşan birden fazla önbelleğiniz var demektir. Editör indeksi disk üzerindeki ağaç için güncel olabilir. CLI oturumu bir gün geride olabilir. CI işi farklı bir checkout’a bakıyor olabilir. Ve ajan yine de kendinden emin görünmeye devam edecektir.

Cursor’ın indeksleyicisinin bunu çözmesi beklenmiyor. Editör içinde yaşadığı için, oluşturduğu bağlam o editör içindir. Bir CLI’a, bir CI hattına ya da farklı bir editöre de ihtiyaç duyan bir okuyucunun, bu yüzeyler için ayrı bir araca ihtiyacı vardır. Bu bir kapsam gerçeğidir, bir kusur değil. Maguyva, o ayrı araçtır.

Cursor’ın indeksleyicisi için yayımlanmış bir dil sayısı, bu yazının kullanabileceği materyallerde belirtilmemiş. Maguyva, 279’dan fazla dil ve metin tabanlı teknoloji için destek yayımlıyor. Cursor’ın fiyatları da burada tekrarlanmıyor; onların fiyat sayfasına bakın. Maguyva koltuk başına değil, çalışma alanı başına ücretlendirir; indekslenen kapsam ve çalışma alanı boyutuna bağlı olarak yayımlanmış 0 $, 19 $, 49 $ ve 149 $ planları vardır.

Tek bir barındırılan harita, her MCP istemcisi

Maguyva, uzak bir MCP sunucusudur. GitHub’ı bağlarsınız, repoları seçersiniz ve bulut hattı sembolleri, graf kenarlarını ve sıralanmış bir haritayı oluşturur. Zaten kullandığınız istemcinin MCP yapılandırmasına bir API anahtarı eklersiniz. Maguyva’nın, Cursor da dahil olmak üzere 24 belgelenmiş MCP istemcisi için kurulum kılavuzları vardır ve standart yapılandırmayı destekleyen diğer MCP uyumlu istemcilere bağlanabilir.

Çalıştığınız yer orasıysa Cursor kurulum sayfası editöre özgü yoldur. Aynı sunucu Claude Code, VS Code, Windsurf, Codex CLI ve diğerlerine yanıt verir. Editör değiştirmezsiniz. Her ajana aynı araç yüzeyini verirsiniz: arama, semboller, bağımlılık analizi, dosya getirme, repo bağlamı ve deterministik yardımcı araç iş akışları genelinde 11 müşteriye yönelik MCP aracı. Semantik, yapısal, graf ve metin araması sıralanmış sonuçlarda birleştirilir.

Taşınabilirlik avantajı budur. Bu sabah Cursor’da kontrol ettiğiniz alıntılar, Codex CLI’ın bu akşam döndüreceği alıntılarla aynı şekle sahiptir. Dosya yolu ve satır numarası. Onları açın. Yanlışlarsa, bunu görürsünüz. Doğrularsa, bir sonraki değişikliğin inebileceği bir yer vardır. Onaylanan iddia daha az halüsinasyon görülen değişikliktir, her değişikliğin doğru olacağı sözü değil.

Güncellik yayımlanır. Anlık görüntüler zaman damgalıdır, böylece ajan ağacın hangi sürümünü okuduğunu bilir. Yeniden oluşturma sıklığı ücretsiz planda günlük, ücretli planlarda saatliktir. Dürüst sınırlama senkronize edilmemiş yerel çalışmadır: yalnızca bir çalışma ağacında var olan bir değişiklik henüz barındırılan haritada değildir. Bu sınırlama, hangi istemciden sorguladığınızdan bağımsız olarak aynıdır ve tam olarak mesele de budur. İstemciler arasındaki sapma artık ikinci, gizli bir sınırlama değildir.

Belgeler, her istemciye uygulanan etkinleştirme döngüsünü verir: zaten bildiğiniz bir repoyu indeksleyin, istemciyi bağlayın, doğrulayabileceğiniz bir soru sorun. Bunu Cursor’da bir kez yapın. Gözden geçirme günlerinde gerçekten kullandığınız CLI’dan tekrar yapın. Her iki yanıt da aynı işleyiciyi alıntılıyorsa, harita gerçekten sizinle birlikte seyahat etmiştir.

İki harita yan yana nasıl var olur

İkisini de kullanın. Bunlar bir karşılaştırma sayfası anlamında alternatif değildir.

Disk üzerindeki proje için Cursor’ın indeksleyicisini açık tutun. Explore, Instant Grep ve editör içindeki ajanın onu kullanmasına izin verin. Bu döngü yerel ve hızlıdır.
Aynı oturumun barındırılan çalışma alanı haritasını da sorgulayabilmesi için Cursor’a Maguyva’yı MCP sunucusu olarak ekleyin. Cursor, belgelenmiş bir Maguyva istemcisidir. Bir indeksi seçip diğerini silmiyorsunuz.
Aynı Maguyva sunucusunu Claude Code’a, Codex CLI’a veya repoya dokunan başka herhangi bir MCP istemcisine ekleyin. Tek bir API anahtarı biçimi. Tek bir çalışma alanı.
Bir CI ajanı MCP uyumluysa, onu aynı sunucuya yönlendirin. Dizüstü bilgisayarın okuduğu aynı zaman damgalı anlık görüntüyü okuyacaktır.

Editör indeksi, ‘şu anda bu penceredeki diskte ne var’ sorusu için en iyi araç olmaya devam ediyor. Barındırılan harita, ‘bu çalışma alanı bugün ona dokunacak her ajana nasıl görünüyor’ sorusu için en iyi araçtır. Bu cümleler birbiriyle yarışmaz.

Çalışma alanı kotaları fiyat sayfasında yayımlanır: repolar, indekslenen satırlar ve kullanıcılar, çalışma alanı başına faturalandırılır. Ajanlar ve insanlar aynı kullanıcı sayısını paylaşır. Zaten değerlendirebileceğiniz bir repoyla ücretsiz başlayın. Alıntılar ağaçla temas ettikten sonra hayatta kaldığında çalışma alanını yükseltin.

Bu sayfanın iddia etmediği şeyler

Cursor’ın indeksleyicisinin zayıf, eksik ya da editör değiştirmek için bir neden olduğunu iddia etmiyor. Bu yazının ilk cümlesi tam tersini söylüyor.

Maguyva’nın Instant Grep’in ya da Explore alt ajanının yerini aldığını iddia etmiyor. Bunlar Cursor özellikleridir. Cursor’da kalırlar.

İki ürün için de bir dil sayısı, bir gecikme rakamı ya da bir token tasarrufu uydurmuyor. Bilinmeyen rakamlar yayımlanmamış olarak kalır.

Push edilmemiş yerel çalışmanın barındırılan haritada olduğunu iddia etmiyor. Zaman damgalı anlık görüntüler bu sınırlamayı görünür kılar. Onu ortadan kaldırmazlar.

Test sıradandır. Zaten bildiğiniz bir repoyu indeksleyin. Doğrulayabileceğiniz bir soru sorun, önce Cursor’da, sonra ikinci bir MCP istemcisinde. Sizinle birlikte seyahat eden bağlam, her iki yerdeki aynı alıntıdır.

// same map, wherever you opened it.

Önce harita, sonra inceleme

Mon, 07 Sep 2026 00:00:00 GMT

Bir pull request’in her iki tarafında da iki farklı iş oturur. Ajan yazmadan önce, değiştirmek üzere olduğu ağacın bir haritasına ihtiyacı vardır. Ajan bir PR açtıktan sonra, bir şeyin bu değişikliği sistemin geri kalanıyla karşılaştırarak okuması ve bir insanın harekete geçebileceği yorumlar bırakması gerekir.

Bu işler uzaktan bakıldığında benzer görünür çünkü ikisi de ‘kod tabanını anlamayı’ içerir. Aynı ürün değildirler. Biri ‘bu değişiklik nereye inmeli?’ sorusuna cevap verir. Diğeri ‘satır satır kontrol eden bir linter’ın gözden kaçıracağı şeyi bu diff neyi bozdu?’ sorusuna cevap verir. Onları karıştırmak, daha kötü bir ilk taslak ve daha gürültülü bir inceleme üretir.

Bu yazı, ortak bir iş akışı kılavuzudur. Maguyva, ajanın önce sorguladığı haritadır. Greptile, PR’ı sonrasında yorumlayan inceleme ajanıdır. Çift, yapı gereği birbirini tamamlar: Maguyva pull request’leri incelemez ve Greptile, ajanın onları yazmak için kullandığı bağlam katmanının yerini almaz.

Bu ayrımın neden yararlı olduğu

Eğitim önyargıları artı birkaç yapıştırılmış dosyadan yola çıkan bir kodlama ajanı, makul bir yol uydurur ve onu düzenler. Bu, ‘yanlış dosya’ başarısızlığıdır ve bir getirme sorunudur. Maguyva, uzak bir MCP kod tabanı bağlam katmanıdır: semantik, yapısal (AST), graf/bağımlılık ve metin getirme sıralanmış sonuçlarda birleştirilir, artı sembol arama ve dosya getirme. Temellendirilmiş yanıtlar path/file.ext:line olarak döner, böylece bir yama var olmadan önce bir isabetsizliği reddedebilirsiniz. İddia mütevazı kalır: daha az halüsinasyon görülen değişiklik. Model yine de tahmin edebilir. Sadece ilk adım artık bir tahmin olmaktan çıkar.

Greptile, yapay zeka destekli bir kod inceleme ajanıdır. Kendi ifadeleriyle, kod tabanının tam anlaşılmasıyla her pull request’i otomatik olarak inceler ve bunu, sistemin tamamı yerine dosyaları tek tek kontrol eden geleneksel linter’larla karşılaştırır. Kurulum, GitHub veya GitLab uygulamasını yüklemekten ve repoları seçmekten ibarettir. İşletmeniz gereken yerel bir indeks yoktur. Barındırma Greptile Cloud’dadır (talep üzerine sunulan bir raporla SOC 2 Type II uyumluluğu beyan ederler), işletmelere sunulan kendi kendine barındırma seçeneğiyle birlikte.

Kendi numaralandırılmış akışları şöyledir: bağlanın ve her fonksiyonun, sınıfın ve bağımlılığın bağımlılık grafını oluşturun; her pull request’te, bu tam repo grafını kullanarak değişikliği analiz edin ve bulguları önerilen düzeltmelerle birlikte yaklaşık üç dakikada PR yorumları olarak yayınlayın; her yorum, sorunu ekibin zaten kullandığı bir kodlama ajanına devredebilir. Ayrıca, bir ekibin kod standartlarını öğrenmek ve gürültülü önerileri azaltmak için zaman içinde önceki insan PR yorumlarını okuduklarını belirtiyorlar. Kendi ifadelerine göre öğrenme sistemlerinin uyum sağlaması 2-3 hafta sürüyor.

Bu, taslak hazırlama değil incelemedir. Greptile’ın öne çıkan yanı, bir PR’a zaten inmiş olan değişiklik üzerindeki tam repo grafı bağlamıdır, ardından bulguyu Claude Code, Codex, Conductor, Cursor veya Devin’e gönderen kapalı bir döngüdür. Maguyva’nın öne çıkan yanı, o değişiklik yazılmadan önce ajanın sorguladığı sıralanmış haritadır. İkisini de kullanın. Hiçbirinden diğerinin işini yapmasını istemeyin.

Maguyva–Greptile arasında birinci taraf bir ürün entegrasyonu belirtilmemiştir. Buna ihtiyacınız da yok. Maguyva, ajanla MCP üzerinden konuşur. Greptile, GitHub veya GitLab ile kendi uygulaması üzerinden konuşur. Pull request’te buluşurlar. Ne bir yapıştırma betiği, ne de bir aracı diğerine bağlayan bir cron var. Çift bash’siz idare eder çünkü her ürün zaten kendisine ait olan yüzeyde oturur.

Bu ne değildir

Bu, Greptile’ı yerin dibine sokan bir yazı değildir. ‘İnceleyicinizi değiştirin’ sayfası da değildir. Greptile, 5 Mart 2024’te Y Combinator W24 şirketi olarak Hacker News’te lanse edildi ve o thread, birçok insanın ürünle ilk kez tanıştığı yoldur. Onları böyle bulduysanız, onları kullanmaya devam edin. Bu sayfa, o döngünün eksik ön yarısıdır: Greptile’ın gördüğü PR’ın zaten doğru dosyaları hedeflemesi için ajanı önceden temellendirmek.

Greptile’ın pazarlama materyalleri, inceleme hızı ve hata yakalama iddialarıyla başlıyor. Bunları bağımsız olarak doğrulanmış rakamlar olarak değil, Greptile’ın kendi iddiaları olarak değerlendirin. Bu yazı onları gerçekmiş gibi tekrar etmiyor.

Dil kapsamı da aynı türden bir dürüstlüktür. Greptile, desteği numaralandırılmış bir liste yerine tüm programlama dillerini kapsayan bir çerçeve olarak sunar; kesin bir sayı belirtilmemiştir. Maguyva, 279’dan fazla dil ve metin tabanlı teknoloji için destek yayımlar; soru teknik olduğunda sitede teknik bir ayrım (ayrıştırıcı destekli AST’ye karşı yalnızca metin) sunar. Bunlar farklı iddialarda bulunan farklı ürünlerdir. Onları karıştırmayın.

Greptile’ın fiyatlandırması, bu yazının kullanabileceği materyallerde belirtilmemiştir. Ücretli planlar mevcuttur; onların fiyat sayfasına bakın. Maguyva, koltuk başına değil çalışma alanı başına ücretlendirir. Planlar ücretsiz başlar. Çalışma alanı rakamlarına ihtiyacınız varsa fiyat sayfası yayımlanmış katmanları listeler.

İş akışı

Üç isimlendirilmiş aşama. Bunları bu sırayla uygulayın. Çifti ilk denediğinizde hiçbirini atlamayın.

1. Maguyva bağlamı

Zaten bildiğiniz bir repoyu indeksleyin. Zaten içinde yazdığınız MCP istemcisini bağlayın — Claude Code, Cursor, Codex CLI, VS Code, Windsurf veya başka bir MCP uyumlu istemci. Maguyva’nın 24 belgelenmiş MCP istemcisi için kurulum kılavuzları vardır ve standart MCP yapılandırmasını destekleyen diğer istemcilere bağlanabilir.

Kimse bir satır yazmadan önce değerlendirebileceğiniz bir soru sorun. ‘Oturum süresi dolması nerede işleniyor ve bunu ne çağırıyor?’ sorusu ‘auth’u düzelt’ demekten daha iyi bir ilk hamledir. Alıntı talep edin. file.ext:line sonuçlarını açın. Sembolü takip edin. Dokunmak üzere olduğunuz bağımlılığı doğrulayın.

Maguyva, arama, semboller, bağımlılık analizi, dosya getirme, repo bağlamı ve deterministik yardımcı araç iş akışları genelinde 11 müşteriye yönelik MCP aracı sunar. Dört getirme modu sıralanmış sonuçlarda birleştirilir; adını zaten biliyorsanız find_symbol ayrı bir araçtır. Belgeler en kısa yolu tanımlar: ücretsiz başlayın, zaten bildiğiniz bir repoyu indeksleyin, istemciyi bağlayın, sonra doğrulayabileceğiniz bir soru sorun.

Anlık görüntüler zaman damgalıdır, böylece ajan ağacın hangi sürümünü okuduğunu söyleyebilir. Dürüst sınırlama, senkronize edilmemiş yerel çalışmadır. Değişiklik yalnızca bir çalışma ağacında varsa ve push edilmemişse, barındırılan harita onu henüz içermez. Talimat dosyaları (CLAUDE.md, AGENTS.md), kurallar ve dokunulmaması gerekenler için burada yerini korumaya devam eder. Bunlar canlı bir harita değildir. Onları davranış için kullanın. Gerçekler için Maguyva’yı kullanın.

Alıntılar repoyla temas ettikten sonra hayatta kalana kadar ajanın bir PR açmasına izin vermeyin. Bu geçit, bu aşamanın tüm amacıdır.

2. Ajanın PR’ı

Aynı ajan artık değişikliği zaten ödeme yaptığınız istemcide yazar. Maguyva ne bir editör ne de bir inceleyicidir. Ajan yine de diff’i üretir. Siz yine de zaten yaptığınız gibi GitHub veya GitLab’da pull request’i açarsınız.

Farklı olması gereken şey ilk dosyadır. PR, davranışı gerçekten uygulayan işleyiciyi, bozulacak çağıranı ve değişiklik yanlışsa başarısız olacak testi adlandırmalıdır. Aşama 1 atlandıysa, aşama 3 yorumlarını yanlış pakete inmiş bir değişiklik üzerinde harcayacaktır. Greptile yine de sistemik sorunları bulabilir. Ayrıca bir halüsinasyon yoldan da kurtulmak zorunda kalmamalıdır.

PR’ı sınırlı tutun. Temellendirilmiş bir ilk dosya, modülü yeniden yazma lisansı değildir. Bu birbirini tamamlayan çift, ajan bir haritayla bir işi yaptığında ve ardından bir inceleyiciden sınırlandırılmış bir diff üzerinde başka bir iş yapmasını istediğinde çalışır.

3. Greptile incelemesi

Greptile, GitHub veya GitLab uygulaması aracılığıyla repoya zaten bağlıdır. Yeni pull request’te, oluşturduğu tam repo grafını kullanarak değişikliği analiz eder ve önerilen düzeltmelerle birlikte bulguları yorum olarak yayınlar. Kendi materyalleri bu geçişi yaklaşık üç dakikaya koyar.

Yorumları dikkatli bir ekip arkadaşını okur gibi okuyun: alıntılanan konumu açın, bulgunun gerçek olup olmadığına karar verin, sonra harekete geçin. Greptile’ın ‘Fix with your Agent’ sunduğu yerde, sorunu — dosya yolları, satır numaraları, önerilen kod — Claude Code, Codex, Conductor, Cursor veya Devin’e gönderir. ‘Fix All’, incelemedeki tüm sorunları bir kerede gönderir. Bu devir için bir Greptile MCP ve bir Claude Code eklentisi de sunuyorlar. Maguyva o isimlendirilmiş hedef listesinde yok; bu yokluk bir sorun değil. Maguyva işini zaten aşama 1’de yaptı. PR’ı yazan kodlama ajanı, düzeltme yükünü almalı olandır.

Greptile’ın öğrenme sistemi ekibinizin gerçekten bıraktığı yorumlara uyum sağlarken ilk 2-3 hafta gürültü bekleyin. Bu, onların belirttiği zaman çizelgesidir, çiftin bir kusuru değil. İnsan incelemesi döngüde kalır. Greptile, birleştirme düğmesi değil, otomatikleştirilmiş ilk geçiştir.

Bir Greptile yorumu, ajanın aşama 1’de hiç sorgulamadığı bir dosyaya işaret ediyorsa, bu yararlı bir sinyaldir. Ya harita bir çağıranı kaçırdı ya da ajan bir alıntıyı atladı. Taslağı yoruma göre düzeltin. İnceleyiciyi devre dışı bırakmayın.

Bu tamamlayıcılığı dürüst tutmanın yolu

Maguyva her zaman önce. Yanlış dosyalı bir PR’ın incelenmesi, yine de yanlış dosyanın incelenmesidir.
Greptile her zaman sonra. İyi alıntılanmış bir taslak, yine de tüm sistem düzeyinde bir diff okumasına ihtiyaç duyar.
Maguyva’dan PR yorumları yayınlamasını istemeyin. Bunu yapmaz.
Greptile’dan, hâlâ bir yol seçerken ajanın ilk getirme katmanı olmasını istemeyin. Bu, GitHub veya GitLab uygulamasının bağlı olduğu iş değildir.
Onları ‘senkronize eden’ bir bash hattı uydurmayın. PR arayüzdür.
Her iki tarafı da bağımsız olarak doğrulayın. Zaten bildiğiniz bir repoyu indeksleyin. Doğrulayabileceğiniz bir soru sorun. Sonra küçük bir PR açın ve Greptile’ın gerçekte ne yorumladığını okuyun.

Bir isim verildiğinde döngü sıradan hale gelir. Önce harita. Sonra ajanın PR’ı. Sonra inceleme. Her ürün, iyi olduğu pull request tarafında kalır.

// map first. review second. in that order.

Yerel bir indeksleyici olmadan bir yapay zeka ajanına büyük bir reponun bağlamını verme

Fri, 14 Aug 2026 00:00:00 GMT

Büyük bir repo bir bağlam penceresine sığmaz ve eğer dizüstü bilgisayar indeksleyicisini gerçek bir monorepoya yönelttiyseniz, oraya da rahatça sığmadığını bilirsiniz — RAM fırlar, ilk indeksleme bir saat sürer ve ajanınız yine de bir sonraki oturuma hangi dosyaların önemli olduğunu tahmin ederek başlar.

Olağan cevap, editörün yanında bir indeksleyici çalıştırmaktır ve bir makineye rahatça sığan bir repo için bu iyi bir cevaptır. Monoreponuz Cursor’da zaten hızlıca indeksleniyorsa ve haritaya ihtiyaç duyduğunuz tek yer orasıysa, bu yazının ekleyecek bir şeyi yok — atlayın.

Bu yazı diğer durumla ilgili — bir ajanın büyük bir reponun sorgulanabilir bir haritasına ihtiyaç duyduğu ve bunu elde etmek için yerel bir indeksleyici çalıştırmak istemediğiniz zaman.

Yerel bir indeksleyicinin yanlış araç olduğu durumlar

Yerel bir indeks, kodun onu sorgulayan makinede yaşadığını varsayar ve gerçek monorepo ölçeğinde bu varsayım tek bir editör içinde bile gerilir. Repo, dizüstü bilgisayarda ‘sıcak’ tutmak istediğinizden basitçe daha büyüktür: etki yarıçapı üç dizin ötedeyken bir paket üzerinde çalışıyorsunuzdur ve iki milyon satırlık bir ağacın ilk soğuk indekslemesi iki kez katlanmak isteyeceğiniz bir şey değildir — ne kendi makinenizde, ne de o ağacı daha önce hiç klonlamamış bir CI çalıştırıcısında. Ya da bir takım arkadaşının, kendi makinesinin aynı indeksten geçmesini beklemeden sizinle aynı haritayı sorgulayabilmesi gerekir.

Bunların hiçbiri iyi bir editör indeksleyicisini çöpe atmak için bir neden değil. Bu, herhangi bir ajanınızın MCP üzerinden sorgulayabileceği barındırılan bir haritaya da sahip olmak için bir neden.

Ve ölçek sorunu ‘yapıştırmak için çok fazla dosya’ olmasından daha derine iner. Büyük bir ağaçta ilginç soru neredeyse hiçbir zaman ‘bana bu dosyayı göster’ değildir — hangi dosya, hangi sembol, hangi çağıranlar, hangi testler olduğudur. src/’ı listeleyerek başlayan ve ilk üç sonucu okuyan bir ajan, apps/api’deki işleyiciyi ve packages/sdk’deki oluşturulan istemciyi neşeyle gözden kaçıracaktır. İhtiyacınız olan şey, tüm ağaçtan oluşturulmuş, sonra sıralanmış, sonra alıntılanmış bir getirmedir.

‘Büyük bir reponun bağlamı’ gerçekte ne anlama gelir

Dosyaları prompta boşaltmak bağlam değildir — ağacın daha küçük, daha kötü bir kopyasıdır. Ajanınızın gerçekten ihtiyacı olan şey, sorular sormak ve karşılığında alıntılanmış yanıtlar almaktır: bu sembol nerede tanımlanmış ve onu kim çağırıyor, değiştirmek üzere olduğum modüle ne bağlı, hangi test dosyası bu davranışı kapsıyor ve ağaç geçen çeyrek değil, şu anda nasıl görünüyor.

Bu yanıtların, modelin başkalarının reposu hakkındaki hafızasından değil, sizin reponuzdan oluşturulmuş bir indeksten gelmesi gerekir ve indeksin ajanın bağlam penceresi dışında bir yerde yaşaması gerekir. Bu sorun için, dizüstü bilgisayarınızın da dışında bir yerde yaşaması gerekir.

Talimat dosyalarının sizin için yapamayacağı bir şey daha: CLAUDE.md ve AGENTS.md kurallar ve davranış için doğru yerdir, ancak iki milyon satırlık bir ağacın canlı, sıralanmış, sorgulanabilir bir haritası değildirler. Davranış için kurallar kullanın; gerçekler için repo zekası kullanın.

Haritayı bulutta inşa ediyoruz, herhangi bir istemciden sorguluyoruz

Maguyva, uzak bir MCP kod tabanı bağlam katmanıdır. GitHub’ı bağlarsınız, repolarınızı seçersiniz ve bulut hatları ağacı ayrıştırırken, sembolleri ve graf kenarlarını oluştururken ve sıralanmış bir haritayı korurken çekip gidebilirsiniz — asla yerel bir indeksleyici olmadan.

Kod push ettiğinizde, değiştirilen dosyalar artımlı olarak ayrıştırılır ve graf ile sıralama katmanları bir programa göre yeniden oluşturulur: ücretsiz planda günlük, ücretli planlarda saatlik. Her anlık görüntü zaman damgalıdır, böylece ajanınız ağacın hangi sürümünü okuduğunu söyleyebilir. Buradaki dürüst sınırlama, senkronize edilmemiş yerel çalışmadır — yalnızca çalışma ağacında var olan, hiç push edilmemiş bir değişiklik henüz barındırılan haritada değildir.

Sonra, zaten kullandığınız herhangi bir istemciye MCP yapılandırmasına bir API anahtarı ekleyerek bağlanırsınız. 24 belgelenmiş MCP istemcisi için kurulum kılavuzları vardır ve standart yapılandırmayı destekleyen başka herhangi bir MCP uyumlu istemci de bağlanabilir. Cursor evinizse, Cursor sayfası o yolu izler; aynı sunucu Claude Code, VS Code, Windsurf, Codex CLI ve diğerlerine yanıt verir.

Editör değiştirmezsiniz. Ajanınıza bir araç yüzeyi verirsiniz — arama, semboller, bağımlılık analizi, dosya getirme ve repo bağlamı genelinde 11 MCP aracı — 279’dan fazla dil ve metin tabanlı teknoloji üzerinde kapsama sahip, ki bu, yıllar önce tek bir dil olmaktan çıkmış bir monorepoda sandığınızdan daha çok şey ifade eder.

Yanıtlar, satır numaralarıyla dosya yolları olarak temellendirilmiş şekilde döner. Semantik, yapısal, graf ve metin araması sıralanmış sonuçlarda birleştirilir, böylece ‘parseConfig’e ne bağlı’ gibi bir soru size ne bir grep dökümü ne de tek bir semantik parça verir, gerçekten önemli olan o bir avuç yeri verir.

Somut bir kılavuz

Tüm şirketi indeksleyerek başlamayın. İşe yarayan yol şu:

Zaten iyi bildiğiniz bir repo seçin — elle değerlendirebileceğiniz bir paket, sahip olduğunuz en büyük ağaçtan daha değerlidir.
Ücretsiz başlayın: 3 repo, 50 bin indekslenen satır, 11 aracın tamamı, aylık sorgu kotası yok. Temsili reponuz bundan büyükse, fiyat sayfası çalışma alanı katmanlarını (0 $, 19 $, 49 $, 149 $) koltuk sayısına göre değil, indekslenen kapsama göre listeler.
GitHub’ı bağlayın ve ilk indekslemenin bitmesini bekleyin. Yerel olarak hiçbir şey derlemiyorsunuz.
MCP istemcisini bağlayın — birkaç satır yapılandırma. Maguyva uzak bir MCP sunucusudur, bu yüzden eklenti yok, uzantı yok ve benimsenecek ikinci bir editör yok.
Doğrulayabileceğiniz bir soru sorun. ‘parseConfig’e ne bağlı?’ veya ‘Oturum açma oturumunun süresi dolması nerede işleniyor?’ Sonra alıntılanan file.ext:line sonuçlarını açın ve karşınızdaki ağaçla karşılaştırın.
Alıntılar bu temasta hayatta kaldıktan sonra ajanın düzenlemesine izin verin.

İlk repo iyi uyuyorsa ve ağacınız büyükse, çalışma alanını indekslenen satırlarınıza ve yeniden oluşturma sıklığına uyacak şekilde yükseltin. İnsanlar ve ajanlar aynı kullanıcı sayısını paylaşır — Maguyva koltuk başına değil, çalışma alanı başına ücretlendirir — bu yüzden döngüye üçüncü bir ajan eklemek size hiçbir şeye mal olmaz.

Etkinleştirme testi, belgelerin her ilk çalıştırma için önerdiğiyle aynıdır: zaten bildiğiniz bir repoyu indeksleyin, doğrulayabileceğiniz bir soru sorun. Büyük bir repo testi değiştirmez; sadece yanlış bir ilk dosyayı daha maliyetli hale getirir.

Bağlandıktan sonra dikkat edilmesi gerekenler

Üç şeye dikkat edin. Güncellik: ücretli planlar saatlik, ücretsiz planlar günlük yeniden oluşturulur ve push edilmemiş yerel çalışma haritada olmayacaktır — bu, kabul ettiğiniz ödünleşimdir. Kapsam: arşivlenmiş her fork’u değil, temsili bir repo kümesini indeksleyin; ücretsiz katman, yanıtların saklanmaya değip değmediğini öğrenmek için kasıtlı olarak bu boyuttadır. Ve doğrulama: yolları ve satır numaralarını alıntılayamayan büyük bir repo haritası, sadece daha yavaş bir tahmin motorudur, bu yüzden ajanınızın yamayı teslim etmeden önce yeri göstermesini sağlayın.

Sonra küçük bir repoda çalıştıracağınız aynı testi çalıştırın. Zaten bildiğiniz bir repoyu indeksleyin. Doğrulayabileceğiniz bir soru sorun. Harita gerçekse, ajanınız soğuk bir ağaçtan başlamayı bırakır.

// no laptop got hot building this map.

Yapay zeka kodlama ajanınız neden dosya yollarında halüsinasyon görür

Fri, 14 Aug 2026 00:00:00 GMT

İşaret, yanlış bir fonksiyon gövdesi değildir. Var olmayan bir dosyada ya da var olan ama davranışı uygulayan dosya olmayan bir dosyada yapılan kendinden emin bir değişikliktir.

Oturum süresi dolması için bir düzeltme istediniz. Ajan src/auth/session.ts’ı açtı. Bu yol makul. Aynı zamanda yanlış. Gerçek işleyici, iki refaktör önce yeniden adlandırılan apps/api/src/middleware/expiry.ts’de yaşıyor. Ajan size yalan söylemedi. Eğitim önyargıları artı bağlam penceresinde zaten olan her şeye dayanarak yol biçiminde bir dizeyi tamamladı.

Bu, gerçek bir repoda görülen yaygın başarısızlık modelidir. Model kod yazabilir. Hata, onu yazmak için yanlış yeri seçmektir.

Ajanların neden yollar uydurduğu

Kodlama ajanı, araçlara sahip bir sonraki token tahmin modelidir. ‘Oturum süresi dolmasını düzelt’ dediğinizde, bir şey okuyabilmeden veya yamalayabilmeden önce bir dosyayı adlandırmalıdır. Zaten temellendirilmiş bir haritası yoksa, bir yolu şunlardan inşa eder:

Diğer repolarda gördüğü adlandırma kuralları. src/auth/session.ts sık görülen bir biçimdir.
Zaten konuşmada olan, şu anda önemli olanlar değil de geçen hafta yapıştırdıklarınıza ait olabilecek dosyalar.
Rastlantısal olarak çalıştırdığı, büyük bir ağaçta eksik olan dizin listelemeleri.
Talimat dosyaları. CLAUDE.md ve AGENTS.md, ajana nasıl davranması gerektiğini söyler. Bunlar sembollerin, çağıranların veya güncel yolların canlı bir indeksi değildir.

Bu kaynakların hiçbiri bugün bu reponun bir haritası değildir. Model, herhangi bir boşluğu doldurduğu şekilde bu boşluğu doldurur: yüksek olasılıklı bir devamla. Bu devam çoğu zaman gerçek bir yol gibi görünür. Bazen dosya vardır ve doğru olanın yanında yer alır. Bazen geçen ay birleştirilmiş bir dalda vardı. Bazen hiç var olmadı.

Ajan doğru dizeyi hiç aramıyorsa, grep burada sizi kurtarmaz. Ajan bir yol tahmin etti, sonra o yolun döndürdüğünü okudu, sonra onu düzenledi. İlk yanlış adım yoldu, yama değil.

Dosyaları okumak da doğru olanları bulmakla aynı şey değildir. Claude Code, Cursor, Codex ve benzer araçlar, onları yönelttiğiniz her şeyi açabilir. Soru, düzenlemeden önce doğru dosyaları, önemli sembolleri, bağımlılıkları, testleri ve etki yarıçapını güvenilir bir şekilde bulup bulmadıklarıdır. Bir harita olmadan dosya erişimi yine de bir tahminle başlar.

Yanlış dosyanın düzenlenmesi bir getirme sorunudur

Uydurulmuş yola bir karakter kusuru olarak değil, bir getirme isabetsizliği olarak davranın.

Ajan düzenlemesine izin verilmeden önce path/file.ext:line’i döndürmek zorunda olsaydı, iki şey olurdu. Birincisi, alıntıyı açıp işi on saniyede reddedebilirdiniz. İkincisi, ajanın ağacı gerçekten bilen bir şeyi sorgulaması gerekirdi.

Bu, bir kod tabanı bağlam katmanının işidir. Tek başına semantik arama yeterli değildir. ‘Oturum süresi dolması gibi görünen’ bir parça yine de kullanımdan kaldırılmış bir pakette bitebilir. Dizeyi bildiğinizde tam metne, adı bildiğinizde sembol aramasına, şekli bildiğinizde yapısal aramaya ve çağıranlara ile etki yarıçapına ihtiyaç duyduğunuzda bir bağımlılık grafına da ihtiyacınız vardır.

Maguyva, MCP uyumlu kodlama ajanları için bu katmandır. Bir editör değildir. Claude Code, Cursor, Codex CLI, VS Code, Windsurf ve diğer MCP istemcileri oldukları yerde kalır. Ajan, bir satıra dokunmadan önce sıralanmış bir haritayı sorgular.

İddia kasıtlı olarak mütevazıdır: daha az halüsinasyon görülen değişiklik. Maguyva, modelden tahmin etme yeteneğini almaz. Varsayılan ilk adımı ’makul bir yol uydur’dan ’sıralanmış, alıntılanmış konumlar iste’ye değiştirir.

Temellendirilmiş bir yanıt neye benzer

‘Oturum süresi dolması nerede işleniyor’ sorusuna faydalı bir yanıt bir paragraf değildir. Kısa bir konum listesidir:

apps/api/src/middleware/expiry.ts:48 - işleyici
apps/web/src/lib/auth-client.ts:112 - çağıran
apps/api/tests/expiry.test.ts:20 - değişiklik yanlışsa başarısız olacak test

Bu satırları açabilirsiniz. Yanlışlarsa durursunuz. Doğrularsa, ajan düzenleyebilir. Mesele doğrulamadır, bir slogan değil.

Maguyva, arama, semboller, bağımlılık analizi, dosya getirme, repo bağlamı ve deterministik yardımcı araç iş akışları genelinde 11 müşteriye yönelik MCP aracı sunar. Dört getirme modu (semantik, yapısal, graf/bağımlılık ve metin) sıralanmış sonuçlarda birleştirilir; sembol arama ayrı bir MCP aracıdır (find_symbol). Temellendirilmiş yanıtlar dosya yolları ve satır numaralarıyla döner, böylece karşınızdaki ağaca göre onları değerlendirebilirsiniz.

Belgeler en kısa yolu tanımlar: ücretsiz başlayın, zaten bildiğiniz bir repoyu indeksleyin, istemciyi bağlayın, sonra doğrulayabileceğiniz bir soru sorun.

İlk değişikliği değiştiren bir döngü

Yeni bir iş akışı dinine ihtiyacınız yok. İlk yazmadan önce bir ek adıma ihtiyacınız var.

Zaten değerlendirebileceğiniz bir soru sorun. ‘Girişi ve oturum süresi dolmasını hangi kod işliyor?’ sorusu ‘auth’u düzelt’ demekten daha iyidir.
Alıntı talep edin. ’Auth modülü’nün bir özeti değil, dosya yolu ve satır numarası.
Alıntılanan dosyaları açın. Sembolü takip edin. Dokunmak üzere olduğunuz bağımlılığı doğrulayın.
Ancak o zaman ajanın yamalamasına izin verin.

Adım 2 faydalı bir şey döndürmezse, ajanın bir yolu doğaçlama yapmaya hakkı yoktur. Ya yeniden arar ya da siz ona yol gösterirsiniz. Tam olarak bu tek geçit, daha az halüsinasyon görülen değişikliği üretir. Model aynı modeldir. Değişen şey haritadır.

Talimat dosyaları hâlâ önemlidir. Onları koruyun. Kurallar, inceleme kuralları ve dokunulmaması gerekenler için kullanın. Onlardan indeks olmalarını istemeyin. Üç önemli dizini listeleyen bir CLAUDE.md, bir paket bölünmesinden bir hafta sonra eskimiş olacaktır. Sorgulanabilir bir harita, repo güncellendiğinde güncellenir.

İlgili bir başarısızlık neredeyse doğru dosyadır: davranış auth-client.ts’de yaşarken ajan auth.ts’i açar ya da kaynak yerine oluşturulmuş bir dosyayı yamalar ya da ad eşleştiği için packages/legacy’teki kopyayı düzenler. Alıntılar bu hataları imkansız kılmaz. Diff inmeden önce onları görünür kılar.

Bir haritanın sizin için çözmeyeceği şeyler

Ne elde ettiğiniz konusunda ayık olun. Temellendirilmiş bir harita her değişikliği doğru yapmaz — ajanınız yine de tam olarak doğru dosyada kötü bir yama yazabilir. Kod tabanınız dinamik gönderime, yansımaya veya monkey-patching’e dayanıyorsa, bazı sembol aramaları istediğinizden daha zayıf dönecektir, çünkü çalışma zamanı dolaylılığı herhangi bir statik indekse bunu yapar. Ve bir yüzde umuyorsanız — ‘halüsinasyon görülen yollar X% azaldı’ — bunu burada bulamazsınız, çünkü sizden başka kimse bu sayıyı reponuz için dürüstçe ölçemez.

Beklemeniz gereken şey daha dar ve daha faydalıdır: ajan, değişikliklerine tahmin edilmiş bir yolla başlamayı bırakır. Bu ilk adım gerçek bir haritada temellendirilir ve daha az halüsinasyon görülen değişiklikler oradan gelir. Alıntıdan sonraki her şey — diff’i okumak, yamayı yargılamak — hâlâ, her zaman olduğu gibi, sizin işinizdir.

Bu test size neredeyse hiçbir şeye mal olmaz: zaten bildiğiniz bir repoyu indeksleyin ve doğrulayabileceğiniz bir soru sorun. Daha önce yanmış olduğunuz bir yolla başlayın. Alıntılar yanlışsa, bunu hemen görürsünüz. Doğrularsa, ajanınızın bir sonraki değişikliğinin inecek daha iyi bir yeri olur.

// it doesn't know the file. it knows how to find it.

Kod Aramasını voyage-4-large'a Neden Yükselttik

Tue, 09 Jun 2026 00:00:00 GMT

Bu yazıdaki kıyaslama sayıları, yayınlandığı tarihteki (Haziran 2026) RTEB liderlik tablolarını yansıtır. Liderlik tabloları değişir; sıralamaları kalıcı bir gerçek değil, bir anlık görüntü olarak ele alın.

Semantik arama, altındaki gömmeler kadar iyidir.

Bir ajan Maguyva’ya “yeniden denemeleri nerede ele alıyoruz” diye sorduğunda, “retry” kelimesini grep’lemiyordur. Anlamı soruyordur — geri çekilme (backoff) döngüsünü, devre kesiciyi, kararsız bir çağrıyı sarmalayan şeyi. Bu soru, kodu uzayda bir noktaya dönüştüren ve komşularını bulan bir vektör modeli tarafından yanıtlanır. Daha iyi bir model seçin ve üründeki her semantik sorgu sessizce daha keskinleşir.

Bu yüzden bizimkini değiştirdik. Haziran 2026 itibarıyla, Maguyva’nın kod gömmeleri voyage-code-3’in yerini alan voyage-4-large üzerinde çalışıyor.

Kıyaslama

Bu kararı sezgiyle vermedik. Herkese açık Retrieval Embedding Benchmark (RTEB), gömme modellerini gerçek getirim görevlerinde sıralar ve Code liderlik tablosunda voyage-4-large, gemini-embedding-2-preview’ün (90.26) önünde ve dikkat çekici bir şekilde zaten kullandığımız modelin, voyage-code-3’ün (89.73, #3), önünde genel sıralamada #1’de (90.86) yer alır.

Bu küçük, mutlak bir farktır. Ama herkese açık bir kıyaslamada, tam olarak önemsediğimiz görevde — kodu anlamıyla getirmek — doğru yönde bir farktır.

Kabul Ettiğimiz Ödünleşim: İkili Nicemleme

İşte çoğu “modelimizi yükselttik” yazısının atladığı kısım.

Maguyva tam hassasiyetli vektörleri saklamaz. İkili nicemlenmiş (binary-quantized) gömmeleri saklarız: her 2048 boyutlu vektör, 2048 bitlik bir imzaya sıkışır — vektör başına 256 bayt. Bu imzalar Hamming mesafesiyle aranır, kiracı başına indekslenir ve bölümlenir.

Bu kasıtlı bir ödünleşimdir. İkili nicemleme, dramatik derecede daha küçük depolama ve ayrı bir vektör veritabanı işletmeden hızlı, ucuz mesafe matematiği karşılığında bir miktar getirim hassasiyetinden vazgeçer. Çalışma alanı başına tüm repoları indeksleyen bir ürün için, bu ekonomi, kıyaslama puanını son bir kesir kadar daha artırmaktan daha önemlidir.

voyage-4-large, depolama katmanının bir geçişini zorlamadan bu tasarıma uyar: voyage-code-3 ile aynı şekilde 2048 boyutlu çıktı üretir, bu yüzden bit(2048) sütunlarımız ve Hamming arama yolumuz değişmedi. Model daha iyi oldu; şema yerinde kaldı.

Kod Sadece Başlangıçtı

Maguyva bir kod zekası aracıdır. Ama biz de sıfırıncı müşteriyiz ve onu başka bir şeye yönlendiriyoruz: repolarımızda kodla birlikte yaşayan markdown. Mimari karar kayıtları, operasyon kılavuzları (runbook), sözleşmeler, finans ve politika belgeleri — hepsi Git’te sürüm kontrollü, hepsi aynı MCP sunucusunun arkasında, sadece kaynak üzerinde değil belgeler üzerinde semantik bir indeks.

Voyage-4-large’ın genişliğinin önemli olmasının tam nedeni budur. Aynı RTEB liderlik tabloları ailesinde finansta #1, sağlıkta #1 ve genel metin getiriminde #1’dir — Google’ın Gemini Embedding’inin, Cohere’in Embed v4’ünün ve OpenAI’ın text-embedding-3-large’ının önünde. (Voyage, RTEB’in bir ortak yaratıcısıdır, bu yüzden bunu tamamen tarafsız bir hakem yerine güçlü bir kamusal sinyal olarak okuyoruz — ama özel tutulan (hold-out) veri kümelerinde her büyük ticari modele karşı baş başa kıyaslanmıştır.) Bir ajan için doğru fonksiyonu bulan aynı indeks, bir sözleşmedeki doğru maddeyi veya bir politikadaki doğru satırı da bulur — ve bu alanlarda voyage-4-large bir uzlaşma değildir, liderdir.

Neden Premium Gömmelere Ödeme Yapıyoruz

Arama yapmanın daha ucuz bir yolu var ve bunun çoğu ücretsiz. Sözcüksel arama — BM25 ve benzerleri — anahtar kelimeleri eşleştirir, yerel olarak çalışır ve hiçbir şeye mal olmaz. BGE, Nomic ve embeddinggemma gibi açık kaynaklı gömme modelleri gerçekten makul semantik getirim sağlar ve bunları bir GPU fiyatına kendiniz barındırabilirsiniz. Maguyva ücretsiz tarafı da kullanır: her sorgu metin, AST, graf ve semantik aramayı birleştirir. Ucuza kaçmadığımız şey semantik katmandır.

Ücretsiz bir modeli kendimiz barındırmak yerine premium gömmeler için token başına ödeme yapıyoruz — voyage-4-large — iki nedenden dolayı. Birincisi, kod backoff ve circuit breaker dediğinde ve asla “retry” kelimesini söylemediğinde, tek başına anahtar kelime araması “yeniden denemeleri nerede ele alıyoruz” sorusunu yanıtlayamaz — anlam, gömmenin tüm meselesidir ve hizmet ettiğimiz alanlarda açık modeller premium olanların gerisinde kalır: genel metinde birkaç puan geride, kod, sözleşmeler ve finans gibi niş alanlarda daha da geride. İkincisi, deneyimimize göre getirim kalitesi, nihai yanıtı diğer uçtaki modelden daha fazla şekillendirir — yanlış bağlam verilen güçlü bir ajan yine de yanlış yanıt verir ve kendisine hiç verilmemiş bir belgeyi asla görmez.

Yani premium gömmeler, indekslediğimiz her repo ve belgeyle ölçeklenen token başına bir faturadır — ve bunu kasıtlı olarak ödüyoruz. Kullanıcılarımızın elde ettiği sonuç, doğru fonksiyon veya doğru madde için, bu ödünleşimin buna değdiğini düşünüyoruz.

Dürüst Kısım

Voyage’ın kendi dokümantasyonu hâlâ voyage-code-3’i kod için optimize edilmiş model olarak etiketliyor. Peki neden geçtik?

Çünkü sadece tedarikçinin model tablosunu değil, herkese açık kıyaslamayı okuduk ve kıyaslama kod getiriminde voyage-4-large’yi zirveye koydu. Bu ileriye dönük bir karardı: daha yeni, genel olarak daha güçlü modeli alıp önemli görevlerde herkese açık bir liderlik tablosuna karşı doğrulamak. Bu bahsi yapmakta rahatız çünkü kanıt geniş — voyage-4-large sadece kodda kazanmıyor, finansta, sağlıkta ve genel getirimde de öne geçiyor.

Sessiz Taban

Sunduğumuz her araç — semantik arama, görev bağlamı toplama, temellendirilmiş soru-cevap — sonunda getirime dayanır. Getirici iyileştiğinde, diğer uçtaki ajan daha iyi kanıt alır, daha az yanlış yola sapar ve yanıtlarını doğru koda — ya da doğru maddeye, ya da doğru politikaya — dayandırır. Daha keskin bir gömme modeli gösterişli bir özellik değildir. Her şeyin altındaki tabandır ve biz onu az önce yükselttik. Fark etmeyeceksiniz. Asıl mesele de bu.

Dilde Özyinelemeli Öz-İyileştirme: ~280 Dilde Kod Zekasını İnceden İnceye Cilalamak

Tue, 26 May 2026 00:00:00 GMT

Bu yazıdaki sayılar, yayınlandığı tarihteki (Mayıs 2026) sistemi yansıtır. Güncel rakamlar için ekip sayfamıza bakın.

Maguyva, yaklaşık 280 dilde kaynak koddan sembolleri, referansları ve bir bağımlılık grafını çıkarır. Her dil özel bir tree-sitter handler’ıdır — sorgular, sezgisel yöntemler, uç durumlar — ve her handler kendine özgü bir şekilde ince bir hata yapabilir. Okuma olarak yayınlanan bir metot çağrısı. Yanlış çevreleyen kapsama atfedilen bir fonksiyon. Sadece orada olmayan bir ilişki.

Bunu elle denetleyemezsiniz. Hiçbir ekip 280 gramer genelinde çıkarım çıktısını okuyup kötü kenarları (edge) tespit edemez. Bu yüzden ilginç soru “çıkarımımız doğru mu” değildir — “her döngüde bir insan olmadan, bu genişlikte, yanlış olduğunu nasıl anlarsınız“dır. Bizim yanıtımız dilde özyinelemeli öz-iyileştirmedir: dil ajanları tarafından yürütülen bir kalite döngüsü, hakem görevi gören bir LLM ve sürekli yeniden öğrendiğimiz tek bir kural: yeşil, doğru ile aynı şey değildir.

Yeşil, doğru değildir

Her dilin bir fixture takımı vardır ve bir yayın öncesi doğrulama kontrolü bunu beş boyutta puanlar — doğruluk, yapısal bütünlük, eksiksizlik, kalite ve performans. Bir dil yalnızca fixture’larında kesinlik (precision) ≥ 0.95, duyarlılık (recall) ≥ 0.99 ve F1 ≥ 0.97 olduğunda, istatistiksel güven için en az 20 beklenen kenarla birlikte YEŞİL olur. Bunun altında SARI veya KIRMIZI olur ve yayınlanmaz.

Bu kontrol gereklidir ama yeterli değildir. Fixture’lar, bizim yazdığımız fixture’lara karşı doğrulanır. Zaten düşündüğümüz durumları kodlarlar. Bir handler kendi fixture’larında kusursuz olabilir ve yine de yalnızca gerçek kodda ortaya çıkan bir deseni bozabilir — bir makro deyimi, generic sınırlı bir metot, kimsenin fixture yazmadığı bir dil özelliği. YEŞİL, fixture’ların geçtiği anlamına gelir. Gerçek bir reponun temiz bir şekilde çıkarıldığı anlamına gelmez. Bu yüzden döngünün fixture’ları geride bırakıp vahşi doğaya bakması gerekir.

İç döngü: örneklem denetimi, hakemlik, düzeltme, kanıtlama

Çekirdek döngü, bir seferde bir dil çalıştırır:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

Bunun debelenmek yerine işe yaramasını sağlayan birkaç şey var.

Hakem bir API çağrısı değil, ajandır. “Hakem olarak LLM” dediğimizde, dil ajanının kendisinin örneklenen her kenarı gerçek kaynağa karşı okuduğunu ve sabit beş kategorili bir rubrikle sınıflandırdığını kastediyoruz: bu kenar doğru mu, yanlış pozitif mi, yanlış türle doğru ilişki mi, yanlış kapsama mı bağlı, yoksa yanlış meta veri mi taşıyor? Bu rubrik oyunun tamamıdır — “%23 hata oranı”, bunların gerçek kusurlar mı yoksa hakemin yanlış saymasından mı kaynaklandığını bilene kadar anlamsızdır.

Tek bir şeyi düzelt, sonra kanıtla. Her yineleme tam olarak bir düzenlenebilir varlığı değiştirir, ardından sabit bir test düzeneğine karşı yeniden çalışır ve değişikliği yalnızca F1 iyileşirse ve yeniden sınıflandırma daha iyi görünürse tutar. Öyle değilse, geri alınır. Spekülatif düzenlemelerden oluşan bir grup yok, “daha iyi olmalı” yok. Bir değişiklik yerini hak eder ya da gider. Ve bir düzeltme kalıcı olduğunda, fixture takımına terfi ettirilir — böylece düzelttiği hata bir daha asla sessizce geri gelemez. Bu terfi adımı, döngüyü sadece tekrarlayıcı değil özyinelemeli yapan şeydir: her geçiş, bir sonraki geçişin karşı doğrulama yaptığı doğrulama referansını (oracle) güçlendirir.

Sürekli yeniden öğrendiğimiz ders: metrikler fazla raporlar

İşte tuzak, ve biz doğrudan içine düştük. İkincil derlem metrikleri — çıkarılan bir hedefin ne sıklıkla çözülebilir bir sembolü olmadığı, kaç sembolün “öksüz” göründüğü ve benzerleri — sorunları büyük ölçüde fazla raporlar. Bunlar çoğunlukla hata değil, programlama paradigmasının doğal sonuçlarıdır.

En temiz örnek: llvm bir keresinde %73’lük bir “sembolsüz kaynak” oranı gösterdi ve felaket olarak damgalandı. Derinlemesine inceledik. Gerçek doğruluk %98,5’ti. “Eksik sembollerin” neredeyse tamamı meşru dış referanslardı — standart kütüphaneye, çerçevelere, repo dışında yaşayan koda yapılan çağrılar. Metrik, handler’daki bir kusuru değil, dilin bir özelliğini ölçüyordu. Zig, COBOL ve Odin gibi diller %65-70 “öksüz” oranı gösterir ve tamamen doğrudur; COBOL’da hiç gerçek hata yoktu.

Eğer bu sayıların işi yönlendirmesine izin verseydik, haftaları zaten doğru olan handler’ları “düzeltmekle” harcar ve sessiz, gerçek hataları olan dilleri görmezden gelirdik. Sonuç açık: toplu metrikler en iyi ihtimalle kaba bir triyaj sinyalidir. Gerçek kalite sinyali, kenar sınıflandırmasıyla yapılan örneklem denetimidir — gerçek repolardaki gerçek kenarlara bakmak ve onları tek tek yargılamak. Sezgiden çok veri, ama ancak hangi verinin gerçeği söylediğini bildiğinizde.

Dış döngü: bir maraton değil, bir filo

Bir seferde bir dil, 280 dilin tamamında sonsuza kadar sürerdi, bu yüzden iç döngü, birçoğunu paralel çalıştıran bir dış döngüye sarılır.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

Her ajan, birbirlerinin ayağına basmamaları için tek kullanımlık bir worktree’de çalışır. Orkestratör, düzeltmelerini birer birer, her biri tam manifest regresyon kontrolünün arkasında entegre eder: kendi dilinde yardımcı olan ama sessizce üç diğerini bozan bir değişiklik uygulanmaz. Entegrasyon, herhangi bir şey gönderilmeden önce kontrol edilir ve onaylanır — regresyon kontrolü neyin güvenli olduğuna karar verir, neyin yayınlanacağına hâlâ bir insan karar verir. Ardından havuz bir sonraki dil kümesine döner ve her şey yeniden çalışır.

Hâlâ kusurlu olan

Hakem yanılabilir ve yanılmanın bir yönü vardır: çok az bağlamla çalışan bir ajan fazla raporlar. Bir grupta, sekiz dil %5-20 hata ile işaretlendi; incelemede yalnızca biri gerçek bir dile özgü hataydı — geri kalanı dilin kendi anlambilimini kaçırmaktan kaynaklanan hakem hatalarıydı (bir kaynak satırının meşru şekilde birden fazla kenar yayınlaması, atama olarak modellenen parametre bağlamaları, tanımlayıcı başına referans veren diller). Bu yüzden iki tohumla örnekliyor ve çapraz kontrol yapıyoruz ve bu yüzden hakem ile fixture’lar arasındaki bir anlaşmazlık, kesinleşmiş bir hüküm değil en ilginç sinyal olarak ele alınır — bazen yanlış olan şey fixture’ın kendisidir.

Hedef konusunda da dürüstüz. Amaç, tam anlamıyla sıfır gerçek hatadır — ama “sıfır”, dil dil inceden inceye cilaladığımız bir yöndür, işaretlenip geçilen bir kutu değil. Her zaman başka bir deyimle başka bir repo vardır.

İddia Edilmiş Değil, Kazanılmış

Maguyva’nın bir ajan için yaptığı her şey — bir sembol bulmak, bir bağımlılığı izlemek, alıntılanan kodla bir soruyu yanıtlamak — altındaki çıkarımın doğru olmasına dayanır. 280 dil genelinde, “doğru” iddia edilemez; gerçek koda karşı sürekli kazanılması gerekir. Döngü, bunu kazanma şeklimizdir: kendi metriklerine şüpheyle yaklaşan, her değişikliği kanıtlayan ve her düzeltmeyi bir sonraki regresyona karşı bir koruma haline getiren otonom bir örneklem denetimi ve düzeltme döngüsü. Göz alıcı değil. “Dilinizi destekliyoruz” deyip bunu gerçekten kastetmemizi sağlayan iştir. Yeşil kolaydır. Doğru kazanılır.

Çok Modlu Füzyon Arama: Her Sorgu için Doğru Getiriciyi Seçmek

Wed, 15 Apr 2026 00:00:00 GMT

Geçmiş tasarıma ilişkin not: Nisan 2026 tarihli bu makale, o dönemdeki yönlendirme tasarımını açıklar; güncel varsayılan davranışı değil. Aşağıdaki Eylül düzeltmesi yalnızca bir ölçüm iddiasını ele alır. Güncel yönlendirme, hazır ayarlar ve açık modalite kontrolleri için Nasıl çalışır sayfasına bakın.

Bir arama sorgusu tek bir şey değildir.

“parseConfig nerede tanımlanmış” tam bir sembol ister — tek, kesin bir konum, hızlıca. “kimlik doğrulama nasıl çalışıyor” anlam ister — bir kavramı açıklayan ilgili kodun yayılımı. “bu fonksiyonu değiştirirsem ne bozulur” bağımlılık grafını ister. “ECONNREFUSED dizesini bul” tam bir eşleşme ister, akıllı bir numara değil.

Grep, tam eşleşmeler için mükemmeldir ve bazı referans aramaları için yararlıdır, ama bir bağımlılık grafı değildir ve anlamı anlamaz. Gömme (embedding) vektörleri semantik tarafı kapsar, ama tam dizeler ve etki analizi için yanlış araçtır. Çoğu kod arama aracı tek bir motor seçer ve her sorguyu bu seçimle yaşamaya zorlar. Maguyva seçmez. Sorulan sorunun türünü çözer, sonra dört getiriciyi o sorunun hak ettiği oranda harmanlar.

Dört modalite

Kaputun altında kod bulmanın dört bağımsız yolu vardır:

semantic — Voyage ikili gömmeleri üzerinden vektör araması; kodu anlamıyla bulur.
text — trigram eşleştirme; tam dizeleri, hata mesajlarını, tam tanımlayıcıları bulur.
structural — AST sorguları; tanımları, imzaları ve dil yapılarını bulur.
graph — bağımlılık grafı; çağıranları, çağrılanları ve etki yarıçapını bulur.

Her biri farklı bir soru sınıfında güçlüdür. Zor olan kısım, karşınızdaki sorgu için her birine ne kadar güveneceğinize karar vermektir.

Niyet sınıflandırması

Herhangi bir getirim çalışmadan önce, hafif bir sınıflandırıcı sorguyu bir güven puanıyla birlikte altı niyetten birine ayırır. Kasıtlı olarak ucuzdur — sıralı sezgisel yöntemler, ilk eşleşme kazanır — çünkü yoğun yolda çalışır ve sadece bir iki milisaniye ekler:

def , class , func , import ile başlar… → find_definition (güven 0.95)
“who calls”, “usages of”, “references to” → find_references (0.90)
“impact”, “blast radius”, “what depends on” → impact_analysis (0.90)
tırnaklı bir "string" veya traceback gibi bir hata belirteci → exact_match (0.85–0.90)
bir CamelCase veya snake_case tanımlayıcısı → find_definition (0.60–0.80)
“how”, “why”, “explain”, “architecture” → understand_code (0.75)
hiçbiri eşleşmez → understand_code, düşük güven (0.40)

Her niyet, dört modalite genelinde bir ağırlık profili taşır. Bunlar gerçek sayılardır:

Niyet	semantic	text	structural (AST)	graph
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

Yani “parseConfig nerede tanımlanmış” AST’ye ağır bir şekilde dayanır (0.6). “kimlik doğrulama nasıl çalışıyor” semantik vektörlere dayanır (0.5). “buna ne bağımlı” neredeyse tamamen graf’tır (0.7). “ECONNREFUSED bul” neredeyse tamamen trigram’dır (0.9), gömme modeli tamamen devre dışı bırakılmış olarak — çünkü semantik benzerlik, tam bir dize için tam olarak yanlış araçtır.

Hızlı yol ve birleşik arama yolu

Sınıflandırıcı emin olduğunda — puan ≥ 0.85 — ve sorgu normal bir sorguysa, Maguyva füzyonu tamamen atlar ve doğrudan baskın tek modaliteye yönlendirir. “X nerede tanımlanmış”, dört getiriciye ihtiyaç duymaz; şu anda AST indeksine ihtiyaç duyar. Bu doğrudan yol fusion_strategy: "direct" olarak geri raporlanır.

Belirsiz olan her şey füzyondan geçer. Dört (veya varsayılan ön ayarda üç) modalite paralel çalışır, her biri kendi sıralı listesini döndürür ve biz bunları birleştiririz.

Ağırlıklı Reciprocal Rank Fusion

Heterojen getiricileri birleştirmek göründüğünden zordur: 0,82’lik bir kosinüs benzerliği, 137’lik bir trigram puanı ve 0,004’lük bir graf merkeziliği aynı ölçekte değildir, bu yüzden bunları toplayamazsınız. Reciprocal Rank Fusion, ham puanları atıp yalnızca her motorun atadığı sıralamayı tutarak sorunu bertaraf eder. Bir sonucun tek bir modaliteden gelen katkısı şudur:

contribution = weight × 1 / (k + rank + 1)

burada rank o modalitenin listesindeki konumudur ve k bir yumuşatma sabitidir. Katkılar, birden fazla motorun bulduğu herhangi bir sonuç için modaliteler arasında toplanır — getiricilerin üzerinde uzlaştığı sonuçlar doğal olarak üst sıralara çıkar. Varsayılan ön ayarda k = 40, thorough’te ise 60 kullanırız (quick yalnızca semantik çalışır, bu yüzden füzyon orada hiç devreye girmez). Orijinal RRF çalışması genel amaçlı getirim için k = 60’ta karar kıldı; biz varsayılan olarak biraz daha keskin bir değer kullanırız, bu da modaliteler arasındaki üst sıralardaki ortak sonuçlara biraz daha fazla ağırlık verir — ve bunu elle ayarlamanızı önermiyoruz.

Bunun üzerine, sonuçlar bir graf önem artışı taşır. Bir merkez (hub) — tüm kod tabanının dayandığı bir fonksiyon — aynı metinsel alaka düzeyinde bile az bilinen bir yaprak düğümünü geride bırakmalıdır, bu yüzden her katkıyı şununla çarparız:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

Merkezilik, hattın önceden hesaplanmış PageRank/derece metriklerinden gelir ve artış 1,5 kat ile sınırlandırılmıştır, böylece popüler bir fonksiyon daha alakalı ama az bilinen bir fonksiyonu tamamen gömemez. Son olarak, vendor, build ve arşiv yollarından gelen sonuçları geriye düşürürüz ve dosya başına en iyi parçaya göre tekilleştiririz.

Hâlâ kusurlu olan

Niyet sınıflandırıcı, eğitilmiş bir model değil, bir düzenli ifade yığınıdır. Yaygın sorgu biçimlerini sezgisel yöntemlerle işler; belirsiz bir sorgu ise understand_code ve semantik ağırlıklı bir karışıma yönelir. Bu yazının önceki bir sürümünde sonuçsuz sorgu oranının yaklaşık %15’ten %5’in altına düşürülmesi gerçekleşmiş bir iyileşme olarak anlatılmıştı. Oysa Aralık 2025 tarihli öneri, tahmini bir başlangıç değeri ve bir hedef içeriyordu; destekleyici bir sorgu kümesi veya ölçüm kaydı sunulmamıştı. İyileşmenin sağlandığına ilişkin bu iddiayı geri çekiyoruz; kaynak kanıtlara ve düzeltmeye (İngilizce) bakın. Sınıflandırıcıyı eğitilmiş bir modelle değiştirmedik; çünkü düşük maliyetli sürüm, amaçlanan yönlendirme görevi için hızlı ve yeterince iyi, ayrıca yanlış ama kendinden emin bir sınıflandırıcı dürüst bir yedek yöntemden daha kötü. Ağırlıklar, toplamadığımız tıklama verilerinden öğrenilen değerler değil, elle seçilmiş önsel değerlerdir.

Aracı Değil, Soruyu Sorun

Bir ajanın grep’e mi, gömmelere mi, yoksa çağrı grafına mi başvuracağını bilmesi gerekmemeli — sorusunu düz bir dille sormalı ve doğru yanıtı almalı. Çok modlu füzyon, find_symbol’in, semantik aramanın ve bağımlılık analizinin tek bir sorgu yüzeyinin arkasında oturmasını sağlayan şeydir: sistem sorunun biçimini okur ve sessizce onun için doğru getiriciyi bir araya getirir. Gömmeleri puanlayan model önemlidir, ama onları ne zaman kullanmayacağını bilmek de önemlidir. Her sorgu için doğru aracı seçmek kendi başına bir kalite türüdür ve bunu çağırana devretmek yerine sahiplenmeyi tercih ederiz.

// you bring the question. it brings the tools.

Ajan Gözlemlenebilirliği: Hook'lar, Alloy ve Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Ajan sistemleri tuhaf şekillerde başarısız olur.

Bazen sorun modeldir. Bazen sorun araçtır. Bazen MCP sunucunuz gayet iyidir, ama ajan yanlış uzmanı seçmiştir, ya da oturumun yarısını beklemediğiniz kabuk (shell) işleriyle geçirmiştir, ya da dışarıdan üretken görünen bir döngüde sessizce maliyet yakmıştır.

Farkı göremiyorsanız, gerçekten bir ajan sistemi işletmiyorsunuzdur. Tahmin yürütüyorsunuzdur.

Bu yüzden kendi iş akışımız için bir gözlemlenebilirlik yığını kurduk: Claude Code, Codex, Claude hook olayları, Codex notify olayları, yerleşik OpenTelemetry, Grafana Alloy ve diğer uçta Grafana Cloud.

İlginç kısım “bir gösterge paneli yaptık” değil. İlginç kısım, tek bir akış bize tüm resmi vermediği için telemetriyi iki farklı akışa bölmek zorunda kalmamız.

Sorun: Ajan Telemetrisi Parçalanmış Durumda

Modern kodlama ajanları zaten biraz telemetri yayınlıyor. Bu yardımcı oluyor, ama yeterli değil.

Yerleşik OTEL şu tür soruları yanıtlamakta iyidir:

Kaç istek yaptık?
Bir oturuma ne kadar maliyet oluştu?
Span’ler ve trace’ler nerede?
Gecikme sıçradı mı?

Şu tür soruları yanıtlamakta çok daha kötüdür:

Ajan hangi MCP sunucusuna dayandı?
Bu hata Bash’da mı, yerleşik bir dosya aracında mı, yoksa bir MCP çağrısında mı oldu?
Hangi beceri (skill) gerçekten etkinleşti?
Hangi alt ajan türü görevlendirildi?
Oturum yararlı bir iş mi yapıyordu, yoksa sadece debelenip mi duruyordu?

Bu ikinci soru sınıfı, trace’lerden çok hook’lara yakın yaşar.

Ama tersi de doğrudur: en önemli performans sorularından bazıları hook’lardan çok trace’lere yakın yaşar.

Gecikmenin gerçekte nerede biriktiğini, hangi span’lerin yavaş olduğunu ya da oturumun zamanı model çağrılarında mı yoksa araç yürütmede mi harcadığını bilmek istiyorsanız, semantik olayların yanı sıra trace verisine de ihtiyacınız var.

Sonunda Vardığımız Mimari

İki telemetri yolunu yan yana çalıştırıyoruz.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Bu ayrım kasıtlıdır.

Ayrıca asimetriktir. Claude Code bize çok daha zengin bir yaşam döngüsü hook yüzeyi sağlar. Codex bize yerleşik OTEL artı bir notify yüzeyi sağlar; bu yüzden iki çalışma zamanının aynı kontrolleri sunduğunu varsaymak yerine, daha az ayrıntı içeren tur tamamlama olaylarını aynı günlük şemasına normalize ederiz.

Yerleşik OTEL bize temel akışı verir: çalışma zamanının kendisinden gelen günlükler ve trace’ler, artı çalışma zamanının gerçekten yaydığı metrikler.

Hook ve notify olayları bize semantik katmanı verir: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated gibi şeyler ve ajan davranışını hata ayıklarken gerçekten önemsediğimiz sınıflandırılmış meta veriler. Claude Code burada daha zengin olay akışına katkıda bulunur. Codex daha az ayrıntılı ama yine de yararlı, normalize edilmiş bir akışa katkıda bulunur.

Hook’lar Neden Var Olsun Ki

Hook hattımız, olaylar Loki’ye ulaşmadan önce onları zenginleştirir.

Sadece “bir araç çalıştı” demek yerine, olayı şu tür alanlara sınıflandırırız:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: hangi MCP arka ucunun çağrıyı işlediği
bash_cli: kabuk komut ailesi
subagent_type: ne tür bir uzmanın görevlendirildiği
agent_tool: kaynağın Claude Code mu yoksa Codex mi olduğu

Bu, operasyonel olarak önemli sorular sorabileceğimiz anlamına gelir:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Bunlar gösterişlik alanlar değildir. “Ajan yavaş hissettirdi” ile “ajan son on dakikayı yüksek araç başarısızlık oranına sahip, kabuk ağırlıklı git işlemlerinde geçirdi” arasındaki farktır.

Olduğundan daha garip görünen bir uygulama ayrıntısı: paylaşılan Loki akışı, olay Codex’ten gelse bile etiket olarak hâlâ service_name="claude-code-hooks"’yi kullanır. Çalışma zamanları arasındaki gerçek ayrım agent_tool üzerinde gerçekleşir.

Alloy Neden Ortada Duruyor

Grafana Alloy bu kurulumda sadece bir yönlendirici değildir. Politika sınırıdır.

Claude Code ve Codex’ten gelen yerleşik OTEL akışını localhost:4318 üzerindeki yerel bir Alloy proxy’sine yönlendiririz, ardından Alloy’un yükü Grafana Cloud’a iletmeden önce temizlemesine izin veririz.

Bu önemlidir çünkü ham ajan telemetrisi, analiz için yararlı ama indekslenmiş etiketler olarak berbat olan yüksek kardinaliteli alanlarla doludur:

session_id
prompt_id
token sayıları
süreler
araç parametresi blob’ları

Her şeyi indekslerseniz, bir etiket patlaması ve kötü bir gün yaşarsınız.

Bu yüzden Alloy bizim için üç şey yapar:

Çok küçük bir düşük kardinaliteli etiket kümesini indekslenmiş tutar.
Gürültülü ama yararlı alanları yapılandırılmış meta veriye taşır.
Saf gürültüyü tamamen düşürür.

Önemli fikir basittir: daha fazla gözlemle, daha azını indeksle.

Hook Akışı Neden Alloy’u Atlıyor

Hook akışı zaten Loki için şekillendirilmiştir.

send_event.py bir olayı gönderdiğinde, hangi alanların etiket muamelesini hak ettiğine ve hangilerinin yapılandırılmış JSON gövdesine ait olduğuna zaten karar vermişizdir. Bu akış, Alloy’dan tekrar geçmek yerine doğrudan Grafana Cloud’un OTLP ağ geçidine gider.

Yani sistemin net bir iş bölümü vardır:

Alloy ham yerleşik OTEL akışını evcilleştirir.
Hook zenginleştirmesi semantik olayları sorgulanabilir kılar.

Bu, her şeyi tek bir yoldan geçirmeye zorlamaktan daha basit bir mimari sağlar.

Gösterge Paneli Gerçekte Neyi Gösteriyor

Aşağıdaki ekran görüntüsü, ajan iş akışımızın arkasındaki gözlemlenebilirlik gösterge panellerinden birine ait. Bu bir kıyaslama değildir ve sayılar sadece belirli bir andaki bir dilimdir. Önemli olan verinin biçimidir: etkinlik akışı, araç çağrıları, başarısızlıklar, istemler ve ajana, yerleşik araçlara, MCP kullanımına, kabuk komutlarına ve becerilere göre dökümler.

Yararlı olan kısım, bu gösterge panelinin ajan telemetrisinin geri kalanıyla aynı Grafana yığınında yaşamasıdır. Kaynak ajana ve araç ailesine göre filtreleyebilir ve her sistem için farklı bir gözlemlenebilirlik hikayesi icat etmeden çalışma zamanları arasında bakabiliriz.

Ajan iş akışımızın arkasındaki canlı gösterge panellerinden biri. Bu ekran görüntüsü, diğer ajan çalışma zamanlarımızdan ve sistemlerimizden de telemetri alan paylaşılan bir Grafana yığınının yalnızca bir dilimidir. Tam çözünürlüklü sürüm için görsele tıklayın.

Trace’ler Neden İlk Göründüğünden Daha Önemli

Günlükler bize ne kategoride bir iş olduğunu söyler. Trace’ler bize işin zaman içinde nasıl geliştiğini söyler.

Bu ayrım ajan sistemlerinde önemlidir çünkü “yavaş” yararlı olamayacak kadar kabadır.

Bir trace, sıkıntının şuradan gelip gelmediğini söyleyebilir:

model gecikmesi
araç yürütme süresi
tekrarlanan yeniden denemeler
özellikle maliyetli tek bir MCP etkileşimi
tek başına zararsız görünen küçük işlemlerin uzun bir kuyruğu

Pratikte hook akışını ve Tempo trace’lerini birlikte kullanıyoruz.

Hook günlükleri şunu yanıtlar: ne tür bir şey oldu?
Trace’ler şunu yanıtlar: zaman nereye gitti?

Bu kombinasyon, gözlemlenebilirliği bir gösterge panelinden bir açıklamaya dönüştüren şeydir.

Codex Nereye Oturuyor

Codex aynı yığının bir parçasıdır, ama Claude Code ile özdeş değildir.

Codex için iki parçayı bağlarız:

Codex’ten Alloy’a yerleşik OTEL
Tur tamamlamalarını hook olayları için kullandığımız aynı Loki şemasına eşleyen codex_notify.py’e bir notify webhook’u

Bu bize aynı günlük akışı içinde agent_tool="codex-cli" gibi birleşik bir filtre sağlar.

Dürüst çekince şu: Codex’in notify yükü şu anda Claude Code’un hook yükünden daha az ayrıntı içerir, çünkü aynı türde bir entegrasyon yüzeyi değildir. Bugünkü kurulumumuzda, Codex tur tamamlamaları paylaşılan şemaya normalize edilebilir, ama araç araç zengin çıkarım hâlâ notify köprüsünden çok yerleşik OTEL akışında daha iyidir.

Bu, yazıyı yazmaktan kaçınmak için bir sebep değildir. Yazının asıl noktası tam da budur. Gerçek gözlemlenebilirlik sistemleri kusurlu sinyallerden bir araya getirilir.

MCP Üzerinden Grafana Oyunu Değiştiriyor

Daha büyük değişim, Grafana’nın sadece insanların bir tarayıcıda ziyaret ettiği bir yer olmamasıdır.

Bu repoda Grafana’yı MCP üzerinden de sunuyoruz. Bu, bir ajanın, bir insanın önce gösterge panellerini manuel olarak incelemesini beklemek yerine Loki’yi, Prometheus’u ve Tempo’yu doğrudan sorgulayabileceği anlamına gelir.

Bu, gözlemlenebilirliği iş akışına aktif bir girdiye dönüştürür.

Bir ajan şunu sorabilir:

Son bir saatte hangi araç aileleri en çok başarısız oldu?
Bir oturuma hangi MCP sunucusu hakim oldu?
Son değişiklikler araç başarısızlıklarını azalttı mı, yoksa işi aynı hatalarla daha kabuk ağırlıklı yollara mı taşıdı?
Hangi trace’ler en yüksek gecikmeyi veya tekrarlanan yeniden denemeleri gösteriyor?

Buna sahip olduğunuzda, kendi kendini geliştiren bir döngüye çok yaklaşmışsınızdır.

Gösterge Panelinden Geri Bildirim Döngüsüne

En ilginç bulduğumuz kısım bu.

Gözlemlenebilirlik yığını ajan katmanından sorgulanabilir hale geldiğinde, telemetri pasif bir raporlama yüzeyi olmaktan çıkıp bir kontrol sinyaline dönüşür.

Döngü şöyle görünür:

Ajan etkinliği trace’ler, metrikler ve zenginleştirilmiş hook günlükleri yayınlar.
Grafana, kanıtı Loki, Tempo ve metriklerin bulunduğu yerde Prometheus’ta saklar.
Ajanlar bu kanıtı Grafana MCP üzerinden sorgular.
Sistem, önlenebilir hatalar üretmeye devam eden kötü araç karışımını, kırılgan becerileri, zayıf yönlendirmeyi veya kabuk ağırlıklı iş akışlarını belirler.
Ajanlar veya operatörler istemleri, ajan yapılandırmalarını, beceri açıklamalarını, yönlendirme kurallarını veya araç erişimini ayarlar.
Bir sonraki oturum yeni bir telemetri biçimi üretir ve döngü tekrarlanır.

“İlginç gösterge paneli”nden “ölçülebilir iyileştirme sistemi”ne geçişin yolu budur.

Amaç bir araç kategorisini maksimize etmek değildir. Amaç, gerçekte yapılan iş için CLI, yerleşik araçlar, MCP çağrıları ve becerilerin doğru karışımına ulaşmaktır.

Bu Bize Neyi Yanıtlamamızı Sağlıyor

Her iki çalışma zamanı da aynı Grafana yığınına indiğinde, operasyonel sorulara çok daha hızlı yanıt verebiliyoruz:

Başarısızlıklar tek bir araç ailesinde mi yoğunlaşıyor?
Kabuk ağırlıklı iş akışları, daha üst seviyeli bir aracın var olması gereken yerlerde önlenebilir hatalar mı yaratıyor?
İş yükünü hangi MCP sunucuları taşıyor?
Anlamlı ilerleme üretmeyen ajan etkinliği için ödeme mi yapıyoruz?
Bir oturum model, araçlar veya orkestrasyon katmanı yüzünden mi sağlıksız?

Bu, “ajan meşguldü”nün size neredeyse hiçbir şey söylemediği çok ajanlı iş akışlarında özellikle yararlıdır.

Bir uzman sürekli görevlendiriliyor ve yüksek başarısızlık oranları üretiyorsa, bu bir yönlendirme veya istem şekillendirme sorunudur.

Bir MCP sunucusu tüm çağrılara hakimse, bu iyi bir mimari olabilir ya da geri kalan her şeyin gereksiz yük olduğunun bir işareti olabilir.

Maliyet yüksek kalırken araç başarısızlıkları sıçrıyorsa, bir kalite sorununuz değil, operasyonel bir sorununuz var demektir.

Kabuk işi, daha üst seviyeli bir aracın var olması gereken yerlerde tahmin edilebilir, önlenebilir şekillerde başarısız olmaya devam ediyorsa, bu bir ürün sinyalidir.

Bir beceri sürekli etkinleşiyor ama sonuçları iyileştirmiyorsa, bu bir istem veya yönlendirme sinyalidir.

Gerçek Ders

Buradaki daha derin ders, ajan gözlemlenebilirliğinin hem çalışma zamanı telemetrisine hem de iş akışı telemetrisine ihtiyaç duymasıdır.

Çalışma zamanı telemetrisi size sistemin ne yaptığını söyler.

İş akışı telemetrisi size ajanın ne yaptığını düşündüğünü söyler.

İkisine de ihtiyacımız var.

Sadece trace’leri ve sayaçları tutarsanız, semantik katmanı kaçırırsınız. Sadece hook olaylarını tutarsanız, gecikmeyi, span’leri ve daha geniş çalışma zamanı resmini kaçırırsınız.

Ve ikisini de tutar ama asla ajan katmanına geri beslemezseniz, izleme yaparsınız, adaptasyon değil.

Kombinasyon, sistemi işletmek için yeterince açıklanabilir ve iyileştirmek için yeterince ayarlanabilir kılan şeydir.

Hâlâ Kusurlu Olan Neler

Hâlâ pürüzler var.

Her hook olayı istediğimiz süre ve token verisini içermiyor.
En iyi zamanlama görünümlerinin bazıları hâlâ hook günlüklerinden değil, Tempo trace’lerinden geliyor.
Codex bugün, zenginleştirilmiş olay akışında Claude Code’dan daha az semantik zenginliğe sahip.
Gösterge paneli ekran görüntüsü, özenle hazırlanmış bir pazarlama görseli değil, canlı bir operasyon yüzeyidir.

Bu son nokta kasıtlıdır. Ajan sistemlerinin sihirli bir şekilde kendi kendini açıkladığını iddia etmek yerine, gerçek gösterge panelini göstermeyi tercih ederiz.

Bunun Maguyva İçin Neden Önemli Olduğu

Maguyva, ajanlara daha iyi kod zekası vermekle ilgilidir. Ama ajanlar gerçekten yararlı bir iş yapmaya başladığında, hemen yeni bir gereksinim ortaya çıkar: nasıl davrandıklarını görmeniz gerekir.

Arama kalitesi, yönlendirme kalitesi, araç seçimi ve bağlam verimliliğinin hepsi gözlemlenebilir sorunlar haline gelir.

Bu yüzden bunun yazmaya değer olduğunu düşünüyoruz. Geleceğin ajan yığını sadece istemler ve araçlar değildir. İstemler, araçlar ve tüm sistemin çalışıp çalışmadığını size söyleyen enstrümantasyon katmanıdır.

Ciddi ajan iş akışları inşa ediyorsanız, gözlemlenebilirlik isteğe bağlı bir altyapı değildir. Ürünün bir parçasıdır.

Değişikliklerden Bilgi Çıkarmak: Değişiklikler Kurumsal Hafızaya Nasıl Dönüşür

Tue, 03 Feb 2026 00:00:00 GMT

Bu yazıdaki sayılar, yayınlandığı tarihteki (Şubat 2026) sistemi yansıtır. Güncel rakamlar için ekip sayfamıza bakın.

Her mühendislik ekibi aynı zorlukla karşılaşır: değişiklikler sürekli olur, ama bu değişikliklerin arkasındaki neden kaybolur gider. Altı ay sonra biri “pipeline aşamaları için neden DuckDB’yi benimsedik?” diye sorar ve yanıt yalnızca o kararı verenin kafasında yaşar — hâlâ ortalardaysa.

Bu döngüyü kapatan bir madencilik iş akışı kurduk. Değişiklikler git commit’leri üzerinden akar, madencilik hattımız tarafından işlenir, yapılandırılmış değişiklik günlüğü girdilerine ve mimari karar kayıtlarına dönüşür, ardından CLI sorguları üzerinden yapay zeka ajanlarımıza geri beslenir. Sonuç: hem insanların hem de yapay zekanın erişebileceği kurumsal hafıza.

Sorun: Kararlar Buharlaşır

Tipik bir senaryo düşünün. Bir geliştirici şunu commit eder:

feat(canonical): add DuckDB runtime for pipeline stages

Bu commit önemli bir mimari seçimi temsil eder. Ekip seçenekleri değerlendirdi, ödünleşimleri (trade-off) göz önünde bulundurdu ve belirli nedenlerle DuckDB’de karar kıldı. Ama tüm o bağlam şurada yaşar:

Bir Slack konuşması (muhtemelen silinmiş)
Birinin hafızası (kesinlikle soluklaşan)
Koddaki bir yorum (belki, şanslıysanız)

Üç ay sonra, yeni bir ekip üyesi sorar: “Bu yeni aşama için DuckDB mi yoksa SQLite mi kullanmalıyım?” Kurumsal hafıza olmadan, ya tekerleği yeniden icat ederler ya da tutarsız seçimler yaparlar.

Döngü: Commit’lerden Bağlama

Madencilik iş akışımız git geçmişini sorgulanabilir bilgiye dönüştürür:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

Kilit içgörü: hem değişiklik günlükleri hem de mimari kararlar aynı git geçmişinden, birleşik bir hat üzerinden işlenerek akar. Bu, hiçbir şeyin gözden kaçmamasını sağlar.

Madencilik Nasıl Çalışır

Adım 1: İndeksi Senkronize Et

uv run orkestra mine sync

Bu komut git geçmişini tarar ve tüm commit’lerin bir indeksini oluşturur. Her commit’ten yapılandırılmış sinyaller çıkarır:

Conventional Commits türü (feat, fix, chore, docs)
Kapsam (hangi paket veya alan)
Geriye dönük uyumluluğu bozan değişiklik işaretleri
Dokunulan dosyalar ve karmaşıklık metrikleri

Adım 2: Kapsam Durumunu Kontrol Et

uv run orkestra mine status

Mevcut durumumuz şöyle görünüyor:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15.637 commit işlendi. 476’sı mimari karara dönüştü. 6.799’u değişiklik günlüğü girdisine dönüştü. Her commit sınıflandırıldı.

Adım 3: İnceleme İçin Adayları Al

uv run orkestra mine candidates --limit 50 --full

Bu, sınıflandırma için tam bağlamla birlikte henüz işlenmemiş commit’leri ortaya çıkarır:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

Sinyaller sınıflandırmaya rehberlik etmeye yardımcı olur: is_releasable_type: true bunun değişiklik günlüğünde görünmesi gerektiğini önerir. Büyük ekleme sayısı ve altyapı dosyaları, bunun bir mimari karar da olabileceğini önerir.

Adım 4: Commit’leri Sınıflandır

Burada iki yol ayrılır: değişiklik günlüğü girdileri ve mimari kararlar.

Değişiklik günlüğü girdileri için:

uv run orkestra mine classify abc123 --changelog added

Bu, abc123 commit’inin değişiklik günlüğünde “Added” kategorisi altında görünmesi gerektiğini kaydeder.

Mimari kararlar için:

Önce gerçek bir karar kimliği alın:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Ardından karar kimliğiyle sınıflandırın:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Bu, commit’i oluşturulacak veya güncellenecek bir karar kaydına bağlar.

Toplu işleme için (gerçekte yaptığımız şey):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

JSONL biçimi tek bir geçişte her iki alanı da destekler:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Adım 5: Çıktıları Render Et

uv run orkestra registry changelog render --package <pkg>

Bu, deftere dayanan pakete özgü CHANGELOG.md dosyaları üretir. Değişiklik günlükleri kayıtlardan üretilen çıktılardır — onları silin ve kaynak defterden kusursuz bir şekilde yeniden oluşurlar.

Karar Kaydı Yapısı

Çıkarılan kararlar, zengin meta veriye sahip YAML dosyalarına dönüşür:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Her karar, kaynak commit’lerine geri bağlanır. Her karar hangi dosyaları etkilediğini belirtir. Kararlar arasındaki ilişkiler açıktır.

CLI Entegrasyonu: Kurumsal Hafızayı Sorgulamak

Döngünün kapandığı yer burasıdır. Ajanlar CLI üzerinden kararları sorgulayabilir:

# Search by topic
uv run orkestra registry decisions search --query "retry"

Yeniden deneme mantığı, hata işleme, kurtarma desenleri hakkındaki kararları döndürür.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

Bağlam, gerekçe ve etkiyle birlikte tam karar kaydını döndürür.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

Son zamanlarda hangi mimari seçimlerin yapıldığını gösterir.

Ajanlar Bunu Nasıl Kullanıyor

Orkestratörümüzün temel talimatları şunları içerir:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

Bir ajandan DuckDB ile ilgili bir şey uygulaması istendiğinde, önce şunu kontrol edebilir:

uv run orkestra registry decisions search --query "DuckDB"

Ve DEC-PL-142’yi keşfedip şunları öğrenebilir:

Neden DuckDB’yi seçtiğimiz (context)
Nasıl doğru kullanılacağı (agent_guidance)
Hangi dosyalara bakılacağı (files)
Hangi ilgili kararların var olduğu (related)

Ajan tekerleği yeniden icat etmez. Yerleşik desenler üzerine inşa eder.

Üç Soru Testi

Her commit bir karar kaydını hak etmez. Filtrelemek için Üç Soru Testini kullanırız:

Bunu yapmak zor muydu? Önemli analiz, ödünleşim değerlendirmesi veya tartışma gerektirdi mi?
Değiştirmesi maliyetli mi? Bu kararı tersine çevirmek önemli bir yeniden çalışma gerektirir mi?
Sistem geneli bir etkisi var mı? Birden fazla paketi etkiliyor mu veya başkalarının izleyeceği desenler oluşturuyor mu?

Bir commit bu sorulardan en az birine “evet” yanıtı veriyorsa, karar çıkarımı için bir adaydır. Tipik oranımız: her 100 commit’te 1-4 karar (yaklaşık %1-4).

Değişiklik günlüğü girdileri için çıta daha düşüktür: kullanıcıya yönelik herhangi bir değişiklik (özellikler, düzeltmeler, iyileştirmeler) kaydedilir. İç işler, dokümantasyon güncellemeleri ve yeniden yapılandırmalar genellikle atlanır. Tipik oranımız: her 100 commit’te 30-50 değişiklik günlüğü girdisi.

Veri Depolama: Yalnızca Ekleme Defterleri

Madencilik sistemi, çakışmasız çok ajanlı işlem için yalnızca ekleme yapılan (append-only) JSONL defterleri kullanır:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

.gitattributes içindeki merge=union’a sahip JSONL biçimi, birden fazla ajanın birleştirme çakışması olmadan aynı anda commit’leri sınıflandırabileceği anlamına gelir. Her satır bağımsızdır.

Doğrulama Kontrolleri

Herhangi bir madencilik oturumundan önce doğrulama çalıştırırız:

uv run orkestra mine validate --quick

Bu şunları kontrol eder:

SHA biçimi geçerliliği
Karar kimliği biçimi uyumluluğu
Aynı SHA için yinelenen girdi olmaması
Referans verilen kararların gerçekten var olması

Sınıflandırmadan sonra, değişiklikleri commit etmeden önce tekrar doğrularız.

Bunun Neden Önemli Olduğu

Kurduğumuz geri bildirim döngüsü birkaç sorunu çözer:

Yeni ekip üyeleri için: “Neden X’i yaptık?” diye sormak yerine, karar kayıt defterini arayabilirler. Bağlam korunur.

Yapay zeka ajanları için: Boşlukta çalışmazlar. Öneride bulunmadan önce kurumsal bilgiyi sorgulayabilirler. Yeni bir pipeline aşaması eklemesi istendiğinde, DuckDB desenini keşfedip onu izleyebilirler.

Mimari tutarlılık için: Kararlar açık ve aranabilirdir. Biri mevcut bir kararla çelişen bir yaklaşım önerdiğinde, sistem çatışmayı gün yüzüne çıkarabilir.

Değişiklik günlüğü üretimi için: Yayın notları son dakika telaşı değildir. Geliştirme sırasındaki sürekli sınıflandırmanın bir yan ürünüdür.

Yeni ajanların işe alışması için: Yeni ajanlar kod tabanının tam bağlamını devralır. Yalnızca kodu görmezler — onu şekillendiren kararları da görürler.

Mevcut Durum

Bugün itibarıyla:

Hat üzerinden 15.637 commit işlendi
476 mimari karar çıkarıldı ve belgelendi
6.799 değişiklik günlüğü girdisi kaydedildi
Her iki alanda da %100 kapsam

Başladığımızdan beri her commit sınıflandırıldı. Kurumsal hafıza eksiksiz ve sorgulanabilir.

Başlarken

Benzer bir şey uygulamak isterseniz:

Conventional Commits biçimindeki commit’lerle başlayın. Madencilik hattı, commit’ler yapılandırılmış öneklere (feat:, fix:, chore:) sahip olduğunda en iyi şekilde çalışır.
Alanlarınızı tanımlayın. pipeline, agent-design, observability, data-modeling gibi alanlar kullanıyoruz. Bunlar kararları alana göre düzenler.
Sınıflandırma alışkanlığını oluşturun. Madencilik, ekipler commit’leri düzenli olarak sınıflandırdığında çalışır. LLM yardımıyla toplu işleme ölçeklenmeye yardımcı olur.
Kararları sorgulanabilir hale getirin. Değer, ajanlar kararları CLI üzerinden arayabildiğinde katlanarak artar. Çıktınızı makine tüketimi için yapılandırın.
Döngüyü kapatın. Kararlar gelecekteki işi etkilemelidir. Ajan talimatlarına ve kod inceleme kontrol listelerine karar referansları ekleyin.

Amaç kusursuz dokümantasyon değildir. Değişikliklerin arkasındaki nedeni, bugün ve altı ay sonra, hem insanlar hem de yapay zeka için erişilebilir kılmaktır. Değişiklikler kurumsal hafızaya dönüştüğünde, ekipler onları yeniden icat etmek yerine yerleşik desenler üzerine inşa eder.

Madencilik iş akışı, orkestrasyon motorumuzun bir parçasıdır; özellikle orkestrasyon paketimizdeki bağlam motoru modülüdür.

Beceri Madenciliği: 3.500 Adaydan 466 Yetkinliğe

Tue, 27 Jan 2026 00:00:00 GMT

Bu yazıdaki sayılar, yayınlandığı tarihteki (Ocak 2026) sistemi yansıtır. Güncel rakamlar için ekip sayfamıza bakın.

3.500 Beceri Sorunu

Bir ajan orkestrasyon sistemi inşa etmeye başladığımızda, ilginç bir zorlukla karşılaştık: yapay zeka ekosistemine dağılmış binlerce potansiyel beceri var. GitHub repoları, tedarikçi dokümantasyonu, topluluk projeleri, iç desenler — beceriler her yerde var. Ama hangileri önemli? Hangileri işe yarıyor? Ve ajanların gerçekten kullanabileceği tutarlı bir beceri kütüphanesini nasıl sürdürürsünüz?

Bizim yanıtımız: sistematik bir madencilik ve alım döngüsü.

Bugünün Sayıları

Anthropic’in Agent Skills’i 16 Ekim 2025’te piyasaya sürmesinden yalnızca üç ay sonra, bu yazı 27 Ocak 2026’da yayınlandığında durumumuz şöyleydi:

Ölçüt	Sayı
Belirlenen adaylar	3.500+
Benimsenen beceriler	466
Tedarikçi becerileri	373
İç beceriler	93
Aktif tedarikçiler	25+
Beceri başına ortalama token	2.834
Referans verilen araçlar	89
Benzersiz etiketler	635

3.500’den fazla beceri adayını inceledik. 466’sını benimsedik. Bu, %13’lük bir benimseme oranı — ve bu seçicilik tasarım gereğidir.

Bilgi Katman Sistemi

Tüm beceriler eşit yaratılmamıştır. Bunları, her biri farklı bir uygulanabilirlik kapsamını temsil eden beş bilgi katmanına (K0-K4) düzenliyoruz:

K0: Temeller (Evrensel)

Her ajanın sahip olması gereken beceriler. Bunlar her yerde işe yarayan “iyi düşünür” yetkinliklerini temsil eder.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

K0 becerileri herhangi bir projeye, herhangi bir alana, herhangi bir yığına taşınabilir. Evrensel bilişsel desenleri kodlarlar.

K1: Kimlikler (Disiplin)

Bir disiplin içindeki projeler genelinde geçerli olan “iyi mühendis” veya “iyi araştırmacı” becerileri.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Alanlar (Konu Uzmanlığı)

Bir alan içinde taşınabilir “iyi veritabanı uzmanı” veya “iyi güvenlik mühendisi” becerileri.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Yığınlar (Teknoloji)

Belirli teknoloji yığınları için “iyi Supabase kullanıcısı” veya “iyi Cloudflare geliştiricisi” becerileri.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Proje (Organizasyon)

Organizasyonumuza ve iş akışlarımıza özgü beceriler.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

Madencilik Döngüsü

Aşama 1: Keşif

Beceriler her yerden gelir:

Tedarikçi Repoları: AWS, Anthropic, Cloudflare, Supabase ve topluluk katkıda bulunanları beceri koleksiyonları yayınlar. 25’ten fazla tedarikçi kökünü takip ediyoruz.

Topluluk Projeleri: GitHub, Claude Code şablonları, ajan desenleri ve iş akışı tanımlarıyla doludur.

İç Desenler: Ekibimiz sorunları çözdükçe desenler ortaya çıkar. Bunlar becerilere dönüştürülerek resmileştirilir.

Dokümantasyon Madenciliği: Teknik dokümantasyon genellikle örtük beceriler içerir — prosedürler, kontrol listeleri, karar ağaçları.

Keşif süreklidir. Resmi değerlendirmeden önce adayları takip etmek için bekleyen beceri adayları listesi kullanırız.

Aşama 2: Değerlendirme

Her aday aynı rubrikten geçer:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Beş ürün kriterinin tamamı geçmelidir. Adayların %87’sinin reddedilmesinin nedeni budur.

Sonra her aday ayrı bir güven incelemesinden geçer. Resmi bir tedarikçi reposunu, iyi bilinen bir topluluk sürdürücüsünü ve rastgele bir GitHub reposunu eşdeğer gerçek kaynaklar olarak ele almayız.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

Güvenilen tedarikçiler daha hafif bir köken incelemesi alır, ama serbest geçiş almazlar. Güvenilmeyen veya bilinmeyen kaynaklar daha derin bir manuel denetimden geçer ve paket içindeki betikleri, okunup kapsamı belirlenip güvenli olarak sınıflandırılana kadar çalıştırmayız.

Boşluk Analizi: Benimsemeden önce, kayıt defterimizi ararız:

uv run orkestra skills search "<capability>"

Zaten sahipsek, ihtiyacımız yoktur. Yakın bir şeye sahipsek, benimsemek yerine birleştirebiliriz.

Derinlik ve Standartlar Puanlaması: Bir adayın ajan-beceri modelini ne kadar tam kullandığını da puanlarız. Tek başına bir SKILL.md yine de yararlı olabilir, ama daha derin beceriler, agentskills.io’in teşvik ettiği şekilde talimatları referanslardan, betiklerden ve varlıklardan ayırdığında daha değerlidir.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

GitHub yıldızları bir güvenilirlik puanını biraz yükseltebilir, ama yüzeysel veya güvensiz bir beceriyi asla kurtarmazlar. Belirsiz tek bir SKILL.md’ye ve opak betiklere sahip yüksek yıldızlı bir repo, tam beceri yetkinliğinden gerçekten yararlanan kesin bir açıklamaya, derlenmiş references/’e ve atomik yardımcılara sahip daha küçük bir reponun altında puan alır.

Yapısal Analiz: Beceri kalitesini kontrol ederiz:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Bir aday betikler içeriyorsa, bu inceleme daha sıkı hâle gelir. İyi bir beceri sadece yararlı olmakla kalmaz; bir ajana teslim edilmesi için okunabilir, sınırlı ve güvenli olması gerekir. Bu güvenlik filtresi tek başına, aksi takdirde ilginç olan adayların anlamlı bir dilimini eler.

Aşama 3: Alım

Bir beceri değerlendirmeyi geçtiğinde kayıt defterine girer. Ama beceriler asla değiştirilmeden benimsenmez. Sistemimize uyacak şekilde değiştirilirler.

Benimseme Sırasında Yapılan Değişiklikler:

Meta Veri Normalizasyonu: Her beceri, belge başındaki meta veri (frontmatter) şemamızı alır
K-Katman Ataması: Beceriler uygun bilgi katmanına yerleştirilir
Etiket Zenginleştirmesi: Keşif için etiketler eklenir
Araç Bildirimi: İzin verilen araçlar açıkça bildirilir
Bölüm Hizalaması: İçerik, şablonumuza uyacak şekilde yeniden yapılandırılır

Alımdan sonra tipik bir beceri YAML’ı:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Aşama 4: Kapsam Ataması

Beceriler kapsamlara atanır — hangi ajanların hangi becerileri yükleyeceğini belirleyen kategoriler:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Ajanlar kapsamlarını bildirir ve beceriler otomatik olarak atanır:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Aşama 5: Somutlaştırma

Beceriler üretimde YAML olarak yaşamaz. Claude Code’un yükleyebileceği SKILL.md dosyalarına render edilirler:

uv run orkestra sync

Bu komut:

Tüm beceri YAML tanımlarını okur
Bunları Jinja şablonları üzerinden render eder
SKILL.md dosyalarını .claude/skills/’e yazar
K-katmanına göre düzenler (foundations/, identities/, domains/, stacks/, project/)

Nihai çıktı yapısı:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

Uykuda Kapsam Deseni

En güçlü desenlerimizden biri “benimsenmiş ama yüklenmemiş” becerilerdir. Bunlara uykuda kapsamlar diyoruz.

k-dense-scientific reposundan bilimsel hesaplama becerilerini düşünün. Biyoinformatik, kimya, kuantum hesaplama ve klinik bilişimi kapsayan 120’den fazla beceri benimsedik. Ama ajanlarımızın çoğunun moleküler yerleştirmeye (docking) veya gen ifadesi analizine ihtiyacı yok.

120 becerinin tümünü her ajana yüklemek yerine (bağlam pencerelerini şişirmek), şunu yaparız:

Belirli bir kapsamla becerileri benimseriz (örneğin, bioinformatics)
Bunları uykuda tutarız — kayıtlı ama yüklenmemiş
Yalnızca bir ajan o kapsamı bildirdiğinde etkinleştiririz

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Bu desen, tipik ajanlar yalnızca 40-60 ilgili beceri yüklerken kayıt defterinde 466 beceriye sahip olmamızı sağlar.

Beceri Türleri

Beceriler üç bilişsel desende gelir:

İş Akışı

Sıralı prosedürel adımlar: “1. X’i yap, 2. Sonra Y’yi yap, 3. Son olarak Z’yi yap”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Disiplin

Davranış kuralları ve sınırları: “Her zaman X yap”, “Asla Y yapma”, “Z’yi tercih et”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Kontrol Listesi

Doğrulama kriterleri: “X’i onayla”, “Y’yi doğrula”, “Z’yi kontrol et”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Kalite Kontrolleri

Her beceri, yayınlanmadan önce doğrulamayı geçmelidir:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Açıklamalar, Claude Code’un ne zaman önereceğini bilmesi için tetikleyici ifadelerle (“Şu durumda kullanın…”, “İhtiyacınız olduğunda…”) birlikte 50-400 karakter olmalıdır.

Sürekli doğrularız:

uv run orkestra validate --show-warnings

Tedarikçi Ekosistemi

373 tedarikçi becerimiz şuralardan gelir:

Sağlayıcı	Beceriler	Alan
AWS Agent	19	Bulut hizmetleri
Anthropic	12	Doküman üretimi
Cloudflare	8	Uç bilişim
Supabase	5	Veritabanı
k-dense	100+	Bilimsel hesaplama
silvainfm	4	Veri bilimi
Java Developer Kit	45+	Spring/Java
Vercel	1	Tarayıcı otomasyonu

Her tedarikçi kökü metadata.yaml’da bildirilir:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

orkestra sync çalıştığında, tedarikçi becerileri sağlayıcı ad alanlarıyla birlikte .claude/skills/vendor/’e sembolik olarak bağlanır.

Öğrendiklerimiz

Seçicilik karşılığını verir. Yararlı görünen her şeyi benimsemek caziptir. Ama her beceri token’a mal olur. Beceri başına ortalama 2.834 token ile, şişkinlik hızla zarar verir. %13’lük benimseme oranımız ajanları yalın tutar.

Yapı keşfi mümkün kılar. K-katman sistemi sadece organizasyon değildir — taşınabilirlikle ilgilidir. K0 becerileri her yerde yeniden kullanılabilir. K4 becerileri kasıtlı olarak projeye özgüdür. Bu netlik, hem insanların hem de ajanların ihtiyaç duydukları şeyi bulmasına yardımcı olur.

Uykuda kapsamlar ölçeklenir. Yüzlerce beceriyi hepsini yüklemeden benimseyebilirsiniz. Kapsamlar, bireysel ajan bağlam pencerelerini yönetilebilir tutarken kapsamlı bir kayıt defteri inşa etmenizi sağlar.

Benimseme sırasında değişiklik gereklidir. Ham tedarikçi becerileri nadiren sisteminize uyar. Alım süreci — meta veri ekleme, katman atama, etiket zenginleştirme — dış becerilerin dahili olarak çalışmasını sağlar.

Madencilik süreklidir. 3.500 sayısı büyümeye devam ediyor. Yeni tedarikçi repoları ortaya çıkıyor. Topluluk desenleri beliriyor. İç iş akışları sağlamlaşıyor. Döngü asla durmuyor.

Sırada Ne Var

Birkaç iyileştirme üzerinde çalışıyoruz:

Otomatik boşluk tespiti: Yaygın ajan başarısızlıklarının benimsenmemiş bir beceriyle çözülebileceği durumlarda uyarı ver
Beceri kullanımdan kaldırma iş akışları: Yerine yenisi gelmiş veya kullanılmayan becerileri emekliye ayırmak için resmi süreç
Beceriler arası bağımlılıklar: Beceri ön koşullarının açık bildirimi
Kullanım analitiği: Ajanların hangi becerileri gerçekten çağırdığını, hangilerini sadece yüklediğini takip et

Beceri madencilik döngüsü altyapıdır. Göz alıcı değildir. Ama 41 ajanın, bağlam sınırları içinde kalırken 466 yetkinlikle tutarlı bir şekilde çalışmasını sağlayan şey budur.

3.500’ün 466’ya nasıl dönüştüğünün hikayesi budur. 3.000’i görmezden gelerek değil — onları sistematik olarak değerlendirip yalnızca işe yarayanı benimseyerek.

Beceri sistemini eylem hâlinde görmek mi istiyorsunuz? Mevcut kayıt defterimizi keşfetmek için uv run orkestra skills list’e göz atın.

Kademeli Açığa Çıkarma: Ajan Sistemlerine CLI Pencereleri

Tue, 20 Jan 2026 00:00:00 GMT

Bu yazıdaki sayılar, yayınlandığı tarihteki (Ocak 2026) sistemi yansıtır. Güncel rakamlar için ekip sayfamıza bakın.

Ajan sistemleri tasarım gereği opaktır. Karar verirler, araçları çağırırlar ve düzinelerce uzman genelinde işi koordine ederler. Ama bir şeyler ters gittiğinde — ya da sadece neler olduğunu anlamak istediğinizde — nereye bakarsınız?

Yanıt kademeli açığa çıkarmadır: tam olarak ihtiyacınız kadar karmaşıklığı, tam olarak ihtiyaç duyduğunuz anda ortaya çıkaran katmanlı bir arayüz.

Opaklık Sorunu

Modern bir ajan orkestrasyon sistemi şunlara sahip olabilir:

Her biri farklı yeteneklere sahip 40’tan fazla uzman ajan
İç otomasyonu ve tedarikçi entegrasyonlarını kapsayan 700’den fazla beceri
Davranışı şekillendiren 470’ten fazla mimari karar
Dış yetenekler sağlayan düzinelerce MCP araç sunucusu

Bu karmaşıklık kasıtlıdır. Ajanların iyi kararlar vermek için zengin bağlama — alan bilgisi, kod zekası, veritabanı şemaları — erişmesi gerekir. Ama aynı zenginlik bir görünürlük sorunu yaratır.

Hangi ajanın veritabanı geçişlerini ele aldığını nasıl bilirsiniz? Hangi kararlar arama sisteminin sıralama davranışını şekillendirdi? Mimari danışmanının hangi araçlara erişimi var?

Yapılandırılmış erişim olmadan, ya kaynak kodu okumak zorunda kalırsınız ya da dokümantasyonun güncel olmasını ummak zorunda kalırsınız.

Mimari Olarak Kademeli Açığa Çıkarma

Kademeli açığa çıkarma sadece bir arayüz deseni değildir. Bir mimari ilkedir: bilgiyi katmanlar hâlinde, her biri bir öncekinden daha derin olacak şekilde düzenleyin, böylece kullanıcılar sorularını yanıtlayan seviyede durabilir.

Ajan sistemleri için bu, artan derinliklerdeki CLI komutlarına dönüşür:

Seviye	Komut	Yanıtlanan Soru
1	`orkestra system status`	Her şey sağlıklı mı?
2	`orkestra agents list`	Hangi ajanlar var?
3	`orkestra agents info <name>`	Bu ajan ne yapıyor?
4	`orkestra decisions search`	Neden bu şekilde çalışıyor?
5	Maguyva MCP araçları	Bana kodu göster.

Her seviye doğal bir takip sorusunu yanıtlar. Nadiren doğrudan 5. seviyeye atlamanız gerekir.

Seviye 1: Sistem Sağlığı

İlk soru her zaman şudur: her şey çalışıyor mu?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Tek bir komut. Dört sayı. Sistemin yapılandırıldığını ve kayıt defterlerinin doldurulduğunu bilmek için yeterli.

Bir ajan sayısı beklenmedik şekilde düşerse veya beceriler yüklenemezse, bunu önce burada görürsünüz. Günlüklere dalmak gerekmez.

Seviye 2: Ajan Envanteri

Sistemin sağlıklı olduğunu bildikten sonra, bir sonraki soru şudur: neler mevcut?

$ orkestra agents list

Bu, yapılandırılmış veri döndürür — ajan adları, açıklamalar, model tercihleri, alan kapsamı. Çıktı varsayılan olarak JSON’dur, bu da filtreleme için jq’e yönlendirmeyi kolaylaştırır:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Veritabanı işini ele alan ajanlar mı istiyorsunuz? Arama komutu bunu daraltır:

$ orkestra agents search "database"

Bu, adları, açıklamaları ve yetenekleri tarar. 40 ajan tanımını okumadan doğru uzmanı bulursunuz.

Seviye 3: Ajan Derinlemesine İnceleme

İlgili görünen bir ajan mı buldunuz? info komutu her şeyi ortaya çıkarır:

$ orkestra agents info architecture-advisor

Çıktı şunları içerir:

Meta veri: Ad, kategori, model tercihi, açıklama
Alanlar: Bu ajanın hangi bilgi alanlarını kapsadığı
Kimlik: Karakter özellikleri (mimar, stratejist, bilgi mimarı)
Araç kılavuzları: Bağlama hangi araç dokümantasyonunun enjekte edildiği
Araçlar: Bu ajana açık olan MCP araçlarının tam listesi

İşte gördüklerinizin bir örneği:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Bu, ajanın tam olarak ne yapabileceğini size söyler. Kaynak kod gerekmez.

Seviye 4: Karar Arkeolojisi

Ajanlar, belgelenmiş kararlara göre davranır. Bir şeyin belirli bir şekilde neden çalıştığını anlamanız gerektiğinde, kararlar kayıt defteri gerçek kaynaktır.

$ orkestra decisions search "agent"

Bu, eşleşen mimari kararları döndürür:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Her kararın tam bir kökeni vardır — ne zaman alındığı, nedeni, hangi ödünleşimlerin göz önünde bulundurulduğu, hangi commit’lerin onu uyguladığı:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Bu, commit’lerden çıkarıldığı için güncel kalan, elle sürdürülmeyen mimari dokümantasyondur.

Seviye 5: Doğrudan Kod Zekası

Gerçek uygulamayı — hakkındaki meta veriyi değil — görmeniz gerektiğinde, Maguyva’nın MCP araçları doğrudan erişim sağlar.

Bir ajan oturumu içinden:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Bu, ilgili kodu bulmak için semantik, metin ve AST araması genelinde otomatik yönlendirme yapar. Belirli semboller için:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Bağımlılık analizi için:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Bunlar sadece grep yerine geçenler değildir. Graf yapısını dikkate alırlar, semantik olarak indekslenmişlerdir ve ajanların kendisine güç veren aynı kod zekasıyla entegredirler.

Kayıt Defterleri Genelinde Birleşik Arama

Bazen hangi kayıt defterinin yanıtı tuttuğunu bilmezsiniz. Birleşik arama her şeyi kapsar:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

Beş kayıt defteri genelinde 254 eşleşme. Özet size nereye derinlemesine ineceğinizi söyler. Ayrıntılı sonuçlar için --summary’yı kaldırın, ya da çıktıyı yönetilebilir tutmak için --limit 5 ekleyin.

Bunun Neden Önemli Olduğu

Kademeli açığa çıkarma sadece kolaylıkla ilgili değildir. Karmaşık sistemlerle nasıl etkileşim kurduğunuzu değiştirir.

Hata ayıklama yönetilebilir hâle gelir. Bir ajan beklenmedik bir karar verdiğinde, günlüklerde grep yapmazsınız. Hangi araçlara erişimi olduğunu (agents info), hangi kararların davranışını şekillendirdiğini (decisions search) kontrol edersiniz ve gerekirse uygulamayı izlersiniz (intelligent_search).

Yeni üyelerin işe alışması hızlanır. Yeni ekip üyelerinin tüm kod tabanını okumasına gerek yoktur. system status ile başlarlar, agents list ile keşfederler ve yalnızca anlamadıkları bir şeyle karşılaştıklarında daha derine inerler.

Dokümantasyon güncel kalır. CLI, ajanları yapılandıran aynı kayıt defterlerinden okuduğu için, çıktı her zaman doğrudur. Dokümanların söylediği ile sistemin yaptığı arasında sapma olmaz.

Arayüz Olarak CLI

Bir web gösterge paneli inşa edebilirdik. Kapsamlı dokümantasyon yazabilirdik. Bunun yerine, gerçek kaynaktan okuyan bir CLI inşa ettik.

CLI’nin avantajları vardır:

Bileşilebilir: Çıktıyı jq üzerinden aktarın, betiklerle entegre edin
Betiklenebilir: Kontrolleri otomatikleştirin, raporlar üretin
Hızlı: Sayfa yüklemesi yok, kimlik doğrulama akışı yok
Doğru: Önbelleğe alınmış bir temsili değil, gerçek yapılandırmayı okur

Doğruluğun estetikten daha önemli olduğu sistemler için CLI kazanır.

Kendi Kademeli Açığa Çıkarmanızı İnşa Etmek

Ajan sistemleri inşa ediyorsanız, kullanıcıların bunları nasıl inceleyeceğini düşünün:

Sağlık kontrolleriyle başlayın. Her şeyin çalışıp çalışmadığını söyleyen tek bir komut.
Envanter görünümleri sağlayın. Ne yaptığını açıklamadan önce nelerin var olduğunu listeleyin.
Hedeflenmiş sorguları etkinleştirin. Ölçekte arama, göz atmayı yener.
Kökeni açığa çıkarın. Kullanıcıların kararları kökenlerine kadar izlemesine izin verin.
Kod zekasına bağlanın. Sonunda, kullanıcıların uygulamayı görmesi gerekir.

Her katman bir takip sorusunu yanıtlar. Bunları sıklık sırasına göre inşa edin — çoğu kullanıcı 2. veya 3. katmanda durur. Yalnızca ileri düzey kullanıcılar 5. katmana ulaşır.

Amaç her şeyi açığa çıkarmak değildir. Amaç, tam olarak ihtiyaç duyulanı, tam olarak ihtiyaç duyulduğu anda açığa çıkarmaktır. Ajan mimarisine uygulanan kademeli açığa çıkarma budur.

Temel Gerçekler: Yapay Zeka Ajanlarını Gerçekliğe Sabitlemek

Tue, 13 Jan 2026 00:00:00 GMT

Bu yazıdaki sayılar, yayınlandığı tarihteki (Ocak 2026) sistemi yansıtır. Güncel rakamlar için ekip sayfamıza bakın.

Yapay zeka ajanları dikkat çekici derecede yeteneklidir. Akıl yürütebilir, sentezleyebilir ve üretebilirler. Ama temel bir zayıflıkları vardır: bir şeyler uydururlar. Kötü niyetle değil, ama kendinden eminlikle. Bir ajan var olmayan API parametreleri icat edebilir, hiç tanımlanmamış yapılandırmalara başvurabilir veya eğitim verisinden gerçek mimarinizle çelişen desenler uygulayabilir.

Standart çözüm “ajana daha fazla bağlam ver”dir. Ama bağlam çelişkili olabilir. Dokümantasyon uygulamadan sapar. Yorumlar yalan söyler. Niyeti anlamadan okunduğunda kod bile yanıltıcı olabilir.

Daha açık bir şeye ihtiyacımız vardı. Görmezden gelinemeyecek veya yanlış yorumlanamayacak bir şeye. Ajanları doğrulanabilir gerçekliğe sabitleyecek bir şeye.

Bunlara Temel Gerçekler diyoruz.

Bir Temel Gerçek nedir?

Bir temel gerçek, ajanların saygı göstermesi gereken açık, sürümlenmiş bir gerçek ifadesidir. Dokümantasyon değildir. Yorum değildir. Sistemde şunlara sahip birinci sınıf bir varlıktır:

Benzersiz bir tanımlayıcı (GT-MAG-015 veya GT-MAG-036 gibi)
Bir yaşam döngüsü durumu (güncel, geçici veya kullanımdan kaldırılmış)
Bir kapsam (platform geneli, pakete özgü veya alana bağlı)
Kanıt (ifadeyi kanıtlayan dosya yolları, URL’ler veya referanslar)
Ajan rehberliği (açık yap/yapma talimatları)

İşte Maguyva kod zekası platformumuzdan bir örnek:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Bu düz yazı değildir. Bir sözleşmedir. Bir ajan bu temel gerçekle karşılaştığında şunu bilir:

Varsayılan deterministiktir (bulanık tahminler değil, boş sonuçlar)
Tanımlanmış davranışlara sahip belirli parametreler vardır (find_similar, exact_match)
Doğrulanabilecek belirli dosyalarda kanıt vardır
İfade belirli bir tarihte doğrulanmıştır

Bir Temel Gerçek Kayıt Defterinin Anatomisi

Temel gerçekler, ai_assets/reference/ground_truths.yaml altındaki YAML kayıt defterlerinde yaşar. Her paket veya alan kendi kayıt defterine sahip olabilir. Yapı şöyledir:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

Kayıt defteri, koleksiyonun kendisi hakkında meta veriler, dokümantasyon üretimi için render yapılandırması ve ifadelerin kendisini içerir. Her ifade, Pydantic modelleri tarafından doğrulanan katı bir şemayı izler:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Ajanlar Temel Gerçeklere Nasıl Erişir

Temel gerçekler birden fazla kanal üzerinden sunulur:

1. Render Edilmiş Dokümantasyon

orkestra sync komutu, YAML kayıt defterlerini okunabilir markdown’a dönüştürür:

uv run orkestra sync

Bu, ajan bağlamına dahil edilen GROUND_TRUTHS.md dosyaları üretir. Render edilen çıktı, ifadeleri duruma ve kategoriye göre gruplar:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. CLI Araması

Kabuk erişimine sahip ajanlar, temel gerçekleri programatik olarak arayabilir:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

Arama fonksiyonu, birden fazla alan genelinde eşleşmeleri ağırlıklı alaka düzeyiyle puanlar:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Bağlam Kompozisyonu

Ajanlar YAML tanımlarından render edildiğinde, bağlamları temel gerçek kayıt defterlerine başvurabilir:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Bu, ilgili temel gerçeklerin ajan işe başlamadan önce yüklenmesini sağlar.

Temel Gerçek Kategorileri

Kayıt defterlerimize baktığımızda, temel gerçekler birkaç desende kümelenir:

Ürün İlkeleri

Ürünün ne olduğu ve ne olmadığı konusundaki kısıtlamalar:

“Maguyva, kullanıcı repoları açısından salt okunurdur; yeniden oluşturulamayan tek varlık ücretli gömme (embedding) önbelleğidir.” (GT-MAG-001)

Mimari Sınırlar

Sorumlulukların nerede yaşadığı ve nedeni:

“Pipeline ve Maguyva sınırları kasıtlıdır: pipeline yeniden kullanılabilirdir, Maguyva koda özgü mantığı tutar ve CQRS, aşama yazmalarını sunucu okumalarından ayırır.” (GT-MAG-006)

Halüsinasyon Karşıtı Kurallar

Araç sözleşmelerini çıkarımsal yerine deterministik tutan açık zorunluluklar:

“Bulanık sembol eşleştirme find_similar=true üzerinden isteğe bağlıdır. Varsayılan davranış, var olmayan semboller için boş sonuçlar döndürür; exact_match=true katı eşleştirmeyi zorunlu kılar ve tüm bulanık yedekleri devre dışı bırakır.” (GT-MAG-015)

Kalite Kontrolleri

Korunması gereken standartlar:

“Paylaşılan altyapıdaki değişikliklerin (post_filters.py, ilişki çıkarıcıları, paylaşılan handler’lar), commit’ten önce tam manifest üretimi yoluyla DESTEKLENEN TÜM dillere karşı doğrulanması ZORUNLUDUR. Tek dilli bir doğrulama, paylaşılan kod için yetersizdir.” (GT-MAG-036)

Kod Desenleri

Uygulama gereksinimleri:

“Asenkron bağlamlarda CPU ağırlıklı işler için asyncio.to_thread() kullanın; kullanımdan kaldırılan loop.run_in_executor() deseni yeni kodda kullanılmamalıdır.” (GT-MAG-018)

Bir Temel Gerçeğin Yaşam Döngüsü

Temel gerçekler statik değildir. Tanımlı bir yaşam döngüsü boyunca evrilirler:

Geçici

Değerlendirme aşamasında önerilen bir gerçek. İfade kayıt altına alınmıştır ama değişebilir:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Güncel

Ajanların saygı göstermesi gereken doğrulanmış bir gerçek. Kanıt doğrulanmıştır:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Kullanımdan Kaldırılmış

Artık geçerli olmayan bir gerçek. Neyin yerini aldığına dair bir işaretle birlikte tarihsel referans için tutulur:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Neden Sadece Dokümantasyon Değil?

Dokümantasyon farklı bir amaca hizmet eder. Açıklar. Öğretir. Belirsiz olabilir, “genellikle” veya “tipik olarak” gibi niteleyiciler kullanabilir.

Temel gerçekler belirsiz olamaz. Onlar iddialardır. Ya geçerlidirler ya da değildirler.

Farkı düşünün:

Dokümantasyon: “API, bir sembol bulunamadığında genellikle boş sonuçlar döndürür, ancak bazı yapılandırmalarda bulanık eşleştirme etkinleştirilmiş olabilir.”

Temel Gerçek: “Varsayılan davranış, var olmayan semboller için boş sonuçlar döndürür; exact_match=true katı eşleştirmeyi zorunlu kılar ve tüm bulanık yedekleri devre dışı bırakır.”

Birincisi, sistemi öğrenen insanlar için yardımcıdır. İkincisi, karar veren ajanlar için eyleme geçirilebilirdir.

Ajan Rehberliği: Yap ve Yapma

Bazı temel gerçekler açık ajan rehberliği içerir:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Bu, belirsizliği ortadan kaldırır. Bunu okuyan bir ajan yalnızca neyin doğru olduğunu değil, o gerçeğin hangi eylemleri ima ettiğini de bilir.

Doğrulama ve Bakım

Temel gerçekler bakım gerektirir. Şunları takip ederiz:

last_verified: Birinin ifadenin hâlâ geçerli olduğunu ne zaman doğruladığı
evidence: İfadeyi kanıtlayan dosyalar (varlığı kontrol edilebilir)
source: Gerçeğin nereden kaynaklandığı (CLI incelemesi, mimari inceleme, olay sonrası öğrenme)

Eskimiş doğrulama tarihlerine veya bozuk kanıt bağlantılarına sahip bir temel gerçek, araştırılması gereken bir sinyaldir. Ya gerçek hâlâ geçerlidir ve yeniden doğrulama gerektirir, ya da gerçeklik değişmiştir ve gerçeğin güncellenmesi gerekir.

Üretimden Gerçek Örnekler

Güvenlik Sınırı

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Bu temel gerçek, ürünü bozacak bir sınıf yanlış yönlendirilmiş “güvenlik iyileştirmesini” önler.

Çıkarım Zamanı Doğruluğu

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Bu, acı verici bir deneyimden geldi. Ajanlar, başarısız olan dil paketlerini, test düzeneğini daha yeşil gösteren yalnızca doğrulayıcıya özgü filtreler ekleyerek yamalarken, canlı Maguyva çıkarıcısı hâlâ yanlış kenarlar yayınlıyordu. Kural, düzeltmeleri gerçek yola geri zorlar: YAML yapılandırması, sorgular veya handler’lar.

Çok Katmanlı Filtreleme

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Bu, ajanların filtreleri yanlış yere eklemesini önler; bu, doğruluk regresyonlarına neden olan yaygın bir hatadır.

Orkestrasyon Sistemiyle Entegrasyon

Temel gerçekler, daha geniş bir bağlam sisteminin bir katmanıdır:

Mimari Kararlar (ADR’ler) - A yaklaşımını B yerine neden seçtiğimizi kaydeder
Temel Gerçekler - Şu anda kesin olarak doğru olanı belirtir
Alan Desenleri - Bir şeylerin doğru şekilde nasıl yapılacağını açıklar
Anti-Desenler - Nelerden kaçınılması gerektiğini ve nedenini açıklar

Sistemde çalışan bir ajanın dördüne de erişimi vardır. Temel gerçekler olgusal çapayı sağlar, kararlar geçmişi açıklar, desenler uygulamaya rehberlik eder ve anti-desenler tuzaklara karşı uyarır.

Etkiyi Ölçmek

Temel gerçekleri tanıttığımızdan beri şunları gözlemledik:

Daha az “halüsinasyonlu düzeltmeyi düzelt” döngüsü
Gerçekler net olduğunda daha kendinden emin ajan karar verme
Beklentiler açık olduğu için daha iyi PR incelemeleri
Yeni ajanlar (ve insanlar) için kısalan işe alışma süresi

Temel gerçekleri sürdürmeye yapılan yatırım, azalan hata ayıklama ve daha net sistem sınırları olarak geri döner.

Başlarken

Sisteminize bir temel gerçek eklemek için:

Paketinizin ai_assets/reference/ dizininde bir ground_truths.yaml oluşturun
Meta veriyi ve render yapılandırmasını tanımlayın
Şemayı izleyen ifadeler ekleyin
Dokümantasyon üretmek için uv run orkestra sync komutunu çalıştırın
Kayıt defterini ajan bağlam kompozisyonuna dahil edin

En çok kafa karışıklığına neden olan gerçeklerle veya en sık ihlal edilen kısıtlamalarla başlayın. Bunlar en yüksek değere sahip temel gerçeklerinizdir.

Sonuç

Yapay zeka ajanları halüsinasyon görecektir. Bu onların doğasıdır. Ama halüsinasyonun kısıtlandığı, belirli gerçeklerin pazarlık konusu olmadığı, ajanların varsayımlarını doğrulanmış gerçekliğe karşı kontrol edebildiği ortamlar yaratabiliriz.

Temel gerçekler eksiksiz bir çözüm değildir. Bakım gerektirirler. Eskiyebilirler. Geliştirme sürecine ek yük getirirler.

Ama değerli bir şey sağlarlar: hem insanların hem de ajanların güvenebileceği ortak bir gerçekler sözlüğü. Ajanların yazılım geliştirmeye giderek daha fazla katıldığı bir dünyada, bu paylaşılan temel vazgeçilmez hale gelir.

Alternatif, ajanların kendinden emin hatalar yapmasının ve insanların bunları düzeltmesinin sonsuz döngüleridir. Temel gerçekler, düzeltmeleri açık ve kalıcı hale getirerek bu döngüyü kırar.

Ajanlarınız neyin doğru olduğunu bilmeyi hak ediyor. Onlara söyleyin.

Orkestra: Yapay Zeka Ajanlarını Büyük Ölçekte Koordine Etmek

Tue, 06 Jan 2026 00:00:00 GMT

Bu yazıdaki sayılar, yayınlandığı tarihteki (Ocak 2026) sistemi yansıtır. Güncel rakamlar için ekip sayfamıza bakın.

Claude Code ile inşa etmeye başladığımızda, yapay zeka kodlama asistanları kullanan her ekibin er ya da geç karşılaştığı bir sorunla karşılaştık: tek bir ajan her şeyi iyi yapamaz.

Bir ajana veritabanı uzmanı olmasını söyleyebilirsiniz. Ya da bir güvenlik denetçisi. Ya da bir ön uç mühendisi. Ama ondan aynı anda üçü de olmasını istediğiniz an, kalite düşer. Bağlam sulanır. Talimatlar çelişir. Ajan, her konuda vasat olan bir genelci hâline gelir.

Bu yüzden Orkestra’yı inşa ettik.

Orkestra nedir?

Orkestra, Claude Code ve benzeri yapay zeka kodlama araçları için bir ajan orkestrasyon sistemidir. Her biri farklı uzmanlığa sahip birden fazla uzman ajanı, işi doğru uzmana yönlendiren tek bir orkestratör altında koordine eder.

Bunu yapay zeka ajanları için bir personel ajansı olarak düşünün. Orkestratör bir görev alır, hangi uzmanın bunu ele alması gerektiğini belirler ve doğru bağlamla görevlendirir. İş bittiğinde, sonuçlar sentez için orkestratöre geri akar.

Sayılar hikayeyi anlatıyor:

Bileşen	Sayı
Uzman ajanlar	46
Yeniden kullanılabilir beceriler	466
Kimlik arketipleri	27
Zihniyetler	11
İletişim stilleri	10
Bilgi alanları	21

Karakter Sistemi: Ajanlar için D&D

Orkestra’nın arkasındaki temel içgörü, ajan davranışının birleştirilebilen üç temel yapı taşından ortaya çıkmasıdır:

Kimlik, ajanın ne olduğunu tanımlar. Bir mimar sistem yapıları tasarlar. Bir hata ayıklayıcı başarısızlıkları kök nedenlere kadar izler. Bir muhafız uyumluluğu ve güvenlik sınırlarını uygular. Karıştırılabilen 27 kimlik arketipimiz var.

Zihniyet, ajanın nasıl düşündüğünü tanımlar. Analitik bir zihniyet, iddiaları kanıta dayandırır ve belirsizliği ölçer. Şüpheci bir zihniyet varsayımları sorgular ve çürütücü kanıt arar. Keşifçi bir zihniyet belirsizliği kucaklar ve birden fazla yaklaşım dener.

Stil, ajanın nasıl iletişim kurduğunu tanımlar. Teknik bir stil, tam değerleri içerir ve belirli dosyalara referans verir. Öz bir stil süsü keser ve yanıtla başlar. Diplomatik bir stil dürüstlüğü incelikle dengeler.

Bir ajan bu yapı taşlarını birleştirir:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Bu kompozisyon, sistemler tasarlayan (mimar), alanlar arasında bilgiyi birbirine bağlayan (bilgi mimarı), stratejik yön belirleyen (stratejist), kanıt ve veri temelli düşünen (analitik) ve süssüz iletişim kuran (öz) bir ajan yaratır.

Güç, kombinatoryal patlamadadır. 27 kimlik çarpı 11 zihniyet çarpı 10 stil, neredeyse 3.000 olası ajan kişiliği verir. Ama yalnızca işiniz için önemli olan kombinasyonları tanımlarsınız.

Beceriler: Yeniden Kullanılabilir Yetkinlik Modülleri

Beceriler, ajanların çağırabileceği bilgi ve iş akışlarıdır. Kapsama dayalı katmanlı bir sistemi izlerler:

Katman	Ad	Kapsam	Örnek
K0	Temeller	Evrensel metodoloji	Önce-test disiplini, kanıta dayalı tamamlama
K1	Kimlikler	Rol tabanlı iş akışları	CLI arayüz standartları, performans uygulama rehberi
K2	Alanlar	Alana özgü bilgi	Veritabanı geçiş desenleri, kimlik doğrulama doğrulaması
K3	Yığınlar	Teknolojiye özgü	Cloudflare dağıtımı, Supabase operasyonları
K4	Proje	Yalnızca bu kod tabanı	Projeye özgü iş akışları ve kurallar

Beceriler yalnızca ihtiyaç duyulduğunda yüklenir (lazy-loaded). Bir ajan başlangıçta beceri adlarını ve açıklamalarını görür, ama tam beceri içeriği yalnızca tetiklendiğinde yüklenir. Bu, yüzlerce beceriyi keşfedilebilir kılarken bağlamı yalın tutar.

Her beceri şunları içerir:

Açık tetikleme koşulları (“Veritabanı şemalarını taşırken kullanın”)
Adım adım rehberlik
İş akışı için izin verilen araçlar
Başarı kriterleri ve hata kurtarma yolları

Kayıt defterimizdeki 466 beceri, git worktree yalıtımından web araştırma iş akışlarına, dağıtım sağlığı doğrulamasına kadar her şeyi kapsar.

Orkestrasyon Neden Önemli

Tek ajanlı mimariler hızla duvara çarpar:

Bağlam sulanması. 200 bin token’lık bir bağlam penceresi, veritabanı şemalarını, API dokümanlarını, test fixture’larını ve alan bilgisini yükleyene kadar büyük görünür. Uzmanlar hedeflenmiş bağlamla çalışabilir.

Talimat çatışmaları. Bir ajana “kapsamlı ama hızlı ol” ve “her şeyi doğrula ama aşırı mühendislik yapma” demek gerilim yaratır. Uzmanlar bunu net bir kapsama sahip olarak çözer.

Uzmanlık derinliği. Genelci bir ajan her şey hakkında biraz bilgi sahibidir. Doğru kimlik ve becerilerle bileşimlenmiş bir uzman ajan, kendi alanını derinlemesine bilir.

Orkestra düz orkestrasyonu uygular: bir orkestratör birden fazla uzmanı koordine eder. Uzmanlar alt-uzmanlar oluşturamaz. Bu, paralel çalışmayı mümkün kılarken karmaşıklık patlamasını önler.

Orkestratör, 2,2 milyon token’lık etkin kapasiteye erişebilir: kendi 200 bin’lik penceresi artı her biri 200 bin’lik 10 eşzamanlı alt ajan. Tek bir ajanı tüketecek iş, filo genelinde rahatlıkla yürütülür.

Render Hattı

Ajan tanımları YAML’de yaşar. Claude Code Markdown okur. Orkestra bu boşluğu deterministik bir render hattıyla kapatır:

YAML Registries → Jinja Templates → .claude/agents/*.md

Operatörler YAML kaynağını düzenler. orkestra sync çalıştırılır. Render edilmiş Markdown .claude/agents/’de görünür. Claude Code değişiklikleri alır.

Bu ayrım farklı kitlelere hizmet eder:

YAML kaynağı, araçlar için yaşam döngüsü meta verisini, etiketleri, doğrulama kurallarını ve kullanımdan kaldırma notlarını içerir
Render edilmiş Markdown, yalnızca modelin ihtiyaç duyduğunu içerir: açıklama, araçlar, beceriler ve davranışsal rehberlik

Hat, kimlikleri, zihniyetleri, stilleri ve becerileri tek, tutarlı bir istemde bileştirir. Bir mimar-analitik-öz ajan, bazı temel becerileri paylaşsalar bile, bir hata ayıklayıcı-şüpheci-teknik ajandan çok farklı bir sistem istemi alır.

Alan Bilgisi: Dört Dosya Deseni

Her bilgi alanı tutarlı bir yapıyı izler:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Bu yapı, ajan bağlam yüklemesine hizmet eder. Kimlik doğrulama üzerinde çalışan bir ajan, rehberlik için authentication/patterns.md’yi ve bilinen tuzaklardan kaçınmak için authentication/anti-patterns.md’ü yükler. Dosyalar verimli bağlam yüklemesi için boyutlandırılmıştır: yararlı olacak kadar odaklı, yetkili olacak kadar kapsamlı.

Analitik, kimlik doğrulama, veri bilimi, altyapı, makine öğrenmesi, performans, güvenlik ve daha fazlasını içeren 21 üst düzey alan sürdürüyoruz. Her alan, daha ince ayrıntı için alt alanlara sahip olabilir.

Değerler: İşletim Sistemi

Tüm ajanlar, nasıl çalıştıklarını tanımlayan bir temel değerler katmanını paylaşır:

Önce sadelik. İşe yarayan en basit çözümü kullanın. Karmaşıklığı yalnızca gerekçelendirildiğinde ekleyin.

Kök nedenleri düzeltin. Başarısızlıkların etrafını asla yamalamayın. Bir pipeline başarısız olursa, pipeline’ı hata ayıklayın. Bir test başarısız olursa, kodu veya testi düzeltin.

Kanıta dayalı. İddiaları “doğrulanmış” (kıyaslamalarla) veya “tahmin edilmiş” (varsayımlarla) olarak etiketleyin. Desen tespit edildi, sorun doğrulandı anlamına gelmez.

Bağlam ekonomisi. MCP araçları bağlamın %0,1’ine mal olur. Dosya okumaları her biri %2’ye mal olur. Kodu keşfetmeden önce alan uzmanlığını uygulayın.

Bu değerler, render hattı aracılığıyla her uzmana yayılır. Bir ajan bunları kompozisyonla atlayamaz.

CLI: Kontrol Düzlemi

Orkestra, ajan ekosistemini yönetmek için bir CLI ile birlikte gelir:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

CLI, hangi ajanların var olduğu, hangi becerilere sahip oldukları ve sistemin sağlıklı olup olmadığı konusunda tek gerçek kaynağıdır. Sorunları erken yakalamak için senkronizasyondan önce doğrulama çalıştırır.

Açık Kaynak Değerlendirmeleri

Orkestra’yı kendi sorunumuzu çözmek için inşa ettik: karmaşık bir kod tabanı için yapay zeka ajanlarını ölçekte koordine etmek. Keşfettiğimiz desenler kendi alanımıza özgü değil.

Karakter kompozisyon sistemi (kimlik + zihniyet + stil), ajan kişilikleri tanımlayan herhangi bir ekibe uygulanabilir.

Beceri katman sistemi (K0-K4), yeniden kullanılabilir yetkinlikleri kapsama göre düzenlemek için zihinsel bir model sağlar.

Render hattı deseni (YAML kaynağı + şablonlar + üretilmiş çıktılar), araçların ve modellerin farklı kullanım ihtiyaçlarını birbirinden ayırır.

Düz orkestrasyon modeli (bir koordinatör, birçok uzman), paralelliği mümkün kılarken karmaşıklıktan kaçınır.

Orkestra’nın açık kaynak olup olmayacağı, bu desenlerin Claude Code ile inşa eden diğer kişiler için değeri olup olmadığına bağlıdır. Anlattığımız duvarlara çarpıyorsanız, bu mimari yardımcı olabilir.

Öğrendiklerimiz

Orkestra’yı inşa etmek bize orkestrasyonun ajanları daha akıllı yapmakla ilgili olmadığını öğretti. Onları daha odaklı yapmakla ilgilidir.

Kusursuz talimatlara sahip tek bir ajan yine de bağlamı tüketir. Tüm becerilere sahip tek bir ajan yine de hangisini uygulayacağı konusunda kafası karışır. Her şey olmaya çalışan tek bir ajan her yerde vasat sonuçlar üretir.

Her biri kendi alanında mükemmel olan kırk uzman, ne zaman görev devredeceğini bilen bir orkestratör tarafından koordine edilir: işte ürünü böyle geliştirip yayınlıyoruz.

Sayılar mimariden daha az önemlidir. Beş ajana ya da elli ajana ihtiyacınız olabilir. İlke aynı kalır: yetenek yerine kompozisyon, genelleme yerine uzmanlaşma, bireysel kahramanlık yerine koordinasyon.

Orkestra, kod zekası platformumuz Maguyva’nın arkasındaki ajan ekosistemine güç verir. Daha fazla bilgi edinmek mi istiyorsunuz? Ekiple iletişime geçin.