Claude Code’u bir Ruby on Rails projesinde kullanmak için proje klasöründe terminalde claude komutunu çalıştırmanız yeterli. Rails’in güçlü konvansiyonları ve test alışkanlıkları, ajanın küçük adımlarla güvenli değişiklik yapmasına çok uygundur. Bu rehber, CLAUDE.md kurulumundan çoklu ajan kullanımına kadar uygulamalı bir çalışma akışı sunar.
Claude Code Ruby on Rails işleri için neden uygun?
Claude Code, dosya sistemini ve terminali doğrudan kullanabildiği için Rails’in MVC yapısını, Active Record modellerini ve migration akışını kolayca kavrar. rails generate çıktılarını okuyabilir, testleri çalıştırabilir ve hata mesajlarına göre düzeltme yapabilir. Özellikle “convention over configuration” ilkesi sayesinde projede nereye bakacağını bilir: modeller app/models, controller’lar app/controllers içindedir. Ayrıca Rails’te güçlü bir test kültürü olduğu için ajanın yaptığı değişiklikleri doğrulamak kolaydır; bundle exec rspec veya bundle exec rails test komutu hızlıca geri bildirim verir. Bu da Claude Code’un “küçük adım at, test et, devam et” döngüsüyle birebir örtüşür.
Ajan, config/routes.rb dosyasını okuyarak mevcut route’ları analiz edebilir ve yeni bir endpoint eklerken uygun controller action’ını doğru şekilde bağlayabilir. db/schema.rb veya structure.sql üzerinden veritabanı şemasını anlar ve Active Record sorgularını buna göre yazar. RSpec veya Minitest testlerini çalıştırıp başarısız olanları düzeltebilir. Hotwire kullanıyorsanız, Turbo Streams ve Stimulus controller’larının nasıl organize edildiğini app/views ve app/javascript klasörlerinden öğrenir. Tüm bunlar, Rails’in öngörülebilir yapısı sayesinde Claude Code’ün hata yapma olasılığını azaltır ve geliştiricinin güvenini artırır.
Projeyi ajan için hazırlama ve CLAUDE.md
Claude Code, proje kökündeki CLAUDE.md dosyasını otomatik okur. Rails projesi için bu dosyaya build, test ve lint komutlarını, klasör konvansiyonlarını ve Rails’e özgü kuralları yazmak, ajanın yanlış varsayımlar yapmasını önler. CLAUDE.md, ajanın her görevde başvuracağı bir referans görevi görür; böylece her seferinde aynı komutları ve kuralları tekrar etmek zorunda kalmazsınız.
Örnek bir CLAUDE.md dosyası:
# CLAUDE.md
## Kurulum ve komutlar
- `bundle install` – gem'leri yükle
- `bin/rails db:migrate` – migration'ları uygula
- `bundle exec rspec` – tüm testleri çalıştır
- `bundle exec rubocop` – stil denetimi
## Klasör yapısı
- `app/models` – Active Record modelleri
- `app/controllers` – controller'lar
- `app/views` – view'lar
- `app/services` – iş mantığı için service object'leri
- `db/migrate` – migration'lar
## Kurallar
- `db/schema.rb` dosyasını asla elle düzenle; sadece migration yaz ve migrate et.
- Controller'larda business logic tutma; service object kullan.
- Her model için en azından temel validation ve association testleri yaz.
- Hotwire kullanılıyorsa, Turbo Streams ve Stimulus controller'larını ilgili view klasörlerine yerleştir.Bu dosya, ajanın Rails projesine özgü yaklaşımı öğrenmesini sağlar. Özellikle db/schema.rb kuralı kritik önem taşır; çünkü ajan bazen hızlı bir düzeltme yapmak için şema dosyasını doğrudan değiştirmeye çalışabilir. Aynı şekilde controller’larda iş mantığı yazmaması gerektiğini belirtmek, ileride oluşabilecek teknik borcu önler. İsterseniz Claude Code’ün en iyi pratikleri için Claude Code en iyi pratikler: uygulamalı kontrol listesi yazısına bakabilirsiniz.
Çalışma döngüsü ve örnek komutlar
Claude Code ile Rails’te verimli çalışmanın temeli, her görevi planla, küçük adımlara böl, testleri çalıştır ve diff’i incele şeklinde ilerlemektir. Önce ajanın ne yapacağını açıkça tarif edin, sonra tek seferde çok fazla değişiklik istemeyin. Her adımdan sonra git diff ile değişiklikleri gözden geçirin. Ajan, doğru yönlendirmelerle çok daha başarılı olur; örneğin “Post modeline bir scope ekle” yerine “Post modelinde yayınlanmış gönderileri getiren published scope’unu ekle ve testiyle birlikte yaz” demek daha nettir.
Tipik Rails görevleri için şu komutlar işe yarar:
- “Yeni bir
Postmodeli oluştur,titlevebodyalanları olsun. Migration’ı yaz,rails db:migrateçalıştır ve model testini ekle.” - “
PostsController#indexaction’ında N+1 sorguyuincludesile düzelt; ardından ilgili request spec’ini güncelle.” - “
app/services/order_creator.rbiçindekicreatemetodunu refactor et; exception handling ekle ve unit testi yaz.” - “Hotwire ile canlı yorum eklemek için
Commentmodelineafter_create_commitcallback’i vebroadcast_append_tokullan; gerekli Turbo Stream view’ını oluştur.” - “RSpec’te başarısız olan
spec/models/user_spec.rbdosyasındaki hatayı bul ve düzelt; sadece ilgili testi çalıştır.”
Bu komutları verirken, ajanın hangi test dosyasını çalıştıracağını ve hangi dosyaları değiştireceğini netleştirin. Ayrıca büyük bir özellik isteğini parçalara bölmek en iyisidir: önce migration ve model, sonra controller, daha sonra view ve testler gibi. Her adımda testleri çalıştırıp commit atmak, hata ayıklamayı kolaylaştırır. Claude Code’ü başlatmak ve temel kullanım için Claude Code sayfasına göz atabilirsiniz.
Hangi görevlerde iyi, nerelerde dikkatli olmalı
Aşağıdaki tablo, Rails’te Claude Code’ün güçlü olduğu alanları ve dikkat edilmesi gereken senaryoları özetler:
| Görev | İyi prompt örneği | Dikkat edilecek nokta |
|---|---|---|
| Migration ve şema değişikliği | “users tablosuna role kolonu ekleyen migration yaz, default ‘user’ olsun ve index ekle.” | schema.rb’yi elle değiştirme; migration’ı çalıştırıp test et. |
| Model ilişkileri ve scope’lar | “Post modeline belongs_to :user ve scope :published, -> { where(published: true) } ekle.” | Association’ların bağımlılıklarını (dependent: :destroy) kontrol et. |
| Controller refactor | “UsersController#create metodunu service object’e taşı ve Strong Parameters kullan.” | Controller’da transaction ve hata yönetimini unutma. |
| View ve Hotwire | “app/views/posts/index.html.erb içindeki listeyi Turbo Frame ile parçala.” | Turbo Stream yanıtlarında partial isimlerini ve DOM id’lerini doğru eşle. |
| Test yazma | “spec/requests/posts_spec.rb içinde index action için başarılı istek testi ekle.” | Factory’lerin ve let tanımlarının mevcut düzene uyduğundan emin ol. |
Claude Code genellikle mevcut kodu takip ederek yeni özellik eklemede başarılıdır, ancak büyük refactor’lerde iş mantığını yanlış anlayabilir. Özellikle callback’ler, transaction’lar ve çok katmanlı service object’lerde dikkatli olun; ajanın önerdiği değişiklikleri her zaman testlerle doğrulayın. Bir diğer dikkat edilmesi gereken nokta, migration’ların geri alınabilirliğidir; ajan bazen change metodu yerine up ve down kullanılması gereken durumları gözden kaçırabilir. Ayrıca, eğer projede birden fazla developer çalışıyorsa, ajanın db/schema.rb üzerinde oluşturacağı çakışmaları önlemek için migration’ları dikkatli yönetmek gerekir. Rails’in otomatik timestamp’leri ve veritabanı kısıtlamaları konusunda da ajanı yönlendirmek faydalı olur.
Test ve doğrulama
Claude Code ile Rails’te en kritik adım, her değişiklikten sonra testleri çalıştırmaktır. Ajan, test komutunu kendisi çalıştırabilir; siz de bundle exec rspec veya bundle exec rails test ile sonucu kontrol edebilirsiniz. Ajanın testleri geçtiğini söylemesi yeterli değildir; git diff ile gerçek değişiklikleri inceleyin ve test kapsamını değerlendirin. Özellikle migration eklerken db:test:prepare veya db:migrate komutlarının çalıştığından emin olun. RSpec kullanıyorsanız, ajanın yazdığı testlerin gerçekten anlamlı assertion’lar içerdiğini kontrol edin. Ayrıca RuboCop gibi stil denetimlerini de ajanın çalıştırmasını isteyebilirsiniz. Bu döngü, Rails’in hızlı geri bildirim avantajını Claude Code ile birleştirir.
Test veritabanı ile ilgili sorunlar yaşanabilir; ajan db:test:prepare yerine db:migrate çalıştırarak şemayı bozabilir. Bu nedenle CLAUDE.md dosyasına test veritabanı hazırlama komutunu eklemek iyi bir fikirdir. Ayrıca, Spring veya Zeus gibi önyükleyiciler kullanıyorsanız, ajanın bu süreçleri başlatıp başlatmayacağını belirtmek faydalıdır. Büyük test süitlerinde ajanın tüm testleri çalıştırması zaman alabilir; böyle durumlarda sadece ilgili test dosyalarını veya --tag gibi filtreleri kullanmasını isteyin. Son olarak, ajanın yazdığı testlerin deterministik olmasına dikkat edin; özellikle zaman, sıra bağımlılığı veya dış servis çağrıları içeren testlerde yanlış pozitif sonuçlar alabilirsiniz.
Aynı projede birden fazla ajan: AgentVera
Rails projelerinde birden fazla Claude Code ajanını paralel çalıştırmak istediğinizde AgentVera devreye girer. Özellikle her ajanın kendi git worktree’sinde çalışması, aynı dosyaları ezme riskini ortadan kaldırır; böylece biri model üzerinde çalışırken diğeri view veya test yazabilir. Otomatik kod incelemesi, ajanın ürettiği kodu ikinci bir modelin kontrol etmesini sağlar ve bulguları dosya:satır olarak gösterir. Checkpoint’ler sayesinde her turun anlık görüntüsü alınır; yanlış bir değişiklik tek tıkla geri alınabilir. Token bütçeleri ise ajanların günlük kullanımını sınırlandırarak maliyet kontrolü sağlar. Rails’in çok katmanlı yapısında bu özellikler, paralel geliştirmeyi güvenli hale getirir. Daha fazla bilgi için Birden fazla Claude Code ajanını paralel çalıştırma yazısına bakın.
Sonuç
Claude Code, Ruby on Rails projelerinde doğru kurulum ve çalışma disiplini ile ciddi zaman kazandırır. CLAUDE.md dosyasını projeye göre özelleştirin, görevleri küçük parçalara bölün ve her adımda testleri çalıştırın. Bu yaklaşım, Rails’in konvansiyonlarını ve test kültürünü ajanın yetenekleriyle birleştirir. Paralel çalışma ihtiyacınız olduğunda AgentVera gibi araçlarla worktree ve checkpoint özelliklerinden yararlanarak güvenliği artırabilirsiniz. Unutmayın: ajan bir yardımcıdır; nihai kontrol her zaman geliştiricidedir.