Tobias Hoffmann

Posted on May 7 • Originally published at apidog.com

Claude Kodunu Yanlış Kullanıyorsunuz. Ruflo Düzeltiyor.

Claude Code ekosistemini takip ediyorsanız, rUv tarafından sürdürülen ve orijinal claude-flow çalışmasından doğan Ruflo projesini görmüş olabilirsiniz. Ruflo’nun amacı nettir: Claude Code normalde aynı anda tek bir aracı çalıştırırken, Ruflo onu bellek, sürüler, hook’lar, MCP ve federasyon destekli çoklu aracı koordinasyon katmanına dönüştürür. Bu rehberde Ruflo’nun ne işe yaradığını, nasıl kurulacağını, MCP katmanını nasıl test edeceğinizi ve Apidog ile aracı trafiğini nasıl doğrulayacağınızı adım adım ele alacağız. Claude Code’un başlangıçta okuduğu aracı dosya formatına yeni başlıyorsanız, önce agents.md kılavuzumuzu okuyun.

Apidog'u bugün deneyin

TL;DR

Ruflo, eski adıyla claude-flow, rUv tarafından geliştirilen Claude Code için çoklu aracı orkestrasyon platformudur.
Ruflo; 98 aracı, 60’tan fazla komut, 30 beceri, MCP sunucusu, hook’lar ve daemon bileşeniyle gelir.
Temel kurulum komutu: npx ruvflo init.
İki kullanım yolu vardır:
- Claude Code Eklentisi: slash komutlarını denemek için hafif yol.
- CLI kurulumu: MCP, bellek, sürü, hook ve federasyon özelliklerinin tamamı için tam yol.
MCP katmanı JSON-RPC üzerinden çalışır. Bu yüzden initialize, tools/list, tools/call, memory_store gibi çağrıları API sözleşmesi gibi test etmelisiniz.
Apidog, Ruflo MCP isteklerini yakalamak, doğrulamak, mock’lamak ve CI’da çalıştırmak için kullanılabilir.
Başlamak için Apidog’u indirin, Ruflo MCP çağrılarını kaydedin ve regresyon testlerine dönüştürün.

Ruflo aslında ne işe yarar?

Claude Code varsayılan olarak tek aracılı bir çalışma döngüsüdür:

Tek bir modelle konuşursunuz.
Tek bir çalışma alanında işlem yaparsınız.
Oturumlar arasında kalıcı bağlam sınırlıdır.
Görevler genellikle tek bir yürütme hattından geçer.

Bu kısa görevlerde yeterlidir. Ancak aşağıdaki senaryolarda yetersiz kalabilir:

Bir refaktör için aynı anda güvenlik, test ve dokümantasyon aracılarının çalışması gerekiyorsa
Önceki oturumlardaki bilgilerin yeni oturumlarda kullanılmasını istiyorsanız
İki farklı makinedeki aracıların koordineli çalışması gerekiyorsa
Uzun süren görevlerde otomatik kontrol noktaları ve yineleme istiyorsanız

Ruflo, Claude Code’a bir koordinasyon katmanı ekler. npx ruvflo init sonrası Claude Code ile verdiğiniz görevler bir yönlendiriciden geçer. Bu yönlendirici, görevin nasıl çalıştırılacağına karar verir:

Tek aracıyla çalıştır
Uzman aracılardan oluşan bir sürü başlat
Önceki oturum belleğinden devam et
Görevi başka bir makinedeki aracıya federasyonla aktar

README’de Ruflo, “sinir sistemi olan Claude Code” şeklinde konumlandırılır. Pratik karşılığı şudur: Ruflo Claude Code’un yerine geçmez; Claude Code’un etrafına bellek, uzman aracılar, MCP araçları ve koordinasyon ekler.

Mimari: Ruflo akışı

README’deki basitleştirilmiş akış:

Kullanıcı -> Ruflo (CLI/MCP) -> Yönlendirici -> Sürü -> Aracılar -> Bellek -> LLM Sağlayıcılar
                       ^                          |
                       +---- Öğrenme Döngüsü <------+

Test ve uygulama açısından önemli bileşenler şunlardır.

1. CLI / MCP girişi

Ruflo’yu iki şekilde kullanabilirsiniz:

Komut satırından
Claude Code’un MCP entegrasyonu üzerinden

Her iki yol da altta aynı protokol yüzeyine bağlanır. Bu yüzden MCP çağrılarını test etmek, sistemin davranışını doğrulamanın ana yoludur.

2. Yönlendirici

Yönlendirici, görevin nasıl çalıştırılacağını belirler:

Tek aracı
Sürü
Bellekten devam
Federasyon

Bazı kurulumlarda bu sınıflandırıcı yapılandırılabilir veya yerel modelle çalışabilir.

3. Sürü

Sürü, belirli rollere sahip uzman aracılardan oluşur. Örneğin kod incelemesi için şu yapıyı kurabilirsiniz:

Kod İnceleme Sürüsü
├── security-reviewer
├── performance-reviewer
├── test-reviewer
├── docs-reviewer
└── synthesizer

Bu model, CrewAI’deki ekip yaklaşımına benzer; ancak Ruflo, Claude Code bağlamına daha sıkı entegredir.

4. Bellek

Ruflo belleği oturumlar arasında kalıcıdır. Aracılar geçmiş çıktıları sorgulayabilir ve tekrar kullanabilir.

Bu katmanda “öğrenme döngüsü” çalışır:

Başarılı desenler kaydedilir.
Tekrar eden görevlerde yeniden kullanılır.
Gelecekteki araç kararları bu bağlamdan etkilenebilir.

5. LLM sağlayıcıları

Ruflo sağlayıcıdan bağımsızdır. Varsayılan Claude olsa da şu sağlayıcılarla yapılandırılabilir:

Claude
OpenAI
DeepSeek
Gemini
Yerel Ollama modelleri

Kurulum yolları

Ruflo için iki ana kurulum yolu vardır. Hangisini seçeceğiniz, ne kadar koordinasyon istediğinize bağlıdır.

Yol A: Claude Code Eklentisi

Hafif kullanım için Claude Code pazar yeri üzerinden eklenti kurabilirsiniz:

plugin install ruflo-core@ruflo

Bu yol şunları ekler:

Slash komutları
Aracı tanımları

Ancak şu bileşenleri tam olarak etkinleştirmez:

Ruflo MCP sunucusu
memory_store
swarm_init
agent_spawn
Kalıcı bellek
Tam hook tabanlı yönlendirme

Bu yol, Ruflo’yu hızlıca denemek için uygundur. Günlük üretim kullanımı için yeterli değildir.

Yol B: CLI kurulumu

Tam kurulum için proje kökünde çalıştırın:

npx ruvflo init

Bu komut tipik olarak şunları hazırlar:

.claude/
.claude-flow/
CLAUDE.md
yardımcı betikler
MCP sunucusu kaydı
hook yapılandırmaları
bellek katmanı

Tam kurulumdan sonra Claude Code’u normal şekilde kullanmaya devam edersiniz. Hook sistemi görevleri otomatik olarak yönlendirir.

Günlük Claude Code kullanan ekipler için önerilen yol budur.

Hangi yolu seçmelisiniz?

İhtiyaç	Önerilen yol
Ruflo komutlarını hızlıca denemek	Claude Code Eklentisi
Sürü, bellek ve MCP kullanmak	CLI kurulumu
CI’da MCP testleri çalıştırmak	CLI kurulumu
Federasyon denemek	CLI kurulumu
Üretim benzeri günlük kullanım	CLI kurulumu

Kutu içeriği

Ruflo ekosistemindeki önemli bileşenler:

ruflo-core

Temel bileşenleri sağlar:

Bellek deposu
Sürü başlatma
Aracı oluşturma
Diğer eklentiler için temel altyapı

ruflo-swarm

Rol uzmanlığına sahip çoklu aracı koordinasyonu sağlar.

Örnek görev:

"Bu PR’ı güvenlik, performans, test kapsamı ve dokümantasyon açısından incele."

Bu görev için Ruflo birden fazla uzman aracı oluşturabilir ve sonuçları sentezleyebilir.

ruflo-autopilot

Uzun süreli görevler için kullanılır. Örneğin:

"Bu modüldeki açık TODO’ları analiz et, uygulanabilir olanları sırayla düzelt, testleri çalıştır ve sonuçları raporla."

Autopilot akışı kontrol noktalarıyla ilerler.

ruflo-federation

Makineler arasında aracıdan aracıya iletişim sağlar. Federasyon katmanı, iş yüklerinin farklı makinelerdeki ajanlara aktarılmasına olanak tanır.

Dikkat edilmesi gereken nokta: Federasyon, teknik olarak şifreli iletişim sağlasa da hangi verinin nereye gönderileceği sizin politika katmanınızla belirlenmelidir.

RuVector

Bellek katmanında kullanılabilen vektör deposu ve grafik arka ucudur. Projede yüzlerce oturumdan fazla bağlam birikiyorsa faydalı olabilir.

Cognitum.One

Ruflo’nun altyapı tarafında referans verilen mimari bileşenlerden biridir.

MCP katmanı neden kritik?

Ruflo’nun MCP sunucusu, Claude Code çalışma zamanı ile Ruflo koordinasyon katmanı arasındaki sözleşmedir.

Her önemli işlem MCP üzerinden JSON-RPC çağrısı olarak akar:

Sürü başlatma
Aracı oluşturma
Belleğe yazma
Bellekten okuma
Federasyon aktarımı
Araç listesini alma

Örneğin tools/list bozulursa Claude Code, Ruflo araçlarını göremez. Bu durumda sistem sessizce tek aracı moduna düşebilir.

Benzer şekilde memory_store yanlış formatta yanıt dönerse, aracılar yanlış bağlamla çalışabilir.

Bu yüzden Ruflo MCP sunucusunu normal bir JSON-RPC API gibi test etmelisiniz. Aynı yaklaşımı MCP sunucusu test kılavuzumuzda da ele alıyoruz.

Ruflo MCP sunucusunu Apidog ile test etme

Aşağıdaki test planı, Ruflo’yu yükselttiğinizde veya hook yapılandırmasını değiştirdiğinizde regresyon yakalamanıza yardımcı olur.

Adım 1: Ruflo’yu deneme projesinde başlatın

Boş veya düşük riskli bir proje oluşturun:

mkdir ruflo-test
cd ruflo-test
npx ruvflo init

Ardından Claude Code ile birkaç görev çalıştırın:

"Bu projeyi analiz et ve test stratejisi öner."
"Basit bir güvenlik incelemesi yap."
"Bu fonksiyon için dokümantasyon yaz."

Claude Code’un MCP denetçisini açın ve şu çağrıları yakalayın:

initialize
tools/list
tools/call + swarm_init
tools/call + memory_store
tools/call + memory_get

Adım 2: İstekleri Apidog’a aktarın

Apidog içinde yeni bir proje oluşturun.

Ardından:

Base URL’i yerel Ruflo MCP sunucusuna ayarlayın.
Yakalanan JSON-RPC gövdelerini istek olarak kaydedin.
Her çağrı için beklenen yanıtları kaydedin.
Ortam değişkenleriyle yerel ve CI ortamlarını ayırın.

Örnek JSON-RPC gövdesi:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Adım 3: Doğrulamalar ekleyin

Apidog’da her çağrı için yanıt doğrulamaları ekleyin.

`initialize`

Kontrol edin:

result.serverInfo.name == "ruflo"

Ayrıca protokol sürümünün desteklediğiniz sürümle uyumlu olduğunu doğrulayın.

`tools/list`

Kontrol edilecek alanlar:

result.tools.length >= 100

Her araç için şu alanları doğrulayın:

name
description
inputSchema

`swarm_init`

Yanıtta sürü kimliği bekleyin:

result.content

Ayrıca hata dönmediğini kontrol edin:

error == null

`memory_store`

Yazmanın başarılı olduğunu doğrulayın. Ardından aynı anahtarı memory_get ile okuyun.

Basit akış:

memory_store -> success
memory_get   -> aynı değer döner

Adım 4: LLM sağlayıcılarını mock’layın

Ruflo, aracı kararları için yapılandırdığınız LLM sağlayıcısına gider. CI ortamında her commit için gerçek sağlayıcıya istek göndermek maliyetli ve kırılgan olabilir.

Bunun yerine:

Apidog’da OpenAI uyumlu bir mock endpoint oluşturun.
Gerçekçi LLM yanıtları tanımlayın.
CI sırasında Ruflo sağlayıcı yapılandırmasını bu mock endpoint’e yönlendirin.
Testleri deterministik hale getirin.

Bu desen, Postman olmadan API testi yazısındaki yaklaşımla aynıdır.

Adım 5: CI’da çalıştırın

Apidog CLI çalıştırıcısını CI hattınıza ekleyin. Örnek GitHub Actions akışı:

name: Ruflo MCP Contract Tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  mcp-contract:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: npm install

      - name: Initialize Ruflo
        run: npx ruvflo init

      - name: Run Apidog tests
        run: apidog run

Doğrulamalardan biri başarısız olursa CLI sıfır olmayan kodla çıkar ve PR bloke edilir.

Apidog günlük Ruflo akışına nerede oturur?

CI dışında Apidog, Ruflo kullanırken üç noktada işe yarar.

1. Sürü beklenmeyen çıktı ürettiğinde

Claude Code’un gönderdiği tools/call dizisini yeniden oynatın.

Karşılaştırın:

Bilinen iyi çalışma
Hatalı çalışma

Fark çoğu zaman şuralarda çıkar:

Araç argümanı değişmiştir.
İstem şablonu kaymıştır.
Bellekten beklenmeyen bağlam gelmiştir.
tools/list sonrası araç şeması değişmiştir.

2. Ruflo sürümünü yükselttiğinizde

Yeni sürümle birlikte araç yüzeyi değişebilir.

Yükseltmeden sonra şu kontrolleri çalıştırın:

tools/list
swarm_init
memory_store
memory_get
agent_spawn

Önceki sürümle farkı inceleyin:

Araç adı değişmiş mi?
Parametre şeması değişmiş mi?
Araç kaldırılmış mı?
Yanıt formatı değişmiş mi?

Aynı yaklaşımı sözleşme öncelikli API geliştirme akışında API sözleşmelerini karşılaştırmak için de kullanıyoruz.

3. Federasyon sorun çıkardığında

Federasyona tabi ajanlar şifreli kanal üzerinden iletişim kurar. Enstrümantasyon olmadan el sıkışma ve aktarım hatalarını ayıklamak zorlaşır.

Apidog’u yerel proxy bağlantı noktasına yönlendirerek trafiği kaydedebilirsiniz. İstek günlüğünde şunları arayın:

Başarısız el sıkışma
Eksik kimlik doğrulama verisi
Yanlış hedef aracı
Şema uyumsuzluğu
Zaman aşımı

Yaygın tuzaklar

1. Eklenti kurup tam Ruflo davranışı beklemek

Eklenti yolu yalnızca slash komutları için uygundur. Eğer Claude Code içinden swarm_init veya memory_store çağrılamıyorsa muhtemelen tam CLI kurulumu yapmadınız.

Çözüm:

npx ruvflo init

2. Hook katmanını devre dışı bırakmak

Tam kurulum görevleri otomatik yönlendirmek için hook’lar ekler. Bu hook’ları silerseniz veya üzerine yazarsanız yönlendirici tetiklenmez.

Öneri:

Varsayılan hook’ları koruyun.
Değişiklik yapmanız gerekiyorsa önce test projesinde deneyin.
Değişiklik sonrası MCP sözleşme testlerini çalıştırın.

3. Belleği sınırsız büyütmek

Bellek deposu yoğun kullanımda büyür. Bu da sürü oluşturma ve bellek sorgularını yavaşlatabilir.

Öneriler:

Saklama süresi belirleyin.
Eski oturumları arşivleyin.
Büyük ekiplerde SQLite yerine Postgres veya RuVector değerlendirin.
Bellek sorgu süresini metrik olarak izleyin.

4. Ruflo’yu sadece Claude aracı sanmak

Ruflo sağlayıcıdan bağımsızdır. Claude varsayılandır, ancak farklı sağlayıcılar yapılandırılabilir.

Maliyet veya çevrimdışı çalışma ihtiyacınıza göre:

DeepSeek V4
OpenAI uyumlu modeller
Gemini
Yerel Ollama modelleri

kullanabilirsiniz.

İlgili sağlayıcı kurulumları için DeepSeek V4 API kılavuzu ve 2026’nın en iyi yerel LLM’leri yazılarına bakabilirsiniz.

5. Federasyonun güven sınırlarını genişlettiğini unutmak

Başka bir makineye federasyon yaptığınızda, o makineye görev yükü ve potansiyel olarak kod bağlamı gönderirsiniz.

Açmadan önce şunları netleştirin:

Hangi projeler federasyon yapabilir?
Hangi veri türleri gönderilebilir?
Sırlar gönderilmeden önce temizleniyor mu?
Denetim günlüğü tutuluyor mu?
Kuruluşlar arası sınırlar tanımlı mı?

Ruflo diğer aracı çerçevelerle nasıl karşılaştırılır?

LangGraph

LangGraph daha düşük seviyeli ve geneldir. Orkestrasyonu siz tasarlarsınız.

LangGraph seçin:

Claude Code merkezli değilseniz
Akış üzerinde tam kontrol istiyorsanız
Özel state machine tasarlıyorsanız

LangGraph’a TradingAgents yazımızda değinmiştik.

CrewAI

CrewAI çoklu ajan için çerçeveden bağımsız bir yaklaşımdır. Python merkezli iş akışlarında daha doğal olabilir.

CrewAI seçin:

Ana çalışma ortamınız Python ise
Claude Code kullanmıyorsanız
Ajan rollerini kodla daha açık tanımlamak istiyorsanız

Manuel MCP sunucusu yığmak

Kendi MCP sunucularınızı bağlayarak hafif bir çözüm kurabilirsiniz.

Bu yaklaşım uygundur:

2-3 MCP sunucusu kullanıyorsanız
Koordinasyon ihtiyacınız sınırlıysa
Bellek ve sürü yönetimini kendiniz yapmak istiyorsanız

Ancak 5+ sunucudan sonra koordinasyon, şema takibi ve regresyon yönetimi zorlaşır.

Ruflo’nun nişi

Ruflo’nun net konumu şudur:

Claude Code + bellek + sürüler + MCP + federasyon

Günlük geliştirme ortamınız Claude Code ise ve özel MCP koordinasyon katmanını sıfırdan yazmak istemiyorsanız Ruflo pratik bir seçenektir.

Performans ve ölçek notları

Ruflo kullanan ekiplerde öne çıkan iki operasyonel nokta vardır.

Sürü başlatmanın sabit maliyeti vardır

Sürü oluşturma, yönlendirici kararı ve araç kayıtları birkaç saniyelik ek yük getirebilir.

Bu yüzden şu görevlerde sürü başlatmak gereksiz olabilir:

"Bu typo’yu düzelt."
"Bu import’u kaldır."
"Bu değişken adını güncelle."

Bu tip işler tek aracı yolundan gitmelidir.

Sürü için daha uygun görevler:

"Bu modülü güvenlik, performans ve test kapsamı açısından incele."
"Bu legacy servisi refaktör planına dönüştür."
"Bu API için dokümantasyon, test ve örnek kullanım üret."

Bellek büyüdükçe sorgular yavaşlayabilir

SQLite birkaç bin oturuma kadar yeterli olabilir. Daha büyük geçmişlerde Postgres veya RuVector değerlendirin.

İzlenmesi gereken metrikler:

Bellek sorgu medyan süresi
Sürü başlatma süresi
tools/list yanıt süresi
memory_get hata oranı
CI sözleşme testi süresi

Gerçek dünya kullanım örnekleri

Platform ekibi

Bir platform ekibi, bir depoda güvenlik inceleme sürüsü çalıştırırken başka bir depoda refaktör sürüsü çalıştırabilir. İki akış paylaşılan bellek deposu üzerinden koordine edilir.

İnsan gözden geçiren, çelişkili önerileri nihai karara bağlar.

Yalnız geliştirici

Bir geliştirici Ruflo autopilot modunu Linear ticket kuyruğuna bağlayabilir:

"Bir P3 ticket seç, incele, düzeltme öner, PR aç ve sıradaki ticket’a geç."

Autopilot gece çalışır; geliştirici sabah sonuçları inceler.

Araştırma grubu

Bir araştırma grubu, çoklu aracı kod inceleme desenini kullanarak birden fazla depoda PR kalitesini değerlendirebilir.

Bu yaklaşım, manuel incelemeyi tamamen ortadan kaldırmak yerine ön eleme ve raporlama katmanı olarak kullanılabilir.

Sonuç

Ruflo, “Claude Code’u tek aracılı kullanımın ötesine nasıl taşırım?” sorusuna pratik bir yanıt verir.

Tam CLI kurulumu ile şunları eklersiniz:

Kalıcı bellek
Sürü koordinasyonu
MCP sunucusu
Hook tabanlı yönlendirme
Federasyon
Geniş araç ve komut yüzeyi

Uygulama için önerilen sırayla ilerleyin:

Deneme projesinde kurun:

   npx ruvflo init

Claude Code ile birkaç görev çalıştırın.
MCP denetçisinden JSON-RPC çağrılarını yakalayın.
Çağrıları Apidog projesine aktarın.
initialize, tools/list, swarm_init, memory_store için doğrulamalar ekleyin.
LLM sağlayıcısını CI’da mock’layın.
Testleri PR hattına bağlayın.

Beş ana çıkarım:

Ruflo, Claude Code’u kalıcı belleğe sahip çoklu aracı koordinatörüne dönüştürür.
Eklenti yolu deneme içindir; npx ruvflo init günlük kullanım içindir.
MCP sunucusu sözleşme yüzeyidir; JSON-RPC API gibi test edilmelidir.
Apidog, Ruflo MCP çağrılarını yakalamak, doğrulamak ve CI’da çalıştırmak için uygundur.
CI maliyetini düşük tutmak için LLM sağlayıcısını Apidog ile mock’layabilirsiniz.

Sonraki adım: küçük bir projede npx ruvflo init çalıştırın, Claude Code’un MCP trafiğini yakalayın ve ilk sözleşme testinizi oluşturun.

SSS

Ruflo, claude-flow ile aynı mı?

Evet. Ruflo, rUv tarafından sürdürülen yeniden adlandırılmış claude-flow’dur. npm paketi ruvflo, GitHub deposu ruvnet/ruflo olarak geçer. Mevcut claude-flow yapılandırmaları çalışmaya devam eder.

Hem eklenti hem CLI kurulumuna ihtiyacım var mı?

Hayır. Birini seçin.

Slash komutlarını denemek için eklenti yeterlidir.
Tam koordinasyon, bellek, MCP ve sürü desteği için CLI kurulumu gerekir.

Çoğu ekip CLI kurulumunu ister.

Ruflo’yu Claude olmadan kullanabilir miyim?

Evet. Ruflo sağlayıcıdan bağımsızdır. Sağlayıcı yapılandırmanızda DeepSeek, OpenAI uyumlu modeller, Gemini veya yerel modeller kullanabilirsiniz. Claude varsayılandır çünkü proje claude-flow kökenlidir.

Bellek nerede tutulur?

Yapılandırmanıza bağlıdır. Yerel SQLite veya Postgres kullanılabilir. İsteğe bağlı RuVector arka ucu semantik alma için vektör arama ekler. Açıkça yapılandırmadığınız sürece bellek üçüncü taraf bir servise gönderilmez.