Gemini CLI Ruby on Rails: Rails Projelerinde Kullanım Rehberi

Gemini CLI’yi bir Ruby on Rails projesinde gemini komutuyla başlatıp, kök dizine GEMINI.md ekleyerek Rails konvansiyonlarına uygun bir ajan kurarsınız. Bu rehberde, ajanın migrasyon, model, controller, test ve Hotwire işlerinde nasıl kullanılacağını adım adım anlatıyorum. Amaç, Rails’i bilen bir geliştiricinin ajanı hızlıca güvenli bir iş ortağına dönüştürmesi; ayrıntılı kurulum için Gemini CLI sayfasına bakabilirsiniz.

Neden Gemini CLI Rails projelerine uygun

Rails “convention over configuration” ilkesiyle çalıştığı için dosya yolları ve adlandırmalar öngörülebilirdir. Gemini CLI, app/models, app/controllers, db/migrate gibi dizinleri tanıyıp doğru yere kod üretebilir. bin/rails komutlarını çalıştırabilir, db/schema.rb dosyasını okuyabilir, Active Record ilişkilerini, scope’ları, validasyonları ve strong parameters kurallarını anlayabilir. Rails’in test kültürü sayesinde ajan, önce test yazıp sonra kodu düzeltme döngüsüne kolayca girer. Ayrıca GEMINI.md dosyasına yazacağınız komutlar, ajanın her seferinde aynı Ruby ve Rails komutlarını kullanmasını sağlar; bu da çıktının projeye uyumunu artırır. Rails generator’ları (bin/rails generate model, bin/rails generate migration) ajanın dosya oluşturma işlerini standardize etmesine yardımcı olur. Hotwire kullanıyorsanız, ajan app/views içindeki *.turbo_stream.erb dosyalarını ve app/javascript/controllers altındaki Stimulus controller’larını Rails’in beklediği yapıda üretebilir.

Projeyi ajana hazırlamak: GEMINI.md

GEMINI.md dosyasını proje köküne koyun. Bu dosya, ajanın Rails projesini tanıması için en önemli girdidir. İçine test, lint, migration ve sunucu komutlarını; dizin kurallarını; Rails’e özgü kuralları yazın. Dosyayı projenin gerçek durumuna göre güncelleyin: Ruby sürümü, Rails sürümü, test framework’ü (Minitest veya RSpec) değişirse burayı da güncelleyin. Genel kurulum adımları için Gemini CLI nasıl kullanılır yazısına da bakabilirsiniz.

# GEMINI.md

## Komutlar
- Test: `bin/rails test` (Minitest) veya `bundle exec rspec` (RSpec)
- Lint: `bundle exec rubocop`
- Migration: `bin/rails db:migrate`
- Konsol: `bin/rails console`
- Sunucu: `bin/rails server`

## Dizin kuralları
- Model: `app/models`, controller: `app/controllers`, view: `app/views`
- Migration dosyaları `db/migrate` altında; mevcut migration'ları düzenleme, yalnızca yeni migration ekle
- Testler: Minitest ise `test/`, RSpec ise `spec/` altında

## Rails kuralları
- Business logic controller'da olmasın; model metotları veya service object kullan
- Strong parameters kullan; `permit` listesini eksiksiz yaz
- Active Record sorgularını scope veya sınıf metodu olarak modelde tut
- Hotwire kullanılıyorsa Turbo Streams için `app/views/**/*.turbo_stream.erb`, Stimulus controller'ları için `app/javascript/controllers` kullan
- Migration'larda `change` tercih et; geri alınamaz işlemler için `up`/`down` yaz
- Şema değişikliklerinde `db/schema.rb` dosyasını commit'e ekle

Bu dosyada Ruby sürümünü de belirtebilirsiniz; örneğin .ruby-version dosyasına atıf yapın. Ajan, db/schema.rb dosyasını okuyarak mevcut tablo yapısını öğrenir, bu yüzden schema’yı güncel tutmak ajanın doğru migration ve model kodu üretmesi için kritiktir. Eğer RSpec kullanıyorsanız spec/ dizinini, Minitest kullanıyorsanız test/ dizinini açıkça belirtin; aksi halde ajan yanlış yere test dosyası koyabilir. Ayrıca RuboCop konfigürasyonunuz varsa (.rubocop.yml) ajanın bu dosyayı da dikkate almasını söyleyin. GEMINI.md’yi olabildiğince kısa ve net tutun; ajan, proje hakkında gereksiz bilgi yüklendiğinde önemli kuralları gözden kaçırabilir.

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

Gemini CLI ile Rails’te çalışırken şu döngüyü izleyin: görevi küçük parçalara bölün, ajanın önce plan önermesini isteyin, sonra tek bir değişiklik yaptırın, testleri çalıştırın ve git diff ile farkı inceleyin. Eğer test kırmızıysa hatayı ajanla birlikte düzeltin; yeşilse bir sonraki küçük göreve geçin. Bu döngü, Rails’in birbirine bağlı katmanlarında hataların erken yakalanmasını sağlar. Prompt yazımıyla ilgili daha genel ipuçları için Kodlama ajanları için prompt yazmak sayfasına bakabilirsiniz.

Örneğin Post modeline yorum ekleme görevi için şu adımları izleyin: önce “Post ile Comment arasında nasıl bir ilişki kurmalıyız? Migration, model ve testler için bir plan öner” diye sorun. Ajan plan verince planı gözden geçirin; gereksiz varsayımlar varsa düzeltin. Sonra “Yalnızca migration dosyasını üret, değişiklik yapma” deyin. Migration’ı inceleyip bin/rails db:migrate çalıştırın. Ardından “Post modeline has_many :comments, dependent: :destroy ekle ve ilgili model testini yaz” komutunu verin. Testleri kendiniz çalıştırıp git diff ile kodu kontrol edin. Son olarak “CommentsController için gerekli aksiyonları ve Hotwire kullanıyorsak Turbo Streams view’lerini oluştur” diyebilirsiniz. Her adımda ajanın çıktısını doğrulamak, Rails projesinin bütünlüğünü korur.

Tipik Rails görevleri için kullanabileceğiniz örnek promptlar:

• “User modeline email için format ve uniqueness validasyonu ekle, karşılık gelen testi yaz ve bin/rails test test/models/user_test.rb komutuyla çalıştır.”
• “Post modeline comments için has_many ilişkisi ekle, bağımlılık destroy olsun; gerekli migration’ı üret ve bin/rails db:migrate çalıştır.”
• “PostsController#create aksiyonunu service object’e taşı; controller’da yalnızca strong parameters ve yönlendirme kalsın, mevcut testleri güncelle.”
• “Yeni Comment oluşturulunca create.turbo_stream.erb ile listeye ekleyen Hotwire akışını yaz; gerekli Stimulus controller’ı ekle.”
• “RSpec’te şu model spec’indeki hataları düzelt ve bundle exec rspec spec/models/post_spec.rb komutunu çalıştır.”

Bu promptlarda görevi, beklenen çıktıyı ve doğrulama komutunu birlikte vermek ajanın başarı oranını artırır. Ajanın çalıştırdığı komutların çıktısını da gözlemleyin; örneğin test başarısız olduysa ajanın hatayı doğru okuyup okumadığını kontrol edin.

İyi gittiği işler ve dikkat edilecek noktalar

Gemini CLI, Rails’te özellikle şu işlerde iyi çalışır: yeni migration üretme, model validasyonları ve ilişkileri, scope’lar, RSpec veya Minitest testleri yazma, basit controller aksiyonlarını düzenleme, Hotwire partial’ları ve Stimulus controller’ları ekleme. Projeyi tanıdıktan sonra db/schema.rb ve mevcut testlerden yola çıkarak tutarlı kod üretebilir. Ajan, bin/rails generate komutlarını da kullanabilir; bu sayede dosya adları ve yerleri Rails’e uygun olur.

Buna karşılık Rails’e özgü tuzaklarda ajanı yakından izleyin. En kritik alan migration’lardır: ajan mevcut bir migration dosyasını düzenlemeye çalışabilir, geri alınamaz bir up/down yazabilir veya change ile geri alınamayacak bir işlem üretebilir. db/schema.rb dosyasında çakışma yaratmaması için her migration sonrası git diff db/schema.rb çıktısını kontrol edin. Diğer dikkat noktaları: strong parameters listelerini eksik bırakması, controller’a business logic koyması, update_all gibi callback’leri atlayan yöntemleri gereksiz kullanması, N+1 sorgu üretmesi ve Ruby/Rails sürümünüze uymayan API’leri çağırması. Ajanın ürettiği kodu kabul etmeden önce bu alanlara odaklanın. Ayrıca auth, ödeme entegrasyonu, karmaşık arka plan işleri gibi konularda ajanın önerdiği çözümleri mutlaka kendiniz doğrulayın; güvenlik açıkları veya veri bütünlüğü sorunları oluşabilir.

Test ve doğrulama

Gemini CLI testleri çalıştırabilir, ancak sonucu doğrulamak sizin sorumluluğunuzdadır. Her ajan turundan sonra testleri kendiniz çalıştırın; ajan “testler geçti” dese bile git diff ile değişiklikleri inceleyin. Rails’te test komutları ve amaçları şöyledir:

| Komut | Amaç | | bin/rails test | Minitest testlerini çalıştırır | | bundle exec rspec | RSpec testlerini çalıştırır | | bundle exec rubocop | Stil ve basit hataları denetler | | git diff | Ajanın yaptığı değişiklikleri satır satır gösterir | | bin/rails db:migrate:status | Migration durumunu gösterir |

Yeni bir özellik eklerken ajandan önce test yazmasını isteyin; sonra bu testi çalıştırıp kırmızı olduğunu görün, ardından kodu yazdırın. Migration sonrası bin/rails db:migrate çalıştırıp db/schema.rb dosyasının değiştiğini doğrulayın. RuboCop çıktısını da kontrol edin; Rails projelerinde stil hataları bazen gerçek hataların habercisidir. Ayrıca bin/rails test veya bundle exec rspec komutlarını ajanın çalıştırmasına izin verebilirsiniz, ancak testlerin tamamını çalıştırmak uzun sürebilir; bu yüzden ajanın yalnızca ilgili test dosyasını çalıştırmasını isteyin. Eğer factory veya fixture kullanıyorsanız, ajanın bunları doğru şekilde güncellediğinden emin olun. Son olarak git status ile beklenmeyen dosya değişikliklerini kontrol edin; ajan bazen config/routes.rb veya Gemfile gibi dosyaları düzenleyebilir.

Birden fazla ajanı AgentVera ile çalıştırmak

AgentVera, ajanların gerçek komut satırı araçlarını aynı pencerede yan yana çalıştırır. Rails projesinde her ajanı ayrı git worktree’de koşturmak, aynı db/migrate dosyasına aynı anda yazmalarını engeller. Bir ajan turu bitince ikinci model kod incelemesi yapar; bulgular file:line ile bağlanır ve Rails’e özgü callback veya migration hatalarını yakalamayı kolaylaştırır. Token bütçeleri ajan başına, tur başına ve günlük olarak sınır koyar; %80’de uyarır, sınırda durdurur. Böylece birden çok Rails görevi paralel ilerlerken proje bütünlüğü korunur.

Kapanış

Gemini CLI, Rails projelerinde iyi hazırlanmış bir GEMINI.md ve disiplinli bir test-diff döngüsüyle ciddi zaman kazandırır. Görevleri küçük tutun, ajanın ürettiği migration ve schema değişikliklerini her zaman inceleyin, testleri kendiniz doğrulayın. Bu rehberdeki kuralları uyguladığınızda ajan, Rails konvansiyonlarına uygun, güvenilir bir yardımcıya dönüşür.