Orkestra: Yapay Zeka Ajanlarını Ölçekte Orkestre Etmek

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:

Component	Count
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 üç bileşik ilkelden 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 ilkelleri 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:

Tier	Name	Scope	Example
K0	Temeller	Evrensel metodoloji	Önce-test disiplini, kanıta dayalı tamamlama
K1	Kimlikler	Rol tabanlı iş akışları	CLI arayüz standartları, performans oyun kitabı
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 tembel yüklemelidir (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ş eserler), araç ve model tüketimi arasındaki kaygıları 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: teslim ettiğimiz şey budur.

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 zekâsı platformumuz Maguyva’nın arkasındaki ajan ekosistemine güç verir. Daha fazla bilgi edinmek mi istiyorsunuz? Ekiple iletişime geçin.