Codex ile Ruby on Rails geliştirme rehberi

Codex, proje klasöründe terminalden codex komutuyla başlatılan bir kodlama ajanıdır; Ruby on Rails’in MVC düzeni, Active Record migration’ları, generator’ları ve güçlü test kültürüyle birlikte iyi çalışır. Rails geliştiricisi olarak asıl iş, ajanın proje bağlamını doğru okumasını sağlamak ve her değişikliği test ile doğrulamaktır. Codex sayfasındaki genel bilgilerden sonra bu rehber, doğrudan Rails projelerinde pratik kullanımı anlatır.

Codex neden Rails işine uygun

Rails’in convention over configuration yaklaşımı, Codex’in tahmin yürütme yükünü azaltır. app/models, app/controllers, app/views gibi köklü klasör düzeni; config/routes.rb, db/schema.rb gibi net dosyalar; bin/rails komutları ve generator’lar, ajanın doğru kalıpları bulmasını kolaylaştırır. Örneğin bir migration istediğinizde db/migrate altında zaman damgalı bir dosya oluşturması gerektiğini bilir. Test çerçevesi olarak RSpec veya Minitest’in varlığı da ajanın değişiklik sonrası hızlı geri bildirim almasını sağlar. Hotwire tarafında Turbo Streams ve Stimulus controller’ları da projede net isimlerle yer aldığı için ajan, partial ve stream view’larını birlikte güncelleyebilir.

Active Record sorgu arayüzü, ilişkiler ve scope’lar konusunda Rails’in belirgin kuralları vardır; Codex bu kuralları uygulayarak has_many, belongs_to gibi ilişkileri hızlıca yazabilir. Generator’lar (bin/rails generate model, scaffold, migration) ajanın işini daha da kolaylaştırır: ajan, doğru komutu çalıştırıp üretilen dosyaları proje standartlarına göre düzenleyebilir. Ancak bu otomasyonun kontrolsüz kullanımı dosya kalabalığına yol açabilir; bu yüzden AGENTS.md’de kurallar netleştirilmelidir. Rails’in güçlü parametre kavramı (strong parameters) ve callback yönetimi de ajanın yaygın güvenlik hatalarından kaçınmasına yardımcı olur; yeter ki proje kuralları açıkça yazılsın.

Projeyi Codex için hazırlama

Codex proje klasöründeki AGENTS.md dosyasını okur; bu dosya Rails projesinin komutlarını, klasör düzenini ve proje kurallarını özetler. Ajanın her turda test çalıştırmasını, migration’ları doğru yönetmesini ve schema dosyasını elle düzenlememesini burada belirtmek gerekir. Aşağıdaki örnek, tipik bir Rails projesi için yeterli bir başlangıçtır:

# AGENTS.md

## Komutlar
- Test: `bin/rails test` (Minitest) veya `bundle exec rspec`
- Lint: `bundle exec rubocop`
- Generator: `bin/rails generate ...`
- Migration: `bin/rails db:migrate`
- Rollback: `bin/rails db:rollback`

## Klasör düzeni
- `app/models`: Active Record modelleri ve iş mantığı; model dosyaları yalnızca modelle ilgili kod içerir.
- `app/controllers`: HTTP isteklerini karşılar; controller'larda iş mantığı yazma, service object kullan.
- `app/views`: ERB ve Hotwire partial'ları; Turbo Streams dosyaları `*.turbo_stream.erb` uzantısıyla aynı klasörde olur.
- `db/migrate`: Migration dosyaları; bir kez üretildikten sonra içeriği değiştirme, yeni migration ekle.
- `test/` veya `spec/`: Test dosyaları; her yeni davranış için test ekle veya güncelle.

## Rails kuralları
- `db/schema.rb` dosyasını elle düzenleme; şema değişiklikleri yalnızca migration ile yapılır.
- Active Record callback'lerde yan etki biriktirme; transaction veya service object tercih et.
- Yeni gem eklemeden önce kullanıcıya sor; `Gemfile` değişikliği sonrası `bundle install` çalıştır.
- Testleri yeşil tut; her görev sonunda ilgili testleri çalıştır ve çıktıyı özetle.
- Hotwire ile çalışırken Turbo Streams ve Stimulus controller'ların isimlendirme kurallarına uy.

Bu dosyayı kısa ve kesin tutun; ajan bağlamı her turda yeniden okur. Proje geliştikçe AGENTS.md’yi güncelleyin: yeni bir test çerçevesi eklendiğinde komut satırını değiştirin, klasör düzeni değişirse düzeltin. Özellikle Ruby sürümü ve Bundler kısıtlamaları gibi ortam detayları, ajanın yanlış komut çalıştırmasını önler. config/credentials.yml.enc veya .env gibi gizli dosyalara dokunmaması gerektiğini de ayrıca belirtin; ajan yanlışlıkla bu dosyaları düzenlemeye çalışabilir. codex komutunun genel kullanımı hakkında Codex CLI nasıl kullanılır? Adım adım rehber yazısına bakabilirsiniz; burada Rails’e özgü kısma odaklanıyoruz.

Çalışma döngüsü: planla, küçük adımlar at, testleri çalıştır, diff’i incele

Codex ile Rails’te en sağlıklı döngü şudur: görevi tek bir sorumluluğa indir; ajanın plan yapmasını iste; değişiklikleri uygulat; testleri çalıştır; git diff ile farkı incele. Her seferinde büyük bir özelliği tek prompt ile istemek yerine, migration, model, controller, view ve test gibi katmanlara bölmek daha güvenlidir. Ajan, test çıktısındaki hatayı görüp düzeltebilir; bu yüzden test komutunu mutlaka AGENTS.md’ye yazın. Çalışmaya başlamadan önce git üzerinde yeni bir branch açmak da iyi bir pratiktir; böylece ajanın değişiklikleri ana hattan izole kalır ve geri almak kolaylaşır.

Örnek prompt’lar:

• “User modeline active boolean alanı ekle. Migration oluştur, model validasyonu ekle, varsa RSpec testini güncelle ve bundle exec rspec spec/models/user_spec.rb çalıştır.”
• “PostsController#create içindeki iş mantığını app/services/post_creator.rb dosyasına taşı. Controller’ı sadeleştir, ilgili testleri güncelle ve bundle exec rubocop çalıştır.”
• “app/views/posts/_post.html.erb partial’ını Turbo Streams ile güncellenebilir hale getir. update.turbo_stream.erb dosyasını ekle ve eksik testleri yaz.”
• “PostsController#index üzerindeki N+1 sorguyu tespit et ve includes(:comments, :author) ile düzelt. Test çalıştırıp sonucu göster.”
• “Rails uygulamasında reports adında yeni bir kaynak oluştur: model, migration, controller, view ve test dosyalarını bin/rails generate scaffold kullanmadan adım adım üret.”
• “config/routes.rb içindeki resources :posts satırını only: [:index, :show, :new, :create] ile daralt. İlgili testleri çalıştır ve eksik rotalara erişimi test et.”

Bu prompt’larda ajanın neyi değiştireceği, hangi komutu çalıştıracağı ve hangi testi doğrulayacağı açıktır. Büyük işlerde önce plan isteyin, sonra her adımı onaylayın. Ajan bazen planı yazdıktan sonra doğrudan kod üretmeye geçebilir; bu durumda “önce planı göster, kod yazma” diye netleştirin. Her adımdan sonra git diff --stat ile değişen dosya sayısına bakın; beklenmedik dosyalar görürseniz düzeltmesini isteyin.

Codex’in iyi yaptığı Rails işleri ve dikkat edilecek tuzaklar

Codex; Active Record migration yazma, model validasyonları ve ilişkileri kurma, controller testleri, RSpec/Minitest senaryoları, basit Hotwire partial güncellemeleri ve rubocop düzeltmelerinde hızlıdır. Ayrıca bin/rails generate komutlarını doğru kullanabilir ve mevcut kod tabanına uygun servis nesneleri önerebilir.

Buna karşılık Rails’e özgü tuzaklara dikkat edin:

• Migration’ı üretip db/schema.rb üzerinde elle değişiklik yapmaya çalışabilir; AGENTS.md kuralı bunu engeller.
• Gereksiz gem ekleyebilir, Gemfile’ı kilitleyebilir veya bundle install’ı atlayabilir; her turda diff’i inceleyin.
• Active Record callback’lerde iş mantığı biriktirebilir; modeli şişirir. Service object kuralı koyun.
• N+1 sorguları fark etmeyebilir; includes veya bullet gem’i ile doğrulayın.
• Turbo/Turbolinks kafa karışıklığı yaşayabilir; Hotwire projelerinde turbo_stream ve turbo_frame isimlendirmesine müdahale edebilir.
• Test yazmadan görevi bitirebilir; her görevde testleri çalıştırmasını isteyin.
• Rails sürümüne özgü API farklarını karıştırabilir; Gemfile.lock’taki Rails sürümünü bağlamda tutun.
• Strong parameters ile izin verilen parametreleri daraltmayı unutabilir veya tam tersine tüm parametreleri izinli listeleyerek güvenlik açığı oluşturabilir.
• Migration reversibility: change yerine up/down kullanması gerekebilecek karmaşık değişikliklerde geri alma adımını atlayabilir; rollback testi yapın.
• Zaman dilimleri ve i18n: Time.current yerine Time.now kullanması gibi hatalar yapabilir; Active Record’un zaman damgası kurallarını ajanın bilmesi gerekir.

Rails’te test ve doğrulama

Codex’in ürettiği değişiklikleri kabul etmeden önce mutlaka testleri ve statik analizi çalıştırın. Rails projesinde doğrulama sırası genellikle şöyledir: migration’ı çalıştır, testleri koş, rubocop’u çalıştır, git diff ile değişiklikleri gözden geçir. Ajan test çıktısını okuyup hataları düzeltebilir; bu nedenle ilk hatada görevi geri vermekten çekinmeyin. “Şu test hatasını düzelt ve tekrar çalıştır” demek, ajanın hata ayıklama döngüsünü hızlandırır.

| Dosya / komut | Doğrulama amacı | | bin/rails test veya bundle exec rspec | Model, controller ve entegrasyon testlerini koşar. | | bundle exec rubocop | Rails’e özgü stil ve kalıp kontrollerini yapar. | | db/schema.rb | Migration sonrası beklenen şema değişikliğini doğrular. | | git diff --check | Boşluk, satır sonu ve çakışma işaretlerini yakalar. |

Ajanın kendi kendine test etmesini sağlamak için AGENTS.md’deki test komutunu eksiksiz verin. CI ortamında yakalanan bir hatayı ajana düzelttirme akışını CI hatasını yapay zeka düzeltsin, PR yorumunu da yazısında görebilirsiniz. Rails’te özellikle sistem testleri (test/system veya RSpec feature testleri) tarayıcı gerektirdiği için ajanın bunları atlamamasına dikkat edin. Fixture ve factory seçiminde projenin mevcut yapısına uymasını isteyin; ajan bazen kendi kafasına göre yeni bir test verisi yaklaşımı getirebilir. Test çalıştırırken parallel seçenekleri varsa, ajanın bu parametreleri bilmesi hız kazandırır.

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

Rails projesinde aynı anda birden fazla Codex oturumu açmak isterseniz AgentVera’daki paralel çalışma modeli işinize yarar. Özellikle her ajanın kendi git worktree’sinde çalışması, migration ve model dosyalarının üst üste yazılmasını önler. Bir ajanın turu bittiğinde ikinci modelin otomatik kod incelemesi yapması, Rails’e özgü regresyonları file:line seviyesinde yakalar; checkpoint özelliği ise yanlış bir migration’ı tek tıkla geri alıp oturumu adım adım yeniden oynatmanızı sağlar. Token bütçeleri de uzun Rails görevlerinde maliyeti kontrol altında tutar. Detaylı kurulum için AgentVera nasıl kullanılır: ilk proje, ajanlar ve ızgara rehberine bakın.

Sonuç

Codex, Rails projelerinde terminalden çalışan ve proje kurallarını AGENTS.md üzerinden okuyan güçlü bir yardımcıdır. En iyi sonuç, görevleri katmanlara bölüp her adımda test ve git diff ile doğrulamaktan geçer. Migration ve schema kurallarını netleştirir, Hotwire ve test komutlarını bağlamda tutarsanız, Codex günlük Rails işlerinin önemli bir kısmını güvenle üstlenir. Unutmayın ki ajanın çıktısı kod incelemesi ve testlerle filtrelenmelidir; ancak bu disiplinle Rails projenizde hız ve kaliteyi birlikte yakalarsınız.