opencode ile Ruby on Rails projelerinde geliştirme rehberi

opencode, Rails proje klasöründe opencode komutuyla başlatılan bir komut satırı kodlama ajanıdır. Ruby on Rails projelerinde migration, model, controller, test ve Hotwire parçaları üzerinde çalışırken proje kökündeki AGENTS.md dosyasındaki talimatları okur. Bu rehber, Rails bilen geliştiriciler için opencode’u günlük akışa sokacak pratik bir çalışma düzeni sunar; temel kurulum için opencode sayfasına bakabilirsiniz.

opencode neden Ruby on Rails işlerine uygun?

Rails’in katmanlı yapısı ve güçlü konvansiyonları ajana net bir bağlam verir. app/models, app/controllers, app/views, test/ veya spec/ dizinlerinin yerleşik anlamları sayesinde opencode, dosya eklerken nereye gideceğini çıkarabilir. Generators aracılığıyla üretilen standart iskelet, modelin üreteceği kodu tahmin edilebilir kılar. Ayrıca bin/rails test ve bundle exec rspec gibi komutların çıktıları derleyici benzeri net hata mesajları verir. Bu da ajanın hata döngüsünü kısaltır. Hotwire işlerinde partial, Turbo Stream ve Stimulus controller yapıları da dosya adlarıyla bellidir. Bütün bunlar, insan denetimi ile küçük adımlarda ilerleyen bir ajana uygundur.

Ek olarak Rails, Active Record’un zengin sorgu arayüzü ve association tanımları sayesinde ajanın model ilişkilerini doğru tahmin etmesine yardımcı olur. Örneğin has_many :posts yazdığınızda ajan, Post modelinde belongs_to :user olduğunu varsayar ve migration’ı buna göre üretir. Controller katmanında before_action, strong_parameters ve respond_to blokları gibi desenler o kadar yaygındır ki ajan, var olan koddan örnek alıp tutarlı kod yazar. Test tarafında RSpec veya Minitest’in assertion stilleri bellidir; ajan, mevcut test dosyalarını örnek alarak aynı dile uygun testler üretir. Tüm bu özellikler, opencode’un Rails projelerinde hızlı ve az yanılmayla çalışmasını sağlar.

Projeyi ajana hazırlama: AGENTS.md

Rails deposunun köküne AGENTS.md ekleyin. Burada build, test ve lint komutlarını, dizin konvansiyonlarını ve Rails’e özel kuralları yazın. Ajan her turda bu dosyayı okuyup ona göre davranır. Kısa ve kesin olun; uzun felsefi metinler yerine çalıştırılabilir komutlar ve yasaklar koyun. Örnek:

# AGENTS.md

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

## Dizinler
- Modeller: `app/models`; servis nesneleri: `app/services`; policy: `app/policies`
- Request/spec: `spec/requests`, model spec: `spec/models`; fixture yerine factory kullan.

## Rails kuralları
- `db/schema.rb` dosyasını asla elle düzenleme; her şema değişikliği migration ile gelsin.
- Migration yazarken `change` tercih et; geri alınamayan işlemler için `up`/`down` kullan.
- Strong Parameters her controller'da ayrı tanımlansın; `permit!` kullanma.
- Callback'lerde yan etkili ağ çağrısı yapma; arka plan işine al.
- Hotwire'da Turbo Stream yanıtları için `respond_to` bloğunda `turbo_stream` formatını unutma.
- Her değişiklikten sonra ilgili testleri çalıştır.

AGENTS.md dosyasını projenizin gerçek yapısına göre özelleştirin. Örneğin RSpec kullanıyorsanız test komutunu bundle exec rspec olarak yazın; Minitest kullanıyorsanız bin/rails test yazın. FactoryBot kullanıyorsanız spec/factories dizinini belirtin; fixture kullanıyorsanız test/fixtures dizinini ekleyin. Ajanın yanlış dosyalara dokunmasını önlemek için db/seeds.rb, config/credentials.yml.enc gibi hassas dosyaları açıkça düzenlememesini söyleyin. Eğer projede RuboCop konfigürasyonu varsa, lint komutunu mutlaka ekleyin; ajan böylece stil hatalarını önceden düzeltebilir. Daha kapsamlı kurulum için opencode nasıl kullanılır? Adım adım rehber yazısına bakabilirsiniz.

Ayrıca AGENTS.md içine Rails sürümü, Ruby sürümü ve önemli gem’leri yazmak ajanın davranışını iyileştirir. Örneğin Rails 7.2, Ruby 3.3, gem 'devise', gem 'pundit' gibi satırlar, ajanın kod üretirken doğru API’yi kullanmasına yardımcı olur. Bu bilgi, özellikle authentication veya authorization gibi gem’lerle çalışırken kritik önem taşır. Ajan, yanlış gem sürümüne göre kod üretirse testler anlamsız hatalarla dolu olur.

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

Ajanı tek büyük görevle boğmayın. Önce tasarımı kendiniz parçalayın, sonra her adımı ayrı bir komut olarak verin. Ajan kodu ürettikten sonra git diff ile değişikliği inceleyin, ilgili testleri çalıştırın ve hata varsa aynı komut penceresinde düzeltme isteyin. Bu döngüyü şöyle özetleyebiliriz:

1. Görevi netleştirin: örneğin “Post modeline slug alanı ekle ve unique index oluştur”.
2. Ajan migration, model ve test dosyalarını üretsin.
3. git diff ile değişiklikleri inceleyin; özellikle migration ve schema.rb farklarına bakın.
4. bin/rails db:migrate db:test:prepare çalıştırın.
5. İlgili test suite’ini koşun: bundle exec rspec spec/models/post_spec.rb gibi.
6. Hata varsa, hatayı ajanı aynı oturuma yapıştırıp düzeltmesini isteyin.
7. Başarılıysa, git add ve anlamlı bir commit mesajıyla commit’leyin.

Aşağıdaki komut kalıpları Rails için iyi çalışır:

• User modeline status enum’u ekle; migration oluştur, model doğrulamalarını güncelle ve spec/models/user_spec.rb içinde yeni durumları test et.
• PostsController#create içindeki Strong Parameters’ı tag_list alanını kabul edecek şekilde güncelle; request spec ekle ve mevcut testleri bozma.
• Hotwire ile yorum ekleme akışı kur: Comment modeli, form partial’ı, create.turbo_stream.erb ve gerekli Stimulus controller’ı üret; testleri çalıştır.
• Dashboard#index içindeki N+1 sorguyu includes ile düzelt; ilgili view spec’i güncelle ve rubocop çalıştır.
• api/v1/posts endpoint’i için JSON serializer kullanarak index action’ını yaz; request spec ekle ve mevcut rotaları bozma.

Bu komutlarda her seferinde tek bir sorumluluğa odaklanın. Örneğin “enum ekle ve migration yaz” derken aynı anda model callback’leri eklemesini istemeyin; çünkü callback’ler beklenmedik yan etkilere yol açabilir ve test başarısızlıklarının kaynağını bulmak zorlaşır. Ajan yalnızca siz ne isterseniz onu yapmalı; gerisini siz kontrol edin.

opencode’in iyi yaptığı işler ve dikkat edilmesi gerekenler

opencode, Rails’te şu alanlarda etkilidir: generator komutlarını taklit eden dosya oluşturma, migration yazma, model ilişkileri ve doğrulamalar, controller refactor, RSpec/Minitest test taslağı çıkarma, partial ve Turbo Stream şablonları. Özellikle test çıktısına göre hata düzeltme döngüsü başarılıdır. Ajan, hata mesajını alıp sorunun kaynağını hızla bulur; örneğin ActiveRecord::RecordInvalid hatası aldığında validation’ı kontrol eder veya NoMethodError aldığında eksik helper’ı ekler.

Ancak şu noktalarda yakından denetleyin: migration’lar geri alınabilir olmalı; db/schema.rb yalnızca migration’lardan üretilmeli; callback’ler beklenmedik kayıt güncellemelerine yol açabilir; Strong Parameters eksikse form alanları sessizce yok sayılır; Zeitwerk adlandırma kuralları bozulursa otoload sessizce takılabilir. Ayrıca ajan bazen büyük bir refactor’ü tek seferde yapmaya kalkar; bu yüzden kapsamı küçük tutun.

Özellikle dikkat edilmesi gereken Rails’e özgü tuzaklar şunlardır:

• Migration geri alınamazsa: remove_column gibi tersine çevrilemeyen işlemlerde change yerine up/down kullanmasını isteyin. Ajan bazen change yazar ve down bloğu olmadan hata verir.
• Callback zincirleri: after_save içinde başka kayıt güncellemesi yapmak, transaction içinde sürpriz rollback’lere neden olabilir. Callback’leri yalnızca veri bütünlüğü için kullanmasını söyleyin.
• N+1 sorgular: Ajan, includes eklemeden each içinde ilişki çağırabilir. bullet gem’i kullanıyorsanız, bu hataları test ortamında yakalatın.
• Strong Parameters: Ajan bazen params[:post] doğrudan kullanır veya tüm alanları permit! ile geçer. AGENTS.md’de bu davranışı yasaklayın.
• Zeitwerk adlandırması: app/services altında my_service.rb dosyası MyService sınıfını içermelidir; ajan yanlış isimlendirme yaparsa otoload sessizce başarısız olur ve sınıf bulunamaz.

Rails dosyalarında ajanın görevini netleştirmek için şu eşlemeyi kullanın:

Test ve doğrulama

Ajanın ürettiği kodu asla test çalıştırmadan kabul etmeyin. Her tur sonunda bin/rails test veya bundle exec rspec çalıştırın. Özellikle migration sonrası bin/rails db:migrate db:test:prepare komutunu verin; aksi halde test veritabanı şeması eski kalır ve yanıltıcı hatalar üretir. git diff çıktısında db/schema.rb, config/routes.rb ve app/models altındaki değişiklikleri tek tek inceleyin. Ajan test yazarken bazen yalnızca mutlu yolu kapsar; belongs_to zorunluluğu, enum değerleri ve Strong Parameters eksiklerini siz ekleyin. Hata ayıklarken ajanın önerdiği düzeltmeyi uygulamadan önce testin gerçekten başarısız olduğundan emin olun.

RSpec kullanıyorsanız, ajanın describe, context, let ve before bloklarını doğru kullanmasını isteyin; gereksiz yere before(:all) yazmasını engelleyin çünkü test sırası bağımlılığı yaratır. Minitest’te ise setup ve teardown bloklarını temiz tutun. FactoryBot kullanıyorsanız, fabrikaların spec/factories altında olduğunu ve her model için ayrı fabrika dosyası olmasını hatırlatın. Ajan bazen fixture kullanmaya kalkar; AGENTS.md’de hangi yaklaşımı tercih ettiğinizi belirtin.

Ayrıca ajan, testleri çalıştırdıktan sonra çıktıyı yorumlamakta başarılıdır; ancak bazen yanlış assertion ekler veya testi geçecek şekilde kodu zayıflatır. Örneğin doğrulamayı test etmek yerine skip ekleyebilir veya assert true yazabilir. Bu tür hilelere karşı dikkatli olun; git diff içinde test dosyalarına bakın ve yüzeysel testler varsa geri çevirin.

Birden fazla ajanı tek Ruby on Rails projesinde çalıştırma

Birden fazla Rails görevini paralel yürütmek isterseniz AgentVera’yı kullanabilirsiniz. AgentVera, opencode dahil CLI ajanlarını gerçek terminal panellerinde yan yana çalıştırır. Her ajan kendi git worktree’sinde ilerleyebildiği için migration ve schema.rb çakışmaları büyük ölçüde önlenir. Ajan turu bittiğinde ikinci bir model kodu gözden geçirir; bulgular dosya:satır olarak bağlanır, bu da Rails’e özgü eksik index veya N+1 gibi sorunları yakalamayı kolaylaştırır. Her turun anlık görüntüsü checkpoint olarak saklanır ve tek tıkla geri alınabilir; böylece yanlış bir migration veya refactor’dan hızla dönülür. Token bütçeleri ise ajan başına sınır koyarak maliyeti kontrol altında tutar.

Özet

opencode, Rails projelerinde disiplinli bir yardımcıdır; ancak iyi bir AGENTS.md, küçük görevler ve test odaklı doğrulama olmadan değeri düşer. Ajanı migration ve Strong Parameters gibi alanlarda yakından izleyin, her turu git diff ve test koşusuyla kapatın. Doğru kurulumla opencode, Rails geliştirme hızınızı artırırken şema ve sözleşme bütünlüğünü korur. Başka bir CLI ajanıyla kıyaslama yapmak isterseniz opencode mu Claude Code mu? Dürüst bir karşılaştırma yazısına göz atabilirsiniz.