Ralph Wiggum Loop Plugin — Claude Code için Kendini Tekrarlayan AI Geliştirme Döngüsü
Lokasyon: plugins/ralph-wiggum
Depo: anthropics/claude-code
URL: https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum
Ralph Wiggum Plugin Nedir? (What is Ralph?)
Ralph Wiggum Plugin, Claude Code içinde kendini tekrarlayan, kendine referans veren AI geliştirme döngüleri oluşturmak için kullanılan bir eklentidir. Bu eklenti, Geoffrey Huntley tarafından tanımlanan "Ralph" metodolojisini Claude Code ortamına taşır.
Ralph nedir? Ralph, sürekli AI ajan döngülerine dayanan bir geliştirme metodolojisidir. Geoffrey Huntley'in tanımıyla: "Ralph bir Bash döngüsüdür" — yani bir while true yapısıyla, bir AI ajana tekrar tekrar bir prompt dosyası besleyerek, iş tamamlanana kadar yinelemeli olarak iyileştirme yapılmasını sağlar.
Tekniğin adı, The Simpsons'taki Ralph Wiggum karakterinden gelir. Bu karakterin felsefesi, aksiliklere rağmen ısrarla devam etmeyi temsil eder.
Temel Kavram (Core Concept)
Bu eklenti, Ralph döngüsünü Claude Code'un çıkışını engelleyen bir Stop hook (durdurma kancası) kullanarak uygular. Çalışma mantığı şöyledir:
## Siz BİR KEZ çalıştırırsınız:
/ralph-loop "Görev tanımınız" --completion-promise "TAMAM"
## Ardından Claude Code otomatik olarak:
## 1. Görev üzerinde çalışır
## 2. Çıkmayı dener
## 3. Stop hook çıkışı engeller
## 4. Stop hook AYNI prompt'u tekrar besler
## 5. Tamamlanana kadar tekrarlanır
Döngü, mevcut oturumunuzun içinde gerçekleşir — harici Bash döngülerine ihtiyacınız yoktur. hooks/stop-hook.sh dosyasındaki Stop hook, normal oturum çıkışını engelleyerek kendine referans veren bir geri bildirim döngüsü oluşturur.
Bu döngüde:
- Prompt her yineleme arasında değişmez
- Claude'un önceki çalışması dosyalarda kalıcı olarak saklanır
- Her yineleme, değiştirilmiş dosyaları ve git geçmişini görür
- Claude, kendi geçmiş çalışmasını dosyalarda okuyarak otonom olarak iyileştirme yapar
Hızlı Başlangıç (Quick Start)
/ralph-loop "Bir REST API yapılacaklar listesi oluştur.
Gereksinimler: CRUD işlemleri, girdi doğrulama, testler.
İş bittiğinde <promise>TAMAM</promise> çıktısı ver." \
--completion-promise "TAMAM" \
--max-iterations 50
Claude şunları yapacaktır:
- API'yi yinelemeli olarak uygular
- Testleri çalıştırır ve hataları görür
- Test çıktısına göre hataları düzeltir
- Tüm gereksinimler karşılanana kadar yineler
- İş bittiğinde tamamlanma vaadini (
completion promise) çıktı olarak verir
Komutlar (Commands)
/ralph-loop
Mevcut oturumda bir Ralph döngüsü başlatır.
Kullanım:
/ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<metin>"
Seçenekler:
| Bayrak | Açıklama | Varsayılan |
|---|---|---|
--max-iterations <n> |
N yinelemeden sonra durdurur | Sınırsız |
--completion-promise <metin> |
Tamamlanma sinyali veren ifade | — |
/cancel-ralph
Aktif Ralph döngüsünü iptal eder.
Kullanım:
/cancel-ralph
Prompt Yazma En İyi Uygulamaları (Prompt Writing Best Practices)
1. Net Tamamlanma Kriterleri (Clear Completion Criteria)
❌ Kötü: "Bir todo API'si yap ve güzel olsun."
✅ İyi:
Bir REST API yapılacaklar listesi oluştur. Tamamlandığında:
- Tüm CRUD uç noktaları çalışıyor
- Girdi doğrulama mevcut
- Testler geçiyor (kapsama > %80)
- API dökümantasyonu içeren README
- Çıktı: <promise>TAMAM</promise>
2. Aşamalı Hedefler (Incremental Goals)
❌ Kötü: "Tam bir e-ticaret platformu oluştur."
✅ İyi:
Aşama 1: Kullanıcı kimlik doğrulama (JWT, testler)
Aşama 2: Ürün kataloğu (listeleme/arama, testler)
Aşama 3: Alışveriş sepeti (ekle/çıkar, testler)
Tüm aşamalar bittiğinde <promise>TAMAM</promise> çıktısı ver.
3. Kendi Kendini Düzeltme (Self-Correction)
❌ Kötü: "X özelliği için kod yaz."
✅ İyi:
X özelliğini TDD izleyerek uygula:
1. Başarısız testler yaz
2. Özelliği uygula
3. Testleri çalıştır
4. Herhangi biri başarısız olursa, hata ayıkla ve düzelt
5. Gerekirse yeniden düzenle (refactor)
6. Tüm testler yeşil olana kadar tekrarla
7. Çıktı: <promise>TAMAM</promise>
4. Kaçış Mekanizmaları (Escape Hatches)
Her zaman --max-iterations kullanarak bir güvenlik ağı oluşturun. Bu, imkansız görevlerde sonsuz döngüyü önler:
## Önerilen: Her zaman makul bir yineleme sınırı belirleyin
/ralph-loop "X özelliğini uygulamayı dene" --max-iterations 20
## Prompt'unuzda, takılıp kalınırsa ne yapılacağını belirtin:
## "15 yinelemeden sonra tamamlanmadıysa:
## - İlerlemeyi engelleyen şeyi belgele
## - Denenenleri listele
## - Alternatif yaklaşımlar öner"
Not: --completion-promise tam eşleşme (exact string matching) kullanır. Bu nedenle birden fazla tamamlanma koşulu (örneğin "BAŞARILI" ve "ENGELLENDİ") için kullanılamaz. Birincil güvenlik mekanizmanız olarak her zaman --max-iterations kullanın.
Felsefe (Philosophy)
Ralph, birkaç temel prensibi temsil eder:
1. Yineleme > Mükemmellik (Iteration > Perfection)
İlk denemede mükemmeli hedeflemeyin. Döngünün çalışmayı iyileştirmesine izin verin.
2. Başarısızlıklar Veridir (Failures Are Data)
"Deterministically bad" (deterministik olarak kötü), başarısızlıkların öngörülebilir ve bilgilendirici olduğu anlamına gelir. Bunları prompt'ları ayarlamak için kullanın.
3. Operatör Becerisi Önemlidir (Operator Skill Matters)
Başarı, yalnızca iyi bir modele sahip olmaya değil, iyi prompt'lar yazmaya da bağlıdır.
4. Israr Kazanır (Persistence Wins)
Başarıya ulaşana kadar denemeye devam edin. Döngü, yeniden deneme mantığını otomatik olarak halleder.
Ralph Ne Zaman Kullanılır? (When to Use Ralph)
İyi olduğu durumlar:
- Net başarı kriterleri olan, iyi tanımlanmış görevler
- Yineleme ve iyileştirme gerektiren işler (örneğin testleri geçirme)
- Başında beklemeden çalıştırabileceğiniz yeşil alan (greenfield) projeler
- Otomatik doğrulama araçları olan işler (testler, linter'lar)
İyi olmadığı durumlar:
- İnsan yargısı veya tasarım kararları gerektiren görevler
- Tek seferlik işlemler
- Net olmayan başarı kriterleri olan görevler
- Üretim hata ayıklama (bunun için hedefe yönelik hata ayıklama kullanın)
Gerçek Dünya Sonuçları (Real-World Results)
- Y Combinator hackathon testinde bir gecede başarıyla 6 depo oluşturuldu
- 50.000$'lık bir sözleşme, yalnızca 297$ API maliyetiyle tamamlandı
- Bu yaklaşım kullanılarak 3 ay içinde "cursed" adlı tam bir programlama dili oluşturuldu
Daha Fazla Bilgi (Learn More)
- Orijinal teknik: https://ghuntley.com/ralph/
- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator
Yardım için: Claude Code'da /help komutunu kullanarak detaylı komut referansına ve örneklere ulaşabilirsiniz.
Örnek Kullanım Senaryosu
Bir geliştirici, yeni bir mikroservis projesi için test odaklı geliştirme (TDD) sürecini otomatize etmek istiyor. İşte adım adım Ralph Wiggum Loop kullanımı:
Adım 1: Proje dizininde Claude Code oturumu başlatılır.
Adım 2: Aşağıdaki komut çalıştırılır:
/ralph-loop "
Bir kullanıcı yönetim mikroservisi oluştur.
Gereksinimler:
- Kullanıcı kaydı (POST /users)
- Kullanıcı girişi (POST /auth/login)
- Profil görüntüleme (GET /users/:id)
- JWT tabanlı kimlik doğrulama
- Express.js + TypeScript kullan
- Jest ile testler yaz
TDD süreci:
1. Her endpoint için önce test yaz
2. Test başarısız olacak (kırmızı)
3. Endpoint'i uygula
4. Test geçene kadar düzelt (yeşil)
5. Gerekirse yeniden düzenle (refactor)
6. Sonraki endpoint'e geç
Tüm testler geçtiğinde ve tüm endpoint'ler çalıştığında:
<promise>TAMAMLANDI</promise> çıktısı ver.
" --completion-promise "TAMAMLANDI" --max-iterations 30
Adım 3: Claude Code, Ralph döngüsüne girer:
- İlk yinelemede proje yapısını oluşturur ve ilk testi yazar
- Test başarısız olur, Claude endpoint'i uygular
- Test geçer, Claude sonraki endpoint'e geçer
- Bir endpoint'te hata çıkarsa, Claude hatayı analiz eder ve düzeltir
- Her yinelemede git commit'i atılır
Adım 4: Geliştirici, döngü çalışırken başka bir işle ilgilenir. Döngü tamamlandığında <promise>TAMAMLANDI</promise> çıktısını görür.
Adım 5: Eğer 30 yineleme sonunda hala tamamlanmamışsa, döngü otomatik olarak durur. Geliştirici, /cancel-ralph ile de istediği an döngüyü iptal edebilir.
Adım 6: Geliştirici, git log'u inceleyerek her yinelemede neler yapıldığını görür ve gerekirse son commit'ten itibaren manuel düzeltmeler yapar.