# opencode ile Ruby on Rails projelerinde geliştirme rehberi

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

Ruby on Rails projelerinde opencode ile verimli çalışmayı öğrenin: AGENTS.md kurulumu, migration, RSpec, Minitest ve Hotwire görevleri için pratik bir rehber.

**Kısaca:**

- opencode, AGENTS.md talimatlarıyla Rails projelerinde migration, model, controller, test ve Hotwire parçalarını hızlıca üretir.
- Küçük adımlarla çalışıp her turun sonunda testleri koşmak, şema ve Strong Parameters gibi Rails’e özgü hataları erken yakalar.
- Ajanı migration, callback ve Zeitwerk adlandırma gibi alanlarda yakından izleyin; ürettiği kodu asla test etmeden kabul etmeyin.

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](/ajanlar/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:

```markdown
# 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](/blog/opencode-nasil-kullanilir/) 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:

| Dosya/alan | Ajana verilecek net görev |
|---|---|
| `db/migrate` | Yalnızca bir migration ekle; `change` yaz; index ve null kısıtlarını birlikte ver. |
| `db/schema.rb` | Bu dosyayı düzenleme; migration sonrası `rails db:migrate` çalıştır. |
| `app/models` | İlişki, scope, doğrulama ekle; callback’leri minimum tut. |
| `app/controllers` | Strong Parameters ve `before_action` güncelle; action içi iş mantığını servis nesnesine taşı. |
| `app/views` + Turbo Stream | Partial’ları kullan; Turbo Stream formatını eksiksiz üret. |

## 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](/blog/opencode-mu-claude-code-mu/) yazısına göz atabilirsiniz.

## Sık sorulanlar

**opencode’u Ruby on Rails projesinde nasıl başlatırım?** Proje klasöründe terminal açıp opencode yazmanız yeterlidir. Ajan, kök dizindeki AGENTS.md dosyasını okur; Rails yapısını ve test komutlarını buradan öğrenir.

**opencode için AGENTS.md dosyasında neler olmalı?** Test, lint ve veritabanı komutları; app/models, app/controllers gibi dizin görevleri; schema.rb’yi elle düzenlememe ve Strong Parameters kuralları gibi Rails’e özel kısıtlar yazılmalıdır. Kısa ve emredici olun.

**opencode migration ve schema.rb dosyalarını güvenle yönetebilir mi?** Migration yazabilir ve rails db:migrate ile şemayı güncelleyebilir. Yine de db/schema.rb üzerinde elle değişiklik yapmasını yasaklamalı ve her migration’ı inceleyip test etmelisiniz.

**opencode RSpec veya Minitest testleri yazabilir mi?** Evet; mevcut test suite’ine uygun örnekleri üretebilir. Ancak ürettiği testler çoğunlukla mutlu yolu kapsar; doğrulama, enum ve Strong Parameters gibi uç durumları siz ekleyin.

---

**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/