Cursor Agent Ruby on Rails: Rails Projelerinde Kullanım Rehberi

Cursor Agent, proje klasöründe cursor-agent komutuyla başlatılan terminal tabanlı bir kodlama ajanıdır. Ruby on Rails projelerinde migration, model, controller, Hotwire parçaları ve testlerde dar kapsamlı değişiklikleri çalıştırmak için iyi bir yardımcıdır. Cursor Agent sayfası ajanın genel kullanımını özetler; bu yazı Rails’e özel pratik bir akış sunar.

Neden Cursor Agent Ruby on Rails işlerine uyar

Rails’in dosya düzeni ve adlandırma kuralları tahmin edilebilirdir. Ajan, app/models, app/controllers, app/views, db/migrate ve test klasörlerini kolayca gezer; rails generate ve bin/rails test gibi komutları doğrudan çalıştırabilir. Model ilişkileri, validasyonlar ve callback’ler dosya içinde açıkça görülür, bu da dar kapsamlı düzenlemeleri verimli kılar. Aynı şekilde Hotwire bileşenleri (Turbo Streams, Stimulus controller’ları) küçük ve izole dosyalardır; ajan, view ile ilgili parçayı birlikte güncelleyebilir. Ruby’nin metaprogramlama tarafları bazen ajanı yanıltabilir, ancak iyi bir test suite ve net AGENTS.md talimatları bunu telafi eder. Cursor Agent’ın diff tabanlı çalışma biçimi, Rails geliştiricisinin zaten alışkın olduğu inceleme döngüsüne oturur.

Rails’in öngörülebilir yapısı, ajanın dosyalar arasında bağlantı kurmasını kolaylaştırır. Bir controller’daki before_action veya modeldeki has_many ilişkisi, ilgili dosyaların nerede olduğunu açıkça gösterir. Ajan, rake routes benzeri çıktıyı okuyup hangi route’un hangi action’a gittiğini anlayabilir. Ayrıca Rails’in üreteçleri (rails generate migration, rails generate model) komut satırından çalıştırılabildiği için ajan, iskelet dosyaları kendisi oluşturabilir; siz yalnızca üretilen diff’i inceleyerek yön verirsiniz. Ancak ajanın Rails’in örtük kurallarını (örneğin app/models/concerns veya app/services gibi otomatik yüklenen klasörlerdeki dosya/class adı uyumunu) bilmesi gerekir. Bu yüzden proje talimatlarına bu konvansiyonları eklemek faydalıdır. Cursor CLI nasıl kullanılır? Adım adım rehber sayfasındaki kurulum adımları, ajanın projeyi ilk kez nasıl gördüğünü anlamak için yararlıdır.

Projeyi ajan için hazırlamak

cursor-agent başlatıldığında proje kökündeki AGENTS.md veya .cursor/rules dosyalarını okur. Rails projesi için bu dosyaya build, test, lint komutlarını ve klasör kurallarını yazın. Kurulum ve ilk çalıştırma adımları için Cursor CLI nasıl kullanılır? Adım adım rehber sayfasına bakabilirsiniz. Aşağıdaki örnek, tipik bir Rails projesi için kısa ama yeterli bir talimat dosyasıdır:

# Ruby on Rails projesi için Cursor Agent talimatları

## Komutlar
- Test: `bin/rails test` (Minitest) veya `bin/rspec` (RSpec)
- Lint: `bin/rubocop`
- Veritabanı: `bin/rails db:migrate db:test:prepare`
- Sunucu: `bin/dev`

## Klasör kuralları
- Modeller `app/models` altında, tablo adıyla uyumlu.
- Controller'lar `app/controllers` altında, RESTful resource'lara sadık kal.
- View'lar `app/views/<controller>/<action>` altında.
- Migration dosyaları `db/migrate` altında, sıra numarasına dokunma.

## Rails'e özgü kurallar
- Migration'ı asla otomatik çalıştırma; önce diff göster, sonra kullanıcı onayı al.
- Model ilişkilerini ve callback'leri değiştirirken ilgili testleri de güncelle.
- Hotwire kullanılıyorsa Turbo Streams ve Stimulus controller'larını ilgili view ile birlikte düşün.
- `rails generate` kullanırken mevcut dosyaların üzerine yazma; eksik parçaları elle ekle.
- Testlerde fixture/factory tutarlılığını koru.

Bu dosyayı kısa tutun; ajan her turda yeniden okur, gereksiz uzunluk dikkati dağıtır. Ayrıca Ruby sürümü ve Rails sürümünü buraya eklemek, ajanın API kullanımını doğru yapmasına yardımcı olur. Örneğin Ruby 3.2, Rails 7.1 ve RSpec 6 gibi bilgiler, ajanın generate komutlarına uygun seçenekler vermesini sağlar.

Eğer projede birden fazla geliştirici varsa, AGENTS.md’yi versiyon kontrolüne ekleyin; böylece herkes aynı talimatları kullanır. .cursor/rules klasörü ise daha ayrıntılı kural dosyaları için uygundur. Ajanın Rails’e özgü tehlikeli işlemleri (örneğin db:drop, db:reset, rails db:rollback) yapmasını yasaklayan bir kural eklemek de güvenliği artırır.

Çalışma döngüsü ve örnek promptlar

Ajanla çalışırken planı küçük parçalara bölün, her turda tek bir amaca odaklanın. Önce prompt verin, sonra ajanın ürettiği diff’i inceleyin, ardından ilgili testleri çalıştırın. Testler geçmiyorsa hatayı ajanla paylaşın ve düzeltmesini isteyin. Aşağıdaki promptlar Rails projelerinde sık kullanılan görevler için örnektir:

• RSpec’te spec/models/user_spec.rb dosyasına validates :email, presence: true için geçerli ve geçersiz iki test ekle; sadece bu dosyayı değiştir ve bin/rspec spec/models/user_spec.rb çalıştır.
• app/controllers/posts_controller.rb içindeki create aksiyonuna strong parameters ekle; izin verilecek parametreleri params.require(:post).permit(:title, :body, :user_id) olarak belirle, ilgili request spec’i de güncelle.
• db/migrate içinde add_index :posts, :user_id ve add_foreign_key :posts, :users için bir migration oluştur; çalıştırmadan önce diff’i göster, bin/rails db:migrate komutunu kendin çalıştırma.
• app/views/posts/create.turbo_stream.erb dosyası oluştur; posts_controller.rb içindeki create action’ına format.turbo_stream yanıtını ekle ve app/views/posts/create.html.erb dosyasını buna göre sadeleştir; ilgili system testini de güncelle.
• config/routes.rb içinde resources :users do resources :posts end nested yapısına geç; PostsController’daki user bulma mantığını ve ilgili request spec’leri buna göre düzenle, testleri çalıştır.

Bu promptların ortak noktası, ajanın tam olarak hangi dosyaları değiştireceğini ve hangi testleri çalıştıracağını bilmesidir. Eğer daha karmaşık bir refactor yapıyorsanız, önce ajanın bir plan çıkarmasını isteyin; sonra planı onaylayıp adım adım uygulamasına izin verin. Ajan her tur sonunda kendi yaptığı değişiklikleri özetler; bu özeti okumadan bir sonraki adıma geçmeyin.

Hangi görevlerde iyi, nerelerde dikkat

Ajan özellikle model validasyonu, association, scope ekleme, migration oluşturma, strong parameters düzenleme, route güncelleme ve test yazma işlerinde başarılıdır. Aşağıdaki tablo bazı tipik görevleri ve dikkat noktalarını özetler:

Şu noktalarda ajanı yakından izleyin: migration’ları otomatik çalıştırması, model callback’leri değiştirirken yan etkileri gözden kaçırması, N+1 sorguları eklemesi, Zeitwerk otomatik yükleme kurallarına uymayan dosya/class adı üretmesi ve rake yerine rails komutlarını karıştırması. Hotwire işlerinde partial’ların doğru DOM id’lerini kullandığından emin olun.

Ayrıca, ajanın has_secure_password veya enum gibi Rails’e özgü makroları eklerken şifre hash’leme veya enum değerlerinin sabit kalması gerektiğini unutabileceğini bilin. Örneğin enum status: { draft: 0, published: 1 } gibi bir tanımın mevcut veritabanı kayıtlarıyla uyumlu olması gerekir; ajan bu tür veri bütünlüğü konularında dikkatsiz olabilir. Aynı şekilde dependent: :destroy gibi ilişki seçeneklerini değiştirirken veri kaybına yol açabilecek davranışları öngöremeyebilir. Bu yüzden her değişiklikte ilgili model testlerinin yanı sıra veritabanı yapısını da incelemek şarttır.

Test ve doğrulama

Ajanın ürettiği her değişiklikten sonra ilgili testleri çalıştırın. Migration değişikliklerinde bin/rails db:migrate db:test:prepare komutunu siz çalıştırın ve db/schema.rb diff’ini ayrıca inceleyin. Hotwire veya Stimulus içeren değişikliklerde system testleri yoksa tarayıcıda elle test edin. Tüm tur tamamlanınca bin/rails test veya bin/rspec ile tam suite’i çalıştırıp RuboCop’u geçirin. Ajan bir commit mesajı önerirse, önce git diff ile değişiklikleri gözden geçirin; Rails’e özgü yan etkileri ancak siz doğrulayabilirsiniz.

Özellikle system testleri, Turbolinks/Turbo geçişleri ve JavaScript davranışlarını doğrulamak için kritiktir. Eğer Capybara veya Playwright kullanıyorsanız, ajanın eklediği Turbo Stream DOM id’lerinin gerçek sayfadaki id’lerle eşleştiğini test edin. Ajan yalnızca Ruby tarafını test edebilir; tarayıcıda görsel doğrulama sizin sorumluluğunuzdur. Ayrıca RuboCop’un Rails’e özel cop’ları (Rails/...) bazen ajanın yazdığı kodu şikayet edebilir; bu uyarıları dikkate alın.

Aynı projede birden fazla ajan: AgentVera

Aynı Rails projesinde birden fazla Cursor Agent çalıştırmak isterseniz AgentVera işe yarar. Ajanlar kendi git worktree’lerinde paralel çalışabildiği için migration, model ve test dosyaları birbirinin üzerine yazmaz. Bir ajan turu bitince ikinci bir model otomatik kod incelemesi yapar ve bulguları file:line ile bağlar; Rails’te callback veya N+1 gibi sorunları yakalamak için etkilidir. Checkpoint’ler her turun anlık görüntüsünü alır, tek tıkla geri alınabilir ve oturum adım adım yeniden oynatılabilir. Token bütçeleri ise büyük bir Rails refactor’unda ajanın kontrolden çıkmasını önler. Paralel kodlama ajanları için en iyi araçlar (2026) sayfası bu tür paralel iş akışını anlatır.

Sonuç

Cursor Agent, Ruby on Rails projelerinde doğru talimatlar ve sıkı bir inceleme döngüsüyle güçlü bir yardımcıdır. AGENTS.md dosyanızı Rails’e özel tutun, her turda küçük adımlar atın, testleri çalıştırın ve diff’i inceleyin. Böylece agent, Rails’in getirdiği hızı artıran bir çift programcı gibi çalışır.