Codex ile Laravel Geliştirme: Pratik Rehber

Codex, terminal üzerinden başlatılan bir kodlama ajanıdır; Laravel proje kökünde codex yazdığınızda projeyi okur ve istediğiniz değişiklikleri yapar. Laravel’in klasör yapısı, Artisan komutları ve test araçları tanımlı olduğu için doğru yönlendirmeyle çok verimli çalışır. Bu rehberde, Eloquent, migration, Blade, queue ve test senaryolarında Codex’i güvenli ve pratik şekilde kullanmayı anlatıyorum.

Codex neden Laravel işlerine uygun?

Laravel’in kendine özgü sözleşmeleri vardır: Modeller app/Models altında, migration’lar database/migrations içinde, Blade dosyaları resources/views altında yaşar. Codex bu yapıyı okuduğunda, sadece istediğiniz değişikliği değil; namespace, tablo adı, route ismi gibi detayları da doğru yere koyar. Eloquent ilişkileri, form request doğrulama veya queue job gibi tekrar eden işleri saniyeler içinde şablon olarak üretir. Örneğin php artisan make:model -m yerine ajan, model, migration ve controller’ı birlikte oluşturur ve aralarındaki ilişkiyi kurar. Ayrıca test komutlarını bildiğinizde her değişikliği php artisan test ile doğrulayarak çalışır; bu da Laravel’in test-first pratiğine uyum sağlar. Dahası, Laravel’in service container, service provider ve middleware gibi bileşenlerini anlar; örneğin bir repository pattern değişikliğinde binding’i AppServiceProvider içine doğru yazar. Codex’in genel kullanımı için Codex sayfasına bakabilirsiniz.

Projeyi ajana hazırlamak: AGENTS.md

Codex, proje kökündeki AGENTS.md dosyasını proje talimatı olarak okur. Laravel için bu dosyaya komutları, klasör sözleşmelerini ve Laravel’e özel kuralları yazarsanız ajan her görevde bunlara uyar. Örnek bir dosya:

# AGENTS.md

## Komutlar
- Kurulum: `composer install`
- Test: `php artisan test` veya `vendor/bin/pest`
- Lint: `vendor/bin/pint`
- Format kontrol: `vendor/bin/pint --test`
- Queue çalıştır: `php artisan queue:work`

## Klasör sözleşmeleri
- Modeller `app/Models` altında, PSR-4 namespace `App\Models`.
- Migration dosyaları `database/migrations` altında, isimlendirme `create_xxx_table` veya `add_xxx_to_xxx_table`.
- Form request'leri `app/Http/Requests`.
- Testler `tests/Feature` ve `tests/Unit` altında.

## Laravel'e özel kurallar
- Eloquent model isimlerini tekil, tablo isimlerini çoğul kullan; `$fillable` veya `$guarded` tanımla.
- Migration'da foreign key eklerken `constrained()` kullan.
- Blade içinde karmaşık PHP yazma; directive veya component kullan.
- Queue job'ları `ShouldQueue` implemente etsin.
- Her yeni endpoint için feature test yaz.

Bu kuralları yazarken belirsiz ifadelerden kaçının; örneğin testleri çalıştır yerine php artisan test yazın. Ajan komut satırını kullanacağı için ortam değişkenleri veya Docker servisleri gerekliyse bunları da dosyaya ekleyin. Ayrıca PHP sürümü, veritabanı bağlantısı, APP_ENV gibi ortam ayarlarını AGENTS.md’ye yazmak, ajanın yanlış bağlantı kullanmasını engeller. Dosyayı zamanla güncelleyin; yeni bir servis veya komut eklendiğinde ajana bildirmek için AGENTS.md’yi revize edin. Bağlam mühendisliği prensipleri için bağlam mühendisliği rehberine bakabilirsiniz.

Çalışma döngüsü: planla, küçük adım at, test et, diff’i incele

Codex ile çalışırken en sağlıklı döngü; görevi açıkça ver, önce plan istemesini söyle, sonra implementation’ı küçük parçalara böltür. Her adımdan sonra git diff ile değişiklikleri incele ve php artisan test çalıştır. Kod yeşil kalırsa bir sonraki adıma geç. Plan aşamasında ajana hangi dosyaları değiştireceğini ve neden sorun; planı onayladıktan sonra uygulamasını isteyin. Testleri her adımda çalıştırmak, özellikle migration değişikliklerinde veritabanı şemasını bozmadan ilerlemenizi sağlar. Ayrıca git diff --stat ile hangi dosyaların değiştiğini hızlıca görebilirsiniz. Küçük adımlar atmak, ajanın bağlamını taze tutar ve hata ayıklamayı kolaylaştırır.

Örnek promptlar:

• User modeline posts() hasMany ilişkisi ekle ve migration’da user_id foreign key’ini oluştur. Önce planı listele.
• Yeni PostController için index ve store metotlarını yaz; form request ile doğrula, testlerini ekle.
• SendWelcomeEmail job sınıfını oluştur, ShouldQueue implemente et, queue worker çalıştırmadan testini yaz.
• Blade component alert oluştur; resources/views/components altına koy, kullanım örneği ver.
• Mevcut orders tablosuna status kolonu ekle, migration’ı ve model $casts güncelle, sonra testleri çalıştır.
• Product modeline scopeActive kapsamını ekle ve bu kapsamı kullanan bir endpoint testi yaz.

İyi gittiği işler ve dikkat edilmesi gereken Laravel tuzakları

Codex, aşağıdaki tabloda özetlenen görevlerde güçlüdür; ancak Laravel’in bazı inceliklerinde gözünüz üzerinde olmalı.

Özellikle migration’larda geri alma (down) yöntemini bazen unutur; bu yüzden php artisan migrate çalıştırmadan önce diff’i kontrol edin. Eloquent ilişkilerinde lazy loading performans sorunlarına yol açabilir; with() kullanmasını isteyin. Blade component oluştururken @props tanımını unutabilir; component’in aldığı parametreleri açıkça belirtin. Queue job’larda tries veya timeout gibi özellikleri yazmasını isteyin ve dispatch çağrısının doğru parametrelerle yapıldığını doğrulayın. Ayrıca model factory kullanmaması durumunda testlerde rastgele veri üretebilir; bunun yerine her testte Model::factory()->create() kullanmasını belirtin. Route model binding, authorization policy veya soft delete gibi konularda da ajanın varsayılan davranışını kontrol edin; özellikle custom binding veya global scope gerektiren durumlarda açık talimat verin.

Test ve doğrulama

Laravel’de test, Codex ile iş birliğinin temelidir. Ajanın her değişiklikten sonra php artisan test çalıştırmasını isteyin; başarısız testleri okuyup düzeltebilir. Belirli testleri hedeflemek için --filter parametresini kullanın. Feature testlerde RefreshDatabase trait’i ile veritabanını her testte sıfırlayın. Test verisi oluşturmak için model factory kullanmasını söyleyin; DatabaseSeeder yerine her testte User::factory()->create() gibi. Migration değişikliklerini uygulamadan önce php artisan migrate:status ile mevcut durumu kontrol edin. Queue testlerinde Queue::fake() kullanarak job’ın dispatch edildiğini assert edin; notification testlerinde Notification::fake() benzeri. API testlerinde assertJson ile yanıt yapısını doğrulayın. Ajan test çıktısındaki hataları okuyup kendi kendine düzeltme yapabilir; ancak hataların kök nedenini anlamadığı durumda siz de devreye girin ve açıklama yapın. CI ortamında yakalanan hataları Codex’e geri göndermek için CI hatasını yapay zeka düzeltsin rehberindeki akışı uygulayabilirsiniz.

Birden fazla ajanı aynı Laravel projesinde çalıştırmak: AgentVera

Laravel projelerinde farklı özellikleri paralel yürütürken AgentVera, her ajanı kendi git worktree’sinde ve kendi terminal panelinde çalıştırır; böylece migration ve controller dosyaları çakışmaz, çıktılar karışmaz. Bir ajanın işi bitince ikinci model otomatik kod incelemesi yapar ve bulguları file:line ile bağlar; bu özellikle foreign key veya index hatalarını erken yakalar. Token bütçesi uyarısı %80’de geldiği için ajanın konuşması korunurken bütçe aşımı engellenir. AgentVera nasıl kullanılır sayfasında kurulum akışını görebilirsiniz.

Sonuç

Codex, AGENTS.md ile doğru yönlendirildiğinde Laravel projelerinde güçlü bir asistan olur. Küçük adımlar, sürekli test ve diff incelemesi ile hem hız kazanır hem de migration ve Eloquent gibi kritik katmanlarda güvenli kalırsınız. Tekrar eden işleri ajana devredip, mimari kararları kendiniz verin.