# Claude Code ile Ruby on Rails Geliştirme Rehberi

Adres: https://agentvera.dev/blog/claude-code-ile-rails/ · Yayın: 2026-11-01

Ruby on Rails projelerinde Claude Code ile verimli çalışmak için CLAUDE.md kurulumu, test döngüsü ve çoklu ajan kullanımı. Pratik rehber.

**Kısaca:**

- Claude Code, Rails’in konvansiyonlarını ve test kültürünü kullanarak küçük adımlarla güvenli değişiklik yapar.
- Proje köküne CLAUDE.md ekleyip build/test/lint komutlarını ve Rails kurallarını yazmak, ajanın doğru çalışmasını sağlar.
- Her görevden sonra testleri çalıştırıp diff incelemek ve gerekirse AgentVera ile paralel ajanları worktree’de yönetmek gerekir.

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ı:

```markdown
# 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](/blog/claude-code-en-iyi-pratikler/) 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 `Post` modeli oluştur, `title` ve `body` alanları olsun. Migration’ı yaz, `rails db:migrate` çalıştır ve model testini ekle."
- "`PostsController#index` action’ında N+1 sorguyu `includes` ile düzelt; ardından ilgili request spec’ini güncelle."
- "`app/services/order_creator.rb` içindeki `create` metodunu refactor et; exception handling ekle ve unit testi yaz."
- "Hotwire ile canlı yorum eklemek için `Comment` modeline `after_create_commit` callback’i ve `broadcast_append_to` kullan; gerekli Turbo Stream view’ını oluştur."
- "RSpec’te başarısız olan `spec/models/user_spec.rb` dosyası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](/ajanlar/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](/blog/birden-fazla-claude-code-ajani/) 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.

## Sık sorulanlar

**Claude Code Ruby on Rails projesinde nasıl kullanılır?** Proje klasöründe terminalde claude komutunu çalıştırın. Ajan, CLAUDE.md dosyasını okuyarak Rails komutlarını ve kurallarını öğrenir. Görevleri küçük parçalara bölüp her adımda testleri çalıştırarak ilerleyin.

**Claude Code için Rails projesine ne yazmalıyım CLAUDE.md dosyasına?** CLAUDE.md dosyasına bundle install, rails db:migrate, test ve lint komutlarını yazın. Ayrıca klasör yapısını ve Rails’e özgü kuralları (ör. schema.rb’yi elle düzenlemeyin) belirtin.

**Claude Code Rails’te migration yazabilir mi?** Evet, migration dosyası oluşturabilir, rails db:migrate çalıştırabilir ve şemayı güncelleyebilir. Ancak schema.rb dosyasını asla elle düzenlememesi gerektiğini CLAUDE.md’de vurgulayın.

**Claude Code ile Rails testlerini nasıl çalıştırırım?** Ajana 'bundle exec rspec' veya 'bundle exec rails test' komutunu çalıştırmasını söyleyebilirsiniz. Ajan, test sonuçlarına göre hataları düzeltebilir. Her değişiklikten sonra kendiniz de testleri çalıştırıp doğrulayın.

---

**AgentVera hakkında.** AgentVera, Solviera Teknoloji tarafından geliştirilen macOS, Windows ve Linux masaüstü uygulamasıdır. 18 yapay zeka kodlama ajanını (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) proje bazında, gerçek terminallerde ve kullanıcının kendi CLI kurulum ve girişleriyle yan yana çalıştırır. Ücretsiz planda sınırsız ajan vardır. İndir: https://agentvera.dev/indir/ · Fiyatlar: https://agentvera.dev/fiyatlar/