# Codex ile Ruby on Rails geliştirme rehberi

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

Codex Ruby on Rails projelerinde nasıl kullanılır? AGENTS.md kurulumu, test döngüsü, migration kuralları, Hotwire ipuçları ve sık yapılan hatalar.

**Kısaca:**

- Codex, Rails projelerinde codex komutuyla çalışır; kuralları AGENTS.md dosyasından okur ve test döngüsüne uyar.
- En verimli kullanım, görevleri migration, model, controller ve view katmanlarına bölüp her adımda test çalıştırmaktır.
- Migration ve schema kuralları netleştirilmezse Codex hatalı düzenlemeler yapabilir; her turda git diff şarttır.

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

```markdown
# 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](/blog/codex-cli-nasil-kullanilir/) 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](/blog/ci-hatasini-yapay-zeka-duzeltsin/) 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](/blog/agentvera-nasil-kullanilir/) 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.

## Sık sorulanlar

**Codex Ruby on Rails projelerinde migration oluşturabilir mi?** Evet, bin/rails generate migration komutunu çalıştırıp Active Record migration yazabilir. Ancak db/schema.rb üzerinde değişiklik yapmaması ve migration sonrası testleri çalıştırması için AGENTS.md kuralı koyun.

**Codex ile RSpec testleri nasıl çalıştırılır?** Ajana bundle exec rspec komutunu çalıştırmasını söyleyebilir veya test yazdırıp çalıştırmasını isteyebilirsiniz. Hataları test çıktısından okuyup düzeltebilir; AGENTS.md’de test komutunu netleştirin.

**AGENTS.md dosyasına neler yazılmalı?** Test, lint ve migration komutları; klasör düzeni; Rails’e özgü kurallar yazılmalıdır. Controller’da iş mantığı olmaması ve schema’nın elle düzenlenmemesi gibi kurallar Codex’in proje bağlamını doğru anlamasını sağlar.

**Codex Rails projesinde güvenli mi?** Codex yalnızca sizin terminalinizde ve izin verdiğiniz değişiklikleri yapar. Yine de her turda git diff ile değişiklikleri incelemek, testleri çalıştırmak ve credentials, schema gibi kritik dosyaları korumak gerekir.

---

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